> ## Documentation Index > Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a SIP trunk > Registers your own SIP provider: creates a platform inbound + outbound trunk pair. Supports DID or Extension (`trunk_kind`), calling-number format, transport, and advanced options (secure trunking, headers, codecs). Use this to bring your own numbers instead of buying from the marketplace. See [BYO SIP trunk](/telephony/sip-trunks). **Required scope:** `sip_trunks:write` (keys without scope restrictions have full access). ## OpenAPI ````yaml /api-reference/openapi.json post /sip-trunks openapi: 3.1.0 info: title: OurAiCalling API version: 1.0.0 description: >- REST API for OurAiCalling. Authenticate with an API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`) as a Bearer token. Every response uses a consistent envelope: `{ "data": ... , "meta": { ... } }` on success and `{ "error": { "code", "message" } }` on failure. List endpoints paginate with `?limit=` (default 50, max 200) and `?offset=`; `meta.pagination.total` carries the total match count. Everything documented here is also exposed as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials and permission model. servers: - url: https://app.famulor.io/api/v1 description: Hosted platform. - url: https://{domain}/api/v1 description: White-label tenant domain — same paths, tenant branding. variables: domain: default: app.famulor.io description: Your white-label tenant domain. security: - bearerAuth: [] tags: - name: Account description: Self-inspection of the calling credential. - name: Migrations description: Preview and import data from supported legacy platforms. - name: Assistants description: Create and manage voice assistants. - name: Tools description: >- Reusable tools (HTTP APIs and external MCP servers) assistants can call mid-conversation. - name: Voices description: Browse the text-to-speech voice library. - name: Calls description: Start outbound calls and read call history, transcripts and recordings. - name: History description: Unified conversation history across calls, messaging and assistant emails. - name: Campaigns description: Outbound calling campaigns with a compliant power dialer. - name: Leads description: Manage Audience contacts across campaigns, channels and Call QA metrics. - name: Segments description: >- Saved, dynamic lead filters — reusable audience definitions used for Audience search and campaign lead assignment. - name: Suppression description: Cross-channel marketing opt-outs and active workspace suppression records. - name: Callbacks description: >- Scheduled callbacks booked by the Schedule callback tool across voice, chat, and email. - name: Phone Numbers description: Marketplace numbers and customer-provided numbers. - name: SIP Trunks description: Bring your own SIP provider and numbers. - name: Carrier Connections description: Connect a supported carrier account and import its existing phone numbers. - name: Knowledge Bases description: RAG knowledge bases and documents for assistants. - name: Settings description: Workspace-level settings such as caller-memory defaults. - name: Billing description: Balance and minutes ledger of the key owner. - name: Automations description: >- Native workspace automations — list, create, update, trigger. Plan gate: automation_platform. - name: Integrations description: >- Calendar integrations (Cal.com, Calendly, Acuity Scheduling, Google Calendar, Outlook, native booking engine). Assign them to assistants to provide availability and booking tools, plus provider-supported appointment lookup, cancellation, and rescheduling. - name: Bookings description: >- Native booking engine — event types with weekly availability, public booking pages at /book/{workspace}/{slug}, and the bookings they produce. - name: Dashboards description: >- Custom analytics dashboards, reusable widgets, and tenant-scoped performance analytics. Requires the custom_dashboards plan feature. - name: Catalog description: >- Read-only platform catalogs — available models, supported assistant languages, and prompt templates. - name: Simulations description: Assistant simulation tests (plan-gated). - name: Versions description: Assistant configuration version history. - name: Caller IDs description: Outbound caller ID verification. - name: Widgets description: Web widget connectors. - name: Messaging description: >- Telegram, Slack, and Messenger text bots linked to assistants (Chat SDK). Includes conversation delay, inactivity end, and conversation-ended webhooks. - name: QA description: Cohort AI Quality Assurance runs over call transcripts. - name: White Label description: >- Manage the customers of your white-label workspace on their behalf — list, register, mint access tokens, log in, log out, and transfer credits. Available to reseller workspaces with white-label access, and to platform admins (scoped to direct platform customers). Requires `platform:read` / `platform:write`. - name: API Keys description: >- Self-service API keys for the calling workspace. A key can only mint further keys with a scope subset of its own. - name: SMS description: Outbound SMS from workspace phone numbers. paths: /sip-trunks: post: tags: - SIP Trunks summary: Create a SIP trunk description: >- Registers your own SIP provider: creates a platform inbound + outbound trunk pair. Supports DID or Extension (`trunk_kind`), calling-number format, transport, and advanced options (secure trunking, headers, codecs). Use this to bring your own numbers instead of buying from the marketplace. See [BYO SIP trunk](/telephony/sip-trunks). **Required scope:** `sip_trunks:write` (keys without scope restrictions have full access). operationId: createSipTrunk requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SipTrunkCreate' example: name: My SIP provider sip_address: sip.example-provider.com numbers: - '+4930123456' auth_username: acme auth_password: s3cret responses: '201': description: The created SIP trunk (sanitized). content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SipTrunk' example: data: id: st1b2c3d-0000-4000-8000-000000000050 name: My SIP provider provider: custom sip_address: sip.example-provider.com auth_username: acme numbers: - '+4930123456' metadata: {} created_at: '2026-06-01T12:00:00Z' updated_at: '2026-06-01T12:00:00Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' components: schemas: SipTrunkCreate: type: object required: - name - sip_address properties: name: type: string sip_address: type: string description: >- Provider termination host, e.g. `sip.provider.com` (no `sip:` prefix, no port). numbers: type: array items: type: string maxItems: 1 description: >- DID: one E.164 required. Extension: optional primary (E.164 or national digits without country code). Omit or empty for extension receive-only. trunk_kind: type: string enum: - did - extension default: did provider: type: string enum: - twilio - custom default: custom auth_username: type: string auth_password: type: string description: Stored server-side; never returned by the API. inbound_auth_username: type: string inbound_auth_password: type: string description: Stored server-side; never returned by the API. credential_mode: type: string enum: - shared - separate default: shared outbound_auth_mode: type: string enum: - credentials - none default: credentials transport: type: string enum: - auto - udp - tcp - tls default: auto calling_number_format: type: string enum: - e164_plus - e164_no_plus - national default: e164_plus destination_country: type: string description: >- ISO-3166 alpha-2 for outbound region pinning, or empty for automatic. secure_trunking: type: boolean default: false description: TLS signaling + SRTP media. media_encryption: type: string enum: - allow - require - disable outbound_headers: type: object additionalProperties: type: string description: Custom outbound INVITE headers (max 10). inbound_headers: type: object additionalProperties: type: string headers_to_attributes: type: object additionalProperties: type: string outbound_headers_to_attributes: type: object additionalProperties: type: string include_headers: type: string enum: - none - x - all default: none media_codecs: type: array items: type: string enum: - PCMU - PCMA - G722 - AMR-WB only_listed_codecs: type: boolean default: false media_timeout_sec: type: integer minimum: 1 maximum: 3600 ringing_timeout_sec: type: integer minimum: 5 maximum: 600 metadata: type: object additionalProperties: true description: >- May include inbound auth mode (`inbound_auth`, `allowed_addresses`) and region hints. SipTrunk: type: object description: >- SIP trunk (sanitized — `auth_password` and `inbound_auth_password` are never returned). properties: id: type: string format: uuid name: type: string provider: type: string enum: - twilio - custom sip_address: type: - string - 'null' description: Provider termination host (no `sip:` prefix, no port). auth_username: type: - string - 'null' inbound_auth_username: type: - string - 'null' numbers: type: array items: type: string description: >- Primary number(s) on this trunk. DID: one E.164. Extension: optional E.164 or national digits without country code (0–1 entry). trunk_kind: type: string enum: - did - extension description: >- `did` = one phone number on the trunk. `extension` = accept any inbound DID; optional primary for outbound caller ID. credential_mode: type: string enum: - shared - separate outbound_auth_mode: type: string enum: - credentials - none transport: type: string enum: - auto - udp - tcp - tls calling_number_format: type: string enum: - e164_plus - e164_no_plus - national description: How the FROM number is formatted toward the carrier. secure_trunking: type: boolean media_encryption: type: string enum: - allow - require - disable outbound_headers: type: object additionalProperties: type: string description: Custom X-* headers on outbound INVITEs. inbound_headers: type: object additionalProperties: type: string headers_to_attributes: type: object additionalProperties: type: string outbound_headers_to_attributes: type: object additionalProperties: type: string include_headers: type: string enum: - none - x - all media_codecs: type: array items: type: string only_listed_codecs: type: boolean media_timeout_sec: type: - integer - 'null' ringing_timeout_sec: type: - integer - 'null' metadata: type: object additionalProperties: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - name - provider - numbers - created_at - updated_at ErrorEnvelope: type: object description: Error envelope returned by every /api/v1 endpoint on failure. required: - error properties: error: type: object required: - code - message properties: code: type: string enum: - unauthorized - forbidden - not_found - invalid_request - rate_limited - conflict - telephony_configuration_error - telephony_unavailable - internal_error description: Stable, machine-readable error code. message: type: string description: Human-readable description of the error. responses: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: invalid_request message: '"to_number" is required (E.164 format, e.g. +4930123456).' Unauthorized: description: Missing, invalid, expired or revoked API key / access token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: Invalid API key. Forbidden: description: >- The API key lacks the required scope, or the plan does not allow this action. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: forbidden message: This API key is missing the required scope "assistants:write". securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: >- API key (`fam_...`, created under **Settings → API Keys**) or an OAuth 2.0 access token (`fam_at_...`). Keys can be restricted to scopes such as `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`, `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`, `settings:write`, `platform:read`, `platform:write`; a `*:write` scope implies the matching `*:read`. Automation and dashboard endpoints also accept the legacy `calls:*` scope. Keys without scope restrictions have full access. ````