> ## Documentation Index > Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create phone number > Adds a phone number to a workspace, either by buying one through Voiceflow or by connecting a number you already own with its provider credentials. A new number is assigned to nothing and answers nothing until you assign it. ## OpenAPI ````yaml /specs-prettified/realtime/openapi.stable.json post /v1/stable/phone-number openapi: 3.0.0 info: title: Realtime description: Realtime gateway API service version: 1.0.0 contact: {} servers: - url: https://realtime-api.voiceflow.com security: [] tags: [] paths: /v1/stable/phone-number: post: tags: - Phone Number summary: Create phone number description: Adds a phone number to a workspace, either by buying one through Voiceflow or by connecting a number you already own with its provider credentials. A new number is assigned to nothing and answers nothing until you assign it. operationId: StablePhoneNumberController_create parameters: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/StablePhoneNumberCreateRequest" responses: "201": description: Returns the new phone number with its ID, `value`, and provider. Its `voice` and `sms` targets are null because it is not assigned to a project yet. content: application/json: schema: $ref: "#/components/schemas/StablePhoneNumberResponse" x-vf-doc: description: Returns the new phone number with its ID, `value`, and provider. Its `voice` and `sms` targets are null because it is not assigned to a project yet. security: - token: [] components: schemas: StablePhoneNumberCreateRequest: oneOf: - type: object properties: name: default: "" description: The display name of the number within the workspace. Callers never see it. Defaults to empty. type: string workspaceID: type: string description: The ID of the workspace to add the number to. provider: type: string enum: - voiceflow-telnyx description: Buy a number through Voiceflow. The carrier picks the digits, so no `value` is sent. x-enumNames: - VOICEFLOW_TELNYX areaCode: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: The area code to buy in (e.g. `415`). The carrier picks the rest of the digits. country: type: string enum: - CA - US description: The country to buy in. x-enumNames: - CA - US required: - workspaceID - provider - areaCode - country additionalProperties: false - type: object properties: name: default: "" description: The display name of the number within the workspace. Callers never see it. Defaults to empty. type: string workspaceID: type: string description: The ID of the workspace to add the number to. provider: type: string enum: - twilio description: Connect a number held in your own Twilio account. x-enumNames: - TWILIO value: type: string pattern: ^\+\d+$ description: "The number you already hold, in E.164: a leading `+`, country code, then digits (e.g. `+14155552671`)." twilioAccountSID: type: string minLength: 34 maxLength: 34 description: The Account SID of the Twilio account holding the number. 34 characters. twilioAuthToken: type: string minLength: 32 maxLength: 32 description: The Twilio auth token. 32 characters. Write-only — it is never returned. required: - workspaceID - provider - value - twilioAccountSID - twilioAuthToken additionalProperties: false - type: object properties: name: default: "" description: The display name of the number within the workspace. Callers never see it. Defaults to empty. type: string workspaceID: type: string description: The ID of the workspace to add the number to. provider: type: string enum: - vonage description: Connect a number held in your own Vonage account. x-enumNames: - VONAGE value: type: string pattern: ^\+\d+$ description: "The number you already hold, in E.164: a leading `+`, country code, then digits (e.g. `+14155552671`)." vonageAPIKey: type: string minLength: 8 maxLength: 8 description: The API key of the Vonage account holding the number. 8 characters. vonageAPISecret: type: string minLength: 1 description: The Vonage API secret. Write-only — it is never returned. vonageSignatureSecret: type: string minLength: 1 description: The Vonage signature secret, used to verify inbound webhooks. Write-only — it is never returned. required: - workspaceID - provider - value - vonageAPIKey - vonageAPISecret - vonageSignatureSecret additionalProperties: false - type: object properties: name: default: "" description: The display name of the number within the workspace. Callers never see it. Defaults to empty. type: string workspaceID: type: string description: The ID of the workspace to add the number to. provider: type: string enum: - telnyx description: Connect a number held in your own Telnyx account. x-enumNames: - TELNYX value: type: string pattern: ^\+\d+$ description: "The number you already hold, in E.164: a leading `+`, country code, then digits (e.g. `+14155552671`)." telnyxAPIKey: type: string minLength: 1 description: The API key of the Telnyx account holding the number. Write-only — it is never returned. telnyxPublicKey: type: string minLength: 1 description: The Telnyx public key, used to verify inbound webhooks. Base64 Ed25519, 32 bytes decoded. required: - workspaceID - provider - value - telnyxAPIKey - telnyxPublicKey additionalProperties: false StablePhoneNumberResponse: type: object properties: phoneNumber: $ref: "#/components/schemas/StablePhoneNumber" required: - phoneNumber StablePhoneNumber: type: object properties: id: type: string description: The ID of the phone number, used to assign, update and delete it. Not the number itself. sms: nullable: true description: Where incoming SMS go, or null when nothing handles SMS on this number. allOf: - $ref: "#/components/schemas/StablePhoneNumberTarget" name: type: string description: The display name of the number within the workspace. Callers never see it. value: type: string description: The number itself, in E.164 (e.g. `+14155552671`). voice: nullable: true description: Where incoming calls go, or null when nothing handles calls on this number. allOf: - $ref: "#/components/schemas/StablePhoneNumberTarget" provider: description: Who the number is held with. `voiceflow-telnyx` is a number bought through Voiceflow; the rest are numbers connected from your own carrier account. Fixed at creation. allOf: - $ref: "#/components/schemas/PhoneNumberProvider" enum: - twilio - vonage - telnyx - voiceflow-telnyx - voiceflow-sip - byo-sip x-enumNames: - TWILIO - VONAGE - TELNYX - VOICEFLOW_TELNYX - VOICEFLOW_SIP - BYO_SIP workspaceID: type: string description: The ID of the workspace the number belongs to. providerResourceID: type: string description: The number's ID with the provider, for reconciling against it. createdAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ updatedAt: type: string format: date-time pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ required: - id - sms - name - value - voice - provider - workspaceID - providerResourceID - createdAt - updatedAt StablePhoneNumberTarget: type: object properties: version: nullable: true description: "Which version of the environment answers: `published`, the one serving live traffic, or `draft`, the working copy. Null when no environment is pinned." type: string enum: - draft - published x-enumNames: - DRAFT - PUBLISHED projectID: type: string description: The ID of the project this side of the number reaches. environmentAlias: nullable: true description: "The alias of the environment this side of the number reaches (e.g. `main`). Null in two cases: the number is assigned to the project with no environment pinned, or the environment it was pinned to has since been deleted — `version` is still whatever the pin asked for, so a null alias beside a non-null `version` is the second case." type: string required: - version - projectID - environmentAlias PhoneNumberProvider: type: string enum: - twilio - vonage - telnyx - voiceflow-telnyx - voiceflow-sip - byo-sip x-enumNames: - TWILIO - VONAGE - TELNYX - VOICEFLOW_TELNYX - VOICEFLOW_SIP - BYO_SIP securitySchemes: token: scheme: bearer bearerFormat: JWT type: http description: Voiceflow bearer token ````