> ## Documentation Index > Fetch the complete documentation index at: https://docs.support.onclarity.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a phone number > Adds a number to the project. It belongs either to a carrier (`provider`) or to one of your inbound SIP trunks (`sip_trunk_id`), never both, and a number can be in only one project. Adding a number to an active inbound SIP trunk updates the trunk so it takes calls on the new number. Needs the publish permission, which organization API keys carry. ## OpenAPI ````yaml api-reference/voice-openapi.json POST /v1/projects/{projectId}/phone-numbers openapi: 3.0.3 info: title: Clarity Voice API version: '1.0' description: >- Voice agents and their tools, outbound calls, conversations, campaigns, telephony, and evals. servers: - url: https://voice-api.onclarity.com security: - organizationApiKey: [] tags: - name: Projects description: >- The projects your organization owns. Every other resource lives in a project. - name: Agents description: Create, configure, version and publish voice agents. - name: Outbound calls description: Have a published agent phone a number now. - name: Conversations description: >- One record per call session, with its calls, recordings, transcripts and artifacts. - name: Calls description: The calls of a project, with their status, direction, timing and outcome. - name: Campaigns description: Outbound calling campaigns that phone a list of numbers on a schedule. - name: Eval suites description: >- Reusable sets of eval scenarios and test cases to measure an agent against. - name: Eval judges description: The LLM judges that score eval calls against your test cases. - name: Eval scenarios description: The simulated-caller scenarios of your eval suites. - name: Eval test cases description: The checks a judge applies to each eval call. - name: Eval submissions description: Run an eval suite against an agent and read the verdicts. - name: Phone numbers description: >- The phone numbers of a project, where their calls come from, and how agents call out from them. - name: Inbound SIP trunks description: Bring calls from your own SIP infrastructure to Clarity agents. - name: Outbound SIP trunks description: >- The SIP endpoints Clarity dials through for outbound calls from your numbers. - name: Tools description: The tools agents call during a conversation, and which agents use them. paths: /v1/projects/{projectId}/phone-numbers: parameters: - $ref: '#/components/parameters/ProjectIdPath' post: tags: - Phone numbers summary: Create a phone number description: >- Adds a number to the project. It belongs either to a carrier (`provider`) or to one of your inbound SIP trunks (`sip_trunk_id`), never both, and a number can be in only one project. Adding a number to an active inbound SIP trunk updates the trunk so it takes calls on the new number. Needs the publish permission, which organization API keys carry. operationId: createPhoneNumber requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePhoneNumberRequest' example: e164: '14155550123' sip_trunk_id: 2d4f6a8c-0e1b-4c3d-8e5f-7a9b1c2d3e4f voice_inbound: true voice_outbound: true outbound_trunk_ids: - 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d responses: '201': description: >- The number was created. `outbound_agents` and `outbound_agents_inherited` are always empty here; read the number to see which agents present it. content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse' example: phone_number: id: 7b0e2c4a-1f3d-4e8a-9c21-5d6f7a8b9c01 project_id: 3f6c1a52-8d0e-4b8f-9a51-2c7d4e0b9f13 e164: '14155550123' provider: null voice_inbound: true voice_outbound: true sip_trunk_id: 2d4f6a8c-0e1b-4c3d-8e5f-7a9b1c2d3e4f outbound_trunk_ids: - 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d outbound_agents: [] outbound_agents_inherited: [] max_calls_per_second: 1 abuse_protection_exempt: false max_calls_per_second_updated_by: null max_calls_per_second_updated_at: null created_at: >- Wed Nov 11 2026 09:30:00 GMT+0000 (Coordinated Universal Time) updated_at: >- Wed Nov 11 2026 09:30:00 GMT+0000 (Coordinated Universal Time) '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Your credential lacks the publish permission (`code: PUBLISH_CAPABILITY_REQUIRED`), or `max_calls_per_second` is above 5, which only Clarity support can set. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: publish_capability_required code: PUBLISH_CAPABILITY_REQUIRED '404': description: The project does not exist or your key cannot reach it. content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: The number is already registered, in this project or another one. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Phone number 14155550123 is already registered '422': description: >- The body failed validation (`issues` locates each problem): for example both or neither of `provider` and `sip_trunk_id`, or an `e164` with a `+`. Also answered when `sip_trunk_id` is not an inbound SIP trunk of this project, when an outbound trunk is unknown or inactive, or when `outbound_trunk_ids` is set without `voice_outbound: true`. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: error: >- provider: A phone number cannot belong to both a provider and a SIP trunk issues: - path: provider code: custom message: >- A phone number cannot belong to both a provider and a SIP trunk '502': description: >- The number was saved, but its inbound SIP trunk could not be updated to take calls on it. Read the number back before you retry. content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id schemas: CreatePhoneNumberRequest: type: object description: >- Send exactly one of `provider` and `sip_trunk_id`. Fields not listed here are ignored. required: - e164 properties: e164: type: string pattern: ^\d{7,15}$ description: >- The number in E.164 form as 7 to 15 digits, with no `+`: `14155550123`. It must not be registered in any project yet. It cannot be changed later. provider: type: string nullable: true enum: - twilio - didww - null description: >- The carrier the number comes from. Leave it out (or `null`) for a number on an inbound SIP trunk. sip_trunk_id: type: string nullable: true minLength: 1 description: >- An inbound SIP trunk of this project the number belongs to. Leave it out (or `null`) for a carrier number. voice_inbound: type: boolean default: false description: The number takes inbound calls. voice_outbound: type: boolean default: false description: >- Agents may place outbound calls from the number. Required for `outbound_trunk_ids`. outbound_trunk_ids: type: array maxItems: 5 uniqueItems: true items: type: string minLength: 1 description: >- Active outbound SIP trunks of this project for calls from this number, primary first, then up to four fallbacks. Needs `voice_outbound: true`. max_calls_per_second: type: integer minimum: 1 maximum: 100 description: >- The most inbound calls per second the number accepts. Default 1. Values above 5 are set by Clarity support (403 otherwise). abuse_protection_exempt: type: boolean description: >- Leave the number out of the project's inbound abuse protection. Default false. PhoneNumberResponse: type: object required: - phone_number properties: phone_number: $ref: '#/components/schemas/PhoneNumber' max_calls_per_second_self_serve_max: type: integer description: >- Returned when you read a number: the highest `max_calls_per_second` you can set yourself. Higher limits are set by Clarity support. Error: type: object required: - error additionalProperties: true properties: error: type: string description: Error message code: type: string description: >- A stable machine-readable reason, present on the refusals a client may branch on. Among them: `PUBLISH_CAPABILITY_REQUIRED` (403, the credential may not change what is live), `AGENT_NOT_PUBLISHED` (409, the agent has no published version yet), `AGENT_TYPE_NOT_DISPATCHABLE` (422, a Voice Assist agent named where an agent must place a call or answer one itself — a campaign, an outbound caller ID, a dispatched call, an eval; a number's inbound dispatch rule accepts one; the body carries `agent_type` and `agent_id`), `ASSIST_FLEET_NOT_CONFIGURED` (422 on a dispatch rule naming a Voice Assist agent in a project whose LiveKit has no Voice Assist listener), `NOT_APPLICABLE_TO_AGENT_TYPE` (422, a voice-only setting written on a Voice Assist agent), `AGENT_TYPE_BOUNDARY` (409), `AGENT_TYPE_NOT_SUPPORTED` (400), `INVALID_CUSTOMER_TIMEZONE` (400, `customer_timezone` is not a time zone name; the body carries the value), `VOICE_ASSISTANT_REQUIRED` (403, the organization is not licensed for Voice Assist), `ORGANIZATION_UNAVAILABLE` (503), `REGION_PROFILE_CONFLICT` (503), `LLM_SERVICE_TIER_UNAVAILABLE` (422, an agent's processing speed is not offered by its model or not enabled for the organization; `reason` says which) and `AUTH_UPSTREAM_UNAVAILABLE` (503 on any endpoint, with `Retry-After`: the credential could not be checked right now; it was not rejected and the request was not carried out). ValidationError: type: object description: >- A validation failure. `error` is a human-readable summary; `issues` (request validation) or `details` (agent configuration validation) locate each problem. A refused processing speed answers with `error` and `code` both `LLM_SERVICE_TIER_UNAVAILABLE` and the fields `path`, `reason`, `tier`, `provider` and `model`. properties: error: type: string code: type: string description: >- A machine-readable code, on the failures that carry one: `LLM_SERVICE_TIER_UNAVAILABLE` for a processing speed the agent cannot use. message: type: string path: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: the refused field, `agent_model_config.llm_service_tier`. reason: type: string enum: - model - organization description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`: `model` when the language model does not offer the speed (or the value is not a speed at all), `organization` when your organization does not have it. tier: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the refused value, as text. provider: type: string description: >- With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model provider. model: type: string description: With `LLM_SERVICE_TIER_UNAVAILABLE`, the agent's language model. issues: type: array items: type: object properties: path: type: string description: Dotted path of the offending field code: type: string message: type: string details: type: array items: {} PhoneNumber: type: object description: >- A phone number of the project. Its inbound calls come from a carrier (`provider`) or from one of your inbound SIP trunks (`sip_trunk_id`), never both; with neither, the number is unassigned. required: - id - project_id - e164 - provider - voice_inbound - voice_outbound - sip_trunk_id - outbound_trunk_ids - outbound_agents - outbound_agents_inherited - max_calls_per_second - abuse_protection_exempt - max_calls_per_second_updated_by - max_calls_per_second_updated_at - created_at - updated_at properties: id: type: string description: Phone number id. project_id: type: string e164: type: string description: >- The number in E.164 form as digits only, with no `+`: `14155550123` for +1 415 555 0123. The response wraps the record in `phone_number`, which is the object, not the number. provider: type: string nullable: true enum: - twilio - didww - null description: >- The carrier the number comes from, or `null` when it comes from an inbound SIP trunk or is unassigned. voice_inbound: type: boolean description: The number takes inbound calls. voice_outbound: type: boolean description: Agents may place outbound calls from the number. sip_trunk_id: type: string nullable: true description: >- The inbound SIP trunk the number belongs to, or `null` when it comes from a carrier or is unassigned. outbound_trunk_ids: type: array items: type: string description: >- Outbound SIP trunks for calls from this number, in order: the first is the primary route, the others are fallbacks tried in turn when the carrier answers with a server error. Empty unless set. outbound_agents: type: array description: >- Agents that present this number as their caller ID on outbound calls. items: $ref: '#/components/schemas/PhoneNumberAgentRef' outbound_agents_inherited: type: array description: >- Agents that present this number on outbound calls without being assigned it: they have no outbound caller ID of their own, and this is the number their inbound calls arrive on. items: $ref: '#/components/schemas/PhoneNumberAgentRef' max_calls_per_second: type: integer minimum: 1 maximum: 100 description: The most inbound calls per second the number accepts. Default 1. abuse_protection_exempt: type: boolean description: >- The project's inbound abuse protection does not apply to this number. max_calls_per_second_updated_by: type: string nullable: true description: >- Who last changed `max_calls_per_second`, or `null` if it was never changed. max_calls_per_second_updated_at: type: string nullable: true description: >- When `max_calls_per_second` was last changed, or `null`. A date string, as `created_at`. created_at: type: string description: >- When the number was added. A date string such as `Mon Nov 09 2026 14:02:11 GMT+0000 (Coordinated Universal Time)`, not ISO 8601. updated_at: type: string description: When the number was last changed. A date string, as `created_at`. PhoneNumberAgentRef: type: object required: - id - name properties: id: type: string description: Agent id. name: type: string responses: Unauthorized: description: >- No credential was sent, or the API key is invalid or revoked. A key that could not be checked at all answers 503 `AUTH_UPSTREAM_UNAVAILABLE` instead (see Errors). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: Invalid or revoked token securitySchemes: organizationApiKey: type: http scheme: bearer description: >- Your organization API key (it starts with `anek_org_`). The same key works on the Voice API and the Support API. See [Authentication](/authentication). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.