> ## Documentation Index > Fetch the complete documentation index at: https://docs.famulor.io/llms.txt > Use this file to discover all available pages before exploring further. # Create a SIP trunk > Registers your own SIP provider for inbound and outbound calling. 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: Famulor API version: 1.0.0 description: >- REST API for Famulor. 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. REST operations require API Access through the workspace plan or a recurring add-on. Without it, regular operations return `403 api_access_required`. The invoice-payment and billing-portal operations remain available with a valid `billing:write` credential after a failed plan payment so an authorized owner, admin, or billing member can recover billing. The same customer-facing capabilities are available as MCP tools at `https://app.famulor.io/mcp` (Model Context Protocol, streamable HTTP) using the same credentials, scopes, and workspace access. MCP availability is controlled separately by Connect AI / MCP, not by API Access. 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: Famulor Loop description: >- Personal business-phone access, directory, presence, devices, and Loop call recents. - 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 transaction ledger of the API key's workspace. - name: Automations description: >- Native workspace automations — list, create, update, trigger. Requires Automations in the workspace plan. - name: Milian Missions description: Recurring jobs that Milian runs unattended on schedule. - 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 Custom dashboards in the workspace plan. - 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 white-label customer accounts, defaults, credit transfers and customer plan offers. Each endpoint documents its required scope and workspace eligibility. - name: API Keys description: >- Self-service API keys for the calling workspace or a same-brand workspace where the credential's user is owner/admin. A key can only mint further keys with a scope subset of its own. - name: Workspaces description: >- List visible workspaces, create an additional workspace for the key owner, and mint a dedicated credential for a selected owner/admin workspace. - name: SMS description: Outbound SMS from workspace phone numbers. - name: Milian description: >- Ask Milian, the AI co-worker in your workspace, and start voice sessions with it. - name: Translation description: >- Live translation sessions that interpret a conversation between two languages. paths: /sip-trunks: post: tags: - SIP Trunks summary: Create a SIP trunk description: >- Registers your own SIP provider for inbound and outbound calling. 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' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/RequestProtectionUnavailable' components: schemas: SipTrunkCreate: type: object required: - name - sip_address - numbers 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 minItems: 1 maxItems: 1 description: >- Exactly one inbound match number is required. DID: E.164. Extension: E.164 or national digits without country code. 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. outbound_from_user_mode: type: string enum: - phone_number - auth_username default: phone_number description: >- Outbound From user for your own SIP trunk. Phone number preserves the existing behavior. SIP username uses the authentication username and keeps the primary DID unchanged. Not available on imported carrier connections. outbound_caller_id_header: type: string enum: - from_display - p_asserted_identity - p_preferred_identity default: from_display description: >- Used with SIP username identity. The primary international DID is sent in the From display name and optionally the selected identity header. Match the carrier caller ID settings. SipTrunk: type: object description: >- Customer-owned BYO/BYOC SIP trunk. Managed platform trunks, passwords, and internal trunk identifiers 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: >- Exactly one primary number on this trunk. DID: E.164. Extension: E.164 or national digits without country code; still used for exact inbound matching. trunk_kind: type: string enum: - did - extension description: >- `did` = one E.164 phone number. `extension` = one exact primary number whose outbound caller-ID format may be national; it is never wildcard inbound. 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 outbound_from_user_mode: type: string enum: - phone_number - auth_username default: phone_number description: >- Outbound From user for your own SIP trunk. Phone number preserves the existing behavior. SIP username uses the authentication username and keeps the primary DID unchanged. Not available on imported carrier connections. outbound_caller_id_header: type: string enum: - from_display - p_asserted_identity - p_preferred_identity default: from_display description: >- Used with SIP username identity. The primary international DID is sent in the From display name and optionally the selected identity header. Match the carrier caller ID settings. 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 - api_access_required - not_found - invalid_request - rate_limited - conflict - telephony_configuration_error - telephony_unavailable - destination_forbidden - internal_error - service_unavailable description: >- Stable, machine-readable error code. `service_unavailable` is returned by POST /bookings and GET /booking-event-types/{id}/slots specifically when the availability engine could not be reached (see AvailabilityOrProtectionUnavailable). 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 credential lacks the required scope or role, or the workspace does not have the required capability. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: scopeDenied: summary: Required scope is missing value: error: code: forbidden message: >- This API key is missing the required scope "assistants:write". apiAccessRequired: summary: API Access is not available value: error: code: api_access_required message: >- API Access is not available for this workspace. Review Settings → Plan. RateLimited: description: Too many requests. Retry after the indicated delay. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limited message: Too many requests. Retry after the indicated delay. RequestProtectionUnavailable: description: Request protection is temporarily unavailable. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: internal_error message: Request protection is temporarily unavailable. 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_...`). REST operations also require API Access for the credential's workspace. Keys can be restricted to scopes such as `assistants:read`, `calls:write`, `campaigns:write`, `automations:read`, `dashboards:read`, `dashboards:write`, `leads:write`, `segments:write`, `loop:read`, `loop:write`, `phone_numbers:write`, `sip_trunks:write`, `knowledge:write`, `voices:read`, `billing:read`, `billing:write`, `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 within the workspace's available capabilities. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.