> ## Documentation Index > Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt > Use this file to discover all available pages before exploring further. # Add custom carrier > Add a custom SIP carrier (Bring Your Own Carrier). **Trunk Types:** - `static_ip` - IP-based authentication (default). Your carrier whitelists TopCalls SBC IP. - `auth` - Credential-based inbound authentication. Requires `inbound_auth` object. - `reg` - SIP registration. Requires `registration` object. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/phone-numbers/carriers openapi: 3.0.3 info: title: TopCalls Voice API description: > TopCalls Voice Gateway API for creating and managing AI-powered phone calls. ## Authentication All API requests require authentication. Include your API key in the `Authorization` header: ``` Authorization: Bearer tc_live_xxxxx ``` ## Rate Limits Direct call creation via `POST /v1/calls` is limited to your account's `max_calls_per_minute` setting (default: 20) per minute. Exceeding it returns `429 Too Many Requests` with a `Retry-After` header. All endpoints are additionally subject to a flat limit of 120 requests per minute per account (all methods). On a `429`, wait for the number of seconds in the `Retry-After` header, then retry the same request. For automated clients, back off progressively on repeated `429`s. Limits are per account and are shared by all API keys. ## Error Format All errors follow RFC 7807 Problem+JSON format: ```json { "type": "https://api.topcalls.ai/errors/insufficient_quota", "title": "Insufficient Quota", "status": 402, "detail": "You need 5 minutes but have 3.5 remaining" } ``` version: 1.0.0 contact: name: TopCalls Support url: https://topcalls.ai license: name: Proprietary servers: - url: https://api.topcalls.ai description: Production security: [] tags: - name: Calls description: Create and manage phone calls - name: Phone Numbers description: Manage phone numbers and carriers - name: Account description: Account information and usage - name: Webhooks description: Webhook configuration and events - name: Configuration description: Available AI models, voices, and platform capabilities paths: /v1/phone-numbers/carriers: post: tags: - Phone Numbers summary: Add custom carrier description: > Add a custom SIP carrier (Bring Your Own Carrier). **Trunk Types:** - `static_ip` - IP-based authentication (default). Your carrier whitelists TopCalls SBC IP. - `auth` - Credential-based inbound authentication. Requires `inbound_auth` object. - `reg` - SIP registration. Requires `registration` object. operationId: addCarrier parameters: - $ref: '#/components/parameters/IdempotencyKeyHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AddCarrierRequest' examples: static_ip: summary: Static IP carrier value: carrier_name: My VoIP Provider trunk_type: static_ip sip_gateway: ipv4: 203.0.113.10 port: 5060 inbound: true outbound: true registration: summary: Registration-based carrier value: carrier_name: My VoIP Provider trunk_type: reg sip_gateway: ipv4: sip.myprovider.com port: 5060 registration: register_username: myuser register_password: mypassword register_sip_realm: sip.myprovider.com responses: '201': description: Carrier created successfully content: application/json: schema: $ref: '#/components/schemas/AddCarrierResponse' '400': description: Invalid request content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/IdempotencyConflict' security: - bearerAuth: [] components: parameters: IdempotencyKeyHeader: name: Idempotency-Key in: header required: false description: | Optional client-supplied idempotency key. When present, the gateway caches the response for 24 hours and returns the same response on retried requests with the same key (account-scoped). Safe for retries on network blips. Format: 8-255 ASCII characters from `[A-Za-z0-9_-]`. schema: type: string minLength: 8 maxLength: 255 pattern: ^[A-Za-z0-9_-]+$ example: a1b2c3d4-e5f6-7890-abcd-ef0123456789 schemas: AddCarrierRequest: type: object required: - carrier_name - sip_gateway properties: carrier_name: type: string minLength: 1 maxLength: 100 description: Display name for the carrier trunk_type: type: string enum: - static_ip - auth - reg default: static_ip description: | SIP trunk authentication type: - `static_ip` - IP-based authentication (default) - `auth` - Credential-based inbound authentication - `reg` - SIP registration sip_gateway: $ref: '#/components/schemas/SipGateway' registration: $ref: '#/components/schemas/Registration' description: Required when trunk_type is 'reg' inbound_auth: $ref: '#/components/schemas/InboundAuth' description: Required when trunk_type is 'auth' AddCarrierResponse: type: object properties: id: type: string format: uuid description: Carrier record ID account_id: type: string format: uuid description: Account UUID voip_carrier_sid: type: string format: uuid description: Carrier UUID (for use in phone number provisioning) carrier_name: type: string description: Display name trunk_type: type: string enum: - static_ip - auth - reg created_at: type: string format: date-time Problem: type: object required: - status - title properties: type: type: string format: uri description: Error type URI title: type: string description: Error title status: type: integer description: HTTP status code detail: type: string description: Human-readable error detail code: type: string description: > Machine-readable error code for programmatic handling. Present on errors that carry a stable identifier (e.g. `PROMPT_SAFETY_FRAUD`, `job_not_found`, `too_many_ids`, `no_matches`). Distinct from the per-field `errors[].code` used for validation failures. Scenario- specific — see each endpoint's response examples for the exact value. instance: type: string format: uuid description: Request instance ID errors: type: array description: Validation errors (for 400 responses) items: type: object properties: path: type: string description: Field path (e.g., "phone_number", "metadata.from_number") message: type: string description: Error message code: type: string description: Error code (e.g., "invalid_string", "custom") details: type: string description: Additional error details (for provider errors) SipGateway: type: object description: > SIP gateway endpoint. Inbound gateways (`inbound: true`) must use IPv4 address; hostnames are rejected by the validator because the telephony platform requires IP for SBC matching. required: - ipv4 properties: ipv4: type: string description: SIP gateway IP address (or hostname for outbound-only gateways) example: 203.0.113.10 port: type: integer minimum: 1 maximum: 65535 default: 5060 description: SIP port inbound: type: boolean default: true description: Allow inbound calls outbound: type: boolean default: true description: Allow outbound calls Registration: type: object required: - register_username - register_password - register_sip_realm properties: register_username: type: string description: SIP registration username register_password: type: string description: SIP registration password register_sip_realm: type: string description: SIP realm for registration InboundAuth: type: object required: - username - password properties: username: type: string description: Inbound authentication username password: type: string description: Inbound authentication password responses: Unauthorized: description: Unauthorized (missing or invalid API key) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 401 title: Unauthorized detail: Invalid or missing API key Forbidden: description: Forbidden (missing required scope) content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 403 title: Forbidden detail: 'Missing required scope: calls:write' IdempotencyConflict: description: | Another request with the same Idempotency-Key is currently being processed. Retry once it completes. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' example: status: 409 title: 'Conflict: request in-flight' detail: >- Another request with the same Idempotency-Key is currently being processed. securitySchemes: bearerAuth: type: http scheme: bearer description: | Use `Authorization: Bearer tc_live_xxxxx` ````