> ## Documentation Index > Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create Provider > Link a telephony provider account. For Twilio, credentials are validated before the provider is created. Each account SID + region combination can only be linked once. For SIP trunks, configure a trunk with an inbound and/or outbound configuration. ## OpenAPI ````yaml 2026-03-01/api.yml POST /agents/phone-numbers/providers openapi: 3.0.1 info: title: Cartesia API version: 0.0.1 servers: - url: https://api.cartesia.ai description: Production security: [] paths: /agents/phone-numbers/providers: post: tags: - Providers summary: Create Provider description: >- Link a telephony provider account. For Twilio, credentials are validated before the provider is created. Each account SID + region combination can only be linked once. For SIP trunks, configure a trunk with an inbound and/or outbound configuration. operationId: providers_create parameters: - $ref: '#/components/parameters/CartesiaVersionHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateProviderBody' responses: '201': description: Provider created. content: application/json: schema: $ref: '#/components/schemas/ProviderAccountResponse' '400': description: Invalid provider credentials or SIP trunk configuration. '409': description: >- A Twilio provider already exists for this account and region. Use PATCH to update the provider. security: - APIKeyAuth: [] components: parameters: CartesiaVersionHeader: name: Cartesia-Version in: header description: API version header. required: true schema: type: string format: date example: '2026-03-01' default: '2026-03-01' enum: - '2026-03-01' schemas: CreateProviderBody: title: Create Provider description: |- Request body for linking a telephony provider. Discriminated by `type`. **Twilio**: - Credentials are validated against Twilio before the provider is created - Each account SID + region combination can only be linked once oneOf: - $ref: '#/components/schemas/CreateTwilioProviderBody' - $ref: '#/components/schemas/CreateSIPProviderBody' discriminator: propertyName: type mapping: twilio: $ref: '#/components/schemas/CreateTwilioProviderBody' sip_trunk: $ref: '#/components/schemas/CreateSIPProviderBody' ProviderAccountResponse: title: Provider Account description: A telephony provider account. oneOf: - $ref: '#/components/schemas/TwilioProviderResponse' - $ref: '#/components/schemas/SIPTrunkProviderResponse' discriminator: propertyName: type mapping: twilio: $ref: '#/components/schemas/TwilioProviderResponse' sip_trunk: $ref: '#/components/schemas/SIPTrunkProviderResponse' CreateTwilioProviderBody: title: Twilio type: object properties: type: type: string enum: - twilio description: Must be `"twilio"`. account_sid: type: string description: Your Twilio account SID. api_key_sid: type: string description: A Twilio API key SID. api_key_secret: type: string format: password description: The corresponding API key secret. region: $ref: '#/components/schemas/TelephonyRegion' default: us1 label: type: string minLength: 1 description: An optional human-readable label for the provider. required: - type - account_sid - api_key_sid - api_key_secret CreateSIPProviderBody: title: SIP Trunk type: object description: >- Link a SIP trunk provider. At least one of `inbound` or `outbound` is required. properties: type: type: string enum: - sip_trunk description: Must be `"sip_trunk"`. label: type: string minLength: 1 description: A human-readable label for the provider. inbound: $ref: '#/components/schemas/InboundSIPTrunkConfig' outbound: $ref: '#/components/schemas/OutboundSIPTrunkConfig' anyOf: - required: - inbound - required: - outbound required: - type - label TwilioProviderResponse: title: Twilio type: object description: >- A linked Twilio account. The `api_key_sid` field is partially masked in responses. properties: type: type: string enum: - twilio description: Always `"twilio"`. id: type: string description: Unique identifier for the provider. account_sid: type: string description: The Twilio account SID. api_key_sid: type: string description: The Twilio API key SID (partially masked). region: $ref: '#/components/schemas/TelephonyRegion' label: type: string nullable: true description: A human-readable label for the provider. required: - type - id - account_sid - api_key_sid - region SIPTrunkProviderResponse: title: SIP Trunk type: object description: A linked SIP trunk provider. properties: type: type: string enum: - sip_trunk description: Always `"sip_trunk"`. id: type: string description: Unique identifier for the provider. label: type: string nullable: true description: A human-readable label for the provider. inbound: description: Inbound configuration. Present when inbound is configured. allOf: - $ref: '#/components/schemas/SIPTrunkInboundDetails' outbound: description: Outbound configuration. Present when outbound is configured. allOf: - $ref: '#/components/schemas/SIPTrunkOutboundDetails' required: - type - id TelephonyRegion: title: TelephonyRegion type: string enum: - us1 - ie1 - au1 description: >- The Twilio region the phone number and API key are configured for. `us1` (US), `ie1` (Ireland), `au1` (Australia). Default is `us1`. default: us1 InboundSIPTrunkConfig: title: InboundSIPTrunkConfig type: object description: Inbound SIP configuration for creating a trunk. properties: credentials: $ref: '#/components/schemas/SIPCredentials' allowed_addresses: type: array items: type: string description: Source IP addresses or CIDR ranges allowed to send SIP traffic. allowed_numbers: type: array items: type: string description: Caller numbers allowed on inbound calls. media_encryption: description: Media encryption policy. Defaults to `allowed`. allOf: - $ref: '#/components/schemas/SIPMediaEncryption' OutboundSIPTrunkConfig: title: OutboundSIPTrunkConfig type: object description: Outbound SIP configuration for creating a trunk. properties: address: type: string minLength: 1 description: SIP server hostname or address used for outbound signaling. transport: $ref: '#/components/schemas/SIPTrunkTransport' destination_country: $ref: '#/components/schemas/Iso3166Alpha2CountryCode' media_encryption: description: Media encryption policy. Defaults to `disabled`. allOf: - $ref: '#/components/schemas/SIPMediaEncryption' credentials: $ref: '#/components/schemas/SIPCredentials' required: - address - transport SIPTrunkInboundDetails: title: SIPTrunkInboundDetails type: object description: >- Inbound SIP configuration. Passwords are never returned; only the configured username is exposed as `auth_username`. properties: allowed_addresses: type: array items: type: string description: Source IP addresses or CIDR ranges allowed to send SIP traffic. allowed_numbers: type: array items: type: string description: Caller numbers allowed on inbound calls. auth_username: type: string description: SIP username returned without the password. media_encryption: description: Media encryption policy. Defaults to `allowed`. allOf: - $ref: '#/components/schemas/SIPMediaEncryption' required: - allowed_addresses - allowed_numbers - auth_username - media_encryption SIPTrunkOutboundDetails: title: SIPTrunkOutboundDetails type: object description: >- Outbound SIP configuration. Passwords are never returned; only the configured username is exposed as `auth_username`. properties: address: type: string description: SIP server hostname or address used for outbound signaling. destination_country: type: string description: >- Two-letter ISO 3166-1 alpha-2 destination country code, or an empty string if not set. transport: $ref: '#/components/schemas/SIPTrunkTransport' media_encryption: description: Media encryption policy. Defaults to `disabled`. allOf: - $ref: '#/components/schemas/SIPMediaEncryption' auth_username: type: string description: SIP username returned without the password. required: - address - transport - media_encryption - auth_username SIPCredentials: title: SIPCredentials type: object description: SIP digest authentication credentials. properties: username: type: string minLength: 1 password: type: string minLength: 1 format: password required: - username - password SIPMediaEncryption: title: SIPMediaEncryption type: string enum: - disabled - allowed - required description: >- SRTP policy for call audio. `disabled` does not negotiate encryption, `allowed` uses encryption when available, and `required` rejects calls that cannot use encryption. SIPTrunkTransport: title: SIPTrunkTransport type: string enum: - tcp - tls description: Transport for outbound SIP signaling. Iso3166Alpha2CountryCode: title: Iso3166Alpha2CountryCode type: string minLength: 2 maxLength: 2 pattern: ^[A-Za-z]{2}$ description: >- Two-letter country code for the country the call terminates in (e.g. `US`, `GB`, `DE`). See [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2). securitySchemes: APIKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- Cartesia API key (`sk_car_...`). Get one at [play.cartesia.ai/keys](https://play.cartesia.ai/keys). x-default: $CARTESIA_API_KEY ````