Add Operator

Attach an operator to a virtual number so inbound calls can be routed to that person.

POSThttps://api.identitycall.ai/api/v1/public/virtual_numbers/:id/add_operator

Attaches an existing operator (by operator_id) or creates a new operator on the fly (by phone_number).

Requires write permission

Scopes

API key scope	Behavior
Account-wide	Can attach to any virtual number on the account; can reference any operator on the account.
Project-scoped	Returns 404 if the virtual number is not in the key’s project. Existing-operator references are also scoped to the project.

The operator is appended at the end of the priority list (next available priority slot). Re-attaching an already-attached operator is a no-op.

Path Parameters

Parameters

Name	Type	Required	Default	Description
`id`	integer	Yes	-	Virtual number ID

Request Body

This endpoint accepts two distinct request shapes. Send exactly one.

Shape A — reference an existing operator

Body Parameters (application/json)

Name	Type	Required	Default	Description
`operator_id`	integer	Yes	-	ID of an existing operator on the account (must be visible under the key scope)


{ "operator_id": 22 }

Shape B — auto-create a new operator

Body Parameters (application/json)

Name	Type	Required	Default	Description
`phone_number`	string	Yes	-	E.164 phone number for the new operator
`name`	string	No	`Operator`	Display name for the new operator


{ "phone_number": "+15555550199", "name": "Greta Hall" }

If both operator_id and phone_number are present, operator_id wins.

Request

cURL


# Shape A: attach existing operator
curl -X POST "https://api.identitycall.ai/api/v1/public/virtual_numbers/7/add_operator" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operator_id": 22}'
 
# Shape B: create-and-attach
curl -X POST "https://api.identitycall.ai/api/v1/public/virtual_numbers/7/add_operator" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+15555550199", "name": "Greta Hall"}'

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
vn_id = 7
url = f"https://api.identitycall.ai/api/v1/public/virtual_numbers/{vn_id}/add_operator"
headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
 
# Shape A: existing operator
requests.post(url, headers=headers, json={"operator_id": 22})
 
# Shape B: auto-create
response = requests.post(url, headers=headers, json={
    "phone_number": "+15555550199",
    "name": "Greta Hall"
})
 
vn = response.json()["data"]
print(f"{vn['phone_number']} now has {len(vn['operators'])} operators")

Node.js


const API_KEY = process.env.IDENTITYCALL_API_KEY;
const vnId = 7;
const url = `https://api.identitycall.ai/api/v1/public/virtual_numbers/${vnId}/add_operator`;
const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};
 
// Shape A: existing operator
await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ operator_id: 22 })
});
 
// Shape B: auto-create
const response = await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ phone_number: '+15555550199', name: 'Greta Hall' })
});
 
const { data: vn } = await response.json();
console.log(`${vn.phone_number} now has ${vn.operators.length} operators`);

Response

Returns the same detail payload as Get Virtual Number, reflecting the new operator list.

Response200 OK

{
"data": {
  "id": 7,
  "phone_number": "+15551234567",
  "name": "US Sales Line",
  "country_code": "US",
  "active": true,
  "recording": true,
  "routing_strategy": "priority",
  "ai_receptionist_enabled": false,
  "stats": { "total_calls": 142, "answered_calls": 118, "missed_calls": 24, "average_duration_seconds": 184 },
  "operators": [
    { "id": 12, "name": "Alice Carter", "phone_number": "+15555550112", "initials": "AC", "priority": 0 },
    { "id": 22, "name": "Greta Hall", "phone_number": "+15555550199", "initials": "GH", "priority": 1 }
  ],
  "available_operators": [],
  "recent_calls": []
}
}

Errors

Status	Error	Description
404	”Resource not found”	Virtual number doesn’t exist, isn’t accessible, or `operator_id` doesn’t resolve under the key scope
422	”operator_id or phone_number is required”	Neither field was supplied
422	Validation errors	New operator failed validation (invalid phone number, etc.)

Try It

API Key

Parameters

id*

Body

operator_id

phone_number

name

Add Operator

Scopes

Path Parameters

Parameters

Request Body

Shape A — reference an existing operator

Body Parameters (application/json)

Shape B — auto-create a new operator

Body Parameters (application/json)

Request

cURL

Python

Node.js

Response

Errors

See Also

Try It

Try It