Introduction

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

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

Authentication

Example usage

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

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

All API keys have the prefix sk_live_.

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

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

Rate limiting

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

Versioning

Example usage

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

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

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

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

People

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

People object

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

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

GET /v0/people

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

Example request

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

Example response

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

Query parameters:

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

GET /v0/people/:id

Returns a Person based on the id provided

Example request

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

Example response

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

POST /v0/people

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

We allow creating People in bulk, as well as individually

Example request (single Person creation)

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

Example response (single Person creation)

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

Example request (multiple Person creation)

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

Example response (multiple Person creation)

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

Parameters:

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

PATCH /v0/people/:id

Example request

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

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

Example response

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

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

Parameters:

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

DELETE /v0/people/:id

Example request

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

Example response

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

Query parameters:

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

Agent states

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

Agent state object

{
  "agent_id": "<uuid>",
  "agent_name": "John Smith",
  "agent_email": "john.smith@example.com",
  "agent_platform_id": "25963324267",
  "platform": "zendesk",
  "start_time": 1664890267,
  "end_time": 1664890367,
  "state": "Online (Tickets)",
  "ticket_id": "4544635",
  "ticket_status": "solved",
  "modified_at": 1664890367
}

Field	Type	Description
agent_id	uuid	Unique identifier for an agent in Assembled.
agent_name	string
agent_email	string
agent_platform_id	string	Unique identifier for the agent for the platform. This can be associated to agents in Assembled with the agent associations endpoint.
platform	string	The platform that the agent state comes from e.g. "api", "zendesk_talk", or "kustomer".
start_time	Unix timestamp, in seconds	Time when agent began their state.
end_time	Unix timestamp, in seconds	Time when agent ended being in this state.
state	string	Agent’s status from upstream system e.g. "online", "away", or "busy". Values are not validated, but can be mapped to activity types on the Assembled application by an Administrator.
ticket_id	string	Identifier for the corresponding ticket.
ticket_status	string	Status of the ticket.
modified_at	Unix timestamp, in seconds	Time when the agent state was last updated.

POST /v0/agents/state

Example request

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

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

Parameters:

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

GET /v0/agents/state

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

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

Example request (single agent)

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

Example response

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

Example request (agents by filters)

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

Example response

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

Example request (all agents)

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

Example response

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

Parameters:

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

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.

Activities

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

Activity object

{
  "id": "<uuid>",
  "agent_id": "<uuid of agent>",
  "channels": ["phone"],
  "type_id": "<uuid of activity_type>",
  "start_time": 1546303260,
  "end_time":  1546303270,
  "created_at": 1546303260,
  "updated_at": 1546303260,
  "description": null
}

Field	Type	Description
id	uuid
agent_id	uuid	Identifier for the corresponding agent.
type_id	uuid	Identifier for the associated activity type.
start_time	Unix timestamp, in seconds
end_time	Unix timestamp, in seconds
created_at	Unix timestamp, in seconds
updated_at	Unix timestamp, in seconds
description	string	An arbitrary string to be displayed to end users.

POST /v0/activities

Example request

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

Example response

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

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

Parameters:

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

POST /v0/activities/bulk

Example request

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

Example response

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

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

Parameters:

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

Bulk Request Parameters:

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

GET /v0/activities

Example request

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

Example response

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

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

Parameters:

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

DELETE /v0/activities

Example request

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

Example response

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

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

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

Parameters:

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

Activity types

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

Activity type object

{
  "id": "<uuid>",
  "import_id": "third_party_identifier",
  "name": "Shift",
  "short_name": "S",
  "value": "shift",
  "channels": ["email"],
  "productive": true,
  "timeoff": false,
  "background_color": "#ffffff",
  "font_color": "#ffffff"
}

Field	Type	Description
id	uuid
import_id	string	Third-party identifier. Supplied to Assembled and is used to uniquely identify activity types across different systems.
name	string
short_name	string
value	string	Corresponds to type in the Activity object, will be deprecated in a future API version.
channels	list[string]	Channels associated with the activity. Must be non-empty when the the activity is productive.
productive	boolean	If true, timeoff must be false.
timeoff	boolean	If true, productive must be false.
background_color	string	Hex string.
font_color	string	Hex string.

GET /v0/activity_types

Example request

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

Example response

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

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

POST /v0/activity_types

Example request

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

Example response

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

Creates an activity type with the specified parameters.

Parameters:

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

DELETE /v0/activity_types/:id

Example request

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

Deletes an activity type.

Event changes

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

Event change object

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

Field	Type	Description
id	uuid
modified_by	object	Object containing information about the person who edited the event
modified_at	Unix timestamp, in seconds	When the event change was created
event_agent_name	string	Name of the agent whose event was changed
event_agent_id	uuid	ID of the agent whose event was changed
event_agent_email	string	Email of the agent whose event was changed
event_change_type	string	Type of event change. One of create, modify, or delete
description	string
old_event_type	string	Value of the event type before the change (this corresponds to the value field of the Activity Type object)
new_event_type	string	Value of the event type after the change (this corresponds to the value field of the Activity Type object)
old_start_time	Unix timestamp, in seconds
new_start_time	Unix timestamp, in seconds
old_end_time	Unix timestamp, in seconds
new_end_time	Unix timestamp, in seconds
old_channels	list[string]
new_channels	list[string]
old_template_id	uuid	UUID for the template that the event comes from
new_template_id	uuid	UUID for the template that the event comes from
old_google_calendar_event_id	string	Google Calendar event ID for the event, if synced from Google Calendar
new_google_calendar_event_id	string	Google Calendar event ID for the event, if synced from Google Calendar

GET /v0/event_changes

Example request

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

Example response

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

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

Parameters:

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

Conversations

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

Conversation object

{
  "created_at": 1549065600,
  "import_id": "122308400000062",
  "channel": "phone",
  "status": "solved",
  "queue": "<uuid>",
  "first_responded_at": 1549065700,
  "solved_at": 1549065800,
  "assignee_import_id": "d613ab77-75f7-4fce-91d8-f9ef5fe55066",
  "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.

POST /v0/sites

Example request

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

Example response

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

Analogous to POST /v0/queues

POST /v0/teams

Example request

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

Example response

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

Analogous to POST /v0/queues

POST /v0/skills

Example request

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

Example response

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

Analogous to POST /v0/queues

DELETE /v0/queues

Example request

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

Deletes queue objects in bulk.

DELETE /v0/sites

Example request

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

Analogous to DELETE /v0/queues

DELETE /v0/teams

Example request

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

Analogous to DELETE /v0/queues

DELETE /v0/skills

Example request

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

Analogous to DELETE /v0/queues

PUT /v0/queues/:id

Example request

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

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

PUT /v0/sites/:id

Example request

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

Analogous to PUT /v0/queues/:external_id

PUT /v0/teams/:id

Example request

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

Analogous to PUT /v0/queues/:external_id

PUT /v0/skills/:id

Example request

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

Analogous to PUT /v0/queues/:external_id

Forecasts

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

Forecast object

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

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

GET /v0/forecasts

Example request

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

Example response

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

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

Parameters:

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

Forecast totals

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

Forecast total object

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

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

GET /v0/forecasts/totals

Example request

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

Example response

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

Returns a list of forecast totals that have been uploaded.

Parameters:

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

GET /v0/forecasts/totals/:id

Returns a forecast total based on the id provided

Example request

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

Example response

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

POST /v0/forecasts/totals

Example request

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

Example response

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

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

Request Parameters:

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

DELETE /v0/forecasts/totals/:id

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

Example request

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

Forecasts vs. actuals

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

Forecasts vs. actuals objects

Forecasted vs. actual pair

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

{
  "forecasted": 3,
  "actual": 4
}

Field	Type	Description
forecasted	float	The value forecasted for the given metric (may be null)
actual	float	The actual value of the metric (may be null)

Forecasted vs. actual response

{
  "start_time": 1668492000,
  "end_time": 1668495600,
  "channel": "email",
  "queue": "<uuid>",
  "service_level": {
    "forecasted": 0,
    "actual": 0
  },
  "service_level_missed": {
    "forecasted": 63.5,
    "actual": 34
  },
  "service_level_met": {
    "forecasted": 0,
    "actual": 0
  },
  "first_response_time": {
    "forecasted": null,
    "actual": 13172
  },
  "cases_opened": {
    "forecasted": 36,
    "actual": 42
  },
  "cases_reopened": {
    "forecasted": 23.5,
    "actual": 32
  },
  "cases_solved": {
    "forecasted": 60,
    "actual": 54
  },
  "productivity": {
    "forecasted": 3.4,
    "actual": 2.8302307428825666
  },
  "staffing_scheduled": 19.75,
  "staffing_required": 19,
  "staffing_net": 0.75
}

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

GET /v0/forecasted_vs_actuals

Example request

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

Example response

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

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

Parameters:

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

Reports

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

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

Currently, the supported report types are:

Adherence

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

• actual_seconds_worked
• actual_utilization
• actual_utilization_all_channels
• adherence_percentage - refers to productive adherence
• available_and_occupied_time_seconds
• conformance_percentage
• schedule_adherence_percentage
• scheduled_seconds_productive
• scheduled_seconds_total
• seconds_in_adherence - refers to productive adherence
• occupancy_percentage
• occupancy_percentage_all_channels
• occupied_time_seconds
• utilization - refers to schedule utilization

Agent Ticket Stats

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

• agent_avg_handle_time
• agent_tickets_solved

Report Request Object

{
  "start_time": "timestamp",
  "end_time": "timestamp",
  "interval": "string",
  "channel": "string",
  "queue_id": "<uuid>",
  "agent_id": "<uuid>",
  "filters": {
    "site_id": "<uuid>",
    "team_id": "<uuid>",
    "skill_id": "<uuid>"
  }
}

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

Report Object

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

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

Metric Object

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

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

POST /v0/reports/:reportType

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

Report	/:reportType
Adherence	/adherence
Agent ticket stats	/agent_ticket_stats

Example request

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

Example response

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

GET /v0/reports/:reportID

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

Example request

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

Example response

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

Query Parameters

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

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

Example request

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

Requirements

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

Requirement object

{
  "requirement_type_id": "<uuid>",
  "required": 42.0,
  "scheduled": 42.0,
  "start_time": 1549065600,
  "end_time": 1549066500
}

Field	Type	Description
requirement_type_id	uuid	Unique identifier for the corresponding requirement type.
required	float	Count of required staffing in the interval, can be partial.
scheduled	float	Count of scheduled staffing in the interval, can be partial.
start_time	Unix timestamp, in seconds
end_time	Unix timestamp, in seconds

POST /v0/requirements

Example request

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

Creates or overwrites a requirement with the specified parameters.

Parameters:

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

GET /v0/requirements

Example request

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

Example response

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

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

Parameters:

Field	Type	Required	Description
start_time	Unix timestamp, in seconds	Required
end_time	Unix timestamp, in seconds	Required	Together with start_time, this determines the interval for which requirements will be retrieved. 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 [Beta]

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

This endpoint is currently in beta. If you want access, please reach out to support@assembled.com.

Time off request object

{
  "id": "<uuid>",
  "agent_id": "<uuid of the agent requesting time off>",
  "start_time": 1546303260,
  "end_time": 1546303270,
  "created_at": 1546303260,
  "description": "Going to the dentist",
  "status": "approved"
}

Field	Type	Description
id	uuid
agent_id	uuid	Unique identifier for the corresponding agent.
start_time	Unix timestamp, in seconds
end_time	Unix timestamp, in seconds
created_at	Unix timestamp, in seconds
description	string	Reason why the agent is requesting time off.
status	string	One of: canceled, denied, approved, pending

Time off update object

{
  "id": "<uuid>",
  "time_off_request_id": "<uuid of the time off request object>",
  "created_at": 1546303260,
  "comment": "Enjoy your vacation",
  "type": "approve"
}

Field	Type	Description
id	uuid
time_off_request_id	uuid	Unique identifier for the time off request.
created_at	Unix timestamp, in seconds
comment	string
type	string	One of: approve, edit, deny, cancel

GET /v0/time_off/updates

Example request

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

Example response

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

}

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

Parameters:

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

GET /v0/time_off/requests

Example request

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

Example response

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

}

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

Parameters:

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

Changelog

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

2022-12-02

• Resource: agent_states
  • Agent state resources will now accept the agent platform ID instead of the agent import ID.
• Resource: activity
  • Activity resources will now return the event UUIDs instead of the event instance ID.

2022-03-21

• Resource: people
  • Defined a new resource for People. Soft-delete is now supported, as well as POST, GET, PATCH and DELETE. These will all live on the /people endpoint. We now return a collection of teams and sites in the GET response.

2019-06-20

• Resource: activity
  • Activity resources will now return a unix timestamp (in seconds) for start_time and end_time instead of a formatted string. Additionally, the type and channels properties have been deprecated. You should be able to find this information for a particular Activity by looking at the associated Activity Type resource using the type_id.
• Resource: activity_type
  • Activity Type resources will now return a channels property which will include the channels that are associated with a particular Activity Type. This takes the place of displaying channels on each Activity resource.

2019-02-22

• Initial API Version