Create Operator

Create a new operator (human agent) that can be assigned to virtual numbers for inbound call routing.

POSThttps://api.identitycall.ai/api/v1/public/operators

Create an operator with a name and phone number. Phone numbers are auto-normalized to E.164.

Requires write permission

Scope and auto-linking

Project-scoped keys auto-link the new operator to the bound project.

When you create an operator with a project-scoped API key, the operator is created and an OperatorProject row is automatically inserted that links the new operator to the key’s bound project. This makes the operator immediately visible to other project-scoped requests.

When you create an operator with an account-wide key, the operator is created unlinked — it belongs to the account but is not yet attached to any project. You must explicitly link it to one or more projects through the project-scoped operator endpoints (or via the dashboard) before project-scoped keys can see it.

API key scope	Behavior
Account-wide	Creates an unlinked account-level operator
Project-scoped	Creates the operator and auto-links it to the bound project

Request Body

Body Parameters (application/json)

Name	Type	Required	Default	Description
`name`	string	Yes	-	Full display name (e.g. "Jane Doe"). Used to derive `initials`.
`phone_number`	string	Yes	-	Phone number in E.164 or local format. Auto-normalized to E.164 on save.
`email`	string	No	-	Optional contact email for the operator.
`active`	boolean	No	`true`	Whether the operator can currently receive routed calls.

Request

cURL


curl -X POST "https://api.identitycall.ai/api/v1/public/operators" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "phone_number": "+15551234567",
    "email": "jane.doe@example.com",
    "active": true
  }'

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
 
response = requests.post(
    "https://api.identitycall.ai/api/v1/public/operators",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "name": "Jane Doe",
        "phone_number": "+15551234567",
        "email": "jane.doe@example.com",
        "active": True
    }
)
 
operator = response.json()["data"]
print(f"Created operator {operator['id']}: {operator['name']}")

Node.js


const API_KEY = process.env.IDENTITYCALL_API_KEY;
 
const response = await fetch(
  'https://api.identitycall.ai/api/v1/public/operators',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Jane Doe',
      phone_number: '+15551234567',
      email: 'jane.doe@example.com',
      active: true
    })
  }
);
 
const { data: operator } = await response.json();
console.log(`Created operator ${operator.id}: ${operator.name}`);

Response

Response201 Created

{
"data": {
  "id": 42,
  "name": "Jane Doe",
  "phone_number": "+15551234567",
  "email": "jane.doe@example.com",
  "active": true,
  "initials": "JD",
  "virtual_numbers": []
}
}

Response Fields

Field	Type	Description
`id`	integer	Unique operator ID
`name`	string	Full display name
`phone_number`	string	E.164 normalized phone number
`email`	string \| null	Contact email
`active`	boolean	Whether the operator is active
`initials`	string	Two-letter initials derived from `name`
`virtual_numbers`	array	Virtual numbers assigned to this operator (empty on create)

Each entry of virtual_numbers (when populated later) has the shape:

Field	Type	Description
`id`	integer	Virtual number ID
`phone_number`	string	The virtual number in E.164
`name`	string	Display name of the virtual number
`active`	boolean	Whether the virtual number is active

Errors

Status	Error	Description
401	”Invalid API key”	Missing or unrecognized bearer token
403	”Write permission required”	API key lacks write permission
422	`["Name can't be blank"]`	`name` was not supplied
422	`["Phone number can't be blank"]`	`phone_number` was not supplied
422	`["Phone number is invalid"]`	Phone number could not be normalized to a valid E.164 value