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/people" \
-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.
All API keys have the prefix sk_live_
.
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/people" \
-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.
People
People handle units of work and can be assigned to events on the Staffing Timeline. They can be grouped by sites or teams and can be assigned to queues or channels based on their skills (which are defined by the managers).
People object
{
"id": "<uuid>",
"agent_id": "string",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"imported_id": "third_party_identifier",
"roles": ["<uuid>"],
"agent_role": "string",
"channels": ["email", "chat", "phone", "social", "sms"],
"site": "<uuid>",
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"],
"platforms": {
"zendesk": "string",
"api": "string"
},
"start_date": 1546303260,
"end_date": 1546303260,
"created_at": 1546303260,
"deleted": false,
"staffable": false
}
Field | Type | Description |
---|---|---|
id | uuid | |
agent_id | uuid | Identifier on Assembled used to uniquely identify the agent related to the Person |
first_name | string | |
last_name | string | |
string | ||
imported_id | string | Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems |
roles | list[uuid] | Unique identifiers for the roles assigned to this Person |
agent_role | string | Person's agent role on Assembled. Supported values are: Agent , Admin |
channels | list[string] | List of channels associated with the Person. Supported values are: ['email', 'phone', 'chat', 'sms', 'social'] . The channels must match what is configured on the Assembled dashboard |
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 |
platforms | map[string]string | A map of unique identifiers from the different platforms that the agent is associated with, keyed on the platform name. Possible platforms include intercom , kustomer , salesforce , twilio , ukg , ujet , zendesk , zendesk_chat , zendesk_talk and api |
start_date | UNIX timestamp, in seconds | Person's start date specified by the user on creation |
end_date | UNIX timestamp, in seconds | Person's end date used to indicate when they can no longer be scheduled. Usually, this field is used to preserve agent data in the event of a role change into a non-staffable role or the termination of their contract |
created_at | UNIX timestamp, in seconds | |
deleted | boolean | Flag that indicates whether the Person has been soft deleted |
staffable | boolean | Indicates whether the Person can be scheduled |
GET /v0/people
Returns a collection of Persons based on the query parameters (if provided)
Example request
curl "https://api.assembledhq.com/v0/people" \
-u sk_live_abc123
Example response
{
"teams": {
"<uuid>": {
"id": "<uuid>",
"name": "string",
"parent_id": "<uuid>",
"created_at": 1546303260,
"updated_at": 1546303260
}
},
"sites": {
"<uuid>": {
"id": "<uuid>",
"name": "string",
"parent_id": "<uuid>",
"created_at": 1546303260,
"updated_at": 1546303260
}
},
"people": {
"<uuid>": {
"id": "<uuid>",
"agent_id": "string",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"imported_id": "third_party_identifier",
"roles": ["<uuid>"],
"agent_role": "string",
"channels": ["email", "chat", "phone", "social", "sms"],
"site": "<uuid>",
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"],
"platforms": {
"zendesk": "string",
"api": "string"
},
"start_date": 1546303260,
"end_date": 1546303260,
"created_at": 1546303260,
"deleted": false,
"staffable": false
}
},
"total": 26,
"limit": null,
"offset": null
}
Query parameters:
Field | Type | Required | Description |
---|---|---|---|
channel | list[string] | Optional | One of phone , email , chat , sms or social . The channel must exist on the Assembled dashboard |
team | uuid | Optional | Unique identifier for a team. Returns people who are part of this team. |
site | uuid | Optional | Unique identifier for a site. Returns people who are part of this site. |
restricted_site | uuid | Optional | Unique identifier for a site. Returns people who are part of this restricted site. Note: Restricted site must be enabled for your company. |
queue | uuid | Optional | Unique identifier for a queue. Returns people who are part of this queue. |
skill | uuid | Optional | Unique identifier for a skill. Returns people who have this skill. |
role | uuid | Optional | Unique identifier for a role. Returns people who are assigned this role. |
include_deleted | boolean | Optional | If true , also includes Persons that have been soft-deleted |
search | string | Optional | Searches Persons based on first_name , last_name or email |
sort_by | string | Optional | Allows for sorting of Persons based on first_name , last_name , or role |
sort_direction | string | Optional | Required if used with sort_by . Supported values: ascending , descending |
limit | int | Optional | 20 responses are returned by default, but the maximum value is 500 |
offset | int | Optional | Adds an offset to the responses returned, starting from 0 |
GET /v0/people/:id
Returns a Person based on the id
provided
Example request
curl "https://api.assembledhq.com/v0/people/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-u sk_live_abc123
Example response
{
"id": "<uuid>",
"agent_id": "string",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"imported_id": "third_party_identifier",
"roles": ["<uuid>"],
"agent_role": "string",
"channels": ["email", "chat", "phone", "social", "sms"],
"site": "<uuid>",
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"],
"platforms": {
"zendesk": "string",
"api": "string"
},
"start_date": 1546303260,
"end_date": 1546303260,
"created_at": 1546303260,
"deleted": false,
"staffable": false
}
POST /v0/people
Creates People with the specified parameters. Valid IDs for site, teams, and queues can be retrieved from endpoints for filters, or via GET /people. This endpoint will return a 400 if invalid IDs for site, teams, or queues are provided.
We allow creating People in bulk, as well as individually
Example request (single Person creation)
curl "https://api.assembledhq.com/v0/people" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d \
'{
"people": [
{
"imported_id": "",
"first_name": "Alice",
"last_name": "Example",
"email": "alice@example.com",
"timezone": "America/Los_Angeles",
"role": "<uuid>",
"staffable": true,
"channels": [
"email", "chat", "phone"
]
}
]
}'
Example response (single Person creation)
{
"id": "<uuid>",
"agent_id": "<uuid>",
"first_name": "Alice",
"last_name": "Example",
"email": "alice@example.com",
"timezone": "",
"imported_id": "<uuid>",
"roles": ["<uuid>"],
"agent_role": "agent",
"channels": ["email"],
"site": null,
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"platforms": {},
"skills": ["<uuid>"],
"start_date": 1647930594,
"end_date": 1647940000,
"created_at": 1648502490,
"deleted": false,
"staffable": false
}
Example request (multiple Person creation)
curl "https://api.assembledhq.com/v0/people" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d \
'{
"people": [
{
"imported_id": "",
"first_name": "Alice",
"last_name": "Example",
"email": "alice@example.com",
"timezone": "America/Los_Angeles",
"role": "<uuid>",
"staffable": true,
"channels": [
"email", "chat", "phone"
]
},
{
"imported_id": "",
"first_name": "Bob",
"last_name": "Example",
"email": "bob@example.com",
"timezone": "America/Los_Angeles",
"role": "<uuid>",
"staffable": true,
"channels": [
"email", "chat", "phone"
]
}
]
}'
Example response (multiple Person creation)
{
"people": [
{
"id": "<uuid>",
"agent_id": "<uuid>",
"first_name": "Alice",
"last_name": "Example",
"email": "alice@example.com",
"timezone": "",
"imported_id": "<uuid>",
"roles": ["<uuid>"],
"agent_role": "agent",
"channels": ["email"],
"site": null,
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"platforms": {},
"skills": ["<uuid>"],
"start_date": 1647930594,
"end_date": 1647940000,
"created_at": 1648502490,
"deleted": false,
"staffable": false
},
{
"id": "<uuid>",
"agent_id": "<uuid>",
"first_name": "Bob",
"last_name": "Example",
"email": "bob@example.com",
"timezone": "",
"imported_id": "<uuid>",
"roles": ["<uuid>"],
"agent_role": "agent",
"channels": ["email"],
"site": null,
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"platforms": {},
"skills": ["<uuid>"],
"start_date": 1647930594,
"end_date": 1647940000,
"created_at": 1648502490,
"deleted": false,
"staffable": false
}
]
}
Parameters:
Field | Type | Required | Description |
---|---|---|---|
imported_id | string | Optional | The ID of the Person that you are creating |
first_name | string | Required | |
last_name | string | Required | |
string | Required | ||
timezone | string | Required | The timezone for the particular Person, based off the IANA timezone strings (e.g America/New_York) |
role | uuid | Required | Unique identifier for the role to assign to this Person |
restricted_sites | list[uuid] | Optional | Restricts the person to only view resources associated with these sites. Values must be valid site IDs |
staffable | boolean | Required | Indicates whether the Person can be scheduled |
channels | list[string] | Optional | One of phone , email , chat , sms or social . The channel must exist on the Assembled dashboard |
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 |
platforms | map[string]string | Optional | A map of unique identifiers from the different platforms that the agent is associated with, keyed on the platform name. Possible platforms include intercom , kustomer , salesforce , twilio , ujet , zendesk , zendesk_chat , and zendesk_talk |
start_date | UNIX timestamp, in seconds | Optional | Person's start date specified by the user on creation |
end_date | UNIX timestamp, in seconds | Optional | Person's end date used to indicate when they can no longer be scheduled. Usually, this field is used to preserve agent data in the event of a role change into a non-staffable role or the termination of their contract |
send_invite_email | boolean | Optional | Indicates whether or not to send the Person an invite e-mail to Assembled |
PATCH /v0/people/:id
Example request
curl "https://api.assembledhq.com/v0/people/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-X PATCH \
-u sk_live_abc123: \
-d '{
"id": "<uuid>",
"agent_id": "<uuid>",
"first_name": "John",
"last_name": "Smith",
"email": "john@smith.com",
"timezone": "",
"import_id": "<uuid>",
"role": "<uuid>",
"agent_role": "agent",
"channels": ["email"],
"site": null,
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"],
"platforms": {
}
"start_date": 1647930594,
"end_date": 1647940000,
"created_at": 1648502490,
"staffable": false
}'
Example response
{
"message": "person successfully updated",
"people": [
{
"id": "<uuid>",
"agent_id": "<uuid>",
"first_name": "string",
"last_name": "string",
"email": "string",
"timezone": "string",
"imported_id": "string",
"roles": ["<uuid>"],
"agent_role": "agent",
"channels": ["email"],
"site": null,
"teams": [],
"queues": [],
"skills": [],
"start_date": 1648518167,
"end_date": 1648518167,
"created_at": 1648618871,
"platforms": {},
"deleted": false,
"staffable": false
}
]
}
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 |
---|---|---|---|
imported_id | string | Optional | The ID of the Person that you are creating |
first_name | string | Optional | |
last_name | string | Optional | |
string | Optional | ||
timezone | string | Optional | The timezone for the particular Person, based off the IANA timezone strings (e.g America/New_York) |
role | uuid | Optional | Unique identifier for the role to assign to this Person |
restricted_sites | list[uuid] | Optional | Restricts the person to only view resources associated with these sites. Values must be valid site IDs |
staffable | boolean | Optional | Indicates whether the Person can be scheduled |
channels | list[string] | Optional | One of phone , email , chat , sms or social . The channel must exist on the Assembled dashboard |
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 |
platforms | map[string]string | Optional | A map of unique identifiers from the different platforms that the agent is associated with, keyed on the platform name. Possible platforms include intercom , kustomer , salesforce , twilio , ujet , zendesk , zendesk_chat , and zendesk_talk |
start_date | UNIX timestamp, in seconds | Optional | Person's start date specified by the user on creation. Set it to null if you want to remove this value |
end_date | UNIX timestamp, in seconds | Optional | Person's end date used to indicate when they can no longer be scheduled. Usually, this field is used to preserve agent data in the event of a role change into a non-staffable role or the termination of their contract |
DELETE /v0/people/:id
Example request
curl "https://api.assembledhq.com/v0/people/8ce1939e-cc6c-48e8-b0ef-a2326b562082?hard=true" \
-X DELETE \
-u sk_live_abc123
Example response
{
"id": "<uuid>",
"message": "person successfully deleted"
}
Query parameters:
Field | Type | Required | Description |
---|---|---|---|
hard | string | Optional | Set to true if you want to completely delete the Person and all associated data. Defaults to false |
Roles
Roles are used to control user access to different parts of assembled.
Role object
{
"id": "<uuid>",
"name": "Admin",
"description": "This is an admin role"
}
Field | Type | Required | Description |
---|---|---|---|
id | uuid | Used to reference the role in other API requests. | |
name | string | Required | The name of the role. |
description | string | Optional | A description of the role. |
GET /v0/roles
Example request
curl "https://api.assembledhq.com/v0/roles" \
-X GET \
-u sk_live_abc123:
Example response
{
"roles": {
"0ff1211d-17a4-4d62-9039-e790eaa6aef9": {
"id": "0ff1211d-17a4-4d62-9039-e790eaa6aef9",
"name": "Admin",
"description": "This is an admin role"
},
...
}
}
Returns a list of roles in an Assembled instance.
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_id": "<uuid>",
"agent_name": "John Smith",
"agent_email": "john.smith@example.com",
"agent_platform_id": "25963324267",
"platform": "zendesk",
"start_time": 1664890267,
"end_time": 1664890367,
"state": "Online (Tickets)",
"ticket_id": "4544635",
"ticket_status": "solved",
"modified_at": 1664890367
}
Field | Type | Description |
---|---|---|
agent_id | uuid | Unique identifier for an agent in Assembled. |
agent_name | string | |
agent_email | string | |
agent_platform_id | string | Unique identifier for the agent for the platform. This can be associated to agents in Assembled with the agent associations endpoint. |
platform | string | The platform that the agent state comes from e.g. "api", "zendesk_talk", or "kustomer". |
start_time | Unix timestamp, in seconds | Time when agent began their state. |
end_time | Unix timestamp, in seconds | Time when agent ended being in this state. |
state | string | Agent’s 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. |
ticket_id | string | Identifier for the corresponding ticket. |
ticket_status | string | Status of the ticket. |
modified_at | Unix timestamp, in seconds | Time when the agent state was last updated. |
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_platform_id": "25963324267",
"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_platform_id | string | Required | Unique identifier for the agent for a platform. This can be associated to agents in Assembled with the agent associations endpoint. |
time | Unix 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/state
Returns a list of agent state objects that match the provided query.
We allow getting agent states for a single agent, agents by filters, and all agents. Valid IDs for site, team, queue, and skill can be retrieved from endpoints for filters, or via GET /people. This endpoint will return 400 if both agent IDs and filter IDs are provided, or if invalid filter IDs are provided.
Example request (single agent)
curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367&agent_id=8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
-u sk_live_abc123:
Example response
{
"agent_states": [
{
"agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
"agent_name": "John Smith",
"agent_email": "john.smith@example.com",
"agent_platform_id": "1511922421021",
"platform": "zendesk",
"start_time": 1664910494,
"end_time": 1664910508,
"state": "Online (Tickets)",
"ticket_id": "4545748",
"ticket_status": "new",
"modified_at": 1664910508
}
],
"limit": 20,
"offset": 0,
"total": 1
}
Example request (agents by filters)
curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367&channel=chat" \
-u sk_live_abc123:
Example response
{
"agent_states": [
{
"agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
"agent_name": "Jane Doe",
"agent_email": "jane.doe@example.com",
"agent_platform_id": "404632334253",
"platform": "zendesk_chat",
"start_time": 1637377993,
"end_time": 1665489600,
"state": "Offline",
"ticket_id": "",
"ticket_status": "",
"modified_at": 1637378038
}
],
"limit": 20,
"offset": 0,
"total": 1
}
Example request (all agents)
curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367" \
-u sk_live_abc123:
Example response
{
"agent_states": [
{
"agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
"agent_name": "Jane Doe",
"agent_email": "jane.doe@example.com",
"agent_platform_id": "404632334253",
"platform": "zendesk_chat",
"start_time": 1637377993,
"end_time": 1665489600,
"state": "Offline",
"ticket_id": "",
"ticket_status": "",
"modified_at": 1637378038
},
{
"agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
"agent_name": "John Smith",
"agent_email": "john.smith@example.com",
"agent_platform_id": "1511922421021",
"platform": "zendesk",
"start_time": 1664910494,
"end_time": 1664910508,
"state": "Online (Tickets)",
"ticket_id": "4545748",
"ticket_status": "new",
"modified_at": 1664910508
}
],
"limit": 20,
"offset": 0,
"total": 2
}
Parameters:
Field | Type | Required | Description |
---|---|---|---|
agent_id | uuid | Optional | Unique identifier for an agent in Assembled. |
platforms | list[string] | Optional | The platforms that the agent states come from, e.g. "api", "zendesk_talk", or "kustomer". |
channel | string | Optional | Filter agents by a specific channel. One of phone , email , chat , sms or social . |
queue | uuid | Optional | Filter agents by a specific queue. |
site | uuid | Optional | Filter agents by a specific site. |
team | uuid | Optional | Filter agents by a specific team. |
skill | uuid | Optional | Filter agents by a specific skill. |
start_time | Unix timestamp, in seconds | Required | States ending after this time will be returned. |
end_time | Unix timestamp, in seconds | Required | States starting before this time will be returned. |
limit | integer | Optional | Maximum number of results to return. Defaults to 20. |
offset | integer | Optional | Offset into the results to return. Defaults to 0. |
GET /v0/agents/state/condensed_timeline
Returns a list of agent state objects that match the provided query, but condenses each agent's states into a single timeline with non-overlapping records. The priority of overlapping records can be specified by passing in a list of comma-separated platforms through the parameter priority_order
.
Platforms that are listed earlier in priority_order
are considered to have a higher priority. In the case where priority order is not specified for a particular platform, Assembled will take the lexicographically smaller platform as higher priority (e.g. Kustomer would be considered higher priority than Zendesk if neither platform is included in the priority list).
For example, consider John Smith has a zendesk
state from 1660000400
to 1660000600
, and a zendesk_clock_in
state from 1660000500
to 1660000600
(100 seconds of overlap). If we set priority_order
to zendesk_clock_in,zendesk
, we are denoting zendesk_clock_in
as having a higher priority. Therefore, we'd get the provided response where the zendesk_clock_in
state is taken over the zendesk
state from 1660000500
to 1660000600
.
Example request (single agent)
curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367&agent_id=8ce1939e-cc6c-48e8-b0ef-a2326b562082&priority_order=zendesk_clock_in,zendesk" \
-u sk_live_abc123:
Example response
{
"agent_states": [
{
"agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
"agent_name": "John Smith",
"agent_email": "john.smith@example.com",
"agent_platform_id": "1511922421021",
"platform": "zendesk",
"start_time": 1660000400,
"end_time": 1660000500,
"state": "Online (Tickets)",
"ticket_id": "4545748",
"ticket_status": "new",
"modified_at": 1664910508
},
{
"agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
"agent_name": "John Smith",
"agent_email": "john.smith@example.com",
"agent_platform_id": "1511922421021",
"platform": "zendesk_clock_in",
"start_time": 1660000500,
"end_time": 1660000600,
"state": "Lunch",
"ticket_id": "",
"ticket_status": "",
"modified_at": 1664910508
}
],
"limit": 20,
"offset": 0,
"total": 2
}
Query parameters:
Field | Type | Required | Description |
---|---|---|---|
agent_id | uuid | Optional | Unique identifier for an agent in Assembled. |
platforms | list[string] | Optional | The platforms that the agent states come from, e.g. "api", "zendesk_talk", or "kustomer". |
priority_order | string | Required | A list of comma-separated platforms in order of descending priority (e.g. "zendesk,customer") |
channel | string | Optional | Filter agents by a specific channel. One of phone , email , chat , sms or social . |
queue | uuid | Optional | Filter agents by a specific queue. |
site | uuid | Optional | Filter agents by a specific site. |
team | uuid | Optional | Filter agents by a specific team. |
skill | uuid | Optional | Filter agents by a specific skill. |
start_time | Unix timestamp, in seconds | Required | States ending after this time will be returned. |
end_time | Unix timestamp, in seconds | Required | States starting before this time will be returned. |
limit | integer | Optional | Maximum number of results to return. Defaults to 20. |
offset | integer | Optional | Offset into the results to return. Defaults to 0. |
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_platform_id": "25963324267",
"agent_id": "<uuid>"
}'
Associates agent unique identifiers to agents in Assembled. If an association already exists with this agent_platform_id, we will update the association with the newly specified agent_id.
This endpoint is used in conjunction with POST requests to /v0/agents/state
, allowing the user to ensure these requests map to the correct agents.
You must associate agent unique identifiers to agents in Assembled - whether that's through this endpoint or within the Assembled app - to ensure that POST requests to the /v0/agents/state endpoint
can be displayed correctly with adherence metrics for a particular agent.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
agent_platform_id | string | Required | Unique identifier used in agent states. |
agent_id | uuid | Required | Unique identifier for an agent in Assembled. |
POST /v0/agents/state/edit
Example request
curl "https://api.assembledhq.com/v0/agents/state/edit" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{
"edits": [
{
"agent_platform_id": "25963324267"
"platform": "zendesk",
"action": "insert"
"data": {
"state": "Online",
"start_time": 1664890267,
"end_time": 1664890367
}
},
{
"agent_platform_id": 25963324267
"platform": "zendesk",
"action": "delete"
"data": {
"id": "<uuid>",
}
},
{
"agent_platform_id": "25963324267"
"platform": "zendesk",
"action": "update"
"data": {
"id": "<uuid>",
"state": "Online",
"start_time": 1664890267,
"end_time": 1664890367
}
},
]
}'
Takes in a list of agent state edits and applies them. Insertions, deletes, and updates are supported. The parameters required are dependent on the type of action specified.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
edits | List[Object] | Required | A list of edits to be made |
agent_platform_id | string | Required | The platform ID of the agent whose state is being edited |
platform | string | Required | The platform of the state to be edited |
action | string | Required | "insert", "delete", or "update" |
data | Object | Required | An object specifying edit details (dependent on the type of edit being made) |
id | uuid | Required | (Required for deletions and updates) The external ID of the state being edited |
state | string | Optional | (Required for insertions and updates) The desired state of the edited record |
start_time | Unix timestamp | Optional | (Required for insertions and updates) Unix timestamp of the edited record's desired start time |
end_time | Unix timestamp | Optional | (Required for insertions and updates) Unix timestamp of the edited record's desired end time |
GET /v0/agents/state/edit/history
Example request
curl "https://api.assembledhq.com/v0/agents/state/edit/history?start_time=1600000000&end_time=1700000000" \
-u sk_live_abc123:
Example response
{
[
{
"edited_agent": {
"name": "John Smith",
"email": "johnsmith@example.com",
"agent_id": "<uuid>"
},
"platform": "zendesk",
"state_external_id": "<uuid>",
"old_record": {
"agent_platform_id": "25963324267",
"start_time": "2023-12-05T08:00:00Z",
"end_time": "2023-12-05T09:00:00Z",
"platform": "zendesk",
"state": "offline",
"attributes": null,
"is_current": false,
"updated_at": "2023-12-06T08:17:38.601462Z",
"active": true,
"start_unix": 1670000100,
"end_unix": 1670000200,
"created_at": 1664890267
},
"new_record": {
"agent_platform_id": "25963324267",
"start_time": "2023-12-05T08:00:00Z",
"end_time": "2023-12-05T010:00:00Z",
"platform": "zendesk",
"state": "online",
"attributes": null,
"is_current": false,
"updated_at": "2023-12-06T08:17:38.601462Z",
"active": true,
"start_unix": 1670000200,
"end_unix": 1670000400,
"created_at": 1701850658
},
"edit": {
"agent_platform_id": "25963324267",
"platform": "api",
"action": "insert",
"data": {
"state": "online",
"start_time": 1670000200,
"end_time": 670000400
}
},
"is_api_edit": false,
"edited_by": {
"id": "<uuid>",
"first_name": "Jane",
"last_name": "Doe",
"role": "admin",
"email": "janedoe@example.com",
"timezone": "America/Los_Angeles",
"restricted_sites": [],
"active": true
},
"created_at": "2023-12-06T08:17:38.601462Z"
},
]
}
Returns a list of edits made to any agents' states that were made between the specified start and end time.
Edits made through the edit_history
endpoint (as indicated by is_api_edit
in the response) will not return editor details in the edited_by
field due to ambuiguity over which specific user made the API request.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | Unix timestamp, in seconds | Required | Edits made after this time will be returned |
end_time | Unix timestamp, in seconds | Required | Edits made before this time will be returned |
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,
"created_at": 1546303260,
"updated_at": 1546303260,
"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 | Unix timestamp, in seconds | |
end_time | Unix timestamp, in seconds | |
created_at | Unix timestamp, in seconds | |
updated_at | Unix 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,
"created_at": 1562251600,
"updated_at": 1562221600,
"description": null,
"agent_id": "<uuid>",
"type_id": "<uuid>"
}
Creates an activity with the specified parameters. Valid IDs for agents can be retrieved from the people 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 | Unix timestamp, in seconds | Required | |
end_time | Unix 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,
"created_at": 1562251600,
"updated_at": 1562221600,
"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 | Value can only be create . |
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,
"created_at": 1562221600,
"updated_at": 1562223600,
"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 | Unix timestamp, in seconds | Required | |
end_time | Unix 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,
"created_at": 1562221600,
"updated_at": 1562223600,
"agent_id": "<uuid>",
"type_id": "<uuid>"
},
...
},
}
Deletes all activities that match the specified parameters. Valid IDs for agents can be retrieved from the people 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 | Unix timestamp, in seconds | Required | The start of the deletion window. |
end_time | Unix 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. |
timeoff_unit | "hours" or "days" | Required for time off event types. Specifies whether time off of this type is taken in increments of hours or days. |
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.
Event changes
Event changes represent changes to an agent's scheduled events. These could be manually added changes, due to applying a template, due to a time off request being approved, or due to any other change to the schedule.
Event change object
{
"id": "<uuid>",
"event_id": "<uuid>",
"modified_by": {
"name": "John Smith",
"id": "<uuid>",
"email": "john.smith@example.com"
},
"modified_at": 1665954677,
"event_agent_name": "Jane Doe",
"event_agent_id": "<uuid>",
"event_agent_email": "jane.doe@example.com",
"event_change_type": "modify",
"description": "Events Edited and Published",
"old_event_type": "activity_type_value1234",
"new_event_type": "activity_type_value5678",
"old_start_time": 1665702700,
"old_end_time": 1665727300,
"new_start_time": 1665703700,
"new_end_time": 1665715900,
"old_channels": ["phone"],
"new_channels": ["chat"],
"old_template_id": "<uuid>",
"new_template_id": "<uuid>",
"old_google_calendar_event_id": "<gcal_event_id>",
"new_google_calendar_event_id": "<gcal_event_id>"
}
Field | Type | Description |
---|---|---|
id | uuid | |
event_id | uuid | ID of the event that was modified |
modified_by | object | Object containing information about the person who edited the event |
modified_at | Unix timestamp, in seconds | When the event change was created |
event_agent_name | string | Name of the agent whose event was changed |
event_agent_id | uuid | ID of the agent whose event was changed |
event_agent_email | string | Email of the agent whose event was changed |
event_change_type | string | Type of event change. One of create , modify , or delete |
description | string | |
old_event_type | string | Value of the event type before the change (this corresponds to the value field of the Activity Type object) |
new_event_type | string | Value of the event type after the change (this corresponds to the value field of the Activity Type object) |
old_start_time | Unix timestamp, in seconds | |
new_start_time | Unix timestamp, in seconds | |
old_end_time | Unix timestamp, in seconds | |
new_end_time | Unix timestamp, in seconds | |
old_channels | list[string] | |
new_channels | list[string] | |
old_template_id | uuid | UUID for the template that the event comes from |
new_template_id | uuid | UUID for the template that the event comes from |
old_google_calendar_event_id | string | Google Calendar event ID for the event, if synced from Google Calendar |
new_google_calendar_event_id | string | Google Calendar event ID for the event, if synced from Google Calendar |
GET /v0/event_changes
Example request
curl "https://api.assembledhq.com/v0/event_changes?start_time=1665888528&end_time=1667270928" \
-u sk_live_abc123: -X GET
Example response
{
"event_changes": {
"<uuid>": {
"id": "<uuid>",
"event_id": "<uuid>",
"modified_by": {
"name": "John Smith",
"id": "<uuid>",
"email": "john.smith@example.com"
},
"modified_at": 1665954677,
"event_agent_name": "Jane Doe",
"event_agent_id": "<uuid>",
"event_agent_email": "jane.doe@example.com",
"event_change_type": "modify",
"description": "Events Edited and Published",
"old_event_type": "activity_type_value1234",
"new_event_type": "activity_type_value5678",
"old_start_time": 1665702700,
"old_end_time": 1665727300,
"new_start_time": 1665703700,
"new_end_time": 1665715900,
"old_channels": ["phone"],
"new_channels": ["chat"],
"old_template_id": "<uuid>",
"new_template_id": "<uuid>",
"old_google_calendar_event_id": "<gcal_event_id>",
"new_google_calendar_event_id": "<gcal_event_id>"
},
...
},
"limit": 0,
"offset": 0,
"total": 100
}
Returns a list of event change objects that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | Unix timestamp, in seconds | Required | |
end_time | Unix timestamp, in seconds | Required | Together with start_time , specifies the range of creation times of retrieved event changes. |
schedule_id | uuid | Optional | Identifier for the corresponding schedule. Defaults to the master schedule. |
agent_id | uuid | Optional | When provided, only retrieve event changes for the specified agent. |
limit | integer | Optional | Maximum number of results to return. Defaults to 20. |
offset | integer | Optional | Offset into the results to return. Defaults to 0. |
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",
"tags": ["tag1", "tag2", "tag3"]
}
Field | Type | Required | Description |
---|---|---|---|
created_at | Unix 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", "chat", "social" or "back_office". |
status | string | Required | One of: "open", "pending", "solved" or "abandoned". |
queue | uuid | Optional | Unique identifier for the corresponding queue. |
first_responded_at | Unix timestamp, in seconds | Optional | Time the conversation was first responded to by an agent. |
solved_at | Unix 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. |
tags | list[string] | Optional | List of tags associated with 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\"
\"tags\": [\"tag1\", \"tag2\", \"tag3\"]
}
]
}"
Creates or overwrites a conversation with the specified parameters. There is a batch limit of 1000 conversations per request.
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 | Unix timestamp, in seconds | Time of creation. |
updated_at | Unix timestamp, in seconds | Time of last update. |
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. Note this will default to associating your queues to all channels enabled in your Assembled instance.
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 | Unix timestamp, in seconds | |
end_time | Unix 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 | Unix timestamp, in seconds | Required | |
end_time | Unix 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. |
Forecast totals
Forecast totals provide more flexibility than standard forecast uploads by allowing you to specify a forecasted contact volume over any time range. Assembled then takes that volume and distributes it based on our forecasted arrival pattern during that period of time, creating a hybrid between your internal predictions and ours.
Forecast total object
{
"id": "<uuid>",
"start_time": 1549065600,
"end_time": 1549066500,
"channel": "phone",
"queue": "<uuid>",
"value": 42.0,
"value_type": "contacts"
}
Field | Type | Required | Description |
---|---|---|---|
id | uuid | Used to reference the forecast total in GET/DELETE requests and error messages. | |
start_time | Unix timestamp, in seconds | Required | Must be greater than or equal to the minimum forecast interval. |
end_time | Unix timestamp, in seconds | Required | Must be greater than or equal to the minimum forecast interval. |
channel | string | Required | One of: "phone", "email", or "chat". |
queue | uuid | Optional | Unique identifier for the corresponding queue. Defaults to null. |
value | float | Required | The number of contacts forecasted for the time interval. |
value_type | float | Optional | Useful for "email" channels where you can have "contacts", "reopened", "messages", or "combined". Defaults to "contacts". |
GET /v0/forecasts/totals
Example request
curl "https://api.assembledhq.com/v0/forecasts/totals?start_time=1549065600&end_time=1549069200&channel=email" \
-X GET \
-u sk_live_abc123:
Example response
{
"forecasts": [
{
"id": "<uuid>",
"start_time": 1549065600,
"end_time": 1549066500,
"channel": "chat",
"queue": "<uuid>",
"value": 42.0,
"value_type": "contacts"
},
...
],
}
Returns a list of forecast totals that have been uploaded.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | Unix timestamp, in seconds | Required | Totals ending after this time will be returned. |
end_time | Unix timestamp, in seconds | Required | Totals starting before this time will be returned. |
channel | string | Optional | One of: "phone", "email", or "chat". |
queue | uuid | Optional | Unique identifier for a queue to associate. |
value_type | string | Optional | Useful for "email" channels where you can have "contacts", "reopened", "messages", or "combined" |
GET /v0/forecasts/totals/:id
Returns a forecast total based on the id
provided
Example request
curl "https://api.assembledhq.com/v0/forecasts/totals/82721999-16b3-41cf-bb12-b195610cd576" \
-u sk_live_abc123
Example response
{
"forecasts": [
{
"id": "<uuid>",
"start_time": 1549065600,
"end_time": 1549066500,
"channel": "chat",
"queue": "<uuid>",
"value": 42.0,
"value_type": "contacts"
}
],
}
POST /v0/forecasts/totals
Example request
curl "https://api.assembledhq.com/v0/forecasts/totals" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d "{
\"overwrite\": false,
\"forecasts\": [
{
\"start_time\": 1549065600,
\"end_time\": 1549069200,
\"channel\": \"chat\",
\"queue\": \"<uuid>\",
\"value\": 42.0,
\"value_type\": \"contacts\"
}
]
}"
Example response
{
"forecasts": [
{
"id": "<uuid>",
"start_time": 1549065600,
"end_time": 1549066500,
"channel": "chat",
"queue": "<uuid>",
"value": 42.0,
"value_type": "contacts"
}
],
}
Creates forecast totals with the given parameters. If the "overwrite" flag is set to true, new totals will overwrite previous totals that overlap perfectly (same start_time and end_time) with them.
Request Parameters:
Field | Type | Required | Description |
---|---|---|---|
overwrite | boolean | Optional | Allows new totals to overwrite existing ones if they overlap perfectly. Default value is false. |
forecasts | list[ForecastTotal] | Required | See documentation for the Forecast total object. |
DELETE /v0/forecasts/totals/:id
Deletes a forecast total based on the id
provided. This allows for targeted removal of conflicting totals and is a permanent action and cannot be undone.
Example request
curl "https://api.assembledhq.com/v0/forecasts/totals/82721999-16b3-41cf-bb12-b195610cd576" \
-X DELETE \
-u sk_live_abc123
Forecasts vs. actuals
Forecasted metrics are those that Assembled predicts based on a combination of historical data and various configured variables within Assembled. Actuals are the historical values of these metrics. This endpoint allows the user to access and compare these two sets of data, much like the "Forecasted vs. actual" report in Assembled.
Forecasts vs. actuals objects
Forecasted vs. actual pair
A forecasted vs. actual pair is an object containing the forecasted and actual value of a given metric.
{
"forecasted": 3,
"actual": 4
}
Field | Type | Description |
---|---|---|
forecasted | float | The value forecasted for the given metric (may be null ) |
actual | float | The actual value of the metric (may be null ) |
Forecasted vs. actual response
{
"start_time": 1668492000,
"end_time": 1668495600,
"channel": "email",
"queue": "<uuid>",
"service_level": {
"forecasted": 0,
"actual": 0
},
"service_level_missed": {
"forecasted": 63.5,
"actual": 34
},
"service_level_met": {
"forecasted": 0,
"actual": 0
},
"first_response_time": {
"forecasted": null,
"actual": 13172
},
"cases_opened": {
"forecasted": 36,
"actual": 42
},
"cases_reopened": {
"forecasted": 23.5,
"actual": 32
},
"cases_solved": {
"forecasted": 60,
"actual": 54
},
"productivity": {
"forecasted": 3.4,
"actual": 2.8302307428825666
},
"staffing_scheduled": 19.75,
"staffing_required": 19,
"staffing_net": 0.75
}
Field | Type | Description |
---|---|---|
start_time | Unix timestamp, in seconds | |
end_time | Unix timestamp, in seconds | |
channel | string | |
queue | uuid | |
service_level | forecasted_actual_pair | Service level percent as a value between 0 and 1. |
service_level_missed | forecasted_actual_pair | Number of contacts that missed service level. |
service_level_met | forecasted_actual_pair | Number of contacts that met service level. |
first_response_time | forecasted_actual_pair | Average first response time in seconds. Only actual values are available for this metric. |
transferred_away | forecasted_actual_pair | Number of tickets transferred away. Only available if ticket lifecycle tracking is enabled. |
reassigned_away | forecasted_actual_pair | Number of tickets reassigned away. Only available if ticket lifecycle tracking is enabled. |
messages_received | forecasted_actual_pair | Number of messages received. Only available for asynchronous channels and if using message-based forecasting. |
cases_answered | forecasted_actual_pair | Number of cases answered. Only available for asynchronous channels and if using message-based forecasting. |
cases_opened | forecasted_actual_pair | Number of new cases opened. Only available for asynchronous channels. |
cases_reopened | forecasted_actual_pair | Number of cases reopened. Only available for asynchronous channels. |
cases_solved | forecasted_actual_pair | Number of cases solved. Only available for asynchronous channels. |
productivity | forecasted_actual_pair | Average email productivity. Only available for asynchronous channels. |
contacts_received | forecasted_actual_pair | Number of contacts received. Only available for realtime channels. |
contacts_abandoned | forecasted_actual_pair | Number of contacts abandoned. Only available for realtime channels. |
handle_time | forecasted_actual_pair | Average handle time. Only available for realtime channels. |
occupancy | forecasted_actual_pair | Occupancy percent as a value between 0 and 1. Only forecasted values are available for this metric. |
staffing_scheduled | float | |
staffing_required | float | |
staffing_net | float |
GET /v0/forecasted_vs_actuals
Example request
curl "https://api.assembledhq.com/v0/forecasted_vs_actuals?start_time=1668492000&end_time=1668495600&channel=phone&interval=3600" \
-u sk_live_abc123: -X GET
Example response
{
"forecasts_vs_actuals": [
{
"start_time": 1668492000,
"end_time": 1668495600,
"channel": "phone",
"queue": "<uuid>",
"service_level": {
"forecasted": 0,
"actual": 0
},
"service_level_missed": {
"forecasted": 63.5,
"actual": 34
},
"service_level_met": {
"forecasted": 0,
"actual": 0
},
"first_response_time": {
"forecasted": null,
"actual": 123
},
"contacts_received": {
"forecasted": 63.5,
"actual": 36
},
"contacts_abandoned": {
"forecasted": null,
"actual": 2
},
"handle_time": {
"forecasted": 243,
"actual": 220
},
"occupancy": {
"forecasted": 0.45,
"actual": null
},
"staffing_scheduled": 19.75,
"staffing_required": 19,
"staffing_net": 0.75
},
...
],
"limit": 0,
"offset": 0,
"total": 100
}
Returns a list of forecasted vs. actual records that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | Unix timestamp, in seconds | Required | |
end_time | Unix timestamp, in seconds | Required | Together with start_time , specifies the range of times to view metrics for. |
interval | integer | Required | Interval in seconds to group the results by. |
channel | string | Required | Name of the channel to view metrics for. |
queue | uuid | Optional | Unique identifier for the corresponding queue. |
limit | integer | Optional | Maximum number of results to return. Defaults to 20. |
offset | integer | Optional | Offset into the results to return. Defaults to 0. |
Quality assurance scores
Assembled can ingest and aggregate quality assurance (QA) scores in our reporting dashboards.
QA scores are considered to be grading an underlying ticket from a ticketing platform (e.g. zendesk
, intercom
, etc.). The ticket's platform and ID can optionally be provided when sending QA scores to Assembled, which allows you to apply filters to group these scores in reports.
Score object
{
"agent_email": "john.smith@assembledhq.com",
"ticket_created_at": 1660000400,
"score": 85.0,
"max_score": 100.0,
"imported_id": "ticket_id_123",
"agent_platform_id": "johns_zendesk_id",
"agent_name": "John Smith",
"grader": "John's Manager",
"graded_at": 1770000400
}
Field | Type | Required | Description |
---|---|---|---|
agent_email | string | Required | Email of the agent being graded. This is used to associate the score with an agent in Assembled. |
ticket_created_at | Unix timestamp, in seconds | Required | Time that the ticket being graded was created. |
score | float | Required | Score that the agent received for this particular ticket. |
imported_id | string | Required | Third-party identifier of the ticket being graded. |
max_score | float | Optional | Maximum score possible. If no value is provided, this will default to 100. |
agent_platform_id | string | Optional | Third-party identifier of the agent being graded from the ticketing platform (zendesk , intercom , etc.). |
agent_name | string | Optional | Name of the agent. |
grader | string | Optional | Identifier for the grader. |
graded_at | Unix timestamp, in seconds | Optional | Time that the ticket was graded. If no value is provided, Assembled will set this to the time the request was sent. |
POST /v0/qa_scores/bulk
curl "https://api.assembledhq.com/v0/qa_scores/bulk" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{
"scores": [
{
"agent_email": "john.smith@assembledhq.com",
"ticket_created_at": 1660000400,
"score": 85,
"imported_id": "ticket_id_1"
},
{
"agent_email": "john.smith@assembledhq.com",
"ticket_created_at": 1660000500,
"score": 100,
"imported_id": "ticket_id_2"
}
]
}'
Creates QA scores in Assembled. There is a batch limit of 1000 scores per request.
Bulk Request Parameters:
Field | Type | Required | Description |
---|---|---|---|
scores | list[Score] | Required | See documentation for the Score object. |
Reports
Reports are sets of historical metrics that can be queried over a given time period. When generating a report, the user is able to specify a full time range as well as a sub interval. For every metric type, we return the value for the full time period as well as the values for each sub interval.
Reports are generated asynchronously. Once a report is created, a user can query the GET /v0/reports/:reportID
endpoint to see if the
report has completed.
Currently, the supported report types are:
Adherence
Adherence reports contain adherence related metrics by agent over a given time period. The associated metrics are:
actual_seconds_worked
actual_productive_seconds_worked_all_channels
actual_productive_and_aux_seconds_worked_all_channels
actual_all_seconds_worked
actual_all_seconds_worked_all_channels
scheduled_seconds
scheduled_seconds_all_channels
actual_seconds_in_adherence
actual_seconds_in_adherence_all_channels
actual_seconds_in_schedule_adherence
actual_utilization
actual_utilization_all_channels
adherence_percentage
- refers to productive adherenceavailable_and_occupied_time_seconds
conformance_percentage
schedule_adherence_percentage
scheduled_seconds_productive
scheduled_seconds_total
seconds_in_adherence
- refers to productive adherenceoccupancy_percentage
occupancy_percentage_all_channels
occupied_time_seconds
utilization
- refers to schedule utilizationin_office_shrinkage
Agent ticket stats
Agent ticket stats reports contain the following metrics by agent over a given time period:
agent_avg_handle_time
agent_tickets_solved
If a case lifecycle integration is being used, the following metrics are also available.
agent_units_of_work_handled
agent_tickets_reassigned_away
agent_tickets_transferred_away
agent_avg_unit_of_work_handle_time
agent_unit_of_work_total_handle_time
agent_units_of_work_handle_time_count
Agent state handle times
This report type is only available for Zendesk customers. It features 3 metrics, all of which are based on agent state data and only include solved tickets.
A more in depth explanation of the metrics can be found here.
agent_state_avg_handle_time_solved
ticket_time_solved
tickets_touched_solved
Report Request Object
{
"start_time": "timestamp",
"end_time": "timestamp",
"interval": "string",
"channel": "string",
"queue_id": "<uuid>",
"agent_id": "<uuid>",
"filters": {
"site_id": "<uuid>",
"team_id": "<uuid>",
"skill_id": "<uuid>"
}
}
Field | Type | Required | Description |
---|---|---|---|
start_time | Unix timestamp (UTC) | Required | Start time of the report, must be a multiple of 900 seconds |
end_time | Unix timestamp (UTC) | Required | End time of the report, must be a multiple of 900 seconds. Time range must be < 31 days |
interval | string | Required | One of: 30m or 1h . For time ranges > 1 day, one of: 24h , or 1w . Note that adherence reports do not support 30m intervals. |
channel | string | Required | One of: back_office , chat , email , phone , sms , or social |
queue_id | uuid | Optional | Unique identifier for the corresponding queue |
agent_id | uuid | Optional | Unique identifier for the corresponding agent. Cannot be provided if filters are provided |
site_id | uuid | Optional | Unique identifier for the corresponding site. Part of "filters". Cannot be provided if agent_id is provided. |
team_id | uuid | Optional | Unique identifier for the corresponding team. Part of "filters". Cannot be provided if agent_id is provided. |
skill_id | uuid | Optional | Unique identifier for the corresponding skill. Part of "filters". Cannot be provided if agent_id is provided. |
Report Object
{
"status": "string",
"created_at": "timestamp",
"total_metric_count": "integer",
"metrics": ["Metrics Object"]
}
Field | Type | Description |
---|---|---|
status | string | Status of the report, either in_progress , complete , or error |
created_at | timestamp (UTC) | The time at which the report was generated |
total_metric_count | int | Total # of metrics returned in the report |
metrics | list[Metric Object] | A list of metric objects |
Metric Object
{
"name": "string",
"value": "float",
"attributes": {
"agent_id": "<uuid>",
"start_time": "timestamp",
"end_time": "timestamp",
"type": "string"
}
}
Field | Type | Description |
---|---|---|
name | string | Name of the metric type. Each report type has a different set of valid metrics name. |
value | float | The value of the metric |
agent_id | uuid | Unique identifier for the associated agent |
start_time | timestamp (UTC) | Start of the period for which the metric is measured. This is either the start of the interval for a full_interval metric, or the start of a sub interval for an interval type metric. |
end_time | timestamp (UTC) | End of the period for which the metric is measured. This is either the end of the interval for a full_interval metric, or the end of a sub interval for an interval type metric. |
type | string | Either full_interval or interval . Denotes if the metric value represents the full time range or one interval |
POST /v0/reports/:reportType
Use this endpoint to request a report. The endpoint will return a reportID
that will be used to retrieve the report object.
Report | /:reportType |
---|---|
Adherence | /adherence |
Agent ticket stats | /agent_ticket_stats |
Agent state handle times | /agent_state_handle_times |
Example request
curl "https://api.assembledhq.com/v0/reports/adherence" \
-X POST \
-u sk_live_abc123: \
-d '{
"report_type": "adherence",
"start_time": 1643673600,
"end_time": 1643760000,
"interval": "1h",
"channel": "phone"
}'
Example response
{
"report_id": "a8fb1af1-7abc-4316-8616-74ac96448b1e"
}
GET /v0/reports/:reportID
Use this endpoint to retrieve the report object and check on the status of your report.
Example request
curl "https://api.assembledhq.com/v0/reports/a8fb1af1-7abc-4316-8616-74ac96448b1e" \
-X GET \
-u sk_live_abc123:
Example response
{
"status": "complete",
"created_at": "2022-03-30T16:42:29.044299Z",
"total_metric_count": 1512,
"metrics": [
{
"name": "seconds_in_adherence",
"value": 629,
"attributes": {
"agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
"start_time": 1643673600,
"end_time": 1643760000,
"type": "full_interval"
}
},
{
"name": "seconds_in_adherence",
"value": 338,
"attributes": {
"agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
"start_time": 1643673600,
"end_time": 1643677200,
"type": "interval"
}
},
...
]
}
Query Parameters
The resulting metric list can be paginated and filtered by metric type(s).
Field | Type | Description |
---|---|---|
limit | int | 500 metrics returned by default |
offset | int | Adds an offset to the responses returned, starts from 0 |
metric | string | List of metric names to filter by. Filter for multiple metrics names using the format &metric=[metric name]&metric=[metric name] . If no metric name filter is provided, then all metric types are returned. Must be a valid metric of the report type |
type | string | List of metric types to filter by. Filter for multiple metrics types using the format &type=[metric type]&type=[metric type] . If no type filter is provided, then all metric types are returned (full_interval and interval ) |
Example request
curl "https://api.assembledhq.com/v0/reports/a8fb1af1-7abc-4316-8616-74ac96448b1e?metric=adherence_percentage&metric=occupancy_percentage" \
-X GET \
-u sk_live_abc123:
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 | Unix timestamp, in seconds | |
end_time | Unix 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 | Unix 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 | Unix 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=1641042000&end_time=1641081600" \
-u sk_live_abc123:
Example response
{
"requirements": [
{
"requirement_type_id": "<uuid>",
"required": 42.0,
"scheduled": 42.0,
"start_time": 1641042000,
"end_time": 1641081600
},
...
],
}
Returns a list of requirement objects that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
start_time | Unix timestamp, in seconds | Required | |
end_time | Unix timestamp, in seconds | Required | Together with start_time, this determines the interval for which requirements will be retrieved. The interval can be a maximum of 31 days. |
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.
Time off
Agents can have time off requests that are either created directly in Assembled or sourced from other applications such as Hibob and Workday. Time off requests can be retrieved via GET /activities after they have been approved. All time off requests (approved, pending, cancelled, denied) can be retrieved via GET /time_off/requests.
Time off request object
{
"id": "<uuid>",
"agent_id": "<uuid of the agent requesting time off>",
"start_time": 1546303260,
"end_time": 1546303270,
"created_at": 1546303260,
"activity_type_id": "<uuid of the activity type of the time off request>",
"description": "Going to the dentist",
"status": "approved"
}
Field | Type | Description |
---|---|---|
id | uuid | |
agent_id | uuid | Unique identifier for the corresponding agent. |
start_time | Unix timestamp, in seconds | |
end_time | Unix timestamp, in seconds | |
created_at | Unix timestamp, in seconds | |
activity_type_id | uuid | Unique identifier for the activity type of the timeoff taken |
description | string | Reason why the agent is requesting time off. |
status | string | One of: canceled , denied , approved , pending |
Time off update object
{
"id": "<uuid>",
"time_off_request_id": "<uuid of the time off request object>",
"created_at": 1546303260,
"comment": "Enjoy your vacation",
"type": "approve"
}
Field | Type | Description |
---|---|---|
id | uuid | |
time_off_request_id | uuid | Unique identifier for the time off request. |
created_at | Unix timestamp, in seconds | |
comment | string | |
type | string | One of: approve , edit , deny , cancel |
GET /v0/time_off/updates
Example request
curl "https://api.assembledhq.com/v0/time_off/updates?updated_since=1546303260&type=approve" \
-u sk_live_abc123: -X GET
Example response
{
"time_off_updates": {
"<uuid>": {
"id": "<uuid>",
"time_off_request_id": "<uuid of the time off request object>",
"created_at": 1546303260,
"comment": "Enjoy your vacation",
"type": "approve"
},
...
},
"time_off_requests": {
"<uuid>": {
"id": "<uuid>",
"agent_id": "<uuid of the agent requesting time off>",
"start_time": 1546303260,
"end_time": 1546303270,
"created_at": 1546303260,
"description": "Going to the dentist",
"status": "approved",
"activity_type_id": "<uuid>",
}
},
"total": 26,
"limit": null,
"offset": null
}
Returns a list of activity objects that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
updated_since | Unix timestamp, in seconds | Required | |
type | One of: approve , edit , deny , cancel |
Optional | |
limit | int | Optional | 20 responses are returned by default, but the maximum value is 500 |
offset | int | Optional | Adds an offset to the responses returned, starting from 0 |
POST /v0/time_off
Creates a time off request with the specified parameters. Valid IDs for user_id
and receiver_ids
can be retrieved from GET /people, and valid IDs for activity_type_id
can be retrieved from GET /activity_types. This endpoint will return a 400 if invalid IDs for user_id
, activity_type_id
, or receiver_ids
are provided.
Example request
curl "https://api.assembledhq.com/v0/time_off" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d \
'{
"user_id": "<uuid>",
"description": "Vacation",
"activity_type_id": "<uuid>",
"start_time": 1709064000,
"end_time": 1709164800,
"editable": false,
"receiver_ids": [
"<uuid>",
"<uuid>"
]
}'
Example response
{
"id": "<uuid>",
"status": "success"
}
Parameters:
Field | Type | Required | Description |
---|---|---|---|
user_id | uuid | Required | The ID of the Person requesting time off |
description | string | Optional | |
activity_type_id | uuid | Required | The ID of the activity type corresponding to this time off request |
start_time | Unix timestamp, in seconds | Required | |
end_time | Unix timestamp, in seconds | Required | |
editable | boolean | Optional | Whether the time off request is editable. Defaults to false . If the "auto-editable" feature is enabled, the value passed here will be ignored. |
receiver_ids | list[uuid] | Optional | The list of IDs of the People who are notified when the time off request is submitted. |
GET /v0/time_off/requests
Example request
curl "https://api.assembledhq.com/v0/time_off/requests?updated_since=1546303260&type=approve" \
-u sk_live_abc123: -X GET
Example response
{
"time_off_updates": {
"<uuid>": {
"id": "<uuid>",
"time_off_request_id": "<uuid of the time off request object>",
"created_at": 1546303260,
"comment": "Enjoy your vacation",
"type": "approve"
},
...
},
"time_off_requests": {
"<uuid>": {
"id": "<uuid>",
"agent_id": "<uuid of the agent requesting time off>",
"start_time": 1546303260,
"end_time": 1546303270,
"created_at": 1546303260,
"description": "Going to the dentist",
"status": "approved",
"activity_type_id": "<uuid>"
}
},
"total": 26,
"limit": 50,
"offset": 10
}
Returns a list of activity objects that match the provided query.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
updated_since | Unix timestamp, in seconds | Required | |
type | One of: approved , pending , denied , canceled |
Optional | |
limit | int | Optional | 20 responses are returned by default, but the maximum value is 500 |
offset | int | Optional | Adds an offset to the responses returned, starting from 0 |
POST /v0/time_off/:id/cancel
Cancels an existing time off request. Valid IDs for id
can be retrieved from GET /time_off/requests.
Example request
curl "https://api.assembledhq.com/v0/time_off/b646e719-6682-4402-aa4c-881a41457a48/cancel" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d \
'{
"user_id": "<uuid>",
"comment": "Accidentally requested wrong dates"
}'
Example response
{
"status": "success"
}
Parameters:
Field | Type | Required | Description |
---|---|---|---|
user_id | uuid | Required | The ID of the Person canceling time off |
comment | string | Optional |
Shift patterns [Beta]
Shift patterns allow managing and viewing each agent’s working hours (aka shifts) directly in Assembled’s schedules to help with scheduling more efficiently. In addition, time off reporting is made more convenient and accurate with agent’s working hours now available. For example, when you or your agents submit and approve full-day or multi-day time off requests, Assembled will use the assigned shift patterns to determine exact start and end times, ensuring accurate placement of time off events on the staffing timeline.
The shift pattern API is currently invite-only, please contact your customer success manager to find out how to access it.
Shift pattern response object
{
"id": "<uuid>",
"name": "Monday - Friday 9am to 5pm shift",
"timezone": "Americas/New_York",
"user_email": "user@email.com",
"excluded_duration_seconds": 1800,
"shifts": [
{
"start_time": {
"day_of_week": 1,
"hour": 17,
"minute": 0
},
"end_time": {
"day_of_week": 2,
"hour": 5,
"minute": 0
}
}
],
"created_at": 1697561882,
"updated_at": 1705516856,
"assigned_agent_count": 23,
"assigned_agent_ids": [
"<uuid>",
"<uuid>",
"<uuid>",
...
]
}
Field | Type | Description |
---|---|---|
id | uuid | Unique identifier for the shift pattern |
name | string | Unique name for the shift pattern |
timezone | string | IANA timezone string for the shift pattern |
user_email | string | Assembled account email of the user who created (or last updated) the shift pattern |
excluded_duration_seconds | integer | Time in seconds of any non-working periods like lunch or breaks. Improves time off reporting accuracy |
description | string | Optional description of further shift pattern details |
shifts | list[object] | Object used to describe details of each shift |
created_at | Unix timestamp, in seconds | Object used to describe details of each shift |
updated_at | Unix timestamp, in seconds | Object used to describe details of each shift |
assigned_agent_count | integer | Count of agents assigned to this shift pattern |
assigned_agent_ids | list[uuid] | List of unique agent IDs assigned to this shift pattern |
Shifts object
Monday from 5pm to 5am
{
"shifts": [
{
"start_time": {
"day_of_week": 1,
"hour": 17,
"minute": 0
},
"end_time": {
"day_of_week": 2,
"hour": 5,
"minute": 0
}
}
]
}
Tuesday from 9am to 5pm
{
"shifts": [
{
"start_time": {
"day_of_week": 2,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 2,
"hour": 17,
"minute": 0
}
}
]
}
Field | Type | Description |
---|---|---|
day_of_week | number | Indicates which day of the week is for this entry, 0 is Sunday and 6 is Saturday |
hour | number | Hour of the shift in 24-hour time, must be between 1 and 24 |
minute | number | Minute of the shift, must be between 0 and 59 |
The shift object is used to define the specific start and end times for each shift.
day_of_week begins on Sunday with 0 and ends on Saturday with 6.
Each entry into the shifts array cannot be longer than 20 hours.
Each entry into the shifts array cannot overlap between 2 days.
Shift pattern creation object
{
"name": "Monday - Friday 9am to 5pm shift",
"timezone": "Americas/New_York",
"user_email": "mike@assembledhq.com",
"excluded_duration_seconds": 1800,
"shifts": [
{
"start_time": {
"day_of_week": 1,
"hour": 17,
"minute": 0
},
"end_time": {
"day_of_week": 2,
"hour": 5,
"minute": 0
}
}
]
}
Field | Type | Required | Description |
---|---|---|---|
name | string | Required | Name of the shift pattern |
timezone | string | Required | IANA timezone name |
user_id | string | Required | UUID of Assembled user creating the shift pattern, used for reporting |
excluded_duration_seconds | string | Optional | Time, in seconds, of any non-working periods like lunch or breaks. Improves time off reporting accuracy |
description | string | Optional | Description of further shift pattern details |
shifts | list[object] | Required | Object used to describe the details of each shift |
GET /v0/shift_patterns
Example request
curl "https://api.assembledhq.com/v0/shift_patterns" \
-H "Content-Type: application/json" \
-X GET \
-u sk_live_abc123:
Example response
[
{
"id": "<uuid>",
"name": "Eastern time Assemblers",
"description": "New York, Massachusetts, Georgia, Ontario",
"shifts": [
{
"start_time": {
"day_of_week": 1,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 1,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 2,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 2,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 3,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 3,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 4,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 4,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 5,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 5,
"hour": 17,
"minute": 0
}
}
],
"timezone": "America/New_York",
"created_at": 1697561882,
"updated_at": 1705516856,
"assigned_agent_count": 23,
"assigned_agent_ids": [
"<uuid>",
"<uuid>",
"<uuid>",
...
]
}
]
Returns a list of shift patterns.
GET /v0/shift_pattern/:id
Example request
curl "https://api.assembledhq.com/v0/shift_patterns" \
-H "Content-Type: application/json" \
-X GET \
-u sk_live_abc123:
Example response
{
"id": "<uuid>",
"name": "Eastern time Assemblers",
"description": "New York, Massachusetts, Georgia, Ontario",
"shifts": [
{
"start_time": {
"day_of_week": 1,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 1,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 2,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 2,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 3,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 3,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 4,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 4,
"hour": 17,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 5,
"hour": 9,
"minute": 0
},
"end_time": {
"day_of_week": 5,
"hour": 17,
"minute": 0
}
}
],
"timezone": "America/New_York",
"created_at": 1697561882,
"updated_at": 1705516856,
"assigned_agent_count": 23,
"assigned_agent_ids": [
"<uuid>",
"<uuid>",
"<uuid>",
...
]
}
Returns a specific shift pattern that matches the supplied ID.
POST /v0/shift_patterns
Example request
curl "https://api.assembledhq.com/v0/shift_patterns" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{
"name": "Central Europe Sunday - Tuesday Overnight",
"timezone": "Europe/Zurich",
"user_id": "<uuid>",
"shifts": [
{
"start_time": {
"day_of_week": 0,
"hour": 17,
"minute": 0
},
"end_time": {
"day_of_week": 1,
"hour": 5,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 1,
"hour": 17,
"minute": 0
},
"end_time": {
"day_of_week": 2,
"hour": 5,
"minute": 0
}
},
{
"start_time": {
"day_of_week": 2,
"hour": 17,
"minute": 0
},
"end_time": {
"day_of_week": 3,
"hour": 5,
"minute": 0
}
},
]
}'
Creates a new shift pattern.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
name | string | Required | Name of the shift pattern |
timezone | string | Required | IANA timezone name |
user_id | string | Required | UUID of Assembled user creating the shift pattern, used for reporting |
excluded_duration_seconds | string | Optional | Time, in seconds, of any non-working periods like lunch or breaks. Improves time off reporting accuracy |
description | string | Optional | Description of further shift pattern details |
shifts | list[object] | Required | Object used to describe the details of each shift |
PUT /v0/shift_patterns/:id
Example request
curl "https://api.assembledhq.com/v0/shift_patterns/<uuid>" \
-H "Content-Type: application/json" \
-X PUT \
-u sk_live_abc123: \
-d '{
"user_id": "<uuid>",
"shifts": [
{
"start_time": {
"day_of_week": 0,
"hour": 1,
"minute": 0
},
"end_time": {
"day_of_week": 0,
"hour": 5,
"minute": 0
}
}
]
}'
Updates an existing shift pattern. Any change to the shifts
object during updates will completely overwrite the existing shifts.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
name | string | Optional | Name of the shift pattern |
timezone | string | Optional | IANA timezone name |
user_id | string | Required | UUID of Assembled user creating the shift pattern, used for reporting |
excluded_duration_seconds | string | Optional | Time, in seconds, of any non-working periods like lunch or breaks. Improves time off reporting accuracy |
description | string | Optional | Description of further shift pattern details |
shifts | list[object] | Optional | Object used to describe the details of each shift |
DELETE /v0/shift_patterns/{id}
Example request
curl "https://api.assembledhq.com/v0/shift_patterns/<uuid>" \
-H "Content-Type: application/json" \
-X DELETE \
-u sk_live_abc123:
Deletes an existing shift pattern.
POST /v0/shift_patterns/assign
Example request
curl "https://api.assembledhq.com/v0/shift_patterns/assign" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{
"shift_pattern_id": "<uuid>",
"agent_ids": [
"<uuid>",
"<uuid>",
"<uuid>",
]
}'
Assigns agents to a shift pattern. If any agents are already assigned to a shift pattern, this will overwrite their assignment to the new shift pattern.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
shift_pattern_id | uuid | Required | Unique identifier for the shift pattern. |
agent_ids | list[uuid] | Required | List of agent IDs |
POST /v0/shift_patterns/unassign
Example request
curl "https://api.assembledhq.com/v0/shift_patterns/unassign" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d '{
"agent_ids": [
"<uuid>",
"<uuid>",
"<uuid>",
]
}'
Unassigns all provided agent IDs from their respective shift pattern.
Parameters:
Field | Type | Required | Description |
---|---|---|---|
agent_ids | list[uuid] | Required | List of agent IDs |
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 2024-05-22
.
2024-06-04
- Resource:
shift_patterns
(Beta)- Added endpoints to create, read, update, and delete shift patterns
- Added endpoints to assign and unassign shift patterns to agents
2024-05-22
- Resource:
time_off
- Rename field
event_type_id
toactivity_type_id
for thePOST /time_off
endpoint - Return
activity_type_id
for time off requests fetched viaGET /time_off/requests
&GET /time_off/updates
- Rename field
2024-02-27
- Resource:
time_off
(Beta)- The
POST /time_off
endpoint can be used to create time off requests. - The
POST /time_off/:id/cancel
endpoint can be used to cancel existing time off requests.
- The
2022-12-02
- Resource:
agent_states
- Agent state resources will now accept the agent platform ID instead of the agent import ID.
- Resource:
activity
- Activity resources will now return the event UUIDs instead of the event instance ID.
2022-03-21
- Resource:
people
- Defined a new resource for People. Soft-delete is now supported, as well as
POST
,GET
,PATCH
andDELETE
. These will all live on the/people
endpoint. We now return a collection ofteams
andsites
in theGET
response.
- Defined a new resource for People. Soft-delete is now supported, as well as
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