Edit an Agent

patch

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

A defaultOutboundCallerId is checked with the phone system before anything is saved: 409 CALLER_ID_NOT_ALLOWED or CALLER_ID_NO_LABEL when the agent may not use it, 502 with nothing saved when the check cannot run. 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…

Path Params

string

required

A XIMA agent's id, or the exact name(extension) of a XIMA or UC agent, URL-encoded.

Query Params

dryRun

boolean

Defaults to false

Check everything a real write would and save nothing. For an edit that changes a caller ID that includes the check with the phone system; a create carries no caller ID, so its dry run never asks. A dry-run create reports no id. The bulk endpoints refuse this parameter: send dryRun in the body.

Body Params

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

200UPDATED, or VALID for a dry run. Check failures.

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.

404AGENT_NOT_FOUND: no agent with that id or name(extension).

409A conflict with stored configuration, a seat limit, an ambiguous identifier, or a caller ID the agent may not use. Nothing was saved.

413BODY_TOO_LARGE: the request's Content-Length header is over 10 MiB, so it was refused before the body was parsed or the token checked. A chunked body without a Content-Length is not counted. May lack the Link header.

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.