Create Agents

post

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

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, names, extensions and emails taken by earlier items count against later ones. The other statuses refuse the whole request. 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*

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

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.