create-phone-number

Vapi Phone Number Setup

Default to a payload or implementation plan. Provision, import, route, or release a number only when the user explicitly requests the live mutation. Require a final explicit confirmation immediately before provisioning or another potentially chargeable action.

Security and Source Rules

• Never ask for carrier passwords, auth tokens, API keys, API secrets, or private keys in chat.
• Use an existing Vapi credentialId for provider imports when the current public schema supports it. If a required credential does not exist, stop and state that API prerequisite.
• If the public API requires raw carrier secrets and exposes no credential-based alternative, source them from local environment variables without displaying them, writing them to payload files, or logging the request body.
• Verify provider fields against the current Create Phone Number API or public OpenAPI schema.
• Never invent phone numbers, SIP realms, credentials, resource IDs, area-code availability, or routing destinations.

Procedure

1. Determine the execution mode.

   • Return a payload or plan when the user asks for a draft or does not clearly authorize a live mutation.
   • For a live request, confirm that VAPI_API_KEY is set without printing it.

2. Choose the transport path.

   • For a nontechnical request for an ordinary number, prefer the documented Vapi-hosted US PSTN path.
   • Use SIP only when the user explicitly asks for SIP. Require an exact supported SIP URI from the user or current public API documentation; if it is unavailable, stop and state the missing prerequisite. Do not invent a regional realm.
   • Use a carrier import only when the user owns the number and the required secure credential path is available.

3. Resolve routing before mutation.

   • List or get assistants and squads through public endpoints. Match a supplied name to one resource.
   • If several resources are plausible, ask the user to choose. Never guess an ID.
   • Route to either one assistantId or one squadId; clear conflicting destination fields when changing an existing route.

4. Check inventory safely.

   • Review existing phone numbers with GET /phone-number to avoid duplicate provisioning.
   • The current public OpenAPI accepts numberDesiredAreaCode but does not expose a public available-area-code inventory endpoint. Accept the user's desired three-digit US area code after explaining that fulfillment is not guaranteed.
   • Do not purchase a number merely to test availability. Do not infer global unavailability from one provisioning response.

5. Confirm and execute.

   • Show the provider, area code or exact owned number, routing destination, and whether the action may incur carrier or usage charges.
   • Obtain explicit confirmation immediately before POST /phone-number or another potentially chargeable mutation.
   • Validate the response for id, provider, number or SIP URI, status when present, and resolved route.

6. Update without destroying configuration.

   • GET /phone-number/{id} first.
   • Build the provider-specific update DTO. Change only requested writable fields and preserve the current provider, hooks, server, fallback destination, and provider-specific settings by omission or exact carry-forward as required by the public schema.
   • Do not send response-only fields such as id, timestamps, or organization metadata.
   • Re-fetch the number and verify the requested route or setting.

7. Handle failures precisely.

   • 400: report the rejected field or unavailable request; correct a documented shape error before at most one retry.
   • 401/403: stop for Vapi authentication or permission issues.
   • 404: report the missing phone number, assistant, squad, or credential.
   • 5xx: report a Vapi service failure and do not claim success.
   • Separate carrier-side ownership, credential, provisioning, or transport failures from Vapi routing configuration.

Free Vapi Number Limits

Vapi-hosted free numbers are for US national use and have a limit of five per account. The first free number can be requested without a payment method. Additional free numbers require a payment method on file, but the numbers themselves remain free.

Free Vapi numbers support outbound calls only to US +1 destinations and do not support international calling. Use an imported provider number or supported SIP/carrier path for international use. Do not describe free numbers as unlimited production telephony.

Payload-Only Example

This template does not provision anything:

{
  "provider": "vapi",
  "numberDesiredAreaCode": "<confirmed-three-digit-area-code>",
  "assistantId": "<verified-assistant-id>",
  "name"

Read Provider API Procedures for Vapi-hosted, Twilio, Vonage, Telnyx, BYO carrier, and routing examples. Read Phone Number API Examples when the user requests TypeScript, Python, or cURL implementation code. Keep placeholders out of live requests.

Public Sources

• Phone calling and Phone quickstart
• Create Phone Number API
• Free Vapi phone numbers
• Import a Twilio number