> ## 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 an inbound SIP trunk > Creates a trunk that accepts calls from the IP ranges in `whitelist_cidrs`. A new trunk starts `inactive` and takes no calls: bind at least one phone number to it (create or update a phone number with its `sip_trunk_id`), then activate it. Needs the publish permission, which organization API keys carry. ## OpenAPI ````yaml api-reference/voice-openapi.json POST /v1/projects/{projectId}/telephony/sip-trunks 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}/telephony/sip-trunks: parameters: - $ref: '#/components/parameters/ProjectIdPath' post: tags: - Inbound SIP trunks summary: Create an inbound SIP trunk description: >- Creates a trunk that accepts calls from the IP ranges in `whitelist_cidrs`. A new trunk starts `inactive` and takes no calls: bind at least one phone number to it (create or update a phone number with its `sip_trunk_id`), then activate it. Needs the publish permission, which organization API keys carry. operationId: createTelephonySipTrunk requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateTelephonySipTrunkRequest' example: name: Head office PBX whitelist_cidrs: - 203.0.113.10/32 - 198.51.100.0/24 secure_media: disabled sip_headers: - header: X-Customer-Id identifies_caller: true responses: '201': description: The trunk was created, inactive. content: application/json: schema: $ref: '#/components/schemas/TelephonySipTrunkResponse' example: sip_trunk: id: 2d4f6a8c-0e1b-4c3d-8e5f-7a9b1c2d3e4f project_id: 3f6c1a52-8d0e-4b8f-9a51-2c7d4e0b9f13 name: Head office PBX whitelist_cidrs: - 203.0.113.10/32 - 198.51.100.0/24 allowed_e164s: [] status: inactive secure_media: disabled livekit_trunk_id: null livekit_dispatch_rule_id: null sip_headers: - header: X-Customer-Id identifies_caller: true created_at: >- Mon Nov 09 2026 14:00:02 GMT+0000 (Coordinated Universal Time) updated_at: >- Mon Nov 09 2026 14:00:02 GMT+0000 (Coordinated Universal Time) '401': $ref: '#/components/responses/Unauthorized' '403': description: >- Your credential lacks the publish permission (`code: PUBLISH_CAPABILITY_REQUIRED`). 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: Another inbound SIP trunk in the project has this name. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: SIP trunk "Head office PBX" already exists '422': description: >- The body failed validation: for example an empty or catch-all (`0.0.0.0/0`, `::/0`) IP range, a reserved `X-Clarity-*` header, or two headers that identify the caller. content: application/json: schema: $ref: '#/components/schemas/ValidationError' example: error: 'whitelist_cidrs: invalid or catch-all CIDR' issues: - path: whitelist_cidrs code: custom message: invalid or catch-all CIDR components: parameters: ProjectIdPath: name: projectId in: path required: true schema: type: string description: Project id schemas: CreateTelephonySipTrunkRequest: type: object required: - name - whitelist_cidrs description: >- Fields not listed here are ignored. Phone numbers are not set here: bind a number to the trunk with the number's `sip_trunk_id`. properties: name: type: string minLength: 1 maxLength: 120 description: Unique within the project. whitelist_cidrs: type: array minItems: 1 items: type: string description: >- The IP ranges the trunk accepts calls from, in CIDR notation with a prefix length (`203.0.113.10/32`, `2001:db8::/32`). A catch-all range (`0.0.0.0/0`, `::/0`) is refused. secure_media: type: string enum: - disabled - enabled - required default: disabled description: >- Media encryption (SRTP). `enabled` offers it with a fallback; `required` refuses calls without it. sip_headers: $ref: '#/components/schemas/TelephonySipTrunkHeaders' TelephonySipTrunkResponse: type: object required: - sip_trunk properties: sip_trunk: $ref: '#/components/schemas/TelephonySipTrunk' 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: {} TelephonySipTrunkHeaders: type: array maxItems: 10 description: >- The SIP headers the trunk passes to the agent as `sip.*` call variables. On update, the list you send replaces the stored one. items: $ref: '#/components/schemas/TelephonySipTrunkHeader' TelephonySipTrunk: type: object description: >- An inbound SIP trunk: calls from your SIP infrastructure, from the IP ranges it allows, to the phone numbers bound to it, are answered by Clarity agents. required: - id - project_id - name - whitelist_cidrs - allowed_e164s - status - secure_media - sip_headers - created_at - updated_at properties: id: type: string description: Inbound SIP trunk id. project_id: type: string name: type: string description: Unique within the project. sip_headers: $ref: '#/components/schemas/TelephonySipTrunkHeaders' whitelist_cidrs: type: array items: type: string description: The IP ranges, in CIDR notation, the trunk accepts calls from. allowed_e164s: type: array items: type: string description: >- The numbers bound to the trunk, as E.164 digits with no `+`. Read only: bind a number by setting its `sip_trunk_id`. status: $ref: '#/components/schemas/TelephonySipTrunkStatus' secure_media: type: string enum: - disabled - enabled - required description: >- Media encryption (SRTP). `disabled`: not offered. `enabled`: offered, with a fallback to plain media. `required`: calls without it are refused. livekit_trunk_id: type: string nullable: true description: >- The trunk's id in Clarity's telephony layer, for support conversations. `null` while the trunk is not registered, which is when it is not active. livekit_dispatch_rule_id: type: string nullable: true description: >- The id of the rule that routes the trunk's calls to agents in Clarity's telephony layer, for support conversations. `null` while the trunk is not registered. Activating the trunk creates it. created_at: type: string description: >- When the trunk was created. A date string such as `Mon Nov 09 2026 14:00:02 GMT+0000 (Coordinated Universal Time)`, not ISO 8601. updated_at: type: string description: When the trunk was last changed. A date string, as `created_at`. TelephonySipTrunkHeader: type: object additionalProperties: false required: - header properties: header: type: string pattern: ^[A-Za-z][A-Za-z0-9-]{0,63}$ description: >- The SIP header name, such as `X-Customer-Id`, matched without regard to case. Unique within the trunk; `X-Clarity-*` is reserved. Its value reaches the agent as the call variable `sip.` plus the name in lower case with `-` turned into `_` (`sip.x_customer_id`). identifies_caller: type: boolean default: false description: >- When the header carries a value, the call starts with the caller already verified, as after a successful verification tool. At most one header of a trunk. TelephonySipTrunkStatus: type: string enum: - active - inactive - draft description: >- `active`: the trunk is registered and takes calls. `inactive`: it takes no calls; a new trunk starts here, and a trunk returns here when it is deactivated or loses its last phone number. `draft` is reserved and not set by this API. 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.