Introduction
Assembled is a modern workforce management platform built for rapidly scaling support teams. We help you forecast support demand, build and manage team schedules, and uncover insights to improve your support operations.
The Assembled API is a general API for querying information from Assembled as well as sending information directly to Assembled. The API is built around REST and returns JSON-encoded responses.
Authentication
Example usage
curl "https://api.assembledhq.com/v0/agents" \
-u sk_live_abc123:
# The colon prevents curl from asking for a password.
The API uses API keys to authenticate requests. You can view your keys from the Settings → API page.
Test mode secret keys have the prefix sk_test_
and live mode secret keys have the prefix sk_live_
. Test mode requests will not be persisted and will not return live data.
Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. Bearer Auth is not currently supported.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Rate limiting
The Assembled API employs rate limits in order to maximize its stability. Users who send too many requests in quick succession may see error responses with status code 429
. By default, we allow 300 requests per minute (5 requests per second), with occasional bursts of up to 20 requests at a time. If your use case requires a higher limit, please contact us at support@assembled.com.
Versioning
Example usage
curl "https://api.assembledhq.com/v0/agents" \
-u sk_live_abc123:
-H "API-Version: 2019-06-20"
Assembled is commited to keeping the API as backwards compatible as possible. However, there are times when backwards incompatible changes are necessary. When making such changes to the API, we will release a new, dated version which will allow you to upgrade at your convenience. You may continue using the version of the API that you initially integrated and we will ensure that any resources or API semantics stay consistent with your API version.
To upgrade to a new version, you can begin by passing the API-Version
header in any API request. This will override the API version that you are currently on. Once you're ready to completely upgrade your version, please email support@assembled.com to have your version upgraded.
The API Changelog provides a complete list of API versions and the changes associated with each version.
Agents
Agents handle units of work and can be assigned to activities or schedules. They can be grouped by site and team and can be assigned to queues or channels based on their skills.
Agent object
{
"id": "<uuid>",
"import_id": "third_party_identifier",
"name": "Michael Scott",
"email": "michael@dundermifflin.com",
"channels": ["phone", "chat"],
"site": "<uuid>",
"teams": ["<uuid>", "<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"]
}
Field | Type | Description |
---|---|---|
id | uuid | |
import_id | string | Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems. |
name | string | |
string | ||
channels | list[string] | |
site | uuid | Unique identifier for associated site. |
teams | list[uuid] | Unique identifiers for associated teams. |
queues | list[uuid] | Unique identifiers for associated queues. |
skills | list[uuid] | Unique identifiers for associated skills. |
POST /v0/agents
Example request
curl "https://api.assembledhq.com/v0/agents" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{"name": "Michael Scott", "email": "michael@dundermifflin.com"}'
Example response
{
"id": "<uuid>",
"import_id": null,
"name": "Michael Scott",
"email": "michael@dundermifflin.com",
"channels": [],
"site": null,
"teams": [],
"queues": [],
"skills": []
}
Creates an agent profile with the specified parameters. Valid IDs for site, teams, and queues can be retrieved from endpoints for filters. This endpoint will return 400 if invalid IDs are provided.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
name | string | Required | |
string | Optional | ||
channels | list[string] | Optional | One of: "phone", "email", or "chat". |
site | uuid | Optional | Unique identifier for a site to associate. |
teams | list[uuid] | Optional | Unique identifiers for teams to associate. |
queues | list[uuid] | Optional | Unique identifiers for queues to associate. |
skills | list[uuid] | Optional | Unique identifiers for skills to associate. |
import_id | string | Optional | Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems. |
PATCH /v0/agents/:id
Example request
curl "https://api.assembledhq.com/v0/agents/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-X PATCH \
-u sk_live_abc123: \
-d '{"name": "Pam Beesly", "email": null}'
Example response
{
"id": "<uuid>",
"import_id": null,
"name": "Pam Beesly",
"email": null,
"channels": [],
"site": null,
"teams": [],
"queues": [],
"skills": []
}
Partial update of an agent with the specified fields. Fields that are not included in the request are not updated, while fields that are explicitly set to null or an appropriate empty value (for example, "[]" for lists) are set to empty. Valid IDs for site, teams, and queues can be retrieved from endpoints for filters. This endpoint will return 400 if invalid filter IDs are provided.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
name | string | Optional | |
string | Optional | ||
channels | list[string] | Optional | One of: "phone", "email", or "chat". |
site | uuid | Optional | Unique identifier for a site to associate. |
teams | list[uuid] | Optional | Unique identifiers for teams to associate. |
queues | list[uuid] | Optional | Unique identifiers for queues to associate. |
skills | list[uuid] | Optional | Unique identifiers for skills to associate. |
import_id | string | Optional | Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems. |
GET /v0/agents
Returns a list of agent objects that match the provided query.
Example request
curl "https://api.assembledhq.com/v0/agents" \
-u sk_live_abc123:
Example response
{
"agents": {
"<uuid>": {
"id": "<uuid>",
"import_id": "third_party_identifier",
"name": "Michael Scott",
"email": "michael@dundermifflin.com",
"channels": ["phone", "chat"],
"site": "<uuid>",
"teams": ["<uuid>", "<uuid>"],
"queues": ["<uuid>"]
},
...
}
}
Parameters:
Field | Type | Required | Description |
---|---|---|---|
channels | list[string] | Optional | One of: "phone", "email", or "chat". |
queue | string | Optional | Name of the queue to filter on. |
site | string | Optional | Name of the site to filter on. |
team | string | Optional | Name of the team to filter on. |
Agent States
Agents can have states that indicate what they are currently working on. For example, in a phone system an agent may be “available for calls”, “busy on a call”, or “wrapping up on a call.” These will be surfaced in our real-time dashboard to track the state of your team and in our reporting, to track agent and team performance.
Agent State object
{
"agent_import_id": "michael@dundermifflin.com",
"state": "online",
"start_time": 1546303260,
"end_time": 1549067400,
"platform": "api"
}
Field | Type | Description |
---|---|---|
agent_import_id | string | Unique identifier for the agent. This can be associated to agents in Assembled with the agent associations endpoint. |
state | string | Agent’s current status from upstream system e.g. "online", "away", or "busy". Values are not validated, but can be mapped to activity types on the Assembled application by an Administrator. |
start_time | timestamp, in seconds | Time when agent began their current state. |
end_time | timestamp, in seconds | Time when agent ended being in this state. |
platform | string | The platform that the agent state comes from e.g. "api", "zendesk_talk", or "kustomer". |
POST /v0/agents/state
Example request
curl "https://api.assembledhq.com/v0/agents/state" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{
"agent_import_id": "michael@dundermifflin.com",
"time": 1549065600,
"state": "online"
}'
Send the current state of an agent to Assembled. The agent will be considered to be in this state until a new state is provided.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
agent_import_id | string | Required | Unique identifier for the agent. This can be associated to agents in Assembled with the agent associations endpoint. |
time | timestamp, in seconds | Required | Current time at which agent is in the specified state. |
state | string | Optional | Agent’s current status from upstream system e.g. "online", "away", or "busy". Values are not validated, but can be mapped to activity types on the Assembled application by an Administrator. If this field is not supplied, this will end the last state provided, while not initiating a new state. |
GET /v0/agents/:agent_id/state
Example request
curl "https://api.assembledhq.com/v0/agents/8ce1939e-cc6c-48e8-b0ef-a2326b562082/state" \
-u sk_live_abc123:
Returns a list of agent state objects that match the provided query.
Example response
{
"agent_states": [
{
"agent_import_id": "michael@dundermifflin.com",
"state": "online",
"start_time": 1549065600,
"platform": "api"
},
]
}
Retrieves the current status of the specified agent.
POST /v0/agents/associations
Example request
curl "https://api.assembledhq.com/v0/agents/associations" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{
"agent_import_id": "michael@dundermifflin.com",
"agent_id": "<uuid>"
}'
Associates agent unique identifiers to agents in Assembled. If an association already exists with this agent_import_id, we will update the association with the newly specified agent_id.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
agent_import_id | string | Required | Unique identifier used in agent states. |
agent_id | uuid | Required | Unique identifier for an agent in Assembled. |
Activities
Agents can have scheduled activities that are either created directly in Assembled or sourced from other calendaring applications such as Google Calendar.
Activity object
{
"id": "<uuid>",
"agent_id": "<uuid of agent>",
"channels": ["phone"],
"type_id": "<uuid of activity_type>",
"start_time": 1546303260,
"end_time": 1546303270,
"description": null
}
Field | Type | Description |
---|---|---|
id | uuid | |
agent_id | uuid | Identifier for the corresponding agent. |
type_id | uuid | Identifier for the associated activity type. |
start_time | timestamp, in seconds | |
end_time | timestamp, in seconds | |
description | string | An arbitrary string to be displayed to end users. |
POST /v0/activities
Example request
curl "https://api.assembledhq.com/v0/activities" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d "{
\"start_time\": 1562223600,
\"end_time\": 1562259600,
\"agent_id\": \"<uuid>\",
\"type_id\": \"<uuid>\"
}"
Example response
{
"id": "<uuid>",
"start_time": 1562223600,
"end_time": 1562259600,
"description": null,
"agent_id": "<uuid>",
"type_id": "<uuid>"
}
Creates an activity with the specified parameters. Valid IDs for agents can be retrieved from the agent endpoints. Valid IDs for activity types can be retrieved from the activity types endpoints. This endpoint will return 400 if invalid IDs are provided.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
agent_id | uuid | Required | Unique identifier for an agent. |
type_id | uuid | Required | Unique identifier for an activity type. |
start_time | timestamp, in seconds | Required | |
end_time | timestamp, in seconds | Required | |
allow_conflicts | boolean | Optional | Whether or not to allow conflicting events. If true , this created activity will be allowed to have conflicts with other activities. If false , any overlapping activities for the specified agent will be deleted. Defaults to false . |
description | string | Optional | An arbitrary string to be displayed to end users. |
schedule_id | string | Optional | Identifier for the corresponding schedule. Defaults to the master schedule. |
POST /v0/activities/bulk
Example request
curl "https://api.assembledhq.com/v0/activities/bulk" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d "{
\"activities\": [
{
\"action\": \"create\",
\"activity\": {
\"start_time\": 1562223600,
\"end_time\": 1562259600,
\"agent_id\": \"<uuid>\",
\"type_id\": \"<uuid>\"
}
}
]
}"
Example response
{
"activities": {
"<uuid>": {
"id": "<uuid>",
"start_time": 1562223600,
"end_time": 1562259600,
"agent_id": "<uuid>",
"type_id": "<uuid>"
},
}
}
Creates, updates, or deletes multiple activities in a single request. A given request occurs within a transaction, so in the event of an error during the request, it should be assumed that no changes were processed.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
activities | list[BulkRequest] | Required | An array of requests following the format below. |
schedule_id | string | Optional | Identifier for the corresponding schedule. Defaults to the master schedule. |
Bulk Request Parameters:
Field | Type | Required | Description |
---|---|---|---|
action | string | Required | One of create , update , or delete . Note that update and delete are currently in beta. Contact us at support@assembled.com to be notified of updates. |
activity | Activity | Required | See documentation for the Activity object. Note that the allow_conflicts parameter is not supported in the bulk endpoint. |
GET /v0/activities
Example request
curl "https://api.assembledhq.com/v0/activities?start_time=1562223600&end_time=1562259600" \
-u sk_live_abc123: -X GET
Example response
{
"activities": {
"<uuid>": {
"id": "<uuid>",
"start_time": 1562223600,
"end_time": 1562259600,
"agent_id": "<uuid>",
"type_id": "<uuid>"
},
...
},
"agents": {
"<uuid>": {
"id": "<uuid>",
"name": "Michael Scott",
...
}
},
"queues": {
"<uuid>": {
"id": "<uuid>",
"name": "Queue Name"
}
}
}
Returns a list of activity objects that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | timestamp, in seconds | Required | |
end_time | timestamp, in seconds | Required | Together with start_time, this determines the interval for which shifts will be retrieved. |
schedule_id | uuid | Optional | Identifier for the corresponding schedule. Defaults to the master schedule. |
include_activity_types | boolean | Optional | If true, include activity types active on the account. Defaults to false . |
include_agents | boolean | Optional | If true, include associated agent objects. Defaults to false . |
team | string | Optional | Filter results to a specific team. |
channel | string | Optional | Filter results to a specific channel. |
types | list[uuid] | Optional | Filter results to a specific set of types. |
agents | list[uuid] | Optional | Filter results to a specific set of agents. |
DELETE /v0/activities
Example request
curl "https://api.assembledhq.com/v0/activities" \
-X DELETE \
-u sk_live_abc123: \
-d "{
\"start_time\": 1562223600,
\"end_time\": 1562259600,
\"agent_ids\": [\"<uuid>\"]
}"
Example response
{
"activities": {
"<uuid>": {
"id": "<uuid>",
"start_time": 1562223600,
"end_time": 1562259600,
"agent_id": "<uuid>",
"type_id": "<uuid>"
},
...
},
}
Deletes all activities that match the specified parameters. Valid IDs for agents can be retrieved from the agent endpoints. This endpoint will return 400 if invalid IDs are provided.
Activities can be partially deleted. For example, if agent XYZ has an activity from 3pm-5pm and the deletion window is from 4pm-5pm, there will still exist a 3-4pm activity for agent XYZ after the deletion is completed.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | timestamp, in seconds | Required | The start of the deletion window. |
end_time | timestamp, in seconds | Required | The end of the deletion window. |
agent_ids | list[uuid] | Required | Unique identifiers for agents. All activities in the deletion window will be deleted for each specified agent. |
schedule_id | string | Optional | Identifier for the corresponding schedule. Defaults to the master schedule. |
Activity Types
Activity types represent a categorization of different activities. Currently they are only editable via the dashboard.
Activity Type object
{
"id": "<uuid>",
"import_id": "third_party_identifier",
"name": "Shift",
"short_name": "S",
"value": "shift",
"channels": ["email"],
"productive": true,
"timeoff": false,
"background_color": "#ffffff",
"font_color": "#ffffff"
}
Field | Type | Description |
---|---|---|
id | uuid | |
import_id | string | Third-party identifier. Supplied to Assembled and is used to uniquely identify activity types across different systems. |
name | string | |
short_name | string | |
value | string | Corresponds to type in the Activity object, will be deprecated in a future API version. |
channels | list[string] | Channels associated with the activity. Must be non-empty when the the activity is productive. |
productive | boolean | If true, timeoff must be false. |
timeoff | boolean | If true, productive must be false. |
background_color | string | Hex string. |
font_color | string | Hex string. |
GET /v0/activity_types
Example request
curl "https://api.assembledhq.com/v0/activity_types" \
-u sk_live_abc123:
Example response
{
"activity_types": {
"<uuid>": {
"id": "<uuid>",
"import_id": "third_party_identifier1",
"name": "Break",
"short_name": "B",
"value": "break",
"channels": [],
"productive": false
},
"<uuid>": {
"id": "<uuid>",
"import_id": "third_party_identifier2",
"name": "Shift",
"short_name": "S",
"value": "shift",
"channels": ["email"],
"productive": true
}
}
}
Returns a list of all activity type objects configured on the account.
POST /v0/activity_types
Example request
curl "https://api.assembledhq.com/v0/activity_types" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{ "name": "Break", "short_name": "B", "timeoff": true }'
Example response
{
"id": "<uuid>",
"import_id": null,
"name": "Break",
"short_name": "B",
"value": "break",
"channels": [],
"productive": false,
"timeoff": true,
"background_color": "#ffffff",
"font_color": "#000000"
}
Creates an activity type with the specified parameters.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
name | string | Required | |
channels | list[string] | Required | Channels associated with the activity. Must be non-empty when the the activity is productive. |
short_name | string | Optional | |
productive | boolean | Optional | If true, timeoff must be false. |
timeoff | boolean | Optional | If true, productive must be false. |
background_color | string | Optional | Hex string. |
font_color | string | Optional | Hex string. |
import_id | string | Optional | Third-party identifier. Supplied to Assembled and is used to uniquely identify activity types across different systems. |
DELETE /v0/activity_types/:id
Example request
curl "https://api.assembledhq.com/v0/activity_types/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-u sk_live_abc123: -X DELETE
Deletes an activity type.
Conversations
Conversations represent a unit of work. They are typically created when a customer and a support agent exchange their first message. Forecasts will be generated based on historical conversation volume.
Conversation object
{
"created_at": 1549065600,
"import_id": "122308400000062",
"channel": "phone",
"status": "solved",
"queue": "<uuid>",
"first_responded_at": 1549065700,
"solved_at": 1549065800,
"assignee_import_id": "d613ab77-75f7-4fce-91d8-f9ef5fe55066",
}
Field | Type | Required | Description |
---|---|---|---|
created_at | timestamp, in seconds | Required | Time the conversation was created. |
import_id | string | Required | Third-party identifier. Must be unique to the conversation. |
channel | string | Required | One of: "phone", "email", or "chat". |
status | string | Required | One of: "open", "pending", or "solved". |
queue | uuid | Optional | Unique identifier for the corresponding queue. |
first_responded_at | timestamp, in seconds | Optional | Time the conversation was first responded to by an agent. |
solved_at | timestamp, in seconds | Optional | Time the conversation was solved or closed. |
assignee_import_id | string | Optional | Third-party identifier for the agent currently assigned to the conversation. |
POST /v0/conversations/bulk
Example request
curl "https://api.assembledhq.com/v0/conversations/bulk" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d "{
\"conversations\": [
{
\"created_at\": 1549065600,
\"import_id\": \"122308400000062\",
\"channel\": \"phone\",
\"status\": \"solved\",
\"queue\": \"<uuid>\",
\"first_responded_at\": \"1549065700\"
\"solved_at\": \"1549065800\"
\"assignee_import_id\": \"d613ab77-75f7-4fce-91d8-f9ef5fe55066\"
}
]
}"
Creates or overwrites a conversation with the specified parameters.
Bulk Request Parameters:
Field | Type | Required | Description |
---|---|---|---|
conversations | list[Conversation] | Required | See documentation for the Conversation object. |
Filters
Filters can be used to categorize or group agents as well as activities.
Filter objects
{
"id": "<uuid>",
"name": "Queue name",
"parent_id": "<uuid>",
"created_at": 123456,
"updated_at": 123456
}
Field | Type | Description |
---|---|---|
id | uuid | |
name | string | Identifier for the filter. |
parent_id | uuid | Identifier for the parent filter. May be null. |
created_at | timestamp, in seconds | Time of creation, in Unix time. |
updated_at | timestamp, in seconds | Time of last update, in Unix time. |
GET /v0/queues
Example request
curl "https://api.assembledhq.com/v0/queues" \
-u sk_live_abc123:
Example response
{
...
"queues": {
"<uuid>": {
"id": "<uuid>",
"name": "Queue Name",
"parent_id": "<uuid>",
"created_at": 123456,
"updated_at": 123456
}
}
}
Returns a list of all queue objects configured on the account.
GET /v0/sites
Example request
curl "https://api.assembledhq.com/v0/sites" \
-u sk_live_abc123:
Example response
{
...
"sites": {
"<uuid>": {
"id": "<uuid>",
"name": "Site Name",
"parent_id": "<uuid>",
"created_at": 123456,
"updated_at": 123456
}
}
}
Analogous to GET /v0/queues
GET /v0/teams
Example request
curl "https://api.assembledhq.com/v0/teams" \
-u sk_live_abc123:
Example response
{
"teams": {
"<uuid>": {
"id": "<uuid>",
"name": "Team Name",
"parent_id": "<uuid>",
"created_at": 123456,
"updated_at": 123456
}
}
}
Analogous to GET /v0/queues
GET /v0/skills
Example request
curl "https://api.assembledhq.com/v0/skills" \
-u sk_live_abc123:
Example response
{
"skills": {
"<uuid>": {
"id": "<uuid>",
"name": "Skill Name",
"parent_id": "<uuid>",
"created_at": 123456,
"updated_at": 123456
}
}
}
Analogous to GET /v0/queues
POST /v0/queues
Example request
curl "https://api.assembledhq.com/v0/queues" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{ "queues" : [{ "name": "Queue Name", "parent_id": "<uuid_parent>"}, { "name": "Queue Name2" } ] }'
Example response
{
...
"queues": {
"<uuid>": {
"id": "<uuid>",
"name": "Queue Name",
"parent_id": "<uuid_parent>",
"created_at": 123456,
"updated_at": 123456
},
"<uuid2>": {
"id": "<uuid2>",
"name": "Queue Name2",
"parent_id": null,
"created_at": 123456,
"updated_at": 123456
}
}
}
Creates queue objects in bulk.
POST /v0/sites
Example request
curl "https://api.assembledhq.com/v0/sites" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{ "sites" : [{ "name": "Site Name", "parent_id": "<uuid_parent>"}, { "name": "Site Name2" } ] }'
Example response
{
...
"sites": {
"<uuid>": {
"id": "<uuid>",
"name": "Site Name",
"parent_id": "<uuid_parent>",
"created_at": 123456,
"updated_at": 123456
},
"<uuid2>": {
"id": "<uuid2>",
"name": "Site Name2",
"parent_id": null,
"created_at": 123456,
"updated_at": 123456
}
}
}
Analogous to POST /v0/queues
POST /v0/teams
Example request
curl "https://api.assembledhq.com/v0/teams" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{ "teams" : [{ "name": "Team Name", "parent_id": "<uuid_parent>"}, { "name": "Team Name2" } ] }'
Example response
{
...
"teams": {
"<uuid>": {
"id": "<uuid>",
"name": "Team Name",
"parent_id": "<uuid_parent>",
"created_at": 123456,
"updated_at": 123456
},
"<uuid2>": {
"id": "<uuid2>",
"name": "Team Name2",
"parent_id": null,
"created_at": 123456,
"updated_at": 123456
}
}
}
Analogous to POST /v0/queues
POST /v0/skills
Example request
curl "https://api.assembledhq.com/v0/skills" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{ "skills" : [{ "name": "Skill Name", "parent_id": "<uuid_parent>"}, { "name": "Skill Name2" } ] }'
Example response
{
...
"skills": {
"<uuid>": {
"id": "<uuid>",
"name": "Skill Name",
"parent_id": "<uuid_parent>",
"created_at": 123456,
"updated_at": 123456
},
"<uuid2>": {
"id": "<uuid2>",
"name": "Skill Name2",
"parent_id": null,
"created_at": 123456,
"updated_at": 123456
}
}
}
Analogous to POST /v0/queues
DELETE /v0/queues
Example request
curl "https://api.assembledhq.com/v0/queues" \
-u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "queue_ids": ["<uuid1>", "<uuid2>"] }'
Deletes queue objects in bulk.
DELETE /v0/sites
Example request
curl "https://api.assembledhq.com/v0/sites" \
-u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "site_ids": ["<uuid1>", "<uuid2>"] }'
Analogous to DELETE /v0/queues
DELETE /v0/teams
Example request
curl "https://api.assembledhq.com/v0/teams" \
-u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "team_ids": ["<uuid1>", "<uuid2>"] }'
Analogous to DELETE /v0/queues
DELETE /v0/skills
Example request
curl "https://api.assembledhq.com/v0/skills" \
-u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "skill_ids": ["<uuid1>", "<uuid2>"] }'
Analogous to DELETE /v0/queues
PUT /v0/queues/:id
Example request
curl "https://api.assembledhq.com/v0/queues/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-H "Content-Type: application/json" \
-X PUT \
-u sk_live_abc123: \
-d '{ "name": "Queue Name", "parent_id": "<uuid_parent>" }'
Updates a single queue object to the specified name and parent_id. If the parent_id in the request is null, the queue parent will be set to null.
PUT /v0/sites/:id
Example request
curl "https://api.assembledhq.com/v0/sites/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-H "Content-Type: application/json" \
-X PUT \
-u sk_live_abc123: \
-d '{ "name": "Site Name", "parent_id": "<uuid_parent>" }'
Analogous to PUT /v0/queues/:external_id
PUT /v0/teams/:id
Example request
curl "https://api.assembledhq.com/v0/teams/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-H "Content-Type: application/json" \
-X PUT \
-u sk_live_abc123: \
-d '{ "name": "Team Name", "parent_id": "<uuid_parent>" }'
Analogous to PUT /v0/queues/:external_id
PUT /v0/skills/:id
Example request
curl "https://api.assembledhq.com/v0/skills/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-H "Content-Type: application/json" \
-X PUT \
-u sk_live_abc123: \
-d '{ "name": "Skill Name", "parent_id": "<uuid_parent>" }'
Analogous to PUT /v0/queues/:external_id
Forecasts
Forecasts represent predicted volume within a given time window. They are associated with a channel and, optionally, a queue.
Forecast object
{
"start_time": 1549065600,
"end_time": 1549066500,
"channel": "phone",
"queue": "<uuid>",
"value": 42.0
}
Field | Type | Description |
---|---|---|
start_time | timestamp, in seconds | |
end_time | timestamp, in seconds | |
channel | string | One of: "phone", "email", or "chat". |
queue | uuid | Unique identifier for the corresponding queue. |
value | float | The number of contacts forecasted for the time interval. |
GET /v0/forecasts
Example request
curl "https://api.assembledhq.com/v0/forecasts?start_time=1549065600&end_time=1549069200" \
-X GET \
-u sk_live_abc123:
Example response
{
"forecasts": [
{
"start_time": 1549065600,
"end_time": 1549066500,
"channel": "chat",
"queue": "<uuid>",
"value": 42.0
},
...
],
}
Returns a list of forecast objects that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | timestamp, in seconds | Required | |
end_time | timestamp, in seconds | Required | Together with start_time, this determines the interval for which forecasts will be retrieved. |
channel | string | Required | One of: "phone", "email", or "chat". |
queue | uuid | Optional | Unique identifier for a queue to associate. |
POST /v0/forecasts/bulk
Example request
curl "https://api.assembledhq.com/v0/forecasts/bulk" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d "{
\"forecasts\": [
{
\"start_time\": 1549065600,
\"end_time\": 1549069200,
\"channel\": \"chat\",
\"queue\": \"<uuid>\",
\"value\": \"42.0\"
}
]
}"
Example response
{
"forecasts": [
{
"id": "<uuid>",
"start_time": 1562223600,
"end_time": 1562259600,
"channel": "chat",
"queue": "<uuid>",
"value": 42.0
},
...
]
}
Creates or overwrites a forecast with the specified parameters.
Bulk Request Parameters:
Field | Type | Required | Description |
---|---|---|---|
forecasts | list[Forecast] | Required | See documentation for the Forecast object. |
Requirements
Requirements represent a set of staffing requirements and grouped staffing against the requirement within a given time window. They correspond to metrics about required staffing and scheduled staffing that appear above the team calendar.
Requirement object
{
"requirement_type_id": "<uuid>",
"required": 42.0,
"scheduled": 42.0,
"start_time": 1549065600,
"end_time": 1549066500
}
Field | Type | Description |
---|---|---|
requirement_type_id | uuid | Unique identifier for the corresponding requirement type. |
required | float | Count of required staffing in the interval, can be partial. |
scheduled | float | Count of scheduled staffing in the interval, can be partial. |
start_time | timestamp, in seconds | |
end_time | timestamp, in seconds |
POST /v0/requirements
Example request
curl "https://api.assembledhq.com/v0/requirements" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{"requirement_type_id": "<uuid>", "start_time": 1549065600, "end_time": 1549069200, "required": 42.0}'
Creates or overwrites a requirement with the specified parameters.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
requirement_type_id | uuid | Required | |
required | float | Required | |
start_time | timestamp, in seconds | Required | Must be a multiple of the configured interval e.g. 3600 for 1 hour or 900 for 15 minutes. |
end_time | timestamp, in seconds | Required | Must be a multiple of the configured interval as above. The difference with start_time must also equal the interval. |
GET /v0/requirements
Example request
curl "https://api.assembledhq.com/v0/requirements?start_time=1549065600&end_time=1549066500" \
-X POST \
-u sk_live_abc123:
Example response
{
"requirements": [
{
"requirement_type_id": "<uuid>",
"required": 42.0,
"scheduled": 42.0,
"start_time": 1549065600,
"end_time": 1549066500
},
...
],
}
Returns a list of requirement objects that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | timestamp, in seconds | Required | |
end_time | timestamp, in seconds | Required | Together with start_time, this determines the interval for which requirements will be retrieved. |
requirement_types | list[uuid] | Optional | Filter results to a specific set of requirement types. |
Requirement Types
Requirement types contain metadata about a named set of staffing requirements. The API supports two types of requirements: 1. Those that apply to a set of activity types. In this case, all activities with the corresponding type would count as scheduled against the requirement. 2. Those that apply to an entire channel and, optionally, a queue. In this case, all activities from agents with a matching channel and, if relevant, queue would count as scheduled.
Requirement types cannot simultaneously apply to both activity types and a channel and queue.
Requirement Type object
{
"id": "<uuid>",
"name": "Requirement",
"activity_type_ids": ["<uuid>", "<uuid>", ...],
"channel": "chat",
"queue": "<uuid>",
}
Field | Type | Description |
---|---|---|
id | uuid | |
name | string | |
activity_type_ids | list[uuid] | If provided, a list of identifiers for activity types that the requirement type applies to. |
channel | string | If provided, the channel that the requirement type applies to. |
queue | uuid | If provided, an identifier for the queue that the requirement type applies to. |
GET /v0/requirement_types
Example request
curl "https://api.assembledhq.com/v0/requirement_types" \
-u sk_live_abc123:
Example response
{
"requirement_types": {
"<uuid>": {
"id": "<uuid>",
"name": "Chat",
"activity_type_ids": ["<uuid>", "<uuid>"],
"channel": "chat",
"queue": "<uuid>"
}
}
}
Returns a list of all requirement type objects configured on the account.
Changelog
The changelog provides a list of dated versions, each containing a number of backwards-incompatible changes. The versions provide a way for Assembled to update the API without breaking past integrations. New additions and forward-compatible changes don’t need a new API version and will not appear in this list. The latest API version is 2019-06-20
.
2019-06-20
- Resource:
activity
- Activity resources will now return a unix timestamp (in seconds) for
start_time
andend_time
instead of a formatted string. Additionally, thetype
andchannels
properties have been deprecated. You should be able to find this information for a particular Activity by looking at the associated Activity Type resource using thetype_id
.
- Activity resources will now return a unix timestamp (in seconds) for
- Resource:
activity_type
- Activity Type resources will now return a
channels
property which will include the channels that are associated with a particular Activity Type. This takes the place of displayingchannels
on each Activity resource.
- Activity Type resources will now return a
2019-02-22
- Initial API Version