Edit Agents

patch

https://{tenant}/rest/api/v1/agents

200 with a result for each item once the request is processed: each item reports its own status, and a refused item does not stop the others. Items are applied in order on one settings save, so seats taken by earlier items count against later ones. The other statuses refuse the whole request. If an 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. The body takes only dryRun and agents: any other key, or a dryRun query parameter, refuses the whole request with 400 MALFORMED_BODY, so a misspelled dryRun can never save for real. Every saved create or edit that changes a XIMA agent's settings pushes the agent's login to the login portal (asynchronously), as the admin edit does. A caller-ID-only edit changes no settings and pushes nothing.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Only dryRun and agents. Any other key is refused with 400 MALFORMED_BODY, and so is a dryRun query parameter: a bulk dry run is dryRun in this body.

dryRun

boolean

Defaults to false

Validate every item and report what would happen, without saving anything. Must be a boolean.

agents

array of objects

required

length between 1 and 500

1 to 500 agents. An empty or missing list is 400 MALFORMED_BODY; more than 500 is 413 TOO_MANY_ITEMS.

agents*

Only the fields present change. agent, name, extension, type and email are accepted read only, so a fetched agent can be sent back; a differing value is ignored with a warning. sendWelcomeEmail is ignored with a warning. Unknown fields in an item are ignored with an IGNORED warning.

string

Required in a bulk edit: the XIMA agent's id or the exact name(extension). On PATCH /{id} it must match the path if sent.

profile

object

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 lists (connectedNumbers) are replaced whole. An unknown key, at any depth, is not applied and is reported as an IGNORED warning (profile.). The rules are the web interface's agent editor's.

licenses

array of strings

Replaces this agent's licenses with exactly this set; other agents are untouched. Omitted, the licenses are left alone, except that an edit carrying a profile re-adds the starter licenses if the agent has lost them, as saving the agent in the web interface does: send licenses in the same edit to control them exactly. Names are 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 and CCAAS_QA_EVALUATION, or UCAAS_* names on UCaaS licensing. Read an agent to see the names your tenant uses.

licenses

skillLevels

array of objects

skillLevels

skillSettings

object

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.

defaultOutboundCallerId

A caller ID, the {label, outboundCallerId} shape GET returns (label ignored; an outboundCallerId of null clears), or null to clear. A value equal to the agent's current default is not a change and is not checked. Any other value is checked with the phone system before anything is saved. An empty string is 400 CALLER_ID_REQUIRED.

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

Language

Credentials

Bearer

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

application/problem+json

200Per-item results.

400The request, or a single write's item, is invalid. Nothing was saved.

401Missing or invalid token. The older error shape. On the agent management endpoints a 413 BODY_TOO_LARGE is decided before the token is checked.

413TOO_MANY_ITEMS: more than 500 agents in the body. BODY_TOO_LARGE: the Content-Length header is over 10 MiB (a chunked body without one is not counted). Nothing was saved. Split the batch.

429WRITE_IN_PROGRESS: another agent write is running on this tenant. Agent writes run one at a time and are not queued. Nothing was saved. Retry after a short wait; parallel writes only produce more 429s.

503SETTINGS_BUSY: another settings save, from the web interface or another API, held the tenant's settings lock for too long. Nothing was saved. Retry.