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
email	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. This search is a CONTAINS search and will search across all three fields.
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
email	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, zendesk_talk and api
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": {
            "zendesk": "string",
            "api": "string"
        }
        "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": {
          "zendesk": "string",
          "api": "string"
      },
      "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
email	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.

POST /v0/agents/state/bulk

Example request

curl "https://api.assembledhq.com/v0/agents/state/bulk" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "agent_states":[{
        "agent_platform_id": "25963324267",
        "time": 1720722260,
        "state": "offline"
    },{
        "agent_platform_id": "25963324268",
        "time": 1720722240,
        "state": "online"
    }]
  }'

Send a list of current agent states to Assembled. Agents remain in these states until new states are provided. You can send up to 1000 states at a time. If any error occurs during the request, the entire batch fails and no changes are processed.

Parameters:

Field	Type	Required	Description
agent_states	list[AgentState]	Required	See documentation for agent states.

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. If any error occurs during the request, the entire batch fails and no changes are 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": {
    "<string>": {
      "id": "<uuid>",
      "id_with_timestamps": "<string>",
      "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.

Note that the id field on the activity object is not guaranteed to be unique. If you need a unique identifier, please use the id_with_timestamps field.

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.
return_full_schedule	boolean	Optional	If true, return full events (including overlaps, ideal if you want to modify events via API) instead of only effective events (only count the event in the highest layer at any moment, ideal for reporting and metrics calculations). Defaults to false.

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", "sms", 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 (Required for SLA data)	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.

PATCH /v0/conversations/bulk

Example request

curl "https://api.assembledhq.com/v0/conversations/bulk" \
  -H "Content-Type: application/json" \
  -X PATCH \
  -u sk_live_abc123: \
  -d '{
    "conversations": [
      {
        "import_id": "id_1",
        "channel": "chat"
      },
      {
        "import_id": "id_2",
        "queue": null
      }
    ]
  }'

Updates existing conversations with the specified parameters. There is a batch limit of 1000 conversations per request.

The import_id field is required to identify which conversation to update. 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. Fields that are marked as required in the Conversation object cannot be set to null.

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", "sms", "social", "chat" or "back_office" (if these are available on your Assembled instance) or "all".
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?channel=phone" \
  -X GET \
  -u sk_live_abc123:

Example response

{
  "forecasts": [
    {
      "start_time": 1549065600,
      "end_time": 1549066500,
      "channel": "phone",
      "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", "sms", "social", "chat" or "back_office" (if these are available on your Assembled instance) or "all".
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", "chat", "sms", "social" or "back_office".
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	See Value types. Defaults to "contacts" if not provided.

Forecast value types

The value_type field is used to specify the type of forecasted value. The following value types are supported:

Value type	Description
contacts	Forecast for case volume if the channel is not using case lifecycle. Otherwise, the numeric forecast for units of work.
case_volume	Forecast for case volume if the channel is using case lifecycle.
messages	Forecast for message volume.
reopened	Forecast for reopened case volume. Only applicable to asynchronous channels like email.
aht	Forecast for average handle time for cases, expressed in seconds. Only applicable to synchronous channels like chat.
productivity	Forecast for number of cases solved per hour per agent. Only applicable to asynchronous channels like email.
unit_of_work_throughput	Forecast for number of units of work solved per hour per agent. Only applicable to asynchronous channels like email.
unit_of_work_aht	Forecast for average handle time for units of work, expressed in minutes. Only applicable to synchronous channels like chat.

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 adherence
• available_and_occupied_time_seconds
• conformance_percentage
• schedule_adherence_percentage
• scheduled_seconds_productive
• scheduled_seconds_total
• seconds_in_adherence - refers to productive adherence
• occupancy_percentage
• occupancy_percentage_all_channels
• occupied_time_seconds
• utilization - refers to schedule utilization
• in_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	Adherence reports: 1h, 24h, or 1w. All other reports: 30m, 1h, 24h, or 1w. The interval cannot be greater than end_time - start_time. If end_time - start_time is greater than 24 hours, the interval must be greater than or equal to 24 hours.
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

Assist replies [Beta]

The Replies API allows you to generate AI-driven replies to customer support cases using Assembled Assist. By passing in the relevant case or ticket details, the API returns a suggested reply generated by a large language model (LLM), along with accompanying metadata. This generated reply adheres to your company's style guide and policies, incorporating relevant workflows and knowledge from Assist's integrated document base. The API helps automate response generation, streamlining case resolution while maintaining consistency and alignment with your support practices.

The Assist API is currently invite-only, please contact assist@assembledhq.com to find out how to access it.

Assist reply object

{
  "id": "<uuid>",
  "reply": {
    "body": "Hi there! I was able to pull up your reservation info, and we are able to offer the following refund options: - Credit that you can use for..."
  },
  "rationale": {
    "body": "The customer is asking about refund options, which matches the criteria for the refund workflow. The workflow step instructs me..."
  },
  "confidence": "high",
  "sources": [
    {
      "platform": "zendesk",
      "platform_id": "3627",
      "name": "Refund options for new customers",
      "visibility": "public",
      "url": "https://...",
      "type": "article",
      "rank": 1
    }
  ],
  "internal_note": {
    "body": "NOTE: As of 1 Oct 2024 the payment validation has been faulty--follow the below steps to ensure payment validation..."
  },
  "created_at": 1770000400
}

Field	Type	Description
id	uuid	Unique identifier for the reply
reply	object	The customer-facing reply generated by Assist in response to the given case
rationale	object	Assist’s reasoning for the generated reply. This is often useful to understand the assumptions and reasoning Assist made when generating the reply
confidence	string	The computed confidence of the customer reply, based on the relevant workflows and knowledge sources. Higher confidence replies imply there’s more relevant knowledge articles related to the ticket. One of: low medium high
sources	object[]	The sources from your knowledge base used by Assist to generate the replies details
internal_note	object	An optional internal note generated by Assist. An example of when this might be useful is if the next step of the case is to escalate it to a more specialized team, as opposed to directly reply back to the customer.
created_at	Unix timestamp, in seconds

Reply, rationale, and internal note objects

Each of the reply, rationale, and internal note objects in the Assist reply object will contain a field "body" which contains markdown formatted text.

Field	Type	Description
body	string	Markdown-formatted text

Source object

Field	Type	Description
platform	string	The platform that the source originated from. One of: zendesk, googledrive, notion, workramp, guru
platform_id	string	The platform ID of the source. For articles, this is the article ID
visibility	string	The field that marks whether the source is viewable only by internal agents or available to anyone. One of: public, private
type	string	The type of source. Currently the only supported type is: article
rank	int	The ranking of the sources in order of relevance to the generated reply. The lower the ranking, the higher the relevance (e.g. 1 is most relevant)
url	string	The URL where you can access this source
name	string	The name/title of the source

The source object is used to capture information about the knowledge base sources used in an Assist-generated reply.

POST /v0/assist/replies

Example request (platform case)

curl "https://api.assembledhq.com/v0/assist/replies" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "case": {
      "input_type": "platform",
      "platform_case": {
        "platform": "zendesk",
        "platform_id": "5730"
      }
    },
    "agent": {
      "platform": "zendesk",
      "platform_id": "9807"
    }
  }'

Example request (direct input case)

curl "https://api.assembledhq.com/v0/assist/replies" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "case": {
      "input_type": "platform",
      "direct_input_case": {
        "subject": "Refund options",
        "messages": [
          {
            "body": "What are my refund options for my reservation?",
            "role": "customer",
            "created_at": 1770090400
          },
          {
            "body": "My booking number is 4819273",
            "role": "customer",
            "created_at": 1770090420
          }
        ],
        "metadata": {
          "channel": "sms"
        }
      }
    },
    "agent": {
      "platform": "zendesk",
      "platform_id": "9807"
    }
  }'

Example response

{
  "id": "<uuid>",
  "reply": {
    "body": "Hi there! I was able to pull up your reservation info, and we are able to offer the following refund options: - Credit that you can use for..."
  },
  "rationale": {
    "body": "The customer is asking about refund options, which matches the criteria for the refund workflow. The workflow step instructs me..."
  },
  "confidence": "high",
  "sources": [
    {
      "platform": "zendesk",
      "platform_id": "3627",
      "name": "Refund options for new customers",
      "visibility": "public",
      "url": "https://...",
      "type": "article",
      "rank": 1
    }
  ],
  "internal_note": {
    "body": "NOTE: As of 1 Oct 2024 the payment validation has been faulty--follow the below steps to ensure payment validation..."
  },
  "created_at": 1770000400
}

Creates a new Assist reply for the given input case.

Parameters:

Field	Type	Required	Description
case	object	Required	The case/ticket to which a reply is being generated. This data is automatically imported via the platform’s integration with your Assembled instance pattern, or you can provide the case details directly in the case input
agent	object	Required	The agent who triggered this Assist interaction. This is required for both tracking purposes as well as adding in personalized style instructions

Case object

Field	Type	Required	Description
input_type	string	Required	One of: platform, direct_input. If platform then we fetch the case via the provided platform and platform id. If direct_input, then we fetch the case details via the user-provided direct_input_case
platform_case	object	Optional	Must be provided if input_type is platform. Do not provide if input_type is direct_input
direct_input_case	object	Optional	Must be provided if input type is direct_input. Do not provide if input_type is platform

There are two ways you can provide the case details for Assist to generate a reply: 1) Specify the platform and platform ID of the case and utilize your platform's integration with Assembled or 2) Directly provide the case details in the API request.

Platform case

Field	Type	Required	Description
platform	string	Required	The platform where Assist will pull the case details. Currently the only supported value is: zendesk
platform_id	object	Required	The id of the case, on the given platform.

Direct input case

Field	Type	Required	Description
subject	string	Required	The subject of this case. Please provide a useful subject description
messages	list[object]	Required	Pass in ALL the messages that you want Assist to have awareness of in order to generate a reply
metadata	map[string]string	Optional	Additional fields that can be useful as added context (e.g. customer_tier: free). These will be passed to the LLM and can be used for routing and filtering replies

Direct input message

Field	Type	Required	Description
body	string	Required	The text content of the case message, formatted in markdown
role	list[object]	Required	One of: customer, agent, internal. Specifies who is the message in this case from
created_at	Unix timestamp, in seconds	Required

Agent object

Field	Type	Required	Description
platform	string	Required	The platform that this agent can be identified on. Currently the only supported value is: zendesk
platform_id	object	Required	The id of the agent, on the given platform

Assist knowledge articles [Beta]

The Knowledge Articles API allows you to manage knowledge articles used by Assembled Assist for generating AI-driven resolutions. This API enables you to create, update, and delete knowledge articles that Assist uses as reference material when generating responses to customer support cases. By maintaining an up-to-date knowledge base through this API, you ensure that Assist's replies accurately reflect your current policies, workflows, and support information.

The Assist API is currently invite-only, please contact assist@assembledhq.com to find out how to access it.

Document metadata object

{
  "id": "article_123456",
  "source_url": "https://support.example.com/articles/refund-policy",
  "title": "Refund Policy for Premium Customers",
  "internal": false,
  "tags": ["refunds", "policy", "premium"],
  "updated_at": 1770000400
}

Field	Type	Description
id	string	Unique identifier for the article (provided by the client)
source_url	string	The full source URL of the document
title	string	Title of the document
internal	boolean	Whether this document is internal (only visible to agents) or customer-facing
tags	list[string]	Tags associated with this document, useful for categorizing and retrieving relevant knowledge
updated_at	Unix timestamp, in seconds	Unix time representing when this article was last updated

POST /v0/assist/articles

Example request

curl "https://api.assembledhq.com/v0/assist/articles" \
  -X POST \
  -u sk_live_abc123: \
  -F "file=@/path/to/refund_policy.pdf" \
  -F "id=article_123456" \
  -F "source_url=https://support.example.com/articles/refund-policy" \
  -F "title=Refund Policy for Premium Customers" \
  -F "internal=false" \
  -F "tags=[\"refunds\", \"policy\", \"premium\"]" \
  -F "updated_at=1770000400"

Example response

{
  "id": "article_123456",
  "source_url": "https://support.example.com/articles/refund-policy",
  "title": "Refund Policy for Premium Customers",
  "internal": false,
  "tags": ["refunds", "policy", "premium"],
  "updated_at": 1770000400
}

Creates a new knowledge article with the specified file content and metadata. The client must provide an ID and a Unix timestamp for updated_at.

Parameters:

Field	Type	Required	Description
file	binary	Required	The file binary to be uploaded (TXT files only at the moment)
id	string	Required	Unique identifier for the article (provided by the client)
source_url	string	Required	The full source URL of the document
title	string	Required	The title for this document
internal	boolean	Required	Whether this document is internal (only visible to agents) or customer-facing
tags	list[string]	Optional	Tags associated with this document
updated_at	Unix timestamp, in seconds	Required	Unix time when this file was last updated, provided by the client

PUT /v0/assist/articles/{id}

Example request

curl "https://api.assembledhq.com/v0/assist/articles/article_123456" \
  -X PUT \
  -u sk_live_abc123: \
  -F "file=@/path/to/updated_refund_policy.pdf" \
  -F "source_url=https://support.example.com/articles/refund-policy" \
  -F "title=Updated Refund Policy for Premium Customers" \
  -F "internal=false" \
  -F "tags=[\"refunds\", \"policy\", \"premium\", \"updated\"]" \
  -F "updated_at=1771000400"

Example response

{
  "id": "article_123456",
  "source_url": "https://support.example.com/articles/refund-policy",
  "title": "Updated Refund Policy for Premium Customers",
  "internal": false,
  "tags": ["refunds", "policy", "premium", "updated"],
  "updated_at": 1771000400
}

Updates an existing knowledge article by replacing its content and metadata. The id in the path parameter must match the article being updated. The updated_at timestamp must be newer than the current file's timestamp, otherwise an error will be returned.

Parameters:

Field	Type	Required	Description
file	binary	Required	The new file content to replace the existing file
source_url	string	Required	New or updated source URL for the document
title	string	Required	New or updated title for this document
internal	boolean	Required	New or updated internal flag for this document
tags	list[string]	Optional	New or updated tags for this document
updated_at	Unix timestamp, in seconds	Required	Unix time when this file is being updated, provided by the client

DELETE /v0/assist/articles/{id}

Example request

curl "https://api.assembledhq.com/v0/assist/articles/article_123456" \
  -X DELETE \
  -u sk_live_abc123:

Deletes an existing knowledge article from the system. If the article with the specified ID is not found, an error will be returned.

Parameters:

Field	Type	Required	Description
id	string	Required	The unique identifier of the article to delete

Assist conversations [Beta]

The Assist conversations API allows you to retrieve information about conversations that occur with an Assembled AI agent. This API provides detailed information including conversation metadata, messages, and evaluation metrics. You can use this API to analyze conversation quality, track user interactions, and monitor AI assistant performance.

The Assist API is currently invite-only, please contact assist@assembledhq.com to find out how to access it.

Assist conversation object

Note: This is different from the Conversation object used in the main Assembled API.

Example 1: Phone conversation with transfer

{
  "id": "<uuid>",
  "created_at": 1770000400,
  "platform_case": {
    "platform": "five9",
    "platform_id": "5730"
  },
  "status": "handed_off",
  "conversation_type": "phone",
  "copilot_action_type": null,
  "transfer_details": {
    "transferred_case_id": "5731",
    "transferred_case_platform": "zendesk",
    "routing_destination": {
      "id": "support_team_1",
      "name": "Technical Support"
    },
    "collected_handoff_data": {
      "customer_tier": "premium",
      "issue_complexity": "high",
      "requires_escalation": true
    }
  },
  "messages": [
    {
      "role": "end_user",
      "content": {
        "type": "text",
        "text": "I need help with my account settings"
      }
    },
    {
      "role": "assistant",
      "content": {
        "type": "text",
        "text": "I understand you need help with your account settings. Based on your premium status, I'll transfer you to our technical support team who can better assist you."
      },
      "sources_used": [
        {
          "url": "https://docs.example.com/account-settings",
          "platform": "internal_docs",
          "title": "Account Settings Guide"
        }
      ]
    }
  ],
  "quality_metrics": null,
  "evaluations": null
}

Example 2: Copilot conversation with quality metrics

{
  "id": "<uuid>",
  "created_at": 1770000401,
  "platform_case": {
    "platform": "zendesk",
    "platform_id": "5732"
  },
  "status": "resolved",
  "conversation_type": "copilot",
  "copilot_action_type": "draft_reply",
  "transfer_details": null,
  "messages": [
    {
      "role": "end_user",
      "content": {
        "type": "text",
        "text": "How do I reset my password?"
      }
    },
    {
      "role": "assistant",
      "content": {
        "type": "text",
        "text": "I can help you reset your password. Here are the steps: 1. Click the 'Forgot Password' link..."
      },
      "sources_used": [
        {
          "url": "https://docs.example.com/password-reset",
          "platform": "internal_docs",
          "title": "Password Reset Instructions"
        }
      ]
    }
  ],
  "quality_metrics": {
    "semantic_similarity": 0.92,
    "trigram_similarity": 0.88,
    "compared_agent_message": {
      "content": "Here's how to reset your password: 1. Click the 'Forgot Password' link...",
      "platform_id": "5733"
    }
  },
  "evaluations": {
    "custom_feedback": {
      "feedback_1": {
        "name": "Response Accuracy",
        "feedback_label": "Very Accurate",
        "feedback_value": 5.0,
        "reasoning_tag": "accurate_response"
      }
    }
  }
}

Field	Type	Description
id	uuid	Unique identifier for the conversation
created_at	Unix timestamp, in seconds	When the conversation was created
platform_case	Platform case object	Information about the platform the case originated from
status	string	For phone conversations, overall status of the conversation. One of: active, handed_off, abandoned, resolved. Will be null for copilot conversations
conversation_type	string	The type of conversation. One of: email, copilot, chat, phone.
copilot_action_type	string	For copilot conversations, the type of action performed. One of: draft_reply, compose_from_notes, respond_as_agent, suggest_canned_responses, rephrase_text, summarize_ticket, initial_greeting. Will be null for non-copilot conversations.
transfer_details	Transfer details object	For phone conversations, transfer-related metadata. Will be null for other conversation types.
messages	Message object[]	The list of messages in the conversation
quality_metrics	Quality metrics object	The evaluated quality of the assistant's response. Will be null if include_evaluation_metrics is false or if the conversation hasn't been evaluated.
evaluations	Evaluations object	Evaluation information for the conversation. Will be null if include_evaluation_metrics is false or if no evaluations exist.

Platform case object

Field	Type	Description
platform	string	The platform the conversation originated from. One of: zendesk, five9
platform_id	string	The case id from the platform

Transfer details object

Field	Type	Description
transferred_case_id	string	The ID of the case created by Assembled
transferred_case_platform	string	The platform of the case created by Assembled
routing_destination	Routing destination object	The routing destination for the call
collected_handoff_data	object	A map of string keys to boolean, number, or string values representing data gathered by the model

Routing destination object

Field	Type	Description
id	string	Unique identifier of the routing destination
name	string	Name of the routing destination

Message object

Field	Type	Description
role	string	Who sent the message. One of: end_user, assistant, agent
content	Message content object	The message content
sources_used	Sources used object[]	The sources used to generate the AI assistant's reply

Message content object

Field	Type	Description
type	string	The type of the message content. One of: text, image_url
text	string	The text content of the message (if type = text)
url	string	The URL or base64 encoded image data (if type = image_url)

Quality metrics object

Field	Type	Description
semantic_similarity	number	The semantic similarity score of the AI assistant's response
trigram_similarity	number	The trigram similarity score of the AI assistant's response
compared_agent_message	Compared agent message object	The agent's response that the similarity scores are calculated against

Compared agent message object

Field	Type	Description
content	string	The message the agent sent
platform_id	string	The id of the message sent on the given platform
platform	string	The platform the message was sent on

Evaluations object

Field	Type	Description
custom_feedback	Custom feedback object	A map of unique identifiers to feedback objects

Custom feedback object

Field	Type	Description
name	string	The name/title of this feedback item
feedback_label	string	The custom feedback option selected
feedback_value	float	The custom feedback value selected
reasoning_tag	string	Tag associated with the feedback

Sources used object

Field	Type	Description
url	string	The URL of the source
platform	string	The platform the source originates from
title	string	The title of the source

GET /v0/assist/conversations

Example request

curl "https://api.assembledhq.com/v0/assist/conversations?limit=20&offset=0&include_messages=true&include_sources=true&include_evaluation_metrics=true" \
  -H "Content-Type: application/json" \
  -X GET \
  -u sk_live_abc123:

Example response

{
  "limit": 20,
  "offset": 0,
  "total": 150,
  "conversations": [
    {
      "id": "<uuid>",
      "created_at": 1770000400,
      "platform_case": {
        "platform": "zendesk",
        "platform_id": "5730"
      },
      "status": null,
      "conversation_type": "email",
      "copilot_action_type": null,
      "transfer_details": null,
      "messages": [
        {
          "role": "end_user",
          "content": {
            "type": "text",
            "text": "I need help with my account settings"
          }
        },
        {
          "role": "assistant",
          "content": {
            "type": "text",
            "text": "I'd be happy to help you with your account settings. What specific changes would you like to make?"
          },
          "sources_used": [
            {
              "url": "https://docs.example.com/account-settings",
              "platform": "internal_docs",
              "title": "Account Settings Guide"
            }
          ]
        }
      ],
      "quality_metrics": {
        "semantic_similarity": 0.92,
        "trigram_similarity": 0.88,
        "compared_agent_message": {
          "content": "I can help you with your account settings. What specific changes would you like to make?",
          "platform_id": "5732"
        }
      },
      "evaluations": {
        "custom_feedback": {
          "feedback_1": {
            "name": "Response Accuracy",
            "feedback_label": "Very Accurate",
            "feedback_value": 5.0,
            "reasoning_tag": "accurate_response"
          }
        }
      }
    }
  ]
}

Retrieves a list of conversations and actions performed by users of Assembled Assist, including message content, timestamps, sources used, and quality review metrics.

Parameters:

Field	Type	Required	Description
transfer_platform	string	Optional	Only used for phone conversations. The platform from which Assembled receives and/or sends call transfers. Required if passing in transfer_platform_id.
transfer_platform_id	string	Optional	Only used for phone conversations. The transfer platform's unique identifier for the conversation.
limit	integer	Optional	The number of conversations to return. Default: 20
offset	integer	Optional	The number of conversations to skip before starting to return results. Default: 0
start_time	integer	Required	Return conversations created after this Unix timestamp (in seconds).
end_time	integer	Required	Return conversations created before this Unix timestamp (in seconds).
include_evaluation_metrics	boolean	Optional	Include information relating to the evaluation of a conversation (e.g., QA evaluation, semantic similarity, responses, etc.). Default: false
include_messages	boolean	Optional	Include information about the conversation messages between the end user and AI assistant. Default: false

Assist chat completions [Beta]

The Assembled Chat API allows you to integrate your own frontend interface for a support chatbot with the Assist for Chat backend. This API enables your applications to create and manage conversations with your own support chatbot using Assembled Assist's workflows, knowledge integrations, and escalation detection.

The Assist API is currently invite-only, please contact assist@assembledhq.com to find out how to access it.

Assist chat completion object

Example 1: Basic chat completion response

{
  "id": "69cae7b6-ab43-4e1f-9f3b-56ccfecb71a4",
  "created_at": 1677858242,
  "message": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "There are eight recognized planets in our solar system: Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, and Neptune."
    },
    "created_at": 1677858242,
    "cited_sources": [
      {
        "position": 34,
        "source": {
          "platform": "public_website",
          "title": "Planet - Wikipedia",
          "url": "https://en.wikipedia.org/wiki/Planet",
          "content": "A planet is a large, rounded astronomical body that is generally required to be in orbit around a star, stellar remnant, or brown dwarf, and is not one itself."
        }
      }
    ],
    "workflow": {
      "id": "7452c621-3698-43ee-a331-b4bba9566291",
      "name": "General Knowledge",
      "in_progress": false
    }
  },
  "handoff_details": {
    "handoff": false,
    "rationale": "The customer's inquiry about planets is a routine information request that does not indicate any frustration or urgency. The question is straightforward and can be addressed by the chatbot without the need for human handoff.",
    "handoff_message": ""
  },
  "conversation_id": "conv_12345abcde"
}

Field	Type	Description
id	uuid	Unique identifier for the chat completion. This same ID can be used to retrieve the full conversation details from the conversations endpoint.
created_at	Unix timestamp, in seconds	When the chat completion was created
message	Message object	The assistant's response message
handoff_details	Handoff details object	Information about whether the conversation should be handed off to a human agent
conversation_id	string	The unique identifier for the conversation thread

Message object

Field	Type	Description
role	string	Who sent the message. One of: user, assistant
content	Message content object	The message content
created_at	integer	The unix timestamp of when the message was created
cited_sources	Cited source object[]	Sources referenced in the message
workflow	Workflow object	Information about the workflow being used

Message content object

Field	Type	Description
type	string	The type of the message content. One of: text, image_url
text	string	The text content of the message (if type = text)
url	string	The URL or base64 encoded image data (if type = image_url)

Cited source object

Field	Type	Description
position	integer	The position in the message where this source was cited
source	Source object	The source that was cited

Source object

Field	Type	Description
platform	string	The platform the source originated from
title	string	The title of the source
url	string	The URL where you can access this source
content	string	The relevant content from the source

Workflow object

Field	Type	Description
id	string	The unique identifier of the workflow
name	string	The name of the workflow
in_progress	boolean	Whether or not the workflow is still in progress and has not yet completed yet

Handoff details object

Field	Type	Description
handoff	boolean	Whether the chat conversation should be handed off to a human agent. This feature is currently only available for chat conversations.
rationale	string	The reasoning behind the handoff decision
handoff_message	string	A personalized message to the user explaining the handoff, tailored to the specific conversation context

When a handoff is recommended, you should transfer the conversation to a human agent using your own handoff mechanism. The handoff details provide guidance on when and why a handoff is needed, but the actual handoff process must be implemented by your application.

Assist chat completion handoff object

The Assist chat completion handoff object is designed to facilitate the transition of a conversation from an AI assistant to a human agent. When retrieving information about a conversation for handoff purposes, this object provides a human-friendly summary of the conversation, including key details such as the main topic, customer issue, sentiment analysis, and a complete transcript. These details allow a human agent to quickly understand the context and history of the conversation without having to parse through raw data, enabling a smoother handoff experience.

Field	Type	Description
title	string	A concise title summarizing the main topic or purpose of the conversation (e.g., "Question about data export functionality")
issue	string	A more detailed description of the customer's issue or request, including any challenges encountered (e.g., "Customer needed help with CSV export feature but received inconsistent information")
start_sentiment	string	The user's sentiment detected at the beginning of the conversation. One of "neutral", "positive", "negative".
end_sentiment	string	The user's sentiment detected at the end of the conversation. One of "neutral", "positive", "negative".
summary	string	A bullet-point summary of key events and outcomes from the conversation, formatted with newlines (\n) between points
transcript	string	A timestamped transcript of the entire conversation, including both user and assistant messages. Each message is prefixed with a timestamp and the sender's role (e.g., "[14:22] user: How do I export my team's data to CSV?")
attachments	array	An array of Attachment objects containing images shared during the conversation

Attachment object

Field	Type	Description
name	string	The name of the attached file
url	string	The URL where the attachment can be accessed
media_type	string	The type of the attachment (e.g., "image/png")

POST /v0/assist/chat/completions

Example request (basic chat completion)

curl "https://api.assembledhq.com/v0/assist/chat/completions" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "conversation_id": "conv_12345abcde",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "How do I reset my password?"
        },
        "created_at": 1677858242
      }
    ],
    "user": {
      "user_id": "12345"
    },
    "stream": true
  }'

Example request (with image)

curl "https://api.assembledhq.com/v0/assist/chat/completions" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "conversation_id": "conv_12345abcde",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "image_url",
          "url": "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
        },
        "created_at": 1677858242
      },
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "Tell me a bit more about this image"
        },
        "created_at": 1677858500
      }
    ],
    "user": {
      "user_id": "12345"
    },
    "stream": true
  }'

Example request (with workflow and user data)

curl "https://api.assembledhq.com/v0/assist/chat/completions" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "conversation_id": "conv_12345abcde",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "How do I reset my password?"
        },
        "created_at": 1677858242
      }
    ],
    "user": {
      "user_id": "12345",
      "email": "user@example.com",
      "name": "John Doe",
      "user_metadata": {
        "account_type": "premium",
        "signup_date": "2023-01-15"
      }
    },
    "workflow_id": "7452c621-3698-43ee-a331-b4bba9566291",
    "stream": true
  }'

Initiates or continues a conversation with the support chatbot.

Parameters:

Field	Type	Required	Description
conversation_id	string	Required	A unique identifier for the conversation. Should be unique to each conversation thread.
messages	array	Required	An array of message objects representing the conversation history.
user	object	Optional	Information about the end user.
workflow_id	string	Optional	Specific workflow ID to use for this conversation.
disable_workflows	boolean	Optional	When set to true, disables all workflows for this conversation. Default: false
possible_workflows	array	Optional	List of workflow IDs that can be used for this conversation.
handoff	object	Optional	Configuration for escalation detection.
stream	boolean	Optional	When set to true, returns responses as server-sent events. Default: false

User request object

Field	Type	Required	Description
user_id	string	Required	A unique identifier for the user in your system. This should be the same ID you use to identify users in your application. This ID is used to maintain conversation context and personalize responses.
email	string	Optional	The user's email address.
name	string	Optional	The user's name.
user_metadata	object	Optional	A key-value map of string to string for additional user metadata.

Handoff request object

Field	Type	Required	Description
enabled	boolean	Optional	When set to true, enables handoff detection. Default depends on account settings.
sensitivity	string	Optional	Determines how readily the system will recommend handoff from AI to a human agent. Valid values: "low", "medium", "high". Higher sensitivity means the system will more aggressively detect potential escalation scenarios and recommend handoff to human agents, even for less severe cases. Lower sensitivity will only trigger handoff for clearly problematic conversations.

GET /v0/assist/chat/completions/handoff

Example request

curl "https://api.assembledhq.com/v0/assist/chat/completions/handoff?language=en-US&conversation_id=conv_12345abcde" \
  -H "Content-Type: application/json" \
  -X GET \
  -u sk_live_abc123:

Example response

{
  "title": "Question about data export functionality",
  "issue": "Customer needed help with CSV export feature but received inconsistent information",
  "start_sentiment": "neutral",
  "end_sentiment": "positive",
  "summary": "- Customer inquired about exporting data to CSV format\n- Initial response provided incomplete information\n- Agent clarified export process with specific steps\n- Customer successfully completed the export",
  "transcript": "[14:22] user: How do I export my team's data to CSV?\n[14:23] assistant: You can export data from the Reports section. Would you like me to explain the process?\n[14:24] user: Yes, please show me the steps\n[14:25] assistant: To export data to CSV: 1) Navigate to Reports, 2) Select your report type, 3) Click the export icon in the top right, 4) Choose CSV format, 5) Click Download\n[14:26] user: Thanks, that worked!",
  "attachments": [
    {
      "name": "export_screenshot.png",
      "url": "https://api.assembledhq.com/v0/files/abc123/export_screenshot.png",
      "media_type": "image/png"
    }
  ]
}

Retrieves detailed information about a specific conversation to facilitate agent handoff and returns an Assist chat completion handoff object. When a conversation transitions from an AI assistant to a human agent, this endpoint provides the human agent with essential context including the conversation transcript, a concise summary, sentiment analysis, and identified issues. This helps agents quickly understand the customer's needs and the conversation history. Note: This endpoint currently only supports chat conversations.

Parameters:

Field	Type	Required	Description
conversation_id	string	Required	The unique identifier for the conversation in your system. This is the conversation ID that was passed in to the POST /assist/chat/completions endpoint, not the Assembled conversation ID.
language	string	Optional	The ISO language code for translating the conversation content. Uses ISO 639-1 two-letter language codes (e.g., 'en', 'es', 'fr') or combined ISO 639-1 and ISO 3166-1 country codes (e.g., 'en-US', 'es-ES', 'fr-FR'). Only the conversation content (transcript, summary, issue) will be translated, while JSON field names remain unchanged.

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 do not need a new API version and will not appear in this list. The latest API version is 2025-04-15.

2025-04-15

• Resource: activities
  • Updated the activity endpoint to return string identifiers instead of uuids

2024-10-02

• Resource: assist_replies (Beta)
  • Added endpoint to generate an Assist reply for a given input case

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 to activity_type_id for the POST /time_off endpoint
  • Return activity_type_id for time off requests fetched via GET /time_off/requests & GET /time_off/updates

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.

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 and DELETE. These will all live on the /people endpoint. We now return a collection of teams and sites in the GET response.

2019-06-20

• Resource: activity
  • Activity resources will now return a unix timestamp (in seconds) for start_time and end_time instead of a formatted string. Additionally, the type and channels 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 the type_id.
• 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 displaying channels on each Activity resource.

2019-02-22

• Initial API Version