> ## Documentation Index > Fetch the complete documentation index at: https://developers.nlpearl.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Custom VoIP Number > Creates a custom VoIP phone number and, in the same call, optionally configures its inbound (`sipConfig`) and/or outbound (`sipTrunkConfig`). When an inbound configuration is provided, the generated SIP domain is returned in `sipConfig.domain`. A number that already exists as a custom VoIP number of the account is rejected with a 400 that gives its id. If the configuration fails, nothing is created and the call can be retried. ## OpenAPI ````yaml post /v2/PhoneNumber/CustomVoip openapi: 3.0.1 info: title: NLPearl Client API description: A sample API that demonstrates features in the OpenAPI specification version: v2 servers: - url: https://api.nlpearl.ai description: Production Environement security: - bearer_auth: [] - oauth2_client_credentials: [] tags: - name: Pearl description: >- Manage your Pearls, the AI agents that handle your inbound and outbound calls. Create and configure Pearls, retrieve their details and settings, run or pause them, list and bulk-export their calls, monitor calls in progress, get analytics, and reset a customer's conversation memory. paths: /v2/PhoneNumber/CustomVoip: post: tags: - PhoneNumber summary: Create Custom VoIP Number description: >- Creates a custom VoIP phone number and, in the same call, optionally configures its inbound (`sipConfig`) and/or outbound (`sipTrunkConfig`). When an inbound configuration is provided, the generated SIP domain is returned in `sipConfig.domain`. A number that already exists as a custom VoIP number of the account is rejected with a 400 that gives its id. If the configuration fails, nothing is created and the call can be retried. requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/CustomVoipNumberRequestApi' description: "Data used to create a custom VoIP phone number. The inbound (`sipConfig`) and outbound\r\n(`sipTrunkConfig`) configurations are independent and optional: provide one, the other, both, or none." text/json: schema: allOf: - $ref: '#/components/schemas/CustomVoipNumberRequestApi' description: "Data used to create a custom VoIP phone number. The inbound (`sipConfig`) and outbound\r\n(`sipTrunkConfig`) configurations are independent and optional: provide one, the other, both, or none." application/*+json: schema: allOf: - $ref: '#/components/schemas/CustomVoipNumberRequestApi' description: "Data used to create a custom VoIP phone number. The inbound (`sipConfig`) and outbound\r\n(`sipTrunkConfig`) configurations are independent and optional: provide one, the other, both, or none." responses: '200': description: >- The created custom VoIP phone number, including the SIP domain when inbound is configured. content: text/plain: schema: $ref: '#/components/schemas/ClientPhoneNumberViewApi' application/json: schema: $ref: '#/components/schemas/ClientPhoneNumberViewApi' text/json: schema: $ref: '#/components/schemas/ClientPhoneNumberViewApi' '400': description: Error content: text/plain: schema: $ref: '#/components/schemas/ValidationProblemDetails' application/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' text/json: schema: $ref: '#/components/schemas/ValidationProblemDetails' components: schemas: CustomVoipNumberRequestApi: required: - number type: object properties: number: minLength: 1 type: string description: >- The phone number, preferably in E.164 format (for example `+14155550123`). Max 100 characters. displayName: type: string description: >- Optional display name of the phone number (max 100 characters). When omitted, the raw number is displayed instead. nullable: true sipConfig: allOf: - $ref: '#/components/schemas/SIPConfigApi' description: >- Optional inbound SIP configuration. Provide it to receive calls on this number: a SIP domain is then generated and returned in `sipConfig.domain`. nullable: true sipTrunkConfig: allOf: - $ref: '#/components/schemas/SIPTrunkConfigApi' description: >- Optional outbound SIP trunk configuration. Provide it to place calls from this number. nullable: true additionalProperties: false description: "Data used to create a custom VoIP phone number. The inbound (`sipConfig`) and outbound\r\n(`sipTrunkConfig`) configurations are independent and optional: provide one, the other, both, or none." ClientPhoneNumberViewApi: type: object properties: id: type: string description: The unique identifier of the phone number. nullable: true number: type: string description: >- The phone number, in E.164 format (a custom VoIP number is returned as it was entered). nullable: true displayName: type: string description: >- The display name of the phone number. Falls back to the raw number when no display name is set. nullable: true direction: allOf: - $ref: '#/components/schemas/ePhoneNumberDirection' description: |+ Phone number direction (supported call capabilities). - InboundOutbound: Supports both inbound and outbound calls. - Inbound: Supports inbound calls only. - Outbound: Supports outbound calls only. - NotSet: Direction is not set. `1 - InboundOutbound` `2 - Inbound` `3 - Outbound` `10 - NotSet` type: allOf: - $ref: '#/components/schemas/ePhoneNumberTypeApi' description: >+ Indicates how the phone number is provisioned and connected to NLPearl. - NLPearlDefault: a shared default number provided by NLPearl. - NLPearl: a number purchased and managed for you by NLPearl. - Twilio: a number from your own Twilio account that you connected. - CustomVoip: a custom VoIP number you connect over SIP. - Undefined: the type could not be determined. `1 - NLPearlDefault` `2 - NLPearl` `3 - Twilio` `4 - CustomVoip` `99 - Undefined` sipConfig: allOf: - $ref: '#/components/schemas/SIPConfigApiView' description: >- The inbound SIP configuration. Present only for custom VoIP numbers that have inbound configured; passwords are never returned. nullable: true sipTrunkConfig: allOf: - $ref: '#/components/schemas/SIPTrunkConfigApiView' description: >- The outbound SIP trunk configuration. Present only for custom VoIP numbers that have outbound configured; passwords are never returned. nullable: true additionalProperties: false description: "A phone number of the account as exposed by the API. For custom VoIP numbers it also carries the\r\nconfigured inbound and/or outbound SIP setup (passwords are never returned)." ValidationProblemDetails: type: object properties: type: type: string nullable: true title: type: string nullable: true status: type: integer format: int32 nullable: true detail: type: string nullable: true instance: type: string nullable: true errors: type: object additionalProperties: type: array items: type: string nullable: true additionalProperties: {} SIPConfigApi: required: - authMethod type: object properties: authMethod: allOf: - $ref: '#/components/schemas/SipAuthMethodApi' description: >- How incoming SIP calls are authenticated (username/password or IP allowlist). Exactly one method is required. isTLS: type: boolean description: Whether inbound SIP traffic uses TLS. additionalProperties: false description: "Inbound SIP configuration of a custom VoIP number: how incoming calls are authenticated and secured.\r\nThe SIP domain is generated by NLPearl and is not provided by the client." SIPTrunkConfigApi: required: - from - sipTrunk type: object properties: sipTrunk: minLength: 1 type: string description: >- The host of your SIP trunk (IP address or domain) where outbound calls are sent. edge: type: string description: >- Optional edge location through which outbound calls are sent to your SIP trunk. Allowed values: `ashburn`, `umatilla`, `dublin`, `frankfurt`, `sao-paulo`, `singapore`, `sydney`, `tokyo`. nullable: true authMethod: allOf: - $ref: '#/components/schemas/SipTrunkAuthMethodApi' description: >- Optional authentication for the outbound trunk (credentials or custom SIP headers). nullable: true isTLS: type: boolean description: Whether outbound SIP traffic uses TLS. from: minLength: 1 type: string description: >- The user part of the originating SIP URI (the caller identity presented on outbound calls). Max 50 characters: only letters, digits and `+ - _ .`. isSipRefer: type: boolean description: Whether call transfers are performed using SIP REFER. additionalProperties: false description: "Outbound SIP trunk configuration of a custom VoIP number: where and how outgoing calls are placed\r\nthrough your own SIP trunk." ePhoneNumberDirection: type: integer description: |+ Phone number direction (supported call capabilities). - InboundOutbound: Supports both inbound and outbound calls. - Inbound: Supports inbound calls only. - Outbound: Supports outbound calls only. - NotSet: Direction is not set. `1 - InboundOutbound` `2 - Inbound` `3 - Outbound` `10 - NotSet` format: int32 ePhoneNumberTypeApi: type: integer description: |+ Indicates how the phone number is provisioned and connected to NLPearl. - NLPearlDefault: a shared default number provided by NLPearl. - NLPearl: a number purchased and managed for you by NLPearl. - Twilio: a number from your own Twilio account that you connected. - CustomVoip: a custom VoIP number you connect over SIP. - Undefined: the type could not be determined. `1 - NLPearlDefault` `2 - NLPearl` `3 - Twilio` `4 - CustomVoip` `99 - Undefined` format: int32 SIPConfigApiView: type: object properties: domain: type: string description: >- The SIP domain to which inbound traffic for this number must be sent (e.g. `{id}-nlpearl-ai.sip.twilio.com`). nullable: true isTLS: type: boolean description: Whether inbound SIP traffic uses TLS. authMethod: allOf: - $ref: '#/components/schemas/SipAuthMethodApiView' description: >- How incoming calls are authenticated (username or IP allowlist). Passwords are never returned. nullable: true additionalProperties: false description: >- Inbound SIP configuration as returned by the API for a custom VoIP number. SIPTrunkConfigApiView: type: object properties: sipTrunk: type: string description: >- The host of your SIP trunk (IP address or domain) where outbound calls are sent. nullable: true edge: type: string description: >- The edge location through which outbound calls are sent to your SIP trunk, if set. nullable: true isTLS: type: boolean description: Whether outbound SIP traffic uses TLS. from: type: string description: >- The user part of the originating SIP URI (the caller identity presented on outbound calls). nullable: true isSipRefer: type: boolean description: Whether call transfers are performed using SIP REFER. authMethod: allOf: - $ref: '#/components/schemas/SipTrunkAuthMethodApiView' description: >- The outbound trunk authentication (username or custom headers). Passwords are never returned. nullable: true additionalProperties: false description: >- Outbound SIP trunk configuration as returned by the API for a custom VoIP number. SipAuthMethodApi: type: object properties: userNamePassword: allOf: - $ref: '#/components/schemas/UserNamePasswordApi' description: >- SIP credentials accepted for inbound calls. The username must be 2 to 32 letters or digits; the password 12 to 72 letters and digits, with at least one uppercase letter, one lowercase letter and one digit. Cannot be combined with `ips`. nullable: true ips: type: array items: type: string description: >- Allowlist of source IP addresses authorized to send inbound calls: 1 to 100 distinct IPv4 addresses, written without leading zeros (for example `203.0.113.10`). Cannot be combined with `userNamePassword`. nullable: true additionalProperties: false description: "Inbound SIP authentication: either a username/password or an allowlist of source IP addresses.\r\nExactly one method must be provided." SipTrunkAuthMethodApi: type: object properties: userNamePassword: allOf: - $ref: '#/components/schemas/UserNamePasswordApi' description: >- SIP credentials sent when placing outbound calls (username and password of up to 200 characters each). Cannot be combined with `headers`. nullable: true headers: type: object additionalProperties: type: string description: >- Custom SIP headers added to the outbound INVITE, up to 15. Each name must start with `X-` and contain only letters, digits and hyphens (max 100 characters). Each value is required and may contain only letters, digits and `- _ . ! ~ * ' ( ) [ ] / : + $` (max 500 characters). Names and values together, counting 2 extra characters per header, must stay under 1024 characters. Cannot be combined with `userNamePassword`. nullable: true additionalProperties: false description: >- Outbound SIP trunk authentication: either credentials or custom SIP headers, not both. SipAuthMethodApiView: type: object properties: userNamePassword: allOf: - $ref: '#/components/schemas/UserNamePasswordApiView' description: >- The SIP credentials accepted for inbound calls. Only the username is returned. nullable: true ips: type: array items: type: string description: Allowlist of source IP addresses authorized to send inbound calls. nullable: true additionalProperties: false description: >- Inbound SIP authentication as returned by the API. Passwords are never included. SipTrunkAuthMethodApiView: type: object properties: userNamePassword: allOf: - $ref: '#/components/schemas/UserNamePasswordApiView' description: >- The SIP credentials sent when placing outbound calls. Only the username is returned. nullable: true headers: type: object additionalProperties: type: string description: Custom SIP headers added to the outbound INVITE. nullable: true additionalProperties: false description: >- Outbound SIP trunk authentication as returned by the API. Passwords are never included. UserNamePasswordApi: required: - password - username type: object properties: username: minLength: 1 type: string description: The SIP username. password: minLength: 1 type: string description: >- The SIP password. Write-only: it is accepted on input but never returned in responses. additionalProperties: false description: >- A SIP username and password pair. The password is write-only and is never returned in responses. UserNamePasswordApiView: type: object properties: username: type: string description: The SIP username. nullable: true additionalProperties: false description: >- A SIP username as returned by the API. The password is write-only and is never returned. securitySchemes: bearer_auth: type: http description: >- Specify the authorization token. For more information, check out the [Authorization Guide](/api-reference/authorization). scheme: bearer oauth2_client_credentials: type: oauth2 description: >- OAuth2 client_credentials grant. Use the Id of an OAuth API key as `client_id` and its one-time secret as `client_secret`. flows: clientCredentials: tokenUrl: /oauth/token scopes: pearls:read: List and view Pearls pearls:write: >- Create and update Pearls (settings, conversation flows, voices); implies pearls:read pearls:moderate: Run/pause Pearls and reset customer memory; implies pearls:read pearls:analytics: Read Pearl analytics; implies pearls:read pearls:leads: Manage and read outbound leads; implies pearls:read pearls:calls: >- Read calls and recordings, make and delete calls; implies pearls:read account:phone_numbers: >- Read account phone numbers and text channels, manage custom VoIP numbers, import Twilio numbers and delete phone numbers account:users: Read account users account:advanced: Manage advanced account settings (blacklist) account:billing: Read account information and credit balance account:audit_log: Read the audit log tts: Synthesise speech and clone voices ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.