Add Phone Number
Attach a new phone number to a telephony configuration
Attach a new phone number to a telephony configuration
Set inbound_workflow_id to bind incoming calls on this number to a specific agent — Paladin will register the inbound webhook with the provider and the response will include a provider_sync block reporting the result. Omit it to add the number for outbound use only.
The (provider, account_id, address) tuple must be globally unique throughout all Paladin organizations, since inbound dispatch keys on it. Attempting to add a number that another organization already owns returns 409.
Quick reference#
Attach a new phone number to a telephony configuration. Send the request to POST /api/v1/organizations/telephony-configs/{configid}/phone-numbers on the Paladin API base URL.
| Method | POST |
|---|---|
| Path | /api/v1/organizations/telephony-configs/{configid}/phone-numbers |
| Path parameters | configid |
| 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/{configid}/phone-numbers
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/{config_id}/phone-numbers:
post:
tags:
- main
- organizations
summary: Create Phone Number
operationId: >-
create_phone_number_api_v1_organizations_telephony_configs__config_id__phone_numbers_post
parameters:
- name: config_id
in: path
required: true
schema:
type: integer
title: Config Id
- 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/PhoneNumberCreateRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/PhoneNumberResponse'
'404':
description: Not found
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
PhoneNumberCreateRequest:
properties:
address:
type: string
maxLength: 255
minLength: 1
title: Address
country_code:
anyOf:
- type: string
maxLength: 2
minLength: 2
- type: 'null'
title: Country Code
label:
anyOf:
- type: string
maxLength: 64
- type: 'null'
title: Label
inbound_workflow_id:
anyOf:
- type: integer
- type: 'null'
title: Inbound Workflow Id
is_active:
type: boolean
title: Is Active
default: true
is_default_caller_id:
type: boolean
title: Is Default Caller Id
default: false
extra_metadata:
additionalProperties: true
type: object
title: Extra Metadata
type: object
required:
- address
title: PhoneNumberCreateRequest
description: >-
Create a new phone number under a telephony configuration.
``address_normalized`` and ``address_type`` are computed server-side
from
``address`` (and ``country_code`` if PSTN). ``address`` itself is stored
verbatim for display.
PhoneNumberResponse:
properties:
id:
type: integer
title: Id
telephony_configuration_id:
type: integer
title: Telephony Configuration Id
address:
type: string
title: Address
address_normalized:
type: string
title: Address Normalized
address_type:
type: string
title: Address Type
country_code:
anyOf:
- type: string
- type: 'null'
title: Country Code
label:
anyOf:
- type: string
- type: 'null'
title: Label
inbound_workflow_id:
anyOf:
- type: integer
- type: 'null'
title: Inbound Workflow Id
inbound_workflow_name:
anyOf:
- type: string
- type: 'null'
title: Inbound Workflow Name
is_active:
type: boolean
title: Is Active
is_default_caller_id:
type: boolean
title: Is Default Caller Id
extra_metadata:
additionalProperties: true
type: object
title: Extra Metadata
created_at:
type: string
format: date-time
title: Created At
updated_at:
type: string
format: date-time
title: Updated At
provider_sync:
anyOf:
- $ref: '#/components/schemas/ProviderSyncStatus'
- type: 'null'
type: object
required:
- id
- telephony_configuration_id
- address
- address_normalized
- address_type
- is_active
- is_default_caller_id
- extra_metadata
- created_at
- updated_at
title: PhoneNumberResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
ProviderSyncStatus:
properties:
ok:
type: boolean
title: Ok
message:
anyOf:
- type: string
- type: 'null'
title: Message
type: object
required:
- ok
title: ProviderSyncStatus
description: |-
Result of pushing a phone-number change to the upstream provider.
Returned alongside create/update responses when the route attempted to
sync inbound webhook configuration. ``ok=False`` is a warning, not a
fatal error — the DB write succeeded.
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