NAV Navbar
shell

Introduction

Assembled is a modern workforce management platform built for rapidly scaling support teams. We help you forecast support demand, build and manage team schedules, and uncover insights to improve your support operations.

The Assembled API is a general API for querying information from Assembled as well as sending information directly to Assembled. The API is built around REST and returns JSON-encoded responses.

Authentication

Example usage

curl "https://api.assembledhq.com/v0/people" \
    -u sk_live_abc123:
# The colon prevents curl from asking for a password.

The API uses API keys to authenticate requests. You can view your keys from the Settings → API page.

All API keys have the prefix sk_live_.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password. Bearer Auth is not currently supported.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Rate limiting

The Assembled API employs rate limits in order to maximize its stability. Users who send too many requests in quick succession may see error responses with status code 429. By default, we allow 300 requests per minute (5 requests per second), with occasional bursts of up to 20 requests at a time. If your use case requires a higher limit, please contact us at support@assembled.com.

Versioning

Example usage

curl "https://api.assembledhq.com/v0/people" \
  -u sk_live_abc123:
  -H "API-Version: 2019-06-20"

Assembled is commited to keeping the API as backwards compatible as possible. However, there are times when backwards incompatible changes are necessary. When making such changes to the API, we will release a new, dated version which will allow you to upgrade at your convenience. You may continue using the version of the API that you initially integrated and we will ensure that any resources or API semantics stay consistent with your API version.

To upgrade to a new version, you can begin by passing the API-Version header in any API request. This will override the API version that you are currently on. Once you're ready to completely upgrade your version, please email support@assembled.com to have your version upgraded.

The API Changelog provides a complete list of API versions and the changes associated with each version.

People

People handle units of work and can be assigned to events on the Staffing Timeline. They can be grouped by sites or teams and can be assigned to queues or channels based on their skills (which are defined by the managers).

People object

{
  "id": "<uuid>",
  "agent_id": "string",
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "imported_id": "third_party_identifier",
  "roles": ["<uuid>"],
  "agent_role": "string",
  "channels": ["email", "chat", "phone", "social", "sms"],
  "site": "<uuid>",
  "teams": ["<uuid>"],
  "queues": ["<uuid>"],
  "skills": ["<uuid>"],
  "platforms": {
    "zendesk": "string",
    "api": "string"
  },
  "start_date": 1546303260,
  "end_date": 1546303260,
  "created_at": 1546303260,
  "deleted": false,
  "staffable": false
}
Field Type Description
id uuid
agent_id uuid Identifier on Assembled used to uniquely identify the agent related to the Person
first_name string
last_name string
email string
imported_id string Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems
roles list[uuid] Unique identifiers for the roles assigned to this Person
agent_role string Person's agent role on Assembled. Supported values are: Agent, Admin
channels list[string] List of channels associated with the Person. Supported values are: ['email', 'phone', 'chat', 'sms', 'social']. The channels must match what is configured on the Assembled dashboard
site uuid Unique identifier for associated site
teams list[uuid] Unique identifiers for associated teams
queues list[uuid] Unique identifiers for associated queues
skills list[uuid] Unique identifiers for associated skills
platforms map[string]string A map of unique identifiers from the different platforms that the agent is associated with, keyed on the platform name. Possible platforms include intercom, kustomer, salesforce, twilio, ukg, ujet, zendesk, zendesk_chat, zendesk_talk and api
start_date UNIX timestamp, in seconds Person's start date specified by the user on creation
end_date UNIX timestamp, in seconds Person's end date used to indicate when they can no longer be scheduled. Usually, this field is used to preserve agent data in the event of a role change into a non-staffable role or the termination of their contract
created_at UNIX timestamp, in seconds
deleted boolean Flag that indicates whether the Person has been soft deleted
staffable boolean Indicates whether the Person can be scheduled

GET /v0/people

Returns a collection of Persons based on the query parameters (if provided)

Example request

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

Example response

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

Query parameters:

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

GET /v0/people/:id

Returns a Person based on the id provided

Example request

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

Example response

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

POST /v0/people

Creates People with the specified parameters. Valid IDs for site, teams, and queues can be retrieved from endpoints for filters, or via GET /people. This endpoint will return a 400 if invalid IDs for site, teams, or queues are provided.

We allow creating People in bulk, as well as individually

Example request (single Person creation)

curl "https://api.assembledhq.com/v0/people" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d \
  '{
      "people": [
          {
            "imported_id": "",
            "first_name": "Alice",
            "last_name": "Example",
            "email": "alice@example.com",
            "timezone": "America/Los_Angeles",
            "role": "<uuid>",
            "staffable": true,
            "channels": [
                "email", "chat", "phone"
            ]
          }
      ]
   }'

Example response (single Person creation)

{
  "id": "<uuid>",
  "agent_id": "<uuid>",
  "first_name": "Alice",
  "last_name": "Example",
  "email": "alice@example.com",
  "timezone": "",
  "imported_id": "<uuid>",
  "roles": ["<uuid>"],
  "agent_role": "agent",
  "channels": ["email"],
  "site": null,
  "teams": ["<uuid>"],
  "queues": ["<uuid>"],
  "platforms": {},
  "skills": ["<uuid>"],
  "start_date": 1647930594,
  "end_date": 1647940000,
  "created_at": 1648502490,
  "deleted": false,
  "staffable": false
}

Example request (multiple Person creation)

curl "https://api.assembledhq.com/v0/people" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d \
  '{
      "people": [
          {
            "imported_id": "",
            "first_name": "Alice",
            "last_name": "Example",
            "email": "alice@example.com",
            "timezone": "America/Los_Angeles",
            "role": "<uuid>",
            "staffable": true,
            "channels": [
                "email", "chat", "phone"
            ]
          },
          {
            "imported_id": "",
            "first_name": "Bob",
            "last_name": "Example",
            "email": "bob@example.com",
            "timezone": "America/Los_Angeles",
            "role": "<uuid>",
            "staffable": true,
            "channels": [
                "email", "chat", "phone"
            ]
          }
      ]
   }'

Example response (multiple Person creation)

{
  "people": [
    {
      "id": "<uuid>",
      "agent_id": "<uuid>",
      "first_name": "Alice",
      "last_name": "Example",
      "email": "alice@example.com",
      "timezone": "",
      "imported_id": "<uuid>",
      "roles": ["<uuid>"],
      "agent_role": "agent",
      "channels": ["email"],
      "site": null,
      "teams": ["<uuid>"],
      "queues": ["<uuid>"],
      "platforms": {},
      "skills": ["<uuid>"],
      "start_date": 1647930594,
      "end_date": 1647940000,
      "created_at": 1648502490,
      "deleted": false,
      "staffable": false
    },
    {
      "id": "<uuid>",
      "agent_id": "<uuid>",
      "first_name": "Bob",
      "last_name": "Example",
      "email": "bob@example.com",
      "timezone": "",
      "imported_id": "<uuid>",
      "roles": ["<uuid>"],
      "agent_role": "agent",
      "channels": ["email"],
      "site": null,
      "teams": ["<uuid>"],
      "queues": ["<uuid>"],
      "platforms": {},
      "skills": ["<uuid>"],
      "start_date": 1647930594,
      "end_date": 1647940000,
      "created_at": 1648502490,
      "deleted": false,
      "staffable": false
    }
  ]
}

Parameters:

Field Type Required Description
imported_id string Optional The ID of the Person that you are creating
first_name string Required
last_name string Required
email string Required
timezone string Required The timezone for the particular Person, based off the IANA timezone strings (e.g America/New_York)
role uuid Required Unique identifier for the role to assign to this Person
restricted_sites list[uuid] Optional Restricts the person to only view resources associated with these sites. Values must be valid site IDs
staffable boolean Required Indicates whether the Person can be scheduled
channels list[string] Optional One of phone, email, chat, sms or social. The channel must exist on the Assembled dashboard
site uuid Optional Unique identifier for a site to associate
teams list[uuid] Optional Unique identifiers for teams to associate
queues list[uuid] Optional Unique identifiers for queues to associate
skills list[uuid] Optional Unique identifiers for skills to associate
platforms map[string]string Optional A map of unique identifiers from the different platforms that the agent is associated with, keyed on the platform name. Possible platforms include intercom, kustomer, salesforce, twilio, ujet, zendesk, zendesk_chat, and zendesk_talk
start_date UNIX timestamp, in seconds Optional Person's start date specified by the user on creation
end_date UNIX timestamp, in seconds Optional Person's end date used to indicate when they can no longer be scheduled. Usually, this field is used to preserve agent data in the event of a role change into a non-staffable role or the termination of their contract
send_invite_email boolean Optional Indicates whether or not to send the Person an invite e-mail to Assembled

PATCH /v0/people/:id

Example request

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

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

Example response

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

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

Parameters:

Field Type Required Description
imported_id string Optional The ID of the Person that you are creating
first_name string Optional
last_name string Optional
email string Optional
timezone string Optional The timezone for the particular Person, based off the IANA timezone strings (e.g America/New_York)
role uuid Optional Unique identifier for the role to assign to this Person
restricted_sites list[uuid] Optional Restricts the person to only view resources associated with these sites. Values must be valid site IDs
staffable boolean Optional Indicates whether the Person can be scheduled
channels list[string] Optional One of phone, email, chat, sms or social. The channel must exist on the Assembled dashboard
site uuid Optional Unique identifier for a site to associate
teams list[uuid] Optional Unique identifiers for teams to associate
queues list[uuid] Optional Unique identifiers for queues to associate
skills list[uuid] Optional Unique identifiers for skills to associate
platforms map[string]string Optional A map of unique identifiers from the different platforms that the agent is associated with, keyed on the platform name. Possible platforms include intercom, kustomer, salesforce, twilio, ujet, zendesk, zendesk_chat, and zendesk_talk
start_date UNIX timestamp, in seconds Optional Person's start date specified by the user on creation. Set it to null if you want to remove this value
end_date UNIX timestamp, in seconds Optional Person's end date used to indicate when they can no longer be scheduled. Usually, this field is used to preserve agent data in the event of a role change into a non-staffable role or the termination of their contract

DELETE /v0/people/:id

Example request

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

Example response

{
  "id": "<uuid>",
  "message": "person successfully deleted"
}

Query parameters:

Field Type Required Description
hard string Optional Set to true if you want to completely delete the Person and all associated data. Defaults to false

Roles

Roles are used to control user access to different parts of assembled.

Role object

{
  "id": "<uuid>",
  "name": "Admin",
  "description": "This is an admin role"
}
Field Type Required Description
id uuid Used to reference the role in other API requests.
name string Required The name of the role.
description string Optional A description of the role.

GET /v0/roles

Example request

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

Example response

{
  "roles": {
    "0ff1211d-17a4-4d62-9039-e790eaa6aef9": {
      "id": "0ff1211d-17a4-4d62-9039-e790eaa6aef9",
      "name": "Admin",
      "description": "This is an admin role"
    },
    ...
  }
}

Returns a list of roles in an Assembled instance.

Agent states

Agents can have states that indicate what they are currently working on. For example, in a phone system an agent may be “available for calls”, “busy on a call”, or “wrapping up on a call.” These will be surfaced in our real-time dashboard to track the state of your team and in our reporting, to track agent and team performance.

Agent state object

{
  "agent_id": "<uuid>",
  "agent_name": "John Smith",
  "agent_email": "john.smith@example.com",
  "agent_platform_id": "25963324267",
  "platform": "zendesk",
  "start_time": 1664890267,
  "end_time": 1664890367,
  "state": "Online (Tickets)",
  "ticket_id": "4544635",
  "ticket_status": "solved",
  "modified_at": 1664890367
}
Field Type Description
agent_id uuid Unique identifier for an agent in Assembled.
agent_name string
agent_email string
agent_platform_id string Unique identifier for the agent for the platform. This can be associated to agents in Assembled with the agent associations endpoint.
platform string The platform that the agent state comes from e.g. "api", "zendesk_talk", or "kustomer".
start_time Unix timestamp, in seconds Time when agent began their state.
end_time Unix timestamp, in seconds Time when agent ended being in this state.
state string Agent’s status from upstream system e.g. "online", "away", or "busy". Values are not validated, but can be mapped to activity types on the Assembled application by an Administrator.
ticket_id string Identifier for the corresponding ticket.
ticket_status string Status of the ticket.
modified_at Unix timestamp, in seconds Time when the agent state was last updated.

POST /v0/agents/state

Example request

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

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

Parameters:

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

GET /v0/agents/state

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

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

Example request (single agent)

curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367&agent_id=8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
  -u sk_live_abc123:

Example response

{
  "agent_states": [
    {
      "agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
      "agent_name": "John Smith",
      "agent_email": "john.smith@example.com",
      "agent_platform_id": "1511922421021",
      "platform": "zendesk",
      "start_time": 1664910494,
      "end_time": 1664910508,
      "state": "Online (Tickets)",
      "ticket_id": "4545748",
      "ticket_status": "new",
      "modified_at": 1664910508
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 1
}

Example request (agents by filters)

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

Example response

{
  "agent_states": [
    {
      "agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
      "agent_name": "Jane Doe",
      "agent_email": "jane.doe@example.com",
      "agent_platform_id": "404632334253",
      "platform": "zendesk_chat",
      "start_time": 1637377993,
      "end_time": 1665489600,
      "state": "Offline",
      "ticket_id": "",
      "ticket_status": "",
      "modified_at": 1637378038
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 1
}

Example request (all agents)

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

Example response

{
  "agent_states": [
    {
      "agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
      "agent_name": "Jane Doe",
      "agent_email": "jane.doe@example.com",
      "agent_platform_id": "404632334253",
      "platform": "zendesk_chat",
      "start_time": 1637377993,
      "end_time": 1665489600,
      "state": "Offline",
      "ticket_id": "",
      "ticket_status": "",
      "modified_at": 1637378038
    },
    {
      "agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
      "agent_name": "John Smith",
      "agent_email": "john.smith@example.com",
      "agent_platform_id": "1511922421021",
      "platform": "zendesk",
      "start_time": 1664910494,
      "end_time": 1664910508,
      "state": "Online (Tickets)",
      "ticket_id": "4545748",
      "ticket_status": "new",
      "modified_at": 1664910508
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 2
}

Parameters:

Field Type Required Description
agent_id uuid Optional Unique identifier for an agent in Assembled.
platforms list[string] Optional The platforms that the agent states come from, e.g. "api", "zendesk_talk", or "kustomer".
channel string Optional Filter agents by a specific channel. One of phone, email, chat, sms or social.
queue uuid Optional Filter agents by a specific queue.
site uuid Optional Filter agents by a specific site.
team uuid Optional Filter agents by a specific team.
skill uuid Optional Filter agents by a specific skill.
start_time Unix timestamp, in seconds Required States ending after this time will be returned.
end_time Unix timestamp, in seconds Required States starting before this time will be returned.
limit integer Optional Maximum number of results to return. Defaults to 20.
offset integer Optional Offset into the results to return. Defaults to 0.

GET /v0/agents/state/condensed_timeline

Returns a list of agent state objects that match the provided query, but condenses each agent's states into a single timeline with non-overlapping records. The priority of overlapping records can be specified by passing in a list of comma-separated platforms through the parameter priority_order.

Platforms that are listed earlier in priority_order are considered to have a higher priority. In the case where priority order is not specified for a particular platform, Assembled will take the lexicographically smaller platform as higher priority (e.g. Kustomer would be considered higher priority than Zendesk if neither platform is included in the priority list).

For example, consider John Smith has a zendesk state from 1660000400 to 1660000600, and a zendesk_clock_in state from 1660000500 to 1660000600 (100 seconds of overlap). If we set priority_order to zendesk_clock_in,zendesk, we are denoting zendesk_clock_in as having a higher priority. Therefore, we'd get the provided response where the zendesk_clock_in state is taken over the zendesk state from 1660000500 to 1660000600.

Example request (single agent)

curl "https://api.assembledhq.com/v0/agents/state?start_time=1664890267&end_time=1664890367&agent_id=8ce1939e-cc6c-48e8-b0ef-a2326b562082&priority_order=zendesk_clock_in,zendesk" \
  -u sk_live_abc123:

Example response

{
  "agent_states": [
    {
      "agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
      "agent_name": "John Smith",
      "agent_email": "john.smith@example.com",
      "agent_platform_id": "1511922421021",
      "platform": "zendesk",
      "start_time": 1660000400,
      "end_time": 1660000500,
      "state": "Online (Tickets)",
      "ticket_id": "4545748",
      "ticket_status": "new",
      "modified_at": 1664910508
    },
    {
      "agent_id": "8ce1939e-cc6c-48e8-b0ef-a2326b562082",
      "agent_name": "John Smith",
      "agent_email": "john.smith@example.com",
      "agent_platform_id": "1511922421021",
      "platform": "zendesk_clock_in",
      "start_time": 1660000500,
      "end_time": 1660000600,
      "state": "Lunch",
      "ticket_id": "",
      "ticket_status": "",
      "modified_at": 1664910508
    }
  ],
  "limit": 20,
  "offset": 0,
  "total": 2
}

Query parameters:

Field Type Required Description
agent_id uuid Optional Unique identifier for an agent in Assembled.
platforms list[string] Optional The platforms that the agent states come from, e.g. "api", "zendesk_talk", or "kustomer".
priority_order string Required A list of comma-separated platforms in order of descending priority (e.g. "zendesk,customer")
channel string Optional Filter agents by a specific channel. One of phone, email, chat, sms or social.
queue uuid Optional Filter agents by a specific queue.
site uuid Optional Filter agents by a specific site.
team uuid Optional Filter agents by a specific team.
skill uuid Optional Filter agents by a specific skill.
start_time Unix timestamp, in seconds Required States ending after this time will be returned.
end_time Unix timestamp, in seconds Required States starting before this time will be returned.
limit integer Optional Maximum number of results to return. Defaults to 20.
offset integer Optional Offset into the results to return. Defaults to 0.

POST /v0/agents/associations

Example request

curl "https://api.assembledhq.com/v0/agents/associations" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "agent_platform_id": "25963324267",
    "agent_id": "<uuid>"
  }'

Associates agent unique identifiers to agents in Assembled. If an association already exists with this agent_platform_id, we will update the association with the newly specified agent_id.

This endpoint is used in conjunction with POST requests to /v0/agents/state, allowing the user to ensure these requests map to the correct agents.

You must associate agent unique identifiers to agents in Assembled - whether that's through this endpoint or within the Assembled app - to ensure that POST requests to the /v0/agents/state endpoint can be displayed correctly with adherence metrics for a particular agent.

Parameters:

Field Type Required Description
agent_platform_id string Required Unique identifier used in agent states.
agent_id uuid Required Unique identifier for an agent in Assembled.

POST /v0/agents/state/edit

Example request

curl "https://api.assembledhq.com/v0/agents/state/edit" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "edits": [
      {
        "agent_platform_id": "25963324267"
        "platform": "zendesk",
        "action": "insert"
        "data": {
          "state": "Online",
          "start_time": 1664890267,
          "end_time": 1664890367
        }
      },
      {
        "agent_platform_id": 25963324267
        "platform": "zendesk",
        "action": "delete"
        "data": {
          "id": "<uuid>",
        }
      },
      {
        "agent_platform_id": "25963324267"
        "platform": "zendesk",
        "action": "update"
        "data": {
          "id": "<uuid>",
          "state": "Online",
          "start_time": 1664890267,
          "end_time": 1664890367
        }
      },
    ]
  }'

Takes in a list of agent state edits and applies them. Insertions, deletes, and updates are supported. The parameters required are dependent on the type of action specified.

Parameters:

Field Type Required Description
edits List[Object] Required A list of edits to be made
agent_platform_id string Required The platform ID of the agent whose state is being edited
platform string Required The platform of the state to be edited
action string Required "insert", "delete", or "update"
data Object Required An object specifying edit details (dependent on the type of edit being made)
id uuid Required (Required for deletions and updates) The external ID of the state being edited
state string Optional (Required for insertions and updates) The desired state of the edited record
start_time Unix timestamp Optional (Required for insertions and updates) Unix timestamp of the edited record's desired start time
end_time Unix timestamp Optional (Required for insertions and updates) Unix timestamp of the edited record's desired end time

GET /v0/agents/state/edit/history

Example request

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

Example response

{
  [
    {
      "edited_agent": {
          "name": "John Smith",
          "email": "johnsmith@example.com",
          "agent_id": "<uuid>"
      },
      "platform": "zendesk",
      "state_external_id": "<uuid>",
      "old_record": {
          "agent_platform_id": "25963324267",
          "start_time": "2023-12-05T08:00:00Z",
          "end_time": "2023-12-05T09:00:00Z",
          "platform": "zendesk",
          "state": "offline",
          "attributes": null,
          "is_current": false,
          "updated_at": "2023-12-06T08:17:38.601462Z",
          "active": true,
          "start_unix": 1670000100,
          "end_unix": 1670000200,
          "created_at": 1664890267
      },
      "new_record": {
          "agent_platform_id": "25963324267",
          "start_time": "2023-12-05T08:00:00Z",
          "end_time": "2023-12-05T010:00:00Z",
          "platform": "zendesk",
          "state": "online",
          "attributes": null,
          "is_current": false,
          "updated_at": "2023-12-06T08:17:38.601462Z",
          "active": true,
          "start_unix": 1670000200,
          "end_unix": 1670000400,
          "created_at": 1701850658
      },
      "edit": {
          "agent_platform_id": "25963324267",
          "platform": "api",
          "action": "insert",
          "data": {
              "state": "online",
              "start_time": 1670000200,
              "end_time": 670000400
          }
      },
      "is_api_edit": false,
      "edited_by": {
          "id": "<uuid>",
          "first_name": "Jane",
          "last_name": "Doe",
          "role": "admin",
          "email": "janedoe@example.com",
          "timezone": "America/Los_Angeles",
          "restricted_sites": [],
          "active": true
      },
      "created_at": "2023-12-06T08:17:38.601462Z"
    },
  ]
}

Returns a list of edits made to any agents' states that were made between the specified start and end time.

Edits made through the edit_history endpoint (as indicated by is_api_edit in the response) will not return editor details in the edited_by field due to ambuiguity over which specific user made the API request.

Parameters:

Field Type Required Description
start_time Unix timestamp, in seconds Required Edits made after this time will be returned
end_time Unix timestamp, in seconds Required Edits made before this time will be returned

Activities

Agents can have scheduled activities that are either created directly in Assembled or sourced from other calendaring applications such as Google Calendar.

Activity object

{
  "id": "<uuid>",
  "agent_id": "<uuid of agent>",
  "channels": ["phone"],
  "type_id": "<uuid of activity_type>",
  "start_time": 1546303260,
  "end_time":  1546303270,
  "created_at": 1546303260,
  "updated_at": 1546303260,
  "description": null
}
Field Type Description
id uuid
agent_id uuid Identifier for the corresponding agent.
type_id uuid Identifier for the associated activity type.
start_time Unix timestamp, in seconds
end_time Unix timestamp, in seconds
created_at Unix timestamp, in seconds
updated_at Unix timestamp, in seconds
description string An arbitrary string to be displayed to end users.

POST /v0/activities

Example request

curl "https://api.assembledhq.com/v0/activities" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d "{
    \"start_time\": 1562223600,
    \"end_time\": 1562259600,
    \"agent_id\": \"<uuid>\",
    \"type_id\": \"<uuid>\"
  }"

Example response

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

Creates an activity with the specified parameters. Valid IDs for agents can be retrieved from the people endpoints. Valid IDs for activity types can be retrieved from the activity types endpoints. This endpoint will return 400 if invalid IDs are provided.

Parameters:

Field Type Required Description
agent_id uuid Required Unique identifier for an agent.
type_id uuid Required Unique identifier for an activity type.
start_time Unix timestamp, in seconds Required
end_time Unix timestamp, in seconds Required
allow_conflicts boolean Optional Whether or not to allow conflicting events. If true, this created activity will be allowed to have conflicts with other activities. If false, any overlapping activities for the specified agent will be deleted. Defaults to false.
description string Optional An arbitrary string to be displayed to end users.
schedule_id string Optional Identifier for the corresponding schedule. Defaults to the master schedule.

POST /v0/activities/bulk

Example request

curl "https://api.assembledhq.com/v0/activities/bulk" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d "{
    \"activities\": [
      {
        \"action\": \"create\",
        \"activity\": {
          \"start_time\": 1562223600,
          \"end_time\": 1562259600,
          \"agent_id\": \"<uuid>\",
          \"type_id\": \"<uuid>\"
        }
      }
    ]
  }"

Example response

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

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

Parameters:

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

Bulk Request Parameters:

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

GET /v0/activities

Example request

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

Example response

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

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

Parameters:

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

DELETE /v0/activities

Example request

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

Example response

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

Deletes all activities that match the specified parameters. Valid IDs for agents can be retrieved from the people endpoints. This endpoint will return 400 if invalid IDs are provided.

Activities can be partially deleted. For example, if agent XYZ has an activity from 3pm-5pm and the deletion window is from 4pm-5pm, there will still exist a 3-4pm activity for agent XYZ after the deletion is completed.

Parameters:

Field Type Required Description
start_time Unix timestamp, in seconds Required The start of the deletion window.
end_time Unix timestamp, in seconds Required The end of the deletion window.
agent_ids list[uuid] Required Unique identifiers for agents. All activities in the deletion window will be deleted for each specified agent.
schedule_id string Optional Identifier for the corresponding schedule. Defaults to the master schedule.

Activity types

Activity types represent a categorization of different activities. Currently they are only editable via the dashboard.

Activity type object

{
  "id": "<uuid>",
  "import_id": "third_party_identifier",
  "name": "Shift",
  "short_name": "S",
  "value": "shift",
  "channels": ["email"],
  "productive": true,
  "timeoff": false,
  "background_color": "#ffffff",
  "font_color": "#ffffff"
}
Field Type Description
id uuid
import_id string Third-party identifier. Supplied to Assembled and is used to uniquely identify activity types across different systems.
name string
short_name string
value string Corresponds to type in the Activity object, will be deprecated in a future API version.
channels list[string] Channels associated with the activity. Must be non-empty when the the activity is productive.
productive boolean If true, timeoff must be false.
timeoff boolean If true, productive must be false.
timeoff_unit "hours" or "days" Required for time off event types. Specifies whether time off of this type is taken in increments of hours or days.
background_color string Hex string.
font_color string Hex string.

GET /v0/activity_types

Example request

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

Example response

{
  "activity_types": {
    "<uuid>": {
      "id": "<uuid>",
      "import_id": "third_party_identifier1",
      "name": "Break",
      "short_name": "B",
      "value": "break",
      "channels": [],
      "productive": false
    },
    "<uuid>": {
      "id": "<uuid>",
      "import_id": "third_party_identifier2",
      "name": "Shift",
      "short_name": "S",
      "value": "shift",
      "channels": ["email"],
      "productive": true
    }
  }
}

Returns a list of all activity type objects configured on the account.

POST /v0/activity_types

Example request

curl "https://api.assembledhq.com/v0/activity_types" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{ "name": "Break", "short_name": "B", "timeoff": true }'

Example response

{
  "id": "<uuid>",
  "import_id": null,
  "name": "Break",
  "short_name": "B",
  "value": "break",
  "channels": [],
  "productive": false,
  "timeoff": true,
  "background_color": "#ffffff",
  "font_color": "#000000"
}

Creates an activity type with the specified parameters.

Parameters:

Field Type Required Description
name string Required
channels list[string] Required Channels associated with the activity. Must be non-empty when the the activity is productive.
short_name string Optional
productive boolean Optional If true, timeoff must be false.
timeoff boolean Optional If true, productive must be false.
background_color string Optional Hex string.
font_color string Optional Hex string.
import_id string Optional Third-party identifier. Supplied to Assembled and is used to uniquely identify activity types across different systems.

DELETE /v0/activity_types/:id

Example request

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

Deletes an activity type.

Event changes

Event changes represent changes to an agent's scheduled events. These could be manually added changes, due to applying a template, due to a time off request being approved, or due to any other change to the schedule.

Event change object

{
  "id": "<uuid>",
  "event_id": "<uuid>",
  "modified_by": {
    "name": "John Smith",
    "id": "<uuid>",
    "email": "john.smith@example.com"
  },
  "modified_at": 1665954677,
  "event_agent_name": "Jane Doe",
  "event_agent_id": "<uuid>",
  "event_agent_email": "jane.doe@example.com",
  "event_change_type": "modify",
  "description": "Events Edited and Published",
  "old_event_type": "activity_type_value1234",
  "new_event_type": "activity_type_value5678",
  "old_start_time": 1665702700,
  "old_end_time": 1665727300,
  "new_start_time": 1665703700,
  "new_end_time": 1665715900,
  "old_channels": ["phone"],
  "new_channels": ["chat"],
  "old_template_id": "<uuid>",
  "new_template_id": "<uuid>",
  "old_google_calendar_event_id": "<gcal_event_id>",
  "new_google_calendar_event_id": "<gcal_event_id>"
}
Field Type Description
id uuid
event_id uuid ID of the event that was modified
modified_by object Object containing information about the person who edited the event
modified_at Unix timestamp, in seconds When the event change was created
event_agent_name string Name of the agent whose event was changed
event_agent_id uuid ID of the agent whose event was changed
event_agent_email string Email of the agent whose event was changed
event_change_type string Type of event change. One of create, modify, or delete
description string
old_event_type string Value of the event type before the change (this corresponds to the value field of the Activity Type object)
new_event_type string Value of the event type after the change (this corresponds to the value field of the Activity Type object)
old_start_time Unix timestamp, in seconds
new_start_time Unix timestamp, in seconds
old_end_time Unix timestamp, in seconds
new_end_time Unix timestamp, in seconds
old_channels list[string]
new_channels list[string]
old_template_id uuid UUID for the template that the event comes from
new_template_id uuid UUID for the template that the event comes from
old_google_calendar_event_id string Google Calendar event ID for the event, if synced from Google Calendar
new_google_calendar_event_id string Google Calendar event ID for the event, if synced from Google Calendar

GET /v0/event_changes

Example request

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

Example response

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

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

Parameters:

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

Conversations

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

Conversation object

{
  "created_at": 1549065600,
  "import_id": "122308400000062",
  "channel": "phone",
  "status": "solved",
  "queue": "<uuid>",
  "first_responded_at": 1549065700,
  "solved_at": 1549065800,
  "assignee_import_id": "d613ab77-75f7-4fce-91d8-f9ef5fe55066",
  "tags": ["tag1", "tag2", "tag3"]
}
Field Type Required Description
created_at Unix timestamp, in seconds Required Time the conversation was created.
import_id string Required Third-party identifier. Must be unique to the conversation.
channel string Required One of: "phone", "email", "chat", "social" or "back_office".
status string Required One of: "open", "pending", "solved" or "abandoned".
queue uuid Optional Unique identifier for the corresponding queue.
first_responded_at Unix timestamp, in seconds Optional Time the conversation was first responded to by an agent.
solved_at Unix timestamp, in seconds Optional Time the conversation was solved or closed.
assignee_import_id string Optional Third-party identifier for the agent currently assigned to the conversation.
tags list[string] Optional List of tags associated with the conversation.

POST /v0/conversations/bulk

Example request

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

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

Bulk Request Parameters:

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

Filters

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

Filter objects

{
  "id": "<uuid>",
  "name": "Queue name",
  "parent_id": "<uuid>",
  "created_at": 123456,
  "updated_at": 123456
}
Field Type Description
id uuid
name string Identifier for the filter.
parent_id uuid Identifier for the parent filter. May be null.
created_at Unix timestamp, in seconds Time of creation.
updated_at Unix timestamp, in seconds Time of last update.

GET /v0/queues

Example request

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

Example response

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

Returns a list of all queue objects configured on the account.

GET /v0/sites

Example request

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

Example response

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

Analogous to GET /v0/queues

GET /v0/teams

Example request

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

Example response

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

Analogous to GET /v0/queues

GET /v0/skills

Example request

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

Example response

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

Analogous to GET /v0/queues.

POST /v0/queues

Example request

curl "https://api.assembledhq.com/v0/queues" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{ "queues" : [{ "name": "Queue Name", "parent_id": "<uuid_parent>"}, { "name": "Queue Name2" } ] }'

Example response

{
  ...
  "queues": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Queue Name",
      "parent_id": "<uuid_parent>",
      "created_at": 123456,
      "updated_at": 123456
    },
    "<uuid2>": {
      "id": "<uuid2>",
      "name": "Queue Name2",
      "parent_id": null,
      "created_at": 123456,
      "updated_at": 123456
    }
  }
}

Creates queue objects in bulk. Note this will default to associating your queues to all channels enabled in your Assembled instance.

POST /v0/sites

Example request

curl "https://api.assembledhq.com/v0/sites" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{ "sites" : [{ "name": "Site Name", "parent_id": "<uuid_parent>"}, { "name": "Site Name2" } ] }'

Example response

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

Analogous to POST /v0/queues

POST /v0/teams

Example request

curl "https://api.assembledhq.com/v0/teams" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{ "teams" : [{ "name": "Team Name", "parent_id": "<uuid_parent>"}, { "name": "Team Name2" } ] }'

Example response

{
  ...
  "teams": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Team Name",
      "parent_id": "<uuid_parent>",
      "created_at": 123456,
      "updated_at": 123456
    },
    "<uuid2>": {
      "id": "<uuid2>",
      "name": "Team Name2",
      "parent_id": null,
      "created_at": 123456,
      "updated_at": 123456
    }
  }
}

Analogous to POST /v0/queues

POST /v0/skills

Example request

curl "https://api.assembledhq.com/v0/skills" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{ "skills" : [{ "name": "Skill Name", "parent_id": "<uuid_parent>"}, { "name": "Skill Name2" } ] }'

Example response

{
  ...
  "skills": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Skill Name",
      "parent_id": "<uuid_parent>",
      "created_at": 123456,
      "updated_at": 123456
    },
    "<uuid2>": {
      "id": "<uuid2>",
      "name": "Skill Name2",
      "parent_id": null,
      "created_at": 123456,
      "updated_at": 123456
    }
  }
}

Analogous to POST /v0/queues

DELETE /v0/queues

Example request

curl "https://api.assembledhq.com/v0/queues" \
  -u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "queue_ids": ["<uuid1>", "<uuid2>"] }'

Deletes queue objects in bulk.

DELETE /v0/sites

Example request

curl "https://api.assembledhq.com/v0/sites" \
  -u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "site_ids": ["<uuid1>", "<uuid2>"] }'

Analogous to DELETE /v0/queues

DELETE /v0/teams

Example request

curl "https://api.assembledhq.com/v0/teams" \
  -u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "team_ids": ["<uuid1>", "<uuid2>"] }'

Analogous to DELETE /v0/queues

DELETE /v0/skills

Example request

curl "https://api.assembledhq.com/v0/skills" \
  -u sk_live_abc123: -H "Content-Type: application/json" -X DELETE -d '{ "skill_ids": ["<uuid1>", "<uuid2>"] }'

Analogous to DELETE /v0/queues

PUT /v0/queues/:id

Example request

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

Updates a single queue object to the specified name and parent_id. If the parent_id in the request is null, the queue parent will be set to null.

PUT /v0/sites/:id

Example request

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

Analogous to PUT /v0/queues/:external_id

PUT /v0/teams/:id

Example request

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

Analogous to PUT /v0/queues/:external_id

PUT /v0/skills/:id

Example request

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

Analogous to PUT /v0/queues/:external_id

Forecasts

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

Forecast object

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

GET /v0/forecasts

Example request

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

Example response

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

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

Parameters:

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

Forecast totals

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

Forecast total object

{
  "id": "<uuid>",
  "start_time": 1549065600,
  "end_time": 1549066500,
  "channel": "phone",
  "queue": "<uuid>",
  "value": 42.0,
  "value_type": "contacts"
}
Field Type Required Description
id uuid Used to reference the forecast total in GET/DELETE requests and error messages.
start_time Unix timestamp, in seconds Required Must be greater than or equal to the minimum forecast interval.
end_time Unix timestamp, in seconds Required Must be greater than or equal to the minimum forecast interval.
channel string Required One of: "phone", "email", or "chat".
queue uuid Optional Unique identifier for the corresponding queue. Defaults to null.
value float Required The number of contacts forecasted for the time interval.
value_type float Optional Useful for "email" channels where you can have "contacts", "reopened", "messages", or "combined". Defaults to "contacts".

GET /v0/forecasts/totals

Example request

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

Example response

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

Returns a list of forecast totals that have been uploaded.

Parameters:

Field Type Required Description
start_time Unix timestamp, in seconds Required Totals ending after this time will be returned.
end_time Unix timestamp, in seconds Required Totals starting before this time will be returned.
channel string Optional One of: "phone", "email", or "chat".
queue uuid Optional Unique identifier for a queue to associate.
value_type string Optional Useful for "email" channels where you can have "contacts", "reopened", "messages", or "combined"

GET /v0/forecasts/totals/:id

Returns a forecast total based on the id provided

Example request

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

Example response

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

POST /v0/forecasts/totals

Example request

curl "https://api.assembledhq.com/v0/forecasts/totals" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d "{
    \"overwrite\": false,
    \"forecasts\": [
      {
        \"start_time\": 1549065600,
        \"end_time\": 1549069200,
        \"channel\": \"chat\",
        \"queue\": \"<uuid>\",
        \"value\": 42.0,
        \"value_type\": \"contacts\"
      }
    ]
  }"

Example response

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

Creates forecast totals with the given parameters. If the "overwrite" flag is set to true, new totals will overwrite previous totals that overlap perfectly (same start_time and end_time) with them.

Request Parameters:

Field Type Required Description
overwrite boolean Optional Allows new totals to overwrite existing ones if they overlap perfectly. Default value is false.
forecasts list[ForecastTotal] Required See documentation for the Forecast total object.

DELETE /v0/forecasts/totals/:id

Deletes a forecast total based on the id provided. This allows for targeted removal of conflicting totals and is a permanent action and cannot be undone.

Example request

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

Forecasts vs. actuals

Forecasted metrics are those that Assembled predicts based on a combination of historical data and various configured variables within Assembled. Actuals are the historical values of these metrics. This endpoint allows the user to access and compare these two sets of data, much like the "Forecasted vs. actual" report in Assembled.

Forecasts vs. actuals objects

Forecasted vs. actual pair

A forecasted vs. actual pair is an object containing the forecasted and actual value of a given metric.

{
  "forecasted": 3,
  "actual": 4
}
Field Type Description
forecasted float The value forecasted for the given metric (may be null)
actual float The actual value of the metric (may be null)

Forecasted vs. actual response

{
  "start_time": 1668492000,
  "end_time": 1668495600,
  "channel": "email",
  "queue": "<uuid>",
  "service_level": {
    "forecasted": 0,
    "actual": 0
  },
  "service_level_missed": {
    "forecasted": 63.5,
    "actual": 34
  },
  "service_level_met": {
    "forecasted": 0,
    "actual": 0
  },
  "first_response_time": {
    "forecasted": null,
    "actual": 13172
  },
  "cases_opened": {
    "forecasted": 36,
    "actual": 42
  },
  "cases_reopened": {
    "forecasted": 23.5,
    "actual": 32
  },
  "cases_solved": {
    "forecasted": 60,
    "actual": 54
  },
  "productivity": {
    "forecasted": 3.4,
    "actual": 2.8302307428825666
  },
  "staffing_scheduled": 19.75,
  "staffing_required": 19,
  "staffing_net": 0.75
}
Field Type Description
start_time Unix timestamp, in seconds
end_time Unix timestamp, in seconds
channel string
queue uuid
service_level forecasted_actual_pair Service level percent as a value between 0 and 1.
service_level_missed forecasted_actual_pair Number of contacts that missed service level.
service_level_met forecasted_actual_pair Number of contacts that met service level.
first_response_time forecasted_actual_pair Average first response time in seconds. Only actual values are available for this metric.
transferred_away forecasted_actual_pair Number of tickets transferred away. Only available if ticket lifecycle tracking is enabled.
reassigned_away forecasted_actual_pair Number of tickets reassigned away. Only available if ticket lifecycle tracking is enabled.
messages_received forecasted_actual_pair Number of messages received. Only available for asynchronous channels and if using message-based forecasting.
cases_answered forecasted_actual_pair Number of cases answered. Only available for asynchronous channels and if using message-based forecasting.
cases_opened forecasted_actual_pair Number of new cases opened. Only available for asynchronous channels.
cases_reopened forecasted_actual_pair Number of cases reopened. Only available for asynchronous channels.
cases_solved forecasted_actual_pair Number of cases solved. Only available for asynchronous channels.
productivity forecasted_actual_pair Average email productivity. Only available for asynchronous channels.
contacts_received forecasted_actual_pair Number of contacts received. Only available for realtime channels.
contacts_abandoned forecasted_actual_pair Number of contacts abandoned. Only available for realtime channels.
handle_time forecasted_actual_pair Average handle time. Only available for realtime channels.
occupancy forecasted_actual_pair Occupancy percent as a value between 0 and 1. Only forecasted values are available for this metric.
staffing_scheduled float
staffing_required float
staffing_net float

GET /v0/forecasted_vs_actuals

Example request

curl "https://api.assembledhq.com/v0/forecasted_vs_actuals?start_time=1668492000&end_time=1668495600&channel=phone&interval=3600" \
  -u sk_live_abc123: -X GET

Example response

{
  "forecasts_vs_actuals": [
    {
      "start_time": 1668492000,
      "end_time": 1668495600,
      "channel": "phone",
      "queue": "<uuid>",
      "service_level": {
        "forecasted": 0,
        "actual": 0
      },
      "service_level_missed": {
        "forecasted": 63.5,
        "actual": 34
      },
      "service_level_met": {
        "forecasted": 0,
        "actual": 0
      },
      "first_response_time": {
        "forecasted": null,
        "actual": 123
      },
      "contacts_received": {
        "forecasted": 63.5,
        "actual": 36
      },
      "contacts_abandoned": {
        "forecasted": null,
        "actual": 2
      },
      "handle_time": {
        "forecasted": 243,
        "actual": 220
      },
      "occupancy": {
        "forecasted": 0.45,
        "actual": null
      },
      "staffing_scheduled": 19.75,
      "staffing_required": 19,
      "staffing_net": 0.75
    },
    ...
  ],
  "limit": 0,
  "offset": 0,
  "total": 100
}

Returns a list of forecasted vs. actual records that match the provided query.

Parameters:

Field Type Required Description
start_time Unix timestamp, in seconds Required
end_time Unix timestamp, in seconds Required Together with start_time, specifies the range of times to view metrics for.
interval integer Required Interval in seconds to group the results by.
channel string Required Name of the channel to view metrics for.
queue uuid Optional Unique identifier for the corresponding queue.
limit integer Optional Maximum number of results to return. Defaults to 20.
offset integer Optional Offset into the results to return. Defaults to 0.

Quality assurance scores

Assembled can ingest and aggregate quality assurance (QA) scores in our reporting dashboards.

QA scores are considered to be grading an underlying ticket from a ticketing platform (e.g. zendesk, intercom, etc.). The ticket's platform and ID can optionally be provided when sending QA scores to Assembled, which allows you to apply filters to group these scores in reports.

Score object

{
  "agent_email": "john.smith@assembledhq.com",
  "ticket_created_at": 1660000400,
  "score": 85.0,
  "max_score": 100.0,
  "imported_id": "ticket_id_123",
  "agent_platform_id": "johns_zendesk_id",
  "agent_name": "John Smith",
  "grader": "John's Manager",
  "graded_at": 1770000400
}
Field Type Required Description
agent_email string Required Email of the agent being graded. This is used to associate the score with an agent in Assembled.
ticket_created_at Unix timestamp, in seconds Required Time that the ticket being graded was created.
score float Required Score that the agent received for this particular ticket.
imported_id string Required Third-party identifier of the ticket being graded.
max_score float Optional Maximum score possible. If no value is provided, this will default to 100.
agent_platform_id string Optional Third-party identifier of the agent being graded from the ticketing platform (zendesk, intercom, etc.).
agent_name string Optional Name of the agent.
grader string Optional Identifier for the grader.
graded_at Unix timestamp, in seconds Optional Time that the ticket was graded. If no value is provided, Assembled will set this to the time the request was sent.

POST /v0/qa_scores/bulk

curl "https://api.assembledhq.com/v0/qa_scores/bulk" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "scores": [
        {
            "agent_email": "john.smith@assembledhq.com",
            "ticket_created_at": 1660000400,
            "score": 85,
            "imported_id": "ticket_id_1"
        },
        {
            "agent_email": "john.smith@assembledhq.com",
            "ticket_created_at": 1660000500,
            "score": 100,
            "imported_id": "ticket_id_2"
        }
    ]
}'

Creates QA scores in Assembled. There is a batch limit of 1000 scores per request.

Bulk Request Parameters:

Field Type Required Description
scores list[Score] Required See documentation for the Score object.

Reports

Reports are sets of historical metrics that can be queried over a given time period. When generating a report, the user is able to specify a full time range as well as a sub interval. For every metric type, we return the value for the full time period as well as the values for each sub interval.

Reports are generated asynchronously. Once a report is created, a user can query the GET /v0/reports/:reportID endpoint to see if the report has completed.

Currently, the supported report types are:

Adherence

Adherence reports contain adherence related metrics by agent over a given time period. The associated metrics are:

Agent ticket stats

Agent ticket stats reports contain the following metrics by agent over a given time period:

If a case lifecycle integration is being used, the following metrics are also available.

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.

Report Request Object

{
  "start_time": "timestamp",
  "end_time": "timestamp",
  "interval": "string",
  "channel": "string",
  "queue_id": "<uuid>",
  "agent_id": "<uuid>",
  "filters": {
    "site_id": "<uuid>",
    "team_id": "<uuid>",
    "skill_id": "<uuid>"
  }
}
Field Type Required Description
start_time Unix timestamp (UTC) Required Start time of the report, must be a multiple of 900 seconds
end_time Unix timestamp (UTC) Required End time of the report, must be a multiple of 900 seconds. Time range must be < 31 days
interval string Required One of: 30m or 1h. For time ranges > 1 day, one of: 24h, or 1w. Note that adherence reports do not support 30m intervals.
channel string Required One of: back_office, chat, email, phone, sms, or social
queue_id uuid Optional Unique identifier for the corresponding queue
agent_id uuid Optional Unique identifier for the corresponding agent. Cannot be provided if filters are provided
site_id uuid Optional Unique identifier for the corresponding site. Part of "filters". Cannot be provided if agent_id is provided.
team_id uuid Optional Unique identifier for the corresponding team. Part of "filters". Cannot be provided if agent_id is provided.
skill_id uuid Optional Unique identifier for the corresponding skill. Part of "filters". Cannot be provided if agent_id is provided.

Report Object

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

Metric Object

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

POST /v0/reports/:reportType

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

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

Example request

curl "https://api.assembledhq.com/v0/reports/adherence" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "report_type": "adherence",
    "start_time": 1643673600,
    "end_time": 1643760000,
    "interval": "1h",
    "channel": "phone"
    }'

Example response

{
  "report_id": "a8fb1af1-7abc-4316-8616-74ac96448b1e"
}

GET /v0/reports/:reportID

Use this endpoint to retrieve the report object and check on the status of your report.

Example request

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

Example response

{
  "status": "complete",
  "created_at": "2022-03-30T16:42:29.044299Z",
  "total_metric_count": 1512,
  "metrics": [
    {
      "name": "seconds_in_adherence",
      "value": 629,
      "attributes": {
        "agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
        "start_time": 1643673600,
        "end_time": 1643760000,
        "type": "full_interval"
      }
    },
    {
      "name": "seconds_in_adherence",
      "value": 338,
      "attributes": {
        "agent_id": "12345678-fb4b-464a-9957-3443ece5210d",
        "start_time": 1643673600,
        "end_time": 1643677200,
        "type": "interval"
      }
    },
    ...
  ]
}

Query Parameters

The resulting metric list can be paginated and filtered by metric type(s).

Field Type Description
limit int 500 metrics returned by default
offset int Adds an offset to the responses returned, starts from 0
metric string List of metric names to filter by. Filter for multiple metrics names using the format &metric=[metric name]&metric=[metric name]. If no metric name filter is provided, then all metric types are returned. Must be a valid metric of the report type
type string List of metric types to filter by. Filter for multiple metrics types using the format &type=[metric type]&type=[metric type]. If no type filter is provided, then all metric types are returned (full_interval and interval)

Example request

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

Requirements

Requirements represent a set of staffing requirements and grouped staffing against the requirement within a given time window. They correspond to metrics about required staffing and scheduled staffing that appear above the team calendar.

Requirement object

{
  "requirement_type_id": "<uuid>",
  "required": 42.0,
  "scheduled": 42.0,
  "start_time": 1549065600,
  "end_time": 1549066500
}
Field Type Description
requirement_type_id uuid Unique identifier for the corresponding requirement type.
required float Count of required staffing in the interval, can be partial.
scheduled float Count of scheduled staffing in the interval, can be partial.
start_time Unix timestamp, in seconds
end_time Unix timestamp, in seconds

POST /v0/requirements

Example request

curl "https://api.assembledhq.com/v0/requirements" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{"requirement_type_id": "<uuid>", "start_time": 1549065600, "end_time": 1549069200, "required": 42.0}'

Creates or overwrites a requirement with the specified parameters.

Parameters:

Field Type Required Description
requirement_type_id uuid Required
required float Required
start_time Unix timestamp, in seconds Required Must be a multiple of the configured interval e.g. 3600 for 1 hour or 900 for 15 minutes.
end_time Unix timestamp, in seconds Required Must be a multiple of the configured interval as above. The difference with start_time must also equal the interval.

GET /v0/requirements

Example request

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

Example response

{
  "requirements": [
    {
      "requirement_type_id": "<uuid>",
      "required": 42.0,
      "scheduled": 42.0,
      "start_time": 1641042000,
      "end_time": 1641081600
    },
    ...
  ],
}

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

Parameters:

Field Type Required Description
start_time Unix timestamp, in seconds Required
end_time Unix timestamp, in seconds Required Together with start_time, this determines the interval for which requirements will be retrieved. The interval can be a maximum of 31 days.

Requirement types

Requirement types contain metadata about a named set of staffing requirements. The API supports two types of requirements: 1. Those that apply to a set of activity types. In this case, all activities with the corresponding type would count as scheduled against the requirement. 2. Those that apply to an entire channel and, optionally, a queue. In this case, all activities from agents with a matching channel and, if relevant, queue would count as scheduled.

Requirement types cannot simultaneously apply to both activity types and a channel and queue.

Requirement type object

{
  "id": "<uuid>",
  "name": "Requirement",
  "activity_type_ids": ["<uuid>", "<uuid>", ...],
  "channel": "chat",
  "queue": "<uuid>",
}
Field Type Description
id uuid
name string
activity_type_ids list[uuid] If provided, a list of identifiers for activity types that the requirement type applies to.
channel string If provided, the channel that the requirement type applies to.
queue uuid If provided, an identifier for the queue that the requirement type applies to.

GET /v0/requirement_types

Example request

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

Example response

{
  "requirement_types": {
    "<uuid>": {
      "id": "<uuid>",
      "name": "Chat",
      "activity_type_ids": ["<uuid>", "<uuid>"],
      "channel": "chat",
      "queue": "<uuid>"
    }
  }
}

Returns a list of all requirement type objects configured on the account.

Time off

Agents can have time off requests that are either created directly in Assembled or sourced from other applications such as Hibob and Workday. Time off requests can be retrieved via GET /activities after they have been approved. All time off requests (approved, pending, cancelled, denied) can be retrieved via GET /time_off/requests.

Time off request object

{
  "id": "<uuid>",
  "agent_id": "<uuid of the agent requesting time off>",
  "start_time": 1546303260,
  "end_time": 1546303270,
  "created_at": 1546303260,
  "activity_type_id": "<uuid of the activity type of the time off request>",
  "description": "Going to the dentist",
  "status": "approved"
}
Field Type Description
id uuid
agent_id uuid Unique identifier for the corresponding agent.
start_time Unix timestamp, in seconds
end_time Unix timestamp, in seconds
created_at Unix timestamp, in seconds
activity_type_id uuid Unique identifier for the activity type of the timeoff taken
description string Reason why the agent is requesting time off.
status string One of: canceled, denied, approved, pending

Time off update object

{
  "id": "<uuid>",
  "time_off_request_id": "<uuid of the time off request object>",
  "created_at": 1546303260,
  "comment": "Enjoy your vacation",
  "type": "approve"
}
Field Type Description
id uuid
time_off_request_id uuid Unique identifier for the time off request.
created_at Unix timestamp, in seconds
comment string
type string One of: approve, edit, deny, cancel

GET /v0/time_off/updates

Example request

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

Example response

{
  "time_off_updates": {
    "<uuid>": {
      "id": "<uuid>",
      "time_off_request_id": "<uuid of the time off request object>",
      "created_at": 1546303260,
      "comment": "Enjoy your vacation",
      "type": "approve"
    },
    ...
  },
  "time_off_requests": {
    "<uuid>": {
      "id": "<uuid>",
      "agent_id": "<uuid of the agent requesting time off>",
      "start_time": 1546303260,
      "end_time":  1546303270,
      "created_at": 1546303260,
      "description": "Going to the dentist",
      "status": "approved",
      "activity_type_id": "<uuid>",
    }
  },
  "total": 26,
  "limit": null,
  "offset": null

}

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

Parameters:

Field Type Required Description
updated_since Unix timestamp, in seconds Required
type One of: approve, edit, deny, cancel Optional
limit int Optional 20 responses are returned by default, but the maximum value is 500
offset int Optional Adds an offset to the responses returned, starting from 0

POST /v0/time_off

Creates a time off request with the specified parameters. Valid IDs for user_id and receiver_ids can be retrieved from GET /people, and valid IDs for activity_type_id can be retrieved from GET /activity_types. This endpoint will return a 400 if invalid IDs for user_id, activity_type_id, or receiver_ids are provided.

Example request

curl "https://api.assembledhq.com/v0/time_off" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d \
  '{
      "user_id": "<uuid>",
      "description": "Vacation",
      "activity_type_id": "<uuid>",
      "start_time": 1709064000,
      "end_time": 1709164800,
      "editable": false,
      "receiver_ids": [
        "<uuid>",
        "<uuid>"
      ]
   }'

Example response

{
  "id": "<uuid>",
  "status": "success"
}

Parameters:

Field Type Required Description
user_id uuid Required The ID of the Person requesting time off
description string Optional
activity_type_id uuid Required The ID of the activity type corresponding to this time off request
start_time Unix timestamp, in seconds Required
end_time Unix timestamp, in seconds Required
editable boolean Optional Whether the time off request is editable. Defaults to false. If the "auto-editable" feature is enabled, the value passed here will be ignored.
receiver_ids list[uuid] Optional The list of IDs of the People who are notified when the time off request is submitted.

GET /v0/time_off/requests

Example request

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

Example response

{
  "time_off_updates": {
    "<uuid>": {
      "id": "<uuid>",
      "time_off_request_id": "<uuid of the time off request object>",
      "created_at": 1546303260,
      "comment": "Enjoy your vacation",
      "type": "approve"
    },
    ...
  },
  "time_off_requests": {
    "<uuid>": {
      "id": "<uuid>",
      "agent_id": "<uuid of the agent requesting time off>",
      "start_time": 1546303260,
      "end_time":  1546303270,
      "created_at": 1546303260,
      "description": "Going to the dentist",
      "status": "approved",
      "activity_type_id": "<uuid>"
    }
  },
  "total": 26,
  "limit": 50,
  "offset": 10

}

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

Parameters:

Field Type Required Description
updated_since Unix timestamp, in seconds Required
type One of: approved, pending, denied, canceled Optional
limit int Optional 20 responses are returned by default, but the maximum value is 500
offset int Optional Adds an offset to the responses returned, starting from 0

POST /v0/time_off/:id/cancel

Cancels an existing time off request. Valid IDs for id can be retrieved from GET /time_off/requests.

Example request

curl "https://api.assembledhq.com/v0/time_off/b646e719-6682-4402-aa4c-881a41457a48/cancel" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d \
  '{
      "user_id": "<uuid>",
      "comment": "Accidentally requested wrong dates"
   }'

Example response

{
  "status": "success"
}

Parameters:

Field Type Required Description
user_id uuid Required The ID of the Person canceling time off
comment string Optional

Shift patterns [Beta]

Shift patterns allow managing and viewing each agent’s working hours (aka shifts) directly in Assembled’s schedules to help with scheduling more efficiently. In addition, time off reporting is made more convenient and accurate with agent’s working hours now available. For example, when you or your agents submit and approve full-day or multi-day time off requests, Assembled will use the assigned shift patterns to determine exact start and end times, ensuring accurate placement of time off events on the staffing timeline.

The shift pattern API is currently invite-only, please contact your customer success manager to find out how to access it.

Shift pattern response object

{
  "id": "<uuid>",
  "name": "Monday - Friday 9am to 5pm shift",
  "timezone": "Americas/New_York",
  "user_email": "user@email.com",
  "excluded_duration_seconds": 1800,
  "shifts": [
    {
      "start_time": {
        "day_of_week": 1,
        "hour": 17,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 2,
        "hour": 5,
        "minute": 0
      }
    }
  ],
  "created_at": 1697561882,
  "updated_at": 1705516856,
  "assigned_agent_count": 23,
  "assigned_agent_ids": [
    "<uuid>",
    "<uuid>",
    "<uuid>",
    ...
  ]
}
Field Type Description
id uuid Unique identifier for the shift pattern
name string Unique name for the shift pattern
timezone string IANA timezone string for the shift pattern
user_email string Assembled account email of the user who created (or last updated) the shift pattern
excluded_duration_seconds integer Time in seconds of any non-working periods like lunch or breaks. Improves time off reporting accuracy
description string Optional description of further shift pattern details
shifts list[object] Object used to describe details of each shift
created_at Unix timestamp, in seconds Object used to describe details of each shift
updated_at Unix timestamp, in seconds Object used to describe details of each shift
assigned_agent_count integer Count of agents assigned to this shift pattern
assigned_agent_ids list[uuid] List of unique agent IDs assigned to this shift pattern

Shifts object

Monday from 5pm to 5am

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

Tuesday from 9am to 5pm

{
  "shifts": [
    {
      "start_time": {
        "day_of_week": 2,
        "hour": 9,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 2,
        "hour": 17,
        "minute": 0
      }
    }
  ]
}
Field Type Description
day_of_week number Indicates which day of the week is for this entry, 0 is Sunday and 6 is Saturday
hour number Hour of the shift in 24-hour time, must be between 1 and 24
minute number Minute of the shift, must be between 0 and 59

The shift object is used to define the specific start and end times for each shift.

day_of_week begins on Sunday with 0 and ends on Saturday with 6.

Each entry into the shifts array cannot be longer than 20 hours.

Each entry into the shifts array cannot overlap between 2 days.

Shift pattern creation object

{
  "name": "Monday - Friday 9am to 5pm shift",
  "timezone": "Americas/New_York",
  "user_email": "mike@assembledhq.com",
  "excluded_duration_seconds": 1800,
  "shifts": [
    {
      "start_time": {
        "day_of_week": 1,
        "hour": 17,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 2,
        "hour": 5,
        "minute": 0
      }
    }
  ]
}
Field Type Required Description
name string Required Name of the shift pattern
timezone string Required IANA timezone name
user_id string Required UUID of Assembled user creating the shift pattern, used for reporting
excluded_duration_seconds string Optional Time, in seconds, of any non-working periods like lunch or breaks. Improves time off reporting accuracy
description string Optional Description of further shift pattern details
shifts list[object] Required Object used to describe the details of each shift

GET /v0/shift_patterns

Example request

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

Example response

[
  {
    "id": "<uuid>",
    "name": "Eastern time Assemblers",
    "description": "New York, Massachusetts, Georgia, Ontario",
    "shifts": [
      {
        "start_time": {
          "day_of_week": 1,
          "hour": 9,
          "minute": 0
        },
        "end_time": {
          "day_of_week": 1,
          "hour": 17,
          "minute": 0
        }
      },
      {
        "start_time": {
          "day_of_week": 2,
          "hour": 9,
          "minute": 0
        },
        "end_time": {
          "day_of_week": 2,
          "hour": 17,
          "minute": 0
        }
      },
      {
        "start_time": {
          "day_of_week": 3,
          "hour": 9,
          "minute": 0
        },
        "end_time": {
          "day_of_week": 3,
          "hour": 17,
          "minute": 0
        }
      },
      {
        "start_time": {
          "day_of_week": 4,
          "hour": 9,
          "minute": 0
        },
        "end_time": {
          "day_of_week": 4,
          "hour": 17,
          "minute": 0
        }
      },
      {
        "start_time": {
          "day_of_week": 5,
          "hour": 9,
          "minute": 0
        },
        "end_time": {
          "day_of_week": 5,
          "hour": 17,
          "minute": 0
        }
      }
    ],
    "timezone": "America/New_York",
    "created_at": 1697561882,
    "updated_at": 1705516856,
    "assigned_agent_count": 23,
    "assigned_agent_ids": [
      "<uuid>",
      "<uuid>",
      "<uuid>",
      ...
    ]
  }
]

Returns a list of shift patterns.

GET /v0/shift_pattern/:id

Example request

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

Example response

{
  "id": "<uuid>",
  "name": "Eastern time Assemblers",
  "description": "New York, Massachusetts, Georgia, Ontario",
  "shifts": [
    {
      "start_time": {
        "day_of_week": 1,
        "hour": 9,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 1,
        "hour": 17,
        "minute": 0
      }
    },
    {
      "start_time": {
        "day_of_week": 2,
        "hour": 9,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 2,
        "hour": 17,
        "minute": 0
      }
    },
    {
      "start_time": {
        "day_of_week": 3,
        "hour": 9,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 3,
        "hour": 17,
        "minute": 0
      }
    },
    {
      "start_time": {
        "day_of_week": 4,
        "hour": 9,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 4,
        "hour": 17,
        "minute": 0
      }
    },
    {
      "start_time": {
        "day_of_week": 5,
        "hour": 9,
        "minute": 0
      },
      "end_time": {
        "day_of_week": 5,
        "hour": 17,
        "minute": 0
      }
    }
  ],
  "timezone": "America/New_York",
  "created_at": 1697561882,
  "updated_at": 1705516856,
  "assigned_agent_count": 23,
  "assigned_agent_ids": [
    "<uuid>",
    "<uuid>",
    "<uuid>",
    ...
  ]
}

Returns a specific shift pattern that matches the supplied ID.

POST /v0/shift_patterns

Example request

curl "https://api.assembledhq.com/v0/shift_patterns" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "name": "Central Europe Sunday - Tuesday Overnight",
    "timezone": "Europe/Zurich",
    "user_id": "<uuid>",
    "shifts": [
        {
            "start_time": {
                "day_of_week": 0,
                "hour": 17,
                "minute": 0
            },
            "end_time": {
                "day_of_week": 1,
                "hour": 5,
                "minute": 0
            }
        },
        {
            "start_time": {
                "day_of_week": 1,
                "hour": 17,
                "minute": 0
            },
            "end_time": {
                "day_of_week": 2,
                "hour": 5,
                "minute": 0
            }
        },
        {
            "start_time": {
                "day_of_week": 2,
                "hour": 17,
                "minute": 0
            },
            "end_time": {
                "day_of_week": 3,
                "hour": 5,
                "minute": 0
            }
        },
    ]
  }'

Creates a new shift pattern.

Parameters:

Field Type Required Description
name string Required Name of the shift pattern
timezone string Required IANA timezone name
user_id string Required UUID of Assembled user creating the shift pattern, used for reporting
excluded_duration_seconds string Optional Time, in seconds, of any non-working periods like lunch or breaks. Improves time off reporting accuracy
description string Optional Description of further shift pattern details
shifts list[object] Required Object used to describe the details of each shift

PUT /v0/shift_patterns/:id

Example request

curl "https://api.assembledhq.com/v0/shift_patterns/<uuid>" \
  -H "Content-Type: application/json" \
  -X PUT \
  -u sk_live_abc123: \
  -d '{
    "user_id": "<uuid>",
    "shifts": [
        {
            "start_time": {
                "day_of_week": 0,
                "hour": 1,
                "minute": 0
            },
            "end_time": {
                "day_of_week": 0,
                "hour": 5,
                "minute": 0
            }
        }
    ]
  }'

Updates an existing shift pattern. Any change to the shifts object during updates will completely overwrite the existing shifts.

Parameters:

Field Type Required Description
name string Optional Name of the shift pattern
timezone string Optional IANA timezone name
user_id string Required UUID of Assembled user creating the shift pattern, used for reporting
excluded_duration_seconds string Optional Time, in seconds, of any non-working periods like lunch or breaks. Improves time off reporting accuracy
description string Optional Description of further shift pattern details
shifts list[object] Optional Object used to describe the details of each shift

DELETE /v0/shift_patterns/{id}

Example request

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

Deletes an existing shift pattern.

POST /v0/shift_patterns/assign

Example request

curl "https://api.assembledhq.com/v0/shift_patterns/assign" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "shift_pattern_id": "<uuid>",
    "agent_ids": [
        "<uuid>",
        "<uuid>",
        "<uuid>",
    ]
  }'

Assigns agents to a shift pattern. If any agents are already assigned to a shift pattern, this will overwrite their assignment to the new shift pattern.

Parameters:

Field Type Required Description
shift_pattern_id uuid Required Unique identifier for the shift pattern.
agent_ids list[uuid] Required List of agent IDs

POST /v0/shift_patterns/unassign

Example request

curl "https://api.assembledhq.com/v0/shift_patterns/unassign" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{
    "agent_ids": [
        "<uuid>",
        "<uuid>",
        "<uuid>",
    ]
  }'

Unassigns all provided agent IDs from their respective shift pattern.

Parameters:

Field Type Required Description
agent_ids list[uuid] Required List of agent IDs

Changelog

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

2024-06-04

2024-05-22

2024-02-27

2022-12-02

2022-03-21

2019-06-20

2019-02-22