Create an Agent

post

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

A create carries no default outbound caller ID (400 FIELD_NOT_ALLOWED_ON_CREATE): create the agent, then set it with PUT /api/v1/agents/{id}/default-outbound-caller-id. A create never asks the phone system, so it never returns 502. 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…

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

A new XIMA agent. No defaultOutboundCallerId: sending it is 400 FIELD_NOT_ALLOWED_ON_CREATE. Create the agent, then PUT its default. profile.id is ignored with a warning (the server assigns it). Unknown fields in an item, including agent, name, extension, type and email at the top level, are ignored with an IGNORED warning.

profile

object

required

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

The agent's complete set of licenses. Omit for the starter licenses the admin create gives (facet DEFAULTED). 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.

sendWelcomeEmail

boolean

Defaults to true

Headers

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Dry run: VALID.

201Created.

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.

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.