The Skills API lets an external system read and maintain CCaaS skills — their settings and which agents belong to them — one skill at a time or up to 500 per request. This page is the endpoint-by-endpoint reference. For how writes behave and integration recipes, see Skill Management APIs.

Overview

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.

Identifying a Skill

Skills are addressed by their id (a UUID), not by name. List Skills returns every skill's id.

Endpoints

List Skills

GET /v1/skills

Lists every skill, sorted by name.

Parameters

Responses

Example Request

curl -L -X GET 'https://<hostname>.xima.cloud/rest/api/v1/skills' \
-H 'Authorization: Bearer <api_bearer_token>'

Example Response — 200 OK

{
  "skills": [
    {
      "id": "70f9cf55-0963-44b7-88de-cb154f1dc598",
      "name": "CC Sales",
      "extension": "2101",
      "isDefault": false
    },
    {
      "id": "28c4f023-a442-4f35-9a63-d65d82d6901d",
      "name": "CC Support",
      "extension": "2102",
      "isDefault": true
    }
  ]
}

Read One Skill

GET /v1/skills/{id}

Returns one skill in full — its settings and its agents. The settings object is the same shape the write endpoints accept, so a skill can be read, changed, and sent back.

Parameters

Responses

Example Response — 200 OK

The following example abbreviates settings:

{
  "id": "70f9cf55-0963-44b7-88de-cb154f1dc598",
  "name": "CC Sales",
  "extension": "2101",
  "isDefault": false,
  "settings": {
    "skillName": "CC Sales",
    "extension": "2101",
    "aliasNumbers": [],
    "priority": 10,
    "voiceSettings": {
      "routingAlgorithm": "LINEAR",
      "agentRingTimeSeconds": 30
    },
    "callbackSettings": {
      "callbackStrategy": "WAIT_IN_QUEUE"
    },
    "messagingSettings": {
      "inviteHeaderText": "Tell us about yourself"
    }
  },
  "agents": [
    {
      "agent": "Agent Kelly(556)",
      "name": "Agent Kelly",
      "extension": "556",
      "skillLevel": 10,
      "maxSimultaneousSessions": 2,
      "voiceEnabled": true,
      "chatEnabled": true,
      "emailEnabled": true
    }
  ]
}

Create a Skill

POST /v1/skills/create

Creates one skill. Only skillName is required; everything else takes a product default.

Parameters

Request Body

A SkillSettings object, optionally with an agents array of AgentMembership entries.

{
  "skillName": "Customer Care",
  "extension": "2091",
  "priority": 10,
  "voiceSettings": {
    "routingAlgorithm": "LINEAR",
    "agentRingTimeSeconds": 30
  },
  "callbackSettings": {
    "callbackStrategy": "WAIT_IN_QUEUE"
  },
  "agents": [
    {
      "agent": "Agent Kelly(556)",
      "skillLevel": 10
    }
  ]
}

Responses

Example Request

curl -L -X POST 'https://<hostname>.xima.cloud/rest/api/v1/skills/create' \
-H 'Authorization: Bearer <api_bearer_token>' \
-H 'Content-Type: application/json' \
-d '{"skillName":"Customer Care","extension":"2091"}'

Edit a Skill

PATCH /v1/skills/{id}

Edits one skill. Only the fields present change, at every level of nesting; an explicit null clears an optional setting. Lists and maps (aliasNumbers, cannedMessages, customChatText.customizations) are replaced whole. A skillName that differs from the current name is refused — skills cannot be renamed.

Parameters

Request Body

A SkillSettings object containing only the fields to change, optionally with an agents array of AgentMembership entries.

{
  "callbackSettings": {
    "callbackStrategy": "NO_QCB"
  }
}

Responses

Create and Edit Many Skills

PATCH /v1/skills

Creates and edits up to 500 skills in one request. In each item, id present means edit and id absent means create. A failing item does not stop the others, and skill destinations are resolved after every skill in the request has been applied, so items do not need to be ordered.

Parameters

Request Body

A SkillBulkWrite.

{
  "skills": [
    {
      "settings": {
        "skillName": "Overflow Team",
        "extension": "2400"
      }
    },
    {
      "id": "70f9cf55-0963-44b7-88de-cb154f1dc598",
      "settings": {
        "priority": 5
      },
      "agents": [
        {
          "agent": "Agent Kelly(556)",
          "skillLevel": 8
        }
      ]
    }
  ]
}

Responses

Delete a Skill

DELETE /v1/skills/{id}

Deletes one skill. The skill's extension must be sent in the body as confirmation — or, for a skill with no extension, its name.

Parameters

Request Body

A SkillDeleteConfirmation.

{
  "extension": "2101"
}

Responses

Models

SkillList

SkillSummary

SkillDetail

SkillSettings

All fields are optional except skillName on a create.

VoiceSettings

Destination

Used by queueTimeout, queueOverflow, maxCallsInQueue, clearCallsAtEndOfDay, and digitActions.

CallbackSettings

MessagingSettings

AgentMembership

One agent's membership in a skill. In a write, listed agents are added or updated and unlisted agents are left alone; send skillLevel: 0 to remove an agent.

An agent entry that matches more than one agent, or no licensed agent, is skipped with an IGNORED warning; the rest of the skill still writes.

SkillBulkWrite

SkillDeleteConfirmation

WriteResponse

Returned by every write, single or bulk.

Warning

A part of the write that was adjusted; the rest of the write happened.

Error

The body of a request-level failure. Nothing was written.

Limits

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

Related Pages

• Skill Management APIs — behavior and integration recipes
• Data API — Agents
• Manage Skills
• API Service Users
• API Limits & Statuses