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",
"role": "string",
"agent_role": "string",
"channels": ["email", "chat", "phone", "social", "sms"],
"site": "<uuid>",
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"],
"platforms": {
"zendesk": "string",
"api": "string"
},
"start_date": "timestamp",
"end_date": "timestamp",
"created_at": "timestamp",
"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 |
role | string | Person's user role on Assembled. Supported values are: standard , admin , manager , basic , lead |
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 , and zendesk_talk |
start_date | string | Person's start date specified by the user on creation |
end_date | string | 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 | string | |
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": "timestamp",
"updated_at": "timestamp"
}
},
"sites": {
"<uuid>": {
"id": "<uuid>",
"name": "string",
"parent_id": "<uuid>",
"created_at": "timestamp",
"updated_at": "timestamp"
}
},
"people": {
"<uuid>": {
"id": "<uuid>",
"agent_id": "string",
"first_name": "John",
"last_name": "Smith",
"email": "john.smith@example.com",
"imported_id": "third_party_identifier",
"role": "string",
"agent_role": "string",
"channels": ["email", "chat", "phone", "social", "sms"],
"site": "<uuid>",
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"],
"platforms": {
"zendesk": "string",
"api": "string"
},
"start_date": "timestamp",
"end_date": "timestamp",
"created_at": "timestamp",
"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 | string | Optional | Filters by assigned role. Supported values are: admin , manager , lead , standard ,basic |
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",
"role": "string",
"agent_role": "string",
"channels": ["email", "chat", "phone", "social", "sms"],
"site": "<uuid>",
"teams": ["<uuid>"],
"queues": ["<uuid>"],
"skills": ["<uuid>"],
"platforms": {
"zendesk": "string",
"api": "string"
},
"start_date": "timestamp",
"end_date": "timestamp",
"created_at": "timestamp",
"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": "standard",
"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>",
"role": "standard",
"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": "standard",
"staffable": true,
"channels": [
"email", "chat", "phone"
]
},
{
"imported_id": "",
"first_name": "Bob",
"last_name": "Example",
"email": "bob@example.com",
"timezone": "America/Los_Angeles",
"role": "standard",
"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>",
"role": "standard",
"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>",
"role": "standard",
"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 | Required | 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 | string | Required | The Person's assigned role. Supported values are: admin , manager , lead , standard ,basic |
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 | string | Optional | Person's start date specified by the user on creation |
end_date | string | 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": "standard",
"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",
"role": "manager",
"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 | string | Optional | The Person's assigned role. Supported values are: admin , manager , lead , standard ,basic |
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 | string | Optional | Person's start date specified by the user on creation. Set it to null if you want to remove this value |
end_date | string | 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 |
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. |
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. |
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. |
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>",
"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 | |
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>",
"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",
}
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. |
POST /v0/conversations/bulk
Example request
curl "https://api.assembledhq.com/v0/conversations/bulk" \
-H "Content-Type: application/json" \
-X POST \
-u sk_live_abc123: \
-d "{
\"conversations\": [
{
\"created_at\": 1549065600,
\"import_id\": \"122308400000062\",
\"channel\": \"phone\",
\"status\": \"solved\",
\"queue\": \"<uuid>\",
\"first_responded_at\": \"1549065700\"
\"solved_at\": \"1549065800\"
\"assignee_import_id\": \"d613ab77-75f7-4fce-91d8-f9ef5fe55066\"
}
]
}"
Creates or overwrites a conversation with the specified parameters. 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.
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. |
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_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 utilization
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
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 |
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 |
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": "actual_seconds_in_adherence",
"value": 629,
"attributes": {
"agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
"start_time": 1643673600,
"end_time": 1643760000,
"type": "full_interval"
}
},
{
"name": "actual_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. |
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 [Beta]
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.
This endpoint is currently in beta. If you want access, please reach out to support@assembled.com.
Time off request object
{
"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"
}
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 | |
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"
}
},
"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 |
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"
}
},
"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 |
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 2022-12-02
.
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