Skip to content

Bind a phone number to a deployed agent for inbound routing

POST
/voice/agents/{agentId}/numbers
curl --request POST \
  --url https://api.pingram.io/voice/agents/example/numbers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "phoneNumber": "example" }'

Authorizations

Parameters

Path Parameters

agentId
required
string

Agent id

Request Bodyrequired

Media typeapplication/json
object
phoneNumber
required
string
Examplegenerated
{
  "phoneNumber": "example"
}

Responses

200

Successful response

Media typeapplication/json
object
agent
required

Agent record returned by GET /voice/agents.

object
agentId
required
string
deployment
required
string
Allowed values: hosted ejected
spec
required
object
name
required
string
instructions
required
string
inbound
required
object
firstAction
required
string
Allowed values: speak wait
greeting
required
string
outbound
required
object
firstAction
required
string
Allowed values: speak wait
opener
required
string
voicemailAction
required
string
Allowed values: hangup message continue
voicemailMessage
string
model
required
One of:
Chained

Separate STT, LLM, and TTS providers. For best call quality, prefer s2s mode.

object
mode
required
string
Allowed values: chained
llm
required

‘provider:model’, e.g. ‘openai:gpt-4o’

string
stt
required

‘provider:model’, e.g. ‘deepgram:nova-3’

string
tts
required

‘provider:model’, e.g. ‘elevenlabs:eleven_multilingual_v2’

string
voiceId
required

Provider-native voice id for the selected TTS provider (e.g. ElevenLabs UUID, OpenAI alloy).

string
language
required
string
speechSpeed
required
number
temperature
required
number
maxTokens
required
number
tools
required
Array
One of:
Transfer
object
type
required
string
Allowed values: transfer
transferMode
required
string
Allowed values: warm cold
destination
required
string
briefing
string
variables
required
Array<object>
object
name
required
string
description
string
defaultValue
string
conversation
required
object
turnDetection
required
string
Allowed values: semantic vad
minEndOfTurnSilenceMs
required
number
allowInterruptions
required
boolean
minInterruptionDurationMs
required
number
silenceTimeoutSeconds
required
number
maxCallLengthSeconds
required
number
agentCanEndCall

When true (default), the agent may invoke the built-in end_call action.

boolean
compliance
required
object
recordingEnabled
required
boolean
phoneNumbers
required
Array<string>
workerPresence
string
Allowed values: online offline
createdAt
required
string
updatedAt
required
string
Example
{
  "agent": {
    "deployment": "hosted",
    "spec": {
      "inbound": {
        "firstAction": "speak"
      },
      "outbound": {
        "firstAction": "speak",
        "voicemailAction": "hangup"
      },
      "model": {
        "mode": "chained"
      },
      "tools": [
        {
          "type": "transfer",
          "transferMode": "warm"
        }
      ],
      "conversation": {
        "turnDetection": "semantic"
      }
    },
    "workerPresence": "online"
  }
}

400

Bad Request - validation errors, invalid input

Media typeapplication/json

Standard error response for API errors.

object
trackingId
required

Unique tracking ID for the request.

string
error
required

Structured error details for API error responses.

object
code
required

Machine-readable error code.

string
message
required

Human-readable error message.

string
fix

Actionable hint for fixing the error.

string
Examplegenerated
{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

401

Unauthorized

402

Payment Required - usage limits exceeded

Media typeapplication/json

Standard error response for API errors.

object
trackingId
required

Unique tracking ID for the request.

string
error
required

Structured error details for API error responses.

object
code
required

Machine-readable error code.

string
message
required

Human-readable error message.

string
fix

Actionable hint for fixing the error.

string
Examplegenerated
{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}

500

Internal Server Error

502

Bad Gateway - provider error

Media typeapplication/json

Standard error response for API errors.

object
trackingId
required

Unique tracking ID for the request.

string
error
required

Structured error details for API error responses.

object
code
required

Machine-readable error code.

string
message
required

Human-readable error message.

string
fix

Actionable hint for fixing the error.

string
Examplegenerated
{
  "trackingId": "example",
  "error": {
    "code": "example",
    "message": "example",
    "fix": "example"
  }
}