Data API — Agents

API reference for listing, reading, creating, editing, and deleting CCaaS agents, and for managing an agent's default outbound caller ID.

The Agents API lets an external system read and maintain the CCaaS agent roster — profile, licenses, skill levels, agent-wide skill settings, and default outbound caller ID — one agent at a time or up to 500 per request. This page is the endpoint-by-endpoint reference. For how writes behave, worked examples, and integration recipes, see Data API — Agent Management.

📘
Interactive Reference
The same endpoints are available in the API Reference, where requests can be built and sent with Try It. The machine-readable OpenAPI 3.1 description is also served by each tenant at GET /v1/openapi.json.

Overview


Base URL	`https://<hostname>.xima.cloud/rest/api`
Authentication	Bearer token from an API Service User. Any valid token can read; writes require a Service User with full access created on the tenant being written to
Request and response format	JSON. Refusals from the agent management endpoints are Problem documents (`application/problem+json`)
Limits	Up to 500 agents per bulk request, a 10 MiB `Content-Length` limit, and one agent write at a time per tenant — see Limits

Authentication

Every request requires a Service User bearer token in the Authorization header:

Authorization: Bearer <api_bearer_token>

Service Users are created under API Enablement > API Service Users. See API Service Users.

⚠️
Writes Require Full Access
Creating, editing, and deleting agents and setting a default outbound caller ID require a Service User with unrestricted access; a restricted one receives 403. A corporate central repository token can read agents but every write, dry runs included, is refused with 403 EPHEMERAL_SERVICE_USER_READ_ONLY.

Identifying an Agent

The {id} path parameter accepts either of the following. A name or an extension on its own is never accepted.

Identifier	Description
The agent's id	A UUID, for `XIMA` agents only
The agent's key	The exact `name(extension)` — for example, `Jane Doe(101)` — URL-encoded (`Jane%20Doe(101)`). Works for both `XIMA` and `UC` agents, and is the only way to address a `UC` agent

Endpoints

Method	Path	Summary
`GET`	`/v1/agents`	List licensed agents
`GET`	`/v1/agents/{id}`	Read one agent in full
`GET`	`/v1/agents/licenses/seats`	Seat counts per license
`POST`	`/v1/agents/create`	Create one `XIMA` agent
`POST`	`/v1/agents/create/bulk`	Create up to 500 `XIMA` agents
`PATCH`	`/v1/agents/{id}`	Edit one agent
`PATCH`	`/v1/agents`	Edit up to 500 agents
`DELETE`	`/v1/agents/{id}`	Delete a `XIMA` agent
`GET`	`/v1/agents/{id}/default-outbound-caller-id`	Read the agent's default outbound caller ID
`PUT`	`/v1/agents/{id}/default-outbound-caller-id`	Set the agent's default outbound caller ID
`DELETE`	`/v1/agents/{id}/default-outbound-caller-id`	Clear the agent's default outbound caller ID
`GET`	`/v1/agents/{id}/outbound-caller-ids`	The caller IDs the phone system offers the agent
`GET`	`/v1/openapi.json`	The OpenAPI description (no token needed)

List Licensed Agents

GET /v1/agents

Lists licensed agents only. An agent without a license is not listed, but can still be read and edited by its id or name(extension). This older endpoint answers errors in the SimpleError shape.

Parameters

Name	In	Type	Required	Description
`type`	query	string	No	`XIMA` or `UC` to list only that type of agent. Any other value is `400`
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`

Responses

Code	Description
`200 OK`	An AgentList
`400 Bad Request`	`type` is not `XIMA` or `UC` (SimpleError)
`401 Unauthorized`	Missing or invalid token (SimpleError)

Example Request

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/agents?type=XIMA' \
-H 'Authorization: Bearer <api_bearer_token>'

Example Response — `200 OK`

{
  "agents": [
    {
      "id": "53436b64-2d5c-4f0e-9a51-6c3b0f8e7d21",
      "agent": "Jane Doe(101)",
      "name": "Jane Doe",
      "extension": "101",
      "type": "XIMA",
      "email": "[email protected]"
    },
    {
      "agent": "Desk Phone(2001)",
      "name": "Desk Phone",
      "extension": "2001",
      "type": "UC",
      "email": "[email protected]"
    }
  ]
}

Read One Agent

GET /v1/agents/{id}

Returns one agent in full. The response is the same shape PATCH /v1/agents/{id} accepts, so an agent can be read, changed, and sent back.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	A `XIMA` agent's id, or the exact `name(extension)` of a `XIMA` or `UC` agent, URL-encoded
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`

Responses

Code	Description
`200 OK`	An AgentDetail
`401 Unauthorized`	Missing or invalid token
`404 Not Found`	`AGENT_NOT_FOUND` — no agent with that id or `name(extension)`
`409 Conflict`	`AGENT_ID_AMBIGUOUS` — more than one phone-system user has that `name(extension)`
`413 Payload Too Large`	`BODY_TOO_LARGE` — the `Content-Length` header is over 10 MiB

Example Request

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/agents/53436b64-2d5c-4f0e-9a51-6c3b0f8e7d21' \
-H 'Authorization: Bearer <api_bearer_token>'

Example Response — `200 OK`

{
  "id": "53436b64-2d5c-4f0e-9a51-6c3b0f8e7d21",
  "agent": "Jane Doe(101)",
  "name": "Jane Doe",
  "extension": "101",
  "type": "XIMA",
  "email": "[email protected]",
  "profile": {
    "id": "53436b64-2d5c-4f0e-9a51-6c3b0f8e7d21",
    "name": "Jane Doe",
    "preferredName": "Jane",
    "emailAddress": "[email protected]",
    "extension": "101",
    "connectedNumbers": [],
    "noAnswerOverflow": {
      "destinationType": "VOICEMAIL_EXTENSION",
      "destination": "101"
    },
    "recordingMode": "AUTOMATIC",
    "canListenOwnRecordings": true,
    "canDownloadOwnRecordings": false,
    "canListenSkillRecordings": false,
    "canDownloadSkillRecordings": false,
    "canListenRoleRecordings": false,
    "canDownloadRoleRecordings": false
  },
  "licenses": [
    "CCAAS_VOICE",
    "CCAAS_VOICE.CCAAS_WEB_CHAT_ADDON"
  ],
  "skillLevels": [
    {
      "skillId": "ee3b0d75-…",
      "skillName": "Support",
      "skillLevel": 7
    }
  ],
  "skillSettings": {
    "maxSimultaneousSessions": 3,
    "voiceEnabled": true,
    "chatEnabled": true,
    "emailEnabled": false
  },
  "defaultOutboundCallerId": {
    "label": "Main",
    "outboundCallerId": "8015550100"
  }
}

License Seats

GET /v1/agents/licenses/seats

Returns the seat counts per license, as the Agent Licensing page shows them.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`

Responses

Code	Description
`200 OK`	LicenseSeats
`401 Unauthorized`	Missing or invalid token
`413 Payload Too Large`	`BODY_TOO_LARGE` — the `Content-Length` header is over 10 MiB

Example Response — `200 OK`

{
  "seats": [
    {
      "license": "CCAAS_VOICE",
      "limit": 50,
      "assigned": 48,
      "remaining": 2,
      "concurrent": false
    }
  ]
}

Create One Agent

POST /v1/agents/create

Creates one XIMA agent. A create carries no default outbound caller ID — sending defaultOutboundCallerId is 400 FIELD_NOT_ALLOWED_ON_CREATE. Create the agent, then set its default with Set Default Outbound Caller ID. Omitting licenses gives the starter licenses a new agent gets in the web interface.

Parameters

Name	In	Type	Required	Description
`dryRun`	query	boolean	No	Check everything a real write would and save nothing. Defaults to `false`. A dry-run create reports no id
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`
`Content-Type`	header	string	Yes	`application/json`

Request Body

An AgentCreate. profile with name, extension, and emailAddress is required.

{
  "profile": {
    "name": "Jane Doe",
    "extension": "101",
    "emailAddress": "[email protected]",
    "recordingMode": "AUTOMATIC"
  },
  "licenses": [
    "CCAAS_VOICE"
  ],
  "skillLevels": [
    {
      "skillName": "Support",
      "skillLevel": 7
    }
  ],
  "skillSettings": {
    "maxSimultaneousSessions": 2
  }
}

Responses

Code	Description
`201 Created`	A WriteResponse with one `CREATED` result. The new agent's id is in `results[0].id`
`200 OK`	Dry run: a WriteResponse with one `VALID` result
`400 Bad Request`	The agent is invalid. `errors[].reason` says why
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	No full access, or a corporate token (`EPHEMERAL_SERVICE_USER_READ_ONLY`)
`409 Conflict`	Name, extension, or email in use; seat limit reached; agent not licensed for a skill
`413 Payload Too Large`	`BODY_TOO_LARGE` — the body is over 10 MiB
`429 Too Many Requests`	`WRITE_IN_PROGRESS` — another agent write is in progress. Retry after a short wait
`503 Service Unavailable`	`SETTINGS_BUSY` — another settings save held the lock. Nothing was saved. Retry

Example Request

curl -L -X POST 'https://<hostname>.xima.cloud/rest/api/v1/agents/create' \
-H 'Authorization: Bearer <api_bearer_token>' \
-H 'Content-Type: application/json' \
-d '{"profile":{"name":"Jane Doe","extension":"101","emailAddress":"[email protected]"},"licenses":["CCAAS_VOICE"]}'

Create Many Agents

POST /v1/agents/create/bulk

Creates up to 500 XIMA agents in one settings save, each exactly as the single create. Once processed, the response is 200 with a result for each item — a refused item does not stop the others. Items are applied in order, so seats, names, extensions, and emails taken by earlier items count against later ones.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`
`Content-Type`	header	string	Yes	`application/json`

Request Body

An AgentBulkCreate — only dryRun and agents. Any other key, or a ?dryRun query parameter, refuses the whole request with 400 MALFORMED_BODY.

{
  "dryRun": false,
  "agents": [
    {
      "profile": {
        "name": "Jane Doe",
        "extension": "101",
        "emailAddress": "[email protected]"
      }
    }
  ]
}

Responses

Code	Description
`200 OK`	A WriteResponse with one result per item. Check `summary` and each result's `status`
`400 Bad Request`	The body is not `dryRun` and a list of `agents`, or the URL has `?dryRun`
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	No full access, or a corporate token. Nothing was processed
`413 Payload Too Large`	`TOO_MANY_ITEMS` (more than 500 agents) or `BODY_TOO_LARGE` (over 10 MiB). Split the batch
`429 Too Many Requests`	`WRITE_IN_PROGRESS` — another agent write is in progress. Retry
`503 Service Unavailable`	`SETTINGS_BUSY` — another settings save held the lock. Nothing was saved. Retry

Edit One Agent

PATCH /v1/agents/{id}

Edits one agent. Only the fields present change; lists such as connectedNumbers and licenses are replaced whole, while skillLevels only adds, updates, or (with skillLevel: 0) removes the skills listed. A defaultOutboundCallerId in the body is checked with the phone system before anything is saved.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	A `XIMA` agent's id, or the exact `name(extension)`, URL-encoded
`dryRun`	query	boolean	No	Check everything a real write would and save nothing, including the phone-system check of a caller ID change
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`
`Content-Type`	header	string	Yes	`application/json`

Request Body

An AgentUpdate. An id in the body is optional; if sent, it must match the path (400 ID_MISMATCH).

{
  "profile": {
    "recordingMode": "MANUAL"
  },
  "skillLevels": [
    {
      "skillName": "Billing",
      "skillLevel": 0
    }
  ]
}

Responses

Code	Description
`200 OK`	A WriteResponse with one `UPDATED` (or `VALID` for a dry run) result. Check `failures`
`400 Bad Request`	The edit is invalid — for example, `RENAME_NOT_ALLOWED` or `UC_PROFILE_NOT_EDITABLE`
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	No full access, or a corporate token
`404 Not Found`	`AGENT_NOT_FOUND`
`409 Conflict`	In use; seat limit; not licensed for a skill; caller ID not allowed or unlabelled; ambiguous id
`413 Payload Too Large`	`BODY_TOO_LARGE`
`429 Too Many Requests`	`WRITE_IN_PROGRESS`. Retry
`502 Bad Gateway`	`CALLER_ID_CHECK_FAILED` — the caller ID could not be checked with the phone system. Nothing was saved. Retry
`503 Service Unavailable`	`SETTINGS_BUSY`. Nothing was saved. Retry

Edit Many Agents

PATCH /v1/agents

Applies up to 500 edits in one settings save, each naming its agent in id. Once processed, the response is 200 with a result for each item. If any item changes a defaultOutboundCallerId that cannot be checked with the phone system, or the request's caller ID checks reach 30 seconds in all, the whole request fails with 502 and nothing is saved.

Parameters

Name	In	Type	Required	Description
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`
`Content-Type`	header	string	Yes	`application/json`

Request Body

An AgentBulkUpdate — only dryRun and agents, with id required on every item.

{
  "dryRun": false,
  "agents": [
    {
      "id": "53436b64-…",
      "licenses": [
        "CCAAS_VOICE"
      ]
    },
    {
      "id": "Desk Phone(2001)",
      "skillLevels": [
        {
          "skillName": "Sales",
          "skillLevel": 5
        }
      ]
    }
  ]
}

Responses

Code	Description
`200 OK`	A WriteResponse with one result per item. Check `summary` and each result's `status`
`400 Bad Request`	The body is not `dryRun` and a list of `agents`, or the URL has `?dryRun`
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	No full access, or a corporate token. Nothing was processed
`413 Payload Too Large`	`TOO_MANY_ITEMS` or `BODY_TOO_LARGE`. Split the batch
`429 Too Many Requests`	`WRITE_IN_PROGRESS`. Retry
`502 Bad Gateway`	`CALLER_ID_CHECK_FAILED` — nothing in the request was saved, for any agent. Retry
`503 Service Unavailable`	`SETTINGS_BUSY`. Nothing was saved. Retry

Delete an Agent

DELETE /v1/agents/{id}

Deletes a XIMA agent and frees its license seats, exactly as the web interface does. The agent's name(extension) must be sent in the body as confirmation. A delete is not refused for an agent on a call or the last agent on a skill, and has no dry run.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	A `XIMA` agent's id, or the exact `name(extension)`, URL-encoded
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`
`Content-Type`	header	string	Yes	`application/json`

Request Body

An AgentDeleteConfirmation. Without it, or with a different name(extension), the delete is refused with 400 DELETE_CONFIRMATION_MISMATCH.

{
  "agent": "Jane Doe(101)"
}

Responses

Code	Description
`200 OK`	A WriteResponse with one `DELETED` result
`400 Bad Request`	`DELETE_CONFIRMATION_MISMATCH` or `UC_AGENT_NOT_DELETABLE`
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	No full access, or a corporate token
`404 Not Found`	`AGENT_NOT_FOUND`
`409 Conflict`	`AGENT_ID_AMBIGUOUS`
`413 Payload Too Large`	`BODY_TOO_LARGE`
`429 Too Many Requests`	`WRITE_IN_PROGRESS`. Retry
`503 Service Unavailable`	`SETTINGS_BUSY`. Nothing was deleted. Retry

Get Default Outbound Caller ID

GET /v1/agents/{id}/default-outbound-caller-id

Returns the caller ID the agent dials out with by default.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	A `XIMA` agent's id, or the exact `name(extension)`, URL-encoded
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`

Responses

Code	Description
`200 OK`	An OutboundCallerId
`204 No Content`	The agent has no default
`401 Unauthorized`	Missing or invalid token
`404 Not Found`	`AGENT_NOT_FOUND`
`409 Conflict`	`AGENT_ID_AMBIGUOUS`
`413 Payload Too Large`	`BODY_TOO_LARGE`

Example Response — `200 OK`

{
  "label": "Main",
  "outboundCallerId": "8015550100"
}

Set Default Outbound Caller ID

PUT /v1/agents/{id}/default-outbound-caller-id

Sets the agent's default outbound caller ID — this is how a new agent gets its default once the create has saved it. The caller ID is checked with the phone system first. The caller ID the agent already has is not a change: it is not checked and nothing is written. A label in the body is ignored; the phone system's label is stored.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	A `XIMA` agent's id, or the exact `name(extension)`, URL-encoded
`dryRun`	query	boolean	No	Check the caller ID with the phone system and save nothing
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`
`Content-Type`	header	string	Yes	`application/json`

Request Body

A CallerIdToSet. A missing, empty, or blank outboundCallerId is 400 CALLER_ID_REQUIRED — use Clear Default Outbound Caller ID to clear it.

{
  "outboundCallerId": "8015550100"
}

Responses

Code	Description
`200 OK`	A WriteResponse with one `UPDATED` (or `VALID`) result; `failures` carries `CALLER_ID_SAVE_FAILED` if the write did not take
`400 Bad Request`	`CALLER_ID_REQUIRED`
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	No full access, or a corporate token
`404 Not Found`	`AGENT_NOT_FOUND`
`409 Conflict`	`CALLER_ID_NOT_ALLOWED` or `CALLER_ID_NO_LABEL` — the agent may not use the caller ID
`413 Payload Too Large`	`BODY_TOO_LARGE`
`429 Too Many Requests`	`WRITE_IN_PROGRESS`. Retry
`502 Bad Gateway`	`CALLER_ID_CHECK_FAILED` — the phone system could not be asked. Nothing was saved. Retry
`503 Service Unavailable`	`SETTINGS_BUSY`. Nothing was saved. Retry

Clear Default Outbound Caller ID

DELETE /v1/agents/{id}/default-outbound-caller-id

Clears the agent's default outbound caller ID. No check with the phone system is needed.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	A `XIMA` agent's id, or the exact `name(extension)`, URL-encoded
`dryRun`	query	boolean	No	Report the outcome and save nothing
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`

Responses

Code	Description
`200 OK`	A WriteResponse with one `UPDATED` (or `VALID`) result
`400 Bad Request`	The request is invalid
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	No full access, or a corporate token
`404 Not Found`	`AGENT_NOT_FOUND`
`409 Conflict`	`AGENT_ID_AMBIGUOUS`
`413 Payload Too Large`	`BODY_TOO_LARGE`
`429 Too Many Requests`	`WRITE_IN_PROGRESS`. Retry
`503 Service Unavailable`	`SETTINGS_BUSY`. Nothing was saved. Retry

List Outbound Caller IDs

GET /v1/agents/{id}/outbound-caller-ids

Returns the caller IDs the phone system offers the agent, and the one currently selected. This older endpoint answers errors in the SimpleError shape. See also Available Outbound Caller IDs.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	The agent's extension, its exact `name(extension)`, or a recording-pause alias, URL-encoded. Not the agent's id — a UUID is not recognized here
`Authorization`	header	string	Yes	`Bearer <api_bearer_token>`

Responses

Code	Description
`200 OK`	OutboundCallerIdOptions
`401 Unauthorized`	Missing or invalid token
`404 Not Found`	No such agent

OpenAPI Description

GET /v1/openapi.json

Returns the OpenAPI 3.1 description of these endpoints. No token is needed.

Code	Description
`200 OK`	The OpenAPI 3.1 document

Models

AgentList

Field	Type	Description
`agents`	array of Agent	The licensed agents. Required

Agent

Field	Type	Description
`id`	string	`XIMA` agents only: the agent's id
`agent`	string	The agent's key, `name(extension)`. Addresses `XIMA` and `UC` agents alike
`name`	string	The agent's name
`extension`	string	The agent's extension
`type`	string	`XIMA` — a browser (WebRTC) agent created in Xima — or `UC` — an agent from the phone system, which cannot be created, deleted, or have its profile edited here
`email`	string	The agent's email address

AgentDetail

The full agent, as returned by Read One Agent. profile is present for XIMA agents only.

Field	Type	Description
`id`, `agent`, `name`, `extension`, `type`, `email`		As in Agent
`profile`	Profile	`XIMA` agents only
`licenses`	array of string	The agent's complete set of licenses, using the Agent Licensing page's identifiers — for example, `CCAAS_VOICE`, `CCAAS_REALTIME`, `CCAAS_VOICE.CCAAS_WEB_CHAT_ADDON`, `CCAAS_VOICE.CCAAS_EMAIL_ADDON`, `CCAAS_CRM`, `CCAAS_TRANSCRIPTION`, `CCAAS_QA_EVALUATION`, or `UCAAS_*` names on UCaaS licensing
`skillLevels`	array of SkillLevel	The skills the agent is on, each at level 1 to 10
`skillSettings`	SkillSettings	Agent-wide skill settings
`defaultOutboundCallerId`	OutboundCallerId	Absent when the agent has no default

Profile

A XIMA agent's profile. On a create, omitted fields take a new agent's defaults; on an edit, only the fields present change and connectedNumbers is replaced whole.

Field	Type	Description
`id`	string	Read only. Ignored with a warning on a create
`name`	string	Required on create. Unique. Cannot contain `(` `)` `[` `]`. Cannot be changed
`preferredName`	string	Display name
`emailAddress`	string	Required on create. A valid address, unique across agents. Can be changed
`extension`	string	Required on create. Not used by another agent, phone-system user, or skill. Cannot be changed
`connectedNumbers`	array of ConnectedNumber	Phones the agent can take calls on. Replaced whole
`noAnswerOverflow`	NoAnswerOverflow	Where an unanswered direct call goes
`recordingMode`	string	`AUTOMATIC` · `AUTOMATIC_PAUSING_PROHIBITED` · `MANUAL` · `DISABLED`. `NOT_WEBRTC_DISABLED` is not offered for `XIMA` agents (`400 RECORDING_MODE_NOT_ALLOWED`). Cannot be cleared
`canListenOwnRecordings`	boolean	Whether the agent can listen to their own recordings
`canDownloadOwnRecordings`	boolean	Needs `canListenOwnRecordings`
`canListenSkillRecordings`	boolean	Whether the agent can listen to recordings for their skills
`canDownloadSkillRecordings`	boolean	Needs `canListenSkillRecordings`
`canListenRoleRecordings`	boolean	Changeable only while `Agent Access to Recordings by Role` is on (else `400 ROLE_RECORDINGS_NOT_ENABLED`)
`canDownloadRoleRecordings`	boolean	Needs `canListenRoleRecordings`; same tenant setting applies

ConnectedNumber

A phone the agent can take calls on.

Field	Type	Description
`name`	string	The number's name
`number`	string	The phone number
`disablePress1ToAnswer`	boolean	Turns off the press-1 confirmation when answering
`disableCallLink`	boolean	Turns off Call Link for this number
`enableSipSubscribe`	boolean	Turns on SIP subscribe for this number
`claimedBy`	string	Read only: the agent currently using this number
`remember`	boolean	Read only

NoAnswerOverflow

Field	Type	Description
`destinationType`	string	`IVR` · `SKILL` · `AGENT` · `DIALABLE_NUMBER` · `VOICEMAIL_EXTENSION`
`destination`	string	The destination of that type

SkillLevel

One skill membership. Skills not listed are left alone.

Field	Type	Description
`skillId`	string	The skill's id from List Skills. Preferred
`skillName`	string	The skill's exact name, used when `skillId` is absent
`skillLevel`	integer	`0` to `10`. Above `0` adds or updates the membership; `0` removes it. Required to add

SkillSettings

Agent-wide settings across all the agent's skills, as in the admin skill grid. In a write, an omitted field is left as it is.

Field	Type	Description
`maxSimultaneousSessions`	integer	`0` to `50` concurrent interactions
`voiceEnabled`	boolean	Voice participation
`chatEnabled`	boolean	Chat participation
`emailEnabled`	boolean	Email participation

OutboundCallerId

Field	Type	Description
`label`	string	The caller ID's label from the phone system
`outboundCallerId`	string	The caller ID

OutboundCallerIdOptions

Field	Type	Description
`selectedOutboundCallerId`	OutboundCallerId	The caller ID the agent currently has selected
`outboundCallerIds`	array of OutboundCallerId	Every caller ID the phone system offers the agent

LicenseSeats

Field	Type	Description
`seats`	array of LicenseSeat	One entry per license: `license`, `limit`, `assigned`, `remaining` (negative when the tenant is over its limit), and `concurrent` (the license limits concurrent logins rather than assignments, so `assigned` can exceed `limit`)

AgentCreate

Field	Type	Description
`profile`	Profile	Required, with `name`, `extension`, and `emailAddress`
`licenses`	array of string	The agent's complete set of licenses. Omit for the starter licenses (facet `DEFAULTED`)
`skillLevels`	array of SkillLevel	Skill memberships
`skillSettings`	SkillSettings	Agent-wide skill settings
`sendWelcomeEmail`	boolean	Defaults to `true`

AgentUpdate

Only the fields present change. agent, name, extension, type, and email are accepted read only, so a fetched agent can be sent back.

Field	Type	Description
`id`	string	Required in a bulk edit. On `PATCH /v1/agents/{id}`, must match the path if sent
`profile`	Profile	`XIMA` agents only
`licenses`	array of string	Replaces this agent's licenses with exactly this set. Omitted, the licenses are left alone — except that an edit carrying a `profile` re-adds the starter licenses if the agent has lost them
`skillLevels`	array of SkillLevel	Skill memberships to add, update, or remove
`skillSettings`	SkillSettings	Agent-wide skill settings
`defaultOutboundCallerId`	string, OutboundCallerId, or null	A caller ID to set, or `null` to clear. Checked with the phone system before anything is saved

AgentBulkCreate

Field	Type	Description
`dryRun`	boolean	Validate every item and save nothing
`agents`	array of AgentCreate	Required. 1 to 500 agents

AgentBulkUpdate

Field	Type	Description
`dryRun`	boolean	Validate every item and save nothing
`agents`	array of AgentUpdate	Required. 1 to 500 agents, each with `id`

AgentDeleteConfirmation

Field	Type	Description
`agent`	string	Required. The agent's `name(extension)`, exactly

CallerIdToSet

Field	Type	Description
`outboundCallerId`	string	Required. The caller ID to set
`label`	string	Ignored: the label stored is the one the phone system gives the caller ID

WriteResponse

Returned by every write, single or bulk.

Field	Type	Description
`dryRun`	boolean	Whether the request was a dry run
`results`	array of WriteResult	One per item, in request order. Each carries `index`, `id` (present exactly when the agent exists after the request), `agent`, `name`, `extension`, `email`, `type`, `status` (`CREATED` · `UPDATED` · `DELETED` · `REJECTED` · `VALID`), `facets`, `defaultOutboundCallerId`, `warnings`, `errors`, and `failures`
`summary`	object	Counts: `created`, `updated`, `deleted`, `rejected`, `valid`, and `withFailures` (items saved with at least one entry in `failures`)

Each result's facets reports profile, licenses, skillLevels, defaultOutboundCallerId, and welcomeEmail separately, each with a status of NOT_REQUESTED, APPLIED, DEFAULTED, VALID, REJECTED, NOT_APPLIED, or FAILED. See How Responses Work.

Problem

The application/problem+json body for every refusal the agent management endpoints make.

Field	Type	Description
`type`	string	A link to the guide section for this kind of refusal
`title`	string	The HTTP reason phrase
`status`	integer	The HTTP status
`detail`	string	For people; may change. Branch on `errors[].reason`
`errors`	array of AgentError	Each with `facet`, `field` (dotted path, or `null`), `reason`, `message`, and optional `details`
`dryRun`, `results`, `summary`		Present on item-level refusals of a single write only

Every reason value is listed under Errors.

SimpleError

The older error shape, used for 401, the 403 for a Service User without full access, 405, 406, 415, and every error from the two older endpoints.

Field	Type	Description
`exception`	string	The server's exception class name
`message`	string	For people

Limits

Limit	Description
Bulk size	500 agents per request. More returns `413 TOO_MANY_ITEMS`
Body size	10 MiB per request, by `Content-Length`, on every agent management endpoint. More returns `413 BODY_TOO_LARGE`
Concurrency	One agent write at a time per tenant. A second concurrent write returns `429 WRITE_IN_PROGRESS` — retry after a short wait, and never send writes in parallel
Caller ID checks	Up to 7 seconds per check and 30 seconds per request. A check that cannot run returns `502 CALLER_ID_CHECK_FAILED` with nothing saved

See API Limits & Statuses for statuses shared by every CCaaS API.

Data API — Agent Management — behavior, worked examples, and the full error reason list
Data API — Skills
API Service Users
API Limits & Statuses

Updated about 2 hours ago

Interactive Reference

Overview

Authentication

Writes Require Full Access

Identifying an Agent

Endpoints

List Licensed Agents

Parameters

Responses

Example Request

Example Response — 200 OK

Read One Agent

Parameters

Responses

Example Request

Example Response — 200 OK

License Seats

Parameters

Responses

Example Response — 200 OK

Create One Agent

Parameters

Request Body

Responses

Example Request

Create Many Agents

Parameters

Request Body

Responses

Edit One Agent

Parameters

Request Body

Responses

Edit Many Agents

Parameters

Request Body

Responses

Delete an Agent

Parameters

Request Body

Responses

Get Default Outbound Caller ID

Parameters

Responses

Example Response — 200 OK

Set Default Outbound Caller ID

Parameters

Request Body

Responses

Clear Default Outbound Caller ID

Parameters

Responses

List Outbound Caller IDs

Parameters

Responses

OpenAPI Description

Models

AgentList

Agent

AgentDetail

Profile

ConnectedNumber

NoAnswerOverflow

SkillLevel

SkillSettings

OutboundCallerId

OutboundCallerIdOptions

LicenseSeats

AgentCreate

AgentUpdate

AgentBulkCreate

AgentBulkUpdate

AgentDeleteConfirmation

CallerIdToSet

WriteResponse

Problem

SimpleError

Limits

Related Pages

Example Response — `200 OK`

Example Response — `200 OK`

Example Response — `200 OK`

Example Response — `200 OK`