List Operators

Retrieve all operators (human agents) accessible to the current API key.

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

Returns operators ordered by name with their virtual number assignment counts.

Requires read permission

Scope

API key scope	Returned operators
Account-wide	All operators in the account, including ones not yet linked to any project
Project-scoped	Only operators linked to the bound project (via `OperatorProject`)

Match your own agents on external_id (your employee/CRM id) — it is unique per account. Do not match on name, which is not unique, and do not assume phone_number is set: it is optional, because one person may answer many lines or none that IdentityCall knows about.

Read recording_project_ids on each operator to see where it is linked. That is what lets you tell “this person exists but is missing from my project” (call add_project) apart from “this person does not exist yet” (call Create Operator) — the distinction that stops a roster sync from creating duplicates.

Query Parameters

This endpoint takes no query parameters. Operators are returned sorted by name ascending.

Request

cURL


curl -X GET "https://api.identitycall.ai/api/v1/public/operators" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY"

Python


import requests
import os
 
API_KEY = os.environ.get("IDENTITYCALL_API_KEY")
 
response = requests.get(
    "https://api.identitycall.ai/api/v1/public/operators",
    headers={"Authorization": f"Bearer {API_KEY}"}
)
 
operators = response.json()["data"]
for op in operators:
    print(f"{op['id']}: {op['name']} ({op['phone_number']}) — {op['virtual_numbers_count']} numbers")

Node.js


const API_KEY = process.env.IDENTITYCALL_API_KEY;
 
const response = await fetch(
  'https://api.identitycall.ai/api/v1/public/operators',
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
 
const { data: operators } = await response.json();
operators.forEach(op => {
  console.log(`${op.id}: ${op.name} (${op.phone_number}) — ${op.virtual_numbers_count} numbers`);
});

Response

Response200 OK

{
"data": [
  {
    "id": 12,
    "name": "Aldona Petrauskaitė",
    "phone_number": "+37060012345",
    "email": "aldona@example.com",
    "active": true,
    "external_id": "crm-4417",
    "initials": "AP",
    "virtual_numbers_count": 2,
    "recording_project_ids": [12, 13]
  },
  {
    "id": 7,
    "name": "Jane Doe",
    "phone_number": "+15551234567",
    "email": "jane.doe@example.com",
    "active": true,
    "initials": "JD",
    "virtual_numbers_count": 1,
    "recording_project_ids": [12]
  },
  {
    "id": 18,
    "name": "Marcus Chen",
    "phone_number": "+14155550199",
    "email": null,
    "active": false,
    "initials": "MC",
    "virtual_numbers_count": 0,
    "recording_project_ids": []
  }
]
}

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	Optional contact email
`active`	boolean	Whether the operator can currently receive routed calls
`external_id`	string \| null	Your own identifier for this person, if you set one
`initials`	string	Two-letter initials derived from `name` (used in UI avatars)
`virtual_numbers_count`	integer	Number of virtual numbers this operator is assigned to
`recording_project_ids`	integer[]	Projects this operator is linked to. Empty means the operator exists but is in no project yet

Errors

Status	Error	Description
401	“Invalid API key”	Missing or unrecognized bearer token
403	“Read permission required”	API key lacks read permission