Skip to navigation

Add Custom Phone Number

Adds a bring-your-own phone number to an agent in the authenticated workspace and project. Use this to connect a phone number and SIP trunk the user is authorized to manage; it does not purchase a number or place a call. Stores the supplied SIP address and credentials for calls and transfers, and saves any configuration endpoint for calls on this number. The user must configure their SIP trunk to route inbound calls to Phonic. A configured endpoint receives requests during call setup; use only an endpoint the user intends Phonic to contact.

Authentication

AuthorizationBearer

Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.

Path parameters

nameOrIdstringRequired
The name or the ID of the agent.

Headers

X-Sip-AddressstringRequired

SIP address of the user’s SIP trunk. Required. All three SIP headers (X-Sip-Address, X-Sip-Auth-Username, X-Sip-Auth-Password) must be provided. They are used for outbound calls and call transfers from the agent.

X-Sip-Auth-UsernamestringRequired

SIP auth username. Required. All three SIP headers (X-Sip-Address, X-Sip-Auth-Username, X-Sip-Auth-Password) must be provided. They are used for outbound calls and call transfers from the agent.

X-Sip-Auth-PasswordstringRequired

SIP auth password. Required. All three SIP headers (X-Sip-Address, X-Sip-Auth-Username, X-Sip-Auth-Password) must be provided. They are used for outbound calls and call transfers from the agent.

Query parameters

projectstringOptionalDefaults to main

The name of the project containing the agent. Only used when nameOrId is a name.

Request

This endpoint expects an object.
phone_numberstringRequired

The E.164 formatted phone number to add (e.g., “+15551234567”).

configuration_endpointobject or nullOptional

When not null, the agent will call this endpoint to get configuration options for calls on this phone number.

sipobjectOptional

SIP trunk settings for this phone number, applied to both its inbound trunk and the trunk created for each outbound call. Set at creation; remove and re-add the number to change them.

Response

Success response
successboolean

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error