Request a US phone number with Saperly assistant settings

Provide the assistant’s instructions to request one US phone number. Choose a local or toll-free number and, for a local number, optionally specify a preferred three-digit area code. You can also include assistant settings such as language, voice and model.

Your AI

Use with your AI

For tasks with several steps, continue in the AI you already use.

CodexClaude CodeCursorWindsurfCline

View instructions

Use `provision-phone-number-saperly` to request one US phone number. Ask for missing `body.connection.instructions`; include the user’s optional assistant settings and local/toll-free preference only as supported by the native input. An area code is a three-digit preference for local numbers only. Use explicit supplied booleans, preserving false and empty disclosure text. Show the actual response and any number/reference details it contains; distinguish requested settings from returned configuration, and do not infer provisioning success or call/SMS readiness. Reuse the existing Toolmu connection or follow https://toolmu.com/SKILL.md, check the current contract and price, and honor the user’s authorized budget before acquisition.

Task:
Request one US virtual phone number for my AI receptionist. Have it say [my greeting], ask [what the caller needs], and [take a short message when needed]. I prefer [a local number or a free-to-call number].

Paste into your connected AI's conversation.

Connection guide

Up to 2.4 credits / call

The final charge is based on confirmed usage. Unused reserved credits return to your available balance.

Saperly

Request a US phone number with Saperly assistant settings

Provide the assistant’s instructions to request one US phone number. Choose a local or toll-free number and, for a local number, optionally specify a preferred three-digit area code. You can also include assistant settings such as language, voice and model.

You receive

Submit a request for one US number with the assistant instructions and settings you provide. Your Agent can show the actual provisioning response and organize any phone number, resource ID or configuration details it contains, keeping your requested settings separate from the returned details.

Start with your task

Request one US virtual phone number for my AI receptionist. Have it say [my greeting], ask [what the caller needs], and [take a short message when needed]. I prefer [a local number or a free-to-call number].

What to know

Number availability may prevent provisioning, including in your preferred area code. A submitted request does not guarantee a number is assigned or ready for calls or SMS.

Inputs & outputs

Inspect the current inputs, availability, and maximum charge before starting.

Input schema

Input schema
Field / Path	Type	Requirement	Meaning
body`body`	`object`	Required	Required fields `connection`
Country`body.country`	`string`	Optional	Only US is accepted. The request defaults to US when this optional field is omitted. Default `US` Fixed value `US`
connection`body.connection`	`object`	Required	The number's AI persona — REQUIRED. Created and attached internally; update it later via /update-numbers/{id}. Required fields `instructions`
llm`body.connection.llm`	`object`	Optional	The model the hosted assistant runs. Required fields `model`
Assistant model`body.connection.llm.model`	`string`	Optional	Optional managed-model selection, such as openai/gpt-4o. If llm is supplied, a nonempty model is required. Minimum length `1`
tts`body.connection.tts`	`object`	Optional	Text-to-speech voice selection. Required fields `voiceId`
Assistant voice ID`body.connection.tts.voiceId`	`string`	Optional	Optional text-to-speech voice selection using an id from the voice list. If tts is supplied, a nonempty voiceId is required. Minimum length `1`
Assistant name`body.connection.name`	`string`	Optional	Optional readable name for the assistant; 1–120 characters. Minimum length `1` Maximum length `120`
Assistant language`body.connection.language`	`string`	Optional	Optional BCP-47 language tag, such as en or es; 2–35 characters. Refer to the language list when selecting a code. Minimum length `2` Maximum length `35`
Opening disclosure text`body.connection.disclosure`	`string`	Optional	Optional AI/TCPA notice requested when compliance is enabled; at most 1,000 characters. An empty string requests the standard organization-named notice. Maximum length `1000`
callControl`body.connection.callControl`	`object`	Optional	Which live-call actions the assistant may take (signaling only).
Allow assistant hang-up`body.connection.callControl.endCall`	`boolean`	Optional	Requests permission for the assistant to signal a call hang-up; default setting: on.
Allow keypad signaling`body.connection.callControl.sendDtmf`	`boolean`	Optional	Requests permission for the assistant to send keypad digits, for example to navigate an automated phone menu; default setting: on.
Assistant instructions`body.connection.instructions`	`string`	Required	Required system prompt describing how the number’s assistant should speak and behave on calls; 1–10,000 characters. Minimum length `1` Maximum length `10000`
SMS auto-reply setting`body.connection.smsAutoReply`	`boolean`	Optional	Requests assistant replies to incoming SMS when true; default setting: false. This setting does not confirm SMS service readiness.
Enable opening disclosure`body.connection.complianceEnabled`	`boolean`	Optional	Requests the opening, uninterruptible disclosure and do-not-message option when true; default setting: true.
phoneNumber`body.phoneNumber`	`object`	Optional	Default `{"numberType":"local"}`
Preferred local area code`body.phoneNumber.areaCode`anyOf · 1	`string`	—	Optional three-digit area-code preference, such as 415, for local numbers only. Omit it to request any available local number; it is not an exact-number reservation. Pattern `^\d{3}$`
Number type`body.phoneNumber.numberType`anyOf · 1	`string`	—	Use local for a local number or toll_free for a toll-free number. The default request is local; toll_free must be supplied explicitly. Default `local` Fixed value `local`
Number type`body.phoneNumber.numberType`anyOf · 2	`string`	—	Use local for a local number or toll_free for a toll-free number. The default request is local; toll_free must be supplied explicitly. Fixed value `toll_free`

View raw JSON

{
  "type": "object",
  "required": [
    "body"
  ],
  "properties": {
    "body": {
      "type": "object",
      "$schema": "https://json-schema.org/draft/2020-12/schema",
      "required": [
        "connection"
      ],
      "~standard": {
        "vendor": "zod",
        "version": 1,
        "jsonSchema": {}
      },
      "properties": {
        "country": {
          "type": "string",
          "const": "US",
          "default": "US",
          "description": "ISO 3166-1 alpha-2 country code. Phase 1 supports 'US' only."
        },
        "connection": {
          "type": "object",
          "required": [
            "instructions"
          ],
          "properties": {
            "llm": {
              "type": "object",
              "required": [
                "model"
              ],
              "properties": {
                "model": {
                  "type": "string",
                  "minLength": 1,
                  "description": "Managed LLM (e.g. \"openai/gpt-4o\")."
                }
              },
              "description": "The model the hosted assistant runs.",
              "additionalProperties": false
            },
            "tts": {
              "type": "object",
              "required": [
                "voiceId"
              ],
              "properties": {
                "voiceId": {
                  "type": "string",
                  "minLength": 1,
                  "description": "TTS voice — an `id` from /list-voices."
                }
              },
              "description": "Text-to-speech voice selection.",
              "additionalProperties": false
            },
            "name": {
              "type": "string",
              "maxLength": 120,
              "minLength": 1,
              "description": "Human-readable persona name (1–120 characters)."
            },
            "language": {
              "type": "string",
              "maxLength": 35,
              "minLength": 2,
              "description": "BCP-47 language tag (e.g. \"en\", \"es\") — see /list-languages."
            },
            "disclosure": {
              "type": "string",
              "maxLength": 1000,
              "description": "The AI/TCPA notice spoken first when compliance is on. Leave empty and a standard org-named default is used."
            },
            "callControl": {
              "type": "object",
              "properties": {
                "endCall": {
                  "type": "boolean",
                  "description": "Allow the assistant to hang up the call (default on)."
                },
                "sendDtmf": {
                  "type": "boolean",
                  "description": "Allow the assistant to press keypad digits, e.g. to navigate an IVR (default on)."
                }
              },
              "description": "Which live-call actions the assistant may take (signaling only).",
              "additionalProperties": false
            },
            "instructions": {
              "type": "string",
              "maxLength": 10000,
              "minLength": 1,
              "description": "System prompt for the number's AI persona (how it speaks and what it does on calls). REQUIRED — every number has exactly one connection."
            },
            "smsAutoReply": {
              "type": "boolean",
              "description": "Auto-answer inbound SMS with the assistant (default off)."
            },
            "complianceEnabled": {
              "type": "boolean",
              "description": "When true (the default), the disclosure is spoken as the line's first, uninterruptible utterance and the do-not-message tool is exposed."
            }
          },
          "description": "The number's AI persona — REQUIRED. Created and attached internally; update it later via /update-numbers/{id}.",
          "additionalProperties": false
        },
        "phoneNumber": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "areaCode": {
                  "type": "string",
                  "pattern": "^\\d{3}$",
                  "description": "Preferred 3-digit area code (e.g. '415'). Local numbers only. Omit to take any available number."
                },
                "numberType": {
                  "type": "string",
                  "const": "local",
                  "default": "local"
                }
              },
              "additionalProperties": false
            },
            {
              "type": "object",
              "required": [
                "numberType"
              ],
              "properties": {
                "numberType": {
                  "type": "string",
                  "const": "toll_free"
                }
              },
              "additionalProperties": false
            }
          ],
          "default": {
            "numberType": "local"
          }
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Result schema

Output fields have not been documented yet.

Additional notes

Saperly’s phone-number provisioning reference covers number requests. The official OpenAPI contract also documents number-availability failures.