Create Configuration
Create a new telephony configuration
Create a new telephony configuration
Call List Supported Providers first to discover the credential fields for the provider you want to configure — they vary per provider.
Configuration name must be unique within your organization. Set is_default_outbound: true to mark this configuration as the org-wide default for outbound calls (any existing default is unset). New configurations have no phone numbers; add them via Add a phone number.
Quick reference#
Create a new telephony configuration. Send the request to POST /api/v1/organizations/telephony-configs on the Paladin API base URL.
| Method | POST |
|---|---|
| Path | /api/v1/organizations/telephony-configs |
| Path parameters | None in the path. |
| Authentication | Use the authentication method shown in the OpenAPI block and the Authentication docs. Keep API keys server-side. |
Before you call#
- Confirm you are using the production base URL shown in the API reference.
- Make sure any path IDs belong to the same Paladin organization as the credential you are using.
- Validate request bodies and required fields before sending production traffic.
Common error checks#
- Use 401 or 403 responses to check credentials, organization scope, and permissions.
- Use 404 responses to check whether the referenced resource exists in the current organization.
- Use 422 responses to inspect missing or invalid request fields.
OpenAPI#
POST /api/v1/organizations/telephony-configs
openapi: 3.1.0
info:
title: Paladin API
description: API for the Paladin app
version: 1.0.0
servers:
- url: https://app.paladin.northmanngrp.com
description: Production
security: []
paths:
/api/v1/organizations/telephony-configs:
post:
tags:
- main
- organizations
summary: Create Telephony Configuration
description: Create a new telephony configuration for the org.
operationId: >-
create_telephony_configuration_api_v1_organizations_telephony_configs_post
parameters:
- name: authorization
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: Authorization
- name: X-API-Key
in: header
required: false
schema:
anyOf:
- type: string
- type: 'null'
title: X-Api-Key
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TelephonyConfigurationCreateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TelephonyConfigurationDetail'
'404':
description: Not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
TelephonyConfigurationCreateRequest:
properties:
name:
type: string
maxLength: 64
minLength: 1
title: Name
is_default_outbound:
type: boolean
title: Is Default Outbound
default: false
config:
oneOf:
- $ref: '#/components/schemas/ARIConfigurationRequest'
- $ref: '#/components/schemas/CloudonixConfigurationRequest'
- $ref: '#/components/schemas/PlivoConfigurationRequest'
- $ref: '#/components/schemas/TelnyxConfigurationRequest'
- $ref: '#/components/schemas/TwilioConfigurationRequest'
- $ref: '#/components/schemas/VobizConfigurationRequest'
- $ref: '#/components/schemas/VonageConfigurationRequest'
title: Config
discriminator:
propertyName: provider
mapping:
ari:
$ref: '#/components/schemas/ARIConfigurationRequest'
cloudonix:
$ref: '#/components/schemas/CloudonixConfigurationRequest'
plivo:
$ref: '#/components/schemas/PlivoConfigurationRequest'
telnyx:
$ref: '#/components/schemas/TelnyxConfigurationRequest'
twilio:
$ref: '#/components/schemas/TwilioConfigurationRequest'
vobiz:
$ref: '#/components/schemas/VobizConfigurationRequest'
vonage:
$ref: '#/components/schemas/VonageConfigurationRequest'
type: object
required:
- name
- config
title: TelephonyConfigurationCreateRequest
description: |-
Body for ``POST /telephony-configs``.
``config`` carries the provider-specific credential fields (the same
discriminated union used by the legacy single-config endpoint). Any
``from_numbers`` on the inner config are ignored — phone numbers are
managed via the dedicated phone-numbers endpoints.
TelephonyConfigurationDetail:
properties:
id:
type: integer
title: Id
name:
type: string
title: Name
provider:
type: string
title: Provider
is_default_outbound:
type: boolean
title: Is Default Outbound
credentials:
additionalProperties: true
type: object
title: Credentials
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
type: object
required:
- id
- name
- provider
- is_default_outbound
- credentials
- created_at
- updated_at
title: TelephonyConfigurationDetail
description: Body of ``GET /telephony-configs/{id}`` — credentials are masked.
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ARIConfigurationRequest:
properties:
provider:
type: string
const: ari
title: Provider
default: ari
ari_endpoint:
type: string
title: Ari Endpoint
description: ARI base URL (e.g., http://asterisk.example.com:8088)
app_name:
type: string
title: App Name
description: Stasis application name registered in Asterisk
app_password:
type: string
title: App Password
description: ARI user password
ws_client_name:
type: string
title: Ws Client Name
description: >-
websocket_client.conf connection name for externalMedia (e.g.,
paladin_staging)
default: ''
from_numbers:
items:
type: string
type: array
title: From Numbers
description: List of SIP extensions/numbers for outbound calls (optional)
type: object
required:
- ari_endpoint
- app_name
- app_password
title: ARIConfigurationRequest
description: Request schema for Asterisk ARI configuration.
CloudonixConfigurationRequest:
properties:
provider:
type: string
const: cloudonix
title: Provider
default: cloudonix
bearer_token:
type: string
title: Bearer Token
description: Cloudonix API Bearer Token
domain_id:
type: string
title: Domain Id
description: Cloudonix Domain ID
application_name:
anyOf:
- type: string
- type: 'null'
title: Application Name
description: >-
Cloudonix Voice Application name. The application's url is updated
when inbound workflows are attached to numbers on this domain. If
omitted, an application is auto-created on save and its name is
stored on the configuration.
from_numbers:
items:
type: string
type: array
title: From Numbers
description: List of Cloudonix phone numbers (optional)
type: object
required:
- bearer_token
- domain_id
title: CloudonixConfigurationRequest
description: Request schema for Cloudonix configuration.
PlivoConfigurationRequest:
properties:
provider:
type: string
const: plivo
title: Provider
default: plivo
auth_id:
type: string
title: Auth Id
description: Plivo Auth ID
auth_token:
type: string
title: Auth Token
description: Plivo Auth Token
application_id:
anyOf:
- type: string
- type: 'null'
title: Application Id
description: >-
Plivo Application ID. The application's answer_url is updated when
inbound workflows are attached to numbers on this account. If
omitted, an application is auto-created on save and its id is stored
on the configuration.
from_numbers:
items:
type: string
type: array
title: From Numbers
description: List of Plivo phone numbers
type: object
required:
- auth_id
- auth_token
title: PlivoConfigurationRequest
description: Request schema for Plivo configuration.
TelnyxConfigurationRequest:
properties:
provider:
type: string
const: telnyx
title: Provider
default: telnyx
api_key:
type: string
title: Api Key
description: Telnyx API Key
connection_id:
anyOf:
- type: string
- type: 'null'
title: Connection Id
description: >-
Telnyx Call Control Application ID (connection_id). If omitted, a
Call Control Application is auto-created on save and its id is
stored on the configuration.
webhook_public_key:
anyOf:
- type: string
- type: 'null'
title: Webhook Public Key
description: >-
Webhook public key from Mission Control Portal → Keys & Credentials
→ Public Key. Used to verify Telnyx webhook signatures.
from_numbers:
items:
type: string
type: array
title: From Numbers
description: List of Telnyx phone numbers
type: object
required:
- api_key
title: TelnyxConfigurationRequest
description: Request schema for Telnyx configuration.
TwilioConfigurationRequest:
properties:
provider:
type: string
const: twilio
title: Provider
default: twilio
account_sid:
type: string
title: Account Sid
description: Twilio Account SID
auth_token:
type: string
title: Auth Token
description: Twilio Auth Token
from_numbers:
items:
type: string
type: array
title: From Numbers
description: List of Twilio phone numbers
type: object
required:
- account_sid
- auth_token
title: TwilioConfigurationRequest
description: Request schema for Twilio configuration.
VobizConfigurationRequest:
properties:
provider:
type: string
const: vobiz
title: Provider
default: vobiz
auth_id:
type: string
title: Auth Id
description: Vobiz Account ID (e.g., MA_SYQRLN1K)
auth_token:
type: string
title: Auth Token
description: Vobiz Auth Token
application_id:
anyOf:
- type: string
- type: 'null'
title: Application Id
description: >-
Vobiz Application ID. The application's answer_url is updated when
inbound workflows are attached to numbers on this account. If
omitted, an application is auto-created on save and its id is stored
on the configuration.
from_numbers:
items:
type: string
type: array
title: From Numbers
description: List of Vobiz phone numbers (E.164 without + prefix)
type: object
required:
- auth_id
- auth_token
title: VobizConfigurationRequest
description: Request schema for Vobiz configuration.
VonageConfigurationRequest:
properties:
provider:
type: string
const: vonage
title: Provider
default: vonage
api_key:
type: string
title: Api Key
description: Vonage API Key
api_secret:
type: string
title: Api Secret
description: Vonage API Secret
application_id:
type: string
title: Application Id
description: Vonage Application ID
private_key:
type: string
title: Private Key
description: Private key for JWT generation
from_numbers:
items:
type: string
type: array
title: From Numbers
description: List of Vonage phone numbers (without + prefix)
type: object
required:
- api_key
- api_secret
- application_id
- private_key
title: VonageConfigurationRequest
description: Request schema for Vonage configuration.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError