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

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

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)

curl "https://api.assembledhq.com/v0/people" \
  -u sk_live_abc123

{
  "teams": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "string",
      "parent_id": "<uuid>",
      "created_at": 1546303260,
      "updated_at": 1546303260
    }
  },
  "sites": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "string",
      "parent_id": "<uuid>",
      "created_at": 1546303260,
      "updated_at": 1546303260
    }
  },
  "people": {
    "<uuid>": {
      "id": "<uuid>",
      "agent_id": "string",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john.smith@example.com",
      "imported_id": "third_party_identifier",
      "roles": ["<uuid>"],
      "agent_role": "string",
      "channels": ["email", "chat", "phone", "social", "sms"],
      "site": "<uuid>",
      "teams": ["<uuid>"],
      "queues": ["<uuid>"],
      "skills": ["<uuid>"],
      "platforms": {
        "zendesk": "string",
        "api": "string"
      },
      "start_date": 1546303260,
      "end_date": 1546303260,
      "created_at": 1546303260,
      "deleted": false,
      "staffable": false
    }
  },
  "total": 26,
  "limit": null,
  "offset": null
}

Query parameters:

Field	Type	Required	Description
channel	list[string]	Optional	One of `phone`, `email`, `chat`, `sms` or `social`. The channel must exist on the Assembled dashboard
team	uuid	Optional	Unique identifier for a team. Returns people who are part of this team.
site	uuid	Optional	Unique identifier for a site. Returns people who are part of this site.
restricted_site	uuid	Optional	Unique identifier for a site. Returns people who are part of this restricted site. Note: Restricted site must be enabled for your company.
queue	uuid	Optional	Unique identifier for a queue. Returns people who are part of this queue.
skill	uuid	Optional	Unique identifier for a skill. Returns people who have this skill.
role	uuid	Optional	Unique identifier for a role. Returns people who are assigned this role.
include_deleted	boolean	Optional	If `true`, also includes Persons that have been soft-deleted
search	string	Optional	Searches Persons based on `first_name`, `last_name` or `email`
sort_by	string	Optional	Allows for sorting of Persons based on `first_name`, `last_name`, or `role`
sort_direction	string	Optional	Required if used with `sort_by`. Supported values: `ascending`, `descending`
limit	int	Optional	20 responses are returned by default, but the maximum value is `500`
offset	int	Optional	Adds an offset to the responses returned, starting from 0

GET /v0/people/:id

Returns a Person based on the id provided

curl "https://api.assembledhq.com/v0/people/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
  -u sk_live_abc123

{
  "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

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"
            ]
          }
      ]
   }'

{
  "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
}

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"
            ]
          }
      ]
   }'

{
  "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`, and `zendesk_talk`
start_date	UNIX timestamp, in seconds	Optional	Person's start date specified by the user on creation
end_date	UNIX timestamp, in seconds	Optional	Person's end date used to indicate when they can no longer be scheduled. Usually, this field is used to preserve agent data in the event of a role change into a non-staffable role or the termination of their contract
send_invite_email	boolean	Optional	Indicates whether or not to send the Person an invite e-mail to Assembled

PATCH /v0/people/:id

curl "https://api.assembledhq.com/v0/people/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
  -X PATCH \
  -u sk_live_abc123: \
  -d '{
        "id": "<uuid>",
        "agent_id": "<uuid>",
        "first_name": "John",
        "last_name": "Smith",
        "email": "john@smith.com",
        "timezone": "",
        "import_id": "<uuid>",
        "role": "<uuid>",
        "agent_role": "agent",
        "channels": ["email"],
        "site": null,
        "teams": ["<uuid>"],
        "queues": ["<uuid>"],
        "skills": ["<uuid>"],
        "platforms": {

        }
        "start_date": 1647930594,
        "end_date": 1647940000,
        "created_at": 1648502490,
        "staffable": false
  }'

{
  "message": "person successfully updated",
  "people": [
    {
      "id": "<uuid>",
      "agent_id": "<uuid>",
      "first_name": "string",
      "last_name": "string",
      "email": "string",
      "timezone": "string",
      "imported_id": "string",
      "roles": ["<uuid>"],
      "agent_role": "agent",
      "channels": ["email"],
      "site": null,
      "teams": [],
      "queues": [],
      "skills": [],
      "start_date": 1648518167,
      "end_date": 1648518167,
      "created_at": 1648618871,
      "platforms": {},
      "deleted": false,
      "staffable": false
    }
  ]
}

Partial update of an agent with the specified fields. Fields that are not included in the request are not updated, while fields that are explicitly set to null or an appropriate empty value (for example, "[]" for lists) are set to empty. Valid IDs for site, teams, and queues can be retrieved from endpoints for filters. This endpoint will return 400 if invalid filter IDs are provided.

Parameters:

Field	Type	Required	Description
imported_id	string	Optional	The ID of the Person that you are creating
first_name	string	Optional
last_name	string	Optional
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

curl "https://api.assembledhq.com/v0/people/8ce1939e-cc6c-48e8-b0ef-a2326b562082?hard=true" \
  -X DELETE \
  -u sk_live_abc123

{
  "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

curl "https://api.assembledhq.com/v0/roles" \
  -X GET \
  -u sk_live_abc123:

{
  "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

curl "https://api.assembledhq.com/v0/agents/state" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "agent_platform_id": "25963324267",
    "time": 1549065600,
    "state": "online"
  }'

Send the current state of an agent to Assembled. The agent will be considered to be in this state until a new state is provided.

Parameters:

Field	Type	Required	Description
agent_platform_id	string	Required	Unique identifier for the agent for a platform. This can be associated to agents in Assembled with the agent associations endpoint.
time	Unix timestamp, in seconds	Required	Current time at which agent is in the specified state.
state	string	Optional	Agent’s current status from upstream system e.g. "online", "away", or "busy". Values are not validated, but can be mapped to activity types on the Assembled application by an Administrator. If this field is not supplied, this will end the last state provided, while not initiating a new state.

GET /v0/agents/state

Returns a list of agent state objects that match the provided query.

We allow getting agent states for a single agent, agents by filters, and all agents. Valid IDs for site, team, queue, and skill can be retrieved from endpoints for filters, or via GET /people. This endpoint will return 400 if both agent IDs and filter IDs are provided, or if invalid filter IDs are provided.

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:

{
  "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
}

curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367&channel=chat" \
  -u sk_live_abc123:

{
  "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
}

curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367" \
  -u sk_live_abc123:

{
  "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.

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:

{
  "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

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

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

curl "https://api.assembledhq.com/v0/agents/state/edit/history?start_time=1600000000&end_time=1700000000" \
  -u sk_live_abc123:

{
  [
    {
      "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

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>\"
  }"

{
  "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

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>\"
        }
      }
    ]
  }"

{
  "activities": {
    "<uuid>": {
      "id": "<uuid>",
      "start_time": 1562223600,
      "end_time": 1562259600,
      "created_at": 1562251600,
      "updated_at": 1562221600,
      "agent_id": "<uuid>",
      "type_id": "<uuid>"
    },
  }
}

Creates, updates, or deletes multiple activities in a single request. A given request occurs within a transaction, so in the event of an error during the request, it should be assumed that no changes were processed.

Parameters:

Field	Type	Required	Description
activities	list[BulkRequest]	Required	An array of requests following the format below.
schedule_id	string	Optional	Identifier for the corresponding schedule. Defaults to the master schedule.

Bulk Request Parameters:

Field	Type	Required	Description
action	string	Required	Value can only be `create`.
activity	Activity	Required	See documentation for the Activity object. Note that the `allow_conflicts` parameter is not supported in the bulk endpoint.

GET /v0/activities

curl "https://api.assembledhq.com/v0/activities?start_time=1562223600&end_time=1562259600" \
  -u sk_live_abc123: -X GET

{
  "activities": {
    "<uuid>": {
      "id": "<uuid>",
      "start_time": 1562223600,
      "end_time": 1562259600,
      "created_at": 1562221600,
      "updated_at": 1562223600,
      "agent_id": "<uuid>",
      "type_id": "<uuid>"
    },
    ...
  },
  "agents": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Michael Scott",
      ...
    }
  },
  "queues": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Queue Name"
    }
  }
}

Returns a list of activity objects that match the provided query.

Parameters:

Field	Type	Required	Description
start_time	Unix timestamp, in seconds	Required
end_time	Unix timestamp, in seconds	Required	Together with start_time, this determines the interval for which shifts will be retrieved.
schedule_id	uuid	Optional	Identifier for the corresponding schedule. Defaults to the master schedule.
include_activity_types	boolean	Optional	If true, include activity types active on the account. Defaults to `false`.
include_agents	boolean	Optional	If true, include associated agent objects. Defaults to `false`.
team	string	Optional	Filter results to a specific team.
channel	string	Optional	Filter results to a specific channel.
types	list[uuid]	Optional	Filter results to a specific set of types.
agents	list[uuid]	Optional	Filter results to a specific set of agents.

DELETE /v0/activities

curl "https://api.assembledhq.com/v0/activities" \
  -X DELETE \
  -u sk_live_abc123: \
  -d "{
    \"start_time\": 1562223600,
    \"end_time\": 1562259600,
    \"agent_ids\": [\"<uuid>\"]
  }"

{
  "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

curl "https://api.assembledhq.com/v0/activity_types" \
  -u sk_live_abc123:

{
  "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

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 }'

{
  "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

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

curl "https://api.assembledhq.com/v0/event_changes?start_time=1665888528&end_time=1667270928" \
  -u sk_live_abc123: -X GET

{
  "event_changes": {
    "<uuid>": {
      "id": "<uuid>",
      "event_id": "<uuid>",
      "modified_by": {
        "name": "John Smith",
        "id": "<uuid>",
        "email": "john.smith@example.com"
      },
      "modified_at": 1665954677,
      "event_agent_name": "Jane Doe",
      "event_agent_id": "<uuid>",
      "event_agent_email": "jane.doe@example.com",
      "event_change_type": "modify",
      "description": "Events Edited and Published",
      "old_event_type": "activity_type_value1234",
      "new_event_type": "activity_type_value5678",
      "old_start_time": 1665702700,
      "old_end_time": 1665727300,
      "new_start_time": 1665703700,
      "new_end_time": 1665715900,
      "old_channels": ["phone"],
      "new_channels": ["chat"],
      "old_template_id": "<uuid>",
      "new_template_id": "<uuid>",
      "old_google_calendar_event_id": "<gcal_event_id>",
      "new_google_calendar_event_id": "<gcal_event_id>"
    },
    ...
  },
  "limit": 0,
  "offset": 0,
  "total": 100
}

Returns a list of event change objects that match the provided query.

Parameters:

Field	Type	Required	Description
start_time	Unix timestamp, in seconds	Required
end_time	Unix timestamp, in seconds	Required	Together with `start_time`, specifies the range of creation times of retrieved event changes.
schedule_id	uuid	Optional	Identifier for the corresponding schedule. Defaults to the master schedule.
agent_id	uuid	Optional	When provided, only retrieve event changes for the specified agent.
limit	integer	Optional	Maximum number of results to return. Defaults to 20.
offset	integer	Optional	Offset into the results to return. Defaults to 0.

Conversations

Conversations represent a unit of work. They are typically created when a customer and a support agent exchange their first message. Forecasts will be generated based on historical conversation volume.

Conversation object

{
  "created_at": 1549065600,
  "import_id": "122308400000062",
  "channel": "phone",
  "status": "solved",
  "queue": "<uuid>",
  "first_responded_at": 1549065700,
  "solved_at": 1549065800,
  "assignee_import_id": "d613ab77-75f7-4fce-91d8-f9ef5fe55066",
  "tags": ["tag1", "tag2", "tag3"]
}

Field	Type	Required	Description
created_at	Unix timestamp, in seconds	Required	Time the conversation was created.
import_id	string	Required	Third-party identifier. Must be unique to the conversation.
channel	string	Required	One of: "phone", "email", "chat", "social" or "back_office".
status	string	Required	One of: "open", "pending", "solved" or "abandoned".
queue	uuid	Optional	Unique identifier for the corresponding queue.
first_responded_at	Unix timestamp, in seconds	Optional	Time the conversation was first responded to by an agent.
solved_at	Unix timestamp, in seconds	Optional	Time the conversation was solved or closed.
assignee_import_id	string	Optional	Third-party identifier for the agent currently assigned to the conversation.
tags	list[string]	Optional	List of tags associated with the conversation.

POST /v0/conversations/bulk

curl "https://api.assembledhq.com/v0/conversations/bulk" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d "{
    \"conversations\": [
      {
        \"created_at\": 1549065600,
        \"import_id\": \"122308400000062\",
        \"channel\": \"phone\",
        \"status\": \"solved\",
        \"queue\": \"<uuid>\",
        \"first_responded_at\": \"1549065700\"
        \"solved_at\": \"1549065800\"
        \"assignee_import_id\": \"d613ab77-75f7-4fce-91d8-f9ef5fe55066\"
        \"tags\": [\"tag1\", \"tag2\", \"tag3\"]
      }
    ]
  }"

Creates or overwrites a conversation with the specified parameters. There is a batch limit of 1000 conversations per request.

Bulk Request Parameters:

Field	Type	Required	Description
conversations	list[Conversation]	Required	See documentation for the Conversation object.

Filters

Filters can be used to categorize or group agents as well as activities.

Filter objects

{
  "id": "<uuid>",
  "name": "Queue name",
  "parent_id": "<uuid>",
  "created_at": 123456,
  "updated_at": 123456
}

Field	Type	Description
id	uuid
name	string	Identifier for the filter.
parent_id	uuid	Identifier for the parent filter. May be null.
created_at	Unix timestamp, in seconds	Time of creation.
updated_at	Unix timestamp, in seconds	Time of last update.

GET /v0/queues

curl "https://api.assembledhq.com/v0/queues" \
  -u sk_live_abc123:

{
  ...
  "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

curl "https://api.assembledhq.com/v0/sites" \
  -u sk_live_abc123:

{
  ...
  "sites": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Site Name",
      "parent_id": "<uuid>",
      "created_at": 123456,
      "updated_at": 123456
    }
  }
}

Analogous to GET /v0/queues

GET /v0/teams

curl "https://api.assembledhq.com/v0/teams" \
  -u sk_live_abc123:

{
  "teams": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Team Name",
      "parent_id": "<uuid>",
      "created_at": 123456,
      "updated_at": 123456
    }
  }
}

Analogous to GET /v0/queues

GET /v0/skills

curl "https://api.assembledhq.com/v0/skills" \
  -u sk_live_abc123:

{
  "skills": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Skill Name",
      "parent_id": "<uuid>",
      "created_at": 123456,
      "updated_at": 123456
    }
  }
}

Analogous to GET /v0/queues.

POST /v0/queues

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" } ] }'

{
  ...
  "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

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" } ] }'

{
  ...
  "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

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" } ] }'

{
  ...
  "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

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" } ] }'

{
  ...
  "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

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

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

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

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

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

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

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

curl "https://api.assembledhq.com/v0/skills/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
  -H "Content-Type: application/json" \
  -X PUT \
  -u sk_live_abc123: \
  -d '{ "name": "Skill Name", "parent_id": "<uuid_parent>" }'

Analogous to PUT /v0/queues/:external_id

Forecasts

Forecasts represent predicted volume within a given time window. They are associated with a channel and, optionally, a queue.

Forecast object

{
  "start_time": 1549065600,
  "end_time": 1549066500,
  "channel": "phone",
  "queue": "<uuid>",
  "value": 42.0
}

Field	Type	Description
start_time	Unix timestamp, in seconds
end_time	Unix timestamp, in seconds
channel	string	One of: "phone", "email", or "chat".
queue	uuid	Unique identifier for the corresponding queue.
value	float	The number of contacts forecasted for the time interval.

GET /v0/forecasts

curl "https://api.assembledhq.com/v0/forecasts?start_time=1549065600&end_time=1549069200" \
  -X GET \
  -u sk_live_abc123:

{
  "forecasts": [
    {
      "start_time": 1549065600,
      "end_time": 1549066500,
      "channel": "chat",
      "queue": "<uuid>",
      "value": 42.0
    },
    ...
  ],
}

Returns a list of forecast objects that match the provided query.

Parameters:

Field	Type	Required	Description
start_time	Unix timestamp, in seconds	Required
end_time	Unix timestamp, in seconds	Required	Together with start_time, this determines the interval for which forecasts will be retrieved.
channel	string	Required	One of: "phone", "email", or "chat".
queue	uuid	Optional	Unique identifier for a queue to associate.

Forecast totals

Forecast totals provide more flexibility than standard forecast uploads by allowing you to specify a forecasted contact volume over any time range. Assembled then takes that volume and distributes it based on our forecasted arrival pattern during that period of time, creating a hybrid between your internal predictions and ours.

Forecast total object

{
  "id": "<uuid>",
  "start_time": 1549065600,
  "end_time": 1549066500,
  "channel": "phone",
  "queue": "<uuid>",
  "value": 42.0,
  "value_type": "contacts"
}

Field	Type	Required	Description
id	uuid		Used to reference the forecast total in GET/DELETE requests and error messages.
start_time	Unix timestamp, in seconds	Required	Must be greater than or equal to the minimum forecast interval.
end_time	Unix timestamp, in seconds	Required	Must be greater than or equal to the minimum forecast interval.
channel	string	Required	One of: "phone", "email", or "chat".
queue	uuid	Optional	Unique identifier for the corresponding queue. Defaults to null.
value	float	Required	The number of contacts forecasted for the time interval.
value_type	float	Optional	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

curl "https://api.assembledhq.com/v0/forecasts/totals?start_time=1549065600&end_time=1549069200&channel=email" \
  -X GET \
  -u sk_live_abc123:

{
  "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

curl "https://api.assembledhq.com/v0/forecasts/totals/82721999-16b3-41cf-bb12-b195610cd576" \
  -u sk_live_abc123

{
  "forecasts": [
    {
      "id": "<uuid>",
      "start_time": 1549065600,
      "end_time": 1549066500,
      "channel": "chat",
      "queue": "<uuid>",
      "value": 42.0,
      "value_type": "contacts"
    }
  ],
}

POST /v0/forecasts/totals

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\"
      }
    ]
  }"

{
  "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.

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

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

{
  "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	One of: `30m` or `1h`. For time ranges > 1 day, one of: `24h`, or `1w`. Note that adherence reports do not support `30m` intervals.
channel	string	Required	One of: `back_office`, `chat`, `email`, `phone`, `sms`, or `social`
queue_id	uuid	Optional	Unique identifier for the corresponding queue
agent_id	uuid	Optional	Unique identifier for the corresponding agent. Cannot be provided if filters are provided
site_id	uuid	Optional	Unique identifier for the corresponding site. Part of "filters". Cannot be provided if agent_id is provided.
team_id	uuid	Optional	Unique identifier for the corresponding team. Part of "filters". Cannot be provided if agent_id is provided.
skill_id	uuid	Optional	Unique identifier for the corresponding skill. Part of "filters". Cannot be provided if agent_id is provided.

Report Object

{
  "status": "string",
  "created_at": "timestamp",
  "total_metric_count": "integer",
  "metrics": ["Metrics Object"]
}

Field	Type	Description
status	string	Status of the report, either `in_progress`, `complete`, or `error`
created_at	timestamp (UTC)	The time at which the report was generated
total_metric_count	int	Total # of metrics returned in the report
metrics	list[Metric Object]	A list of metric objects

Metric Object

{
  "name": "string",
  "value": "float",
  "attributes": {
    "agent_id": "<uuid>",
    "start_time": "timestamp",
    "end_time": "timestamp",
    "type": "string"
  }
}

Field	Type	Description
name	string	Name of the metric type. Each report type has a different set of valid metrics name.
value	float	The value of the metric
agent_id	uuid	Unique identifier for the associated agent
start_time	timestamp (UTC)	Start of the period for which the metric is measured. This is either the start of the interval for a `full_interval` metric, or the start of a sub interval for an `interval` type metric.
end_time	timestamp (UTC)	End of the period for which the metric is measured. This is either the end of the interval for a `full_interval` metric, or the end of a sub interval for an `interval` type metric.
type	string	Either `full_interval` or `interval`. Denotes if the metric value represents the full time range or one interval

POST /v0/reports/:reportType

Use this endpoint to request a report. The endpoint will return a reportID that will be used to retrieve the report object.

Report	/:reportType
Adherence	`/adherence`
Agent ticket stats	`/agent_ticket_stats`
Agent state handle times	`/agent_state_handle_times`

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"
    }'

{
  "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.

curl "https://api.assembledhq.com/v0/reports/a8fb1af1-7abc-4316-8616-74ac96448b1e" \
  -X GET \
  -u sk_live_abc123:

{
  "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`)

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

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

curl "https://api.assembledhq.com/v0/requirements?start_time=1641042000&end_time=1641081600" \
  -u sk_live_abc123:

{
  "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

curl "https://api.assembledhq.com/v0/requirement_types" \
  -u sk_live_abc123:

{
  "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

curl "https://api.assembledhq.com/v0/time_off/updates?updated_since=1546303260&type=approve" \
  -u sk_live_abc123: -X GET

{
  "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.

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>"
      ]
   }'

{
  "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

curl "https://api.assembledhq.com/v0/time_off/requests?updated_since=1546303260&type=approve" \
  -u sk_live_abc123: -X GET

{
  "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.

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"
   }'

{
  "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

{
  "shifts": [
    {
      "start_time": {
        "day_of_week": 1,
        "hour": 17,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 2,
        "hour": 5,
        "minute": 0
      }
    }
  ]
}

{
  "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

curl "https://api.assembledhq.com/v0/shift_patterns" \
  -H "Content-Type: application/json" \
  -X GET \
  -u sk_live_abc123:

[
  {
    "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

curl "https://api.assembledhq.com/v0/shift_patterns" \
  -H "Content-Type: application/json" \
  -X GET \
  -u sk_live_abc123:

{
  "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

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

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}

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

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

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

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"
    }
  }'

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"
    }
  }'

{
  "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

Changelog

The changelog provides a list of dated versions, each containing a number of backwards-incompatible changes. The versions provide a way for Assembled to update the API without breaking past integrations. New additions and forward-compatible changes don’t need a new API version and will not appear in this list. The latest API version is 2024-05-22.

2024-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