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/agents" \
    -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.

Test mode secret keys have the prefix sk_test_ and live mode secret keys have the prefix sk_live_. Test mode requests will not be persisted and will not return live data.

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/agents" \
  -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.

Agents

Agents handle units of work and can be assigned to activities or schedules. They can be grouped by site and team and can be assigned to queues or channels based on their skills.

Agent object

{
  "id": "<uuid>",
  "import_id": "third_party_identifier",
  "name": "Michael Scott",
  "email": "michael@dundermifflin.com",
  "channels": ["phone", "chat"],
  "site": "<uuid>",
  "teams": ["<uuid>", "<uuid>"],
  "queues": ["<uuid>"],
  "skills": ["<uuid>"]
}

Field	Type	Description
id	uuid
import_id	string	Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems.
name	string
email	string
channels	list[string]
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.

POST /v0/agents

Example request

curl "https://api.assembledhq.com/v0/agents" \
  -H "Content-Type: application/json" \
  -X POST \
  -u sk_live_abc123: \
  -d '{"name": "Michael Scott", "email": "michael@dundermifflin.com"}'

Example response

{
  "id": "<uuid>",
  "import_id": null,
  "name": "Michael Scott",
  "email": "michael@dundermifflin.com",
  "channels": [],
  "site": null,
  "teams": [],
  "queues": [],
  "skills": []
}

Creates an agent profile with the specified parameters. Valid IDs for site, teams, and queues can be retrieved from endpoints for filters. This endpoint will return 400 if invalid IDs are provided.

Parameters:

Field	Type	Required	Description
name	string	Required
email	string	Optional
channels	list[string]	Optional	One of: "phone", "email", or "chat".
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.
import_id	string	Optional	Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems.

PATCH /v0/agents/:id

Example request

curl "https://api.assembledhq.com/v0/agents/8ce1939e-cc6c-48e8-b0ef-a2326b562082" \
  -X PATCH \
  -u sk_live_abc123: \
  -d '{"name": "Pam Beesly", "email": null}'

Example response

{
  "id": "<uuid>",
  "import_id": null,
  "name": "Pam Beesly",
  "email": null,
  "channels": [],
  "site": null,
  "teams": [],
  "queues": [],
  "skills": []
}

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
name	string	Optional
email	string	Optional
channels	list[string]	Optional	One of: "phone", "email", or "chat".
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.
import_id	string	Optional	Third-party identifier. Supplied to Assembled and is used to uniquely identify agents across different systems.

GET /v0/agents

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

Example request

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

Example response

{
  "agents": {
    "<uuid>": {
      "id": "<uuid>",
      "import_id": "third_party_identifier",
      "name": "Michael Scott",
      "email": "michael@dundermifflin.com",
      "channels": ["phone", "chat"],
      "site": "<uuid>",
      "teams": ["<uuid>", "<uuid>"],
      "queues": ["<uuid>"]
    },
    ...
  }
}

Parameters:

Field	Type	Required	Description
channels	list[string]	Optional	One of: "phone", "email", or "chat".
queue	string	Optional	Name of the queue to filter on.
site	string	Optional	Name of the site to filter on.
team	string	Optional	Name of the team to filter on.

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_import_id": "michael@dundermifflin.com",
  "state": "online",
  "start_time": 1546303260,
  "end_time": 1549067400,
  "platform": "api"
}

Field	Type	Description
agent_import_id	string	Unique identifier for the agent. This can be associated to agents in Assembled with the agent associations endpoint.
state	string	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.
start_time	timestamp, in seconds	Time when agent began their current state.
end_time	timestamp, in seconds	Time when agent ended being in this state.
platform	string	The platform that the agent state comes from e.g. "api", "zendesk_talk", or "kustomer".

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_import_id": "michael@dundermifflin.com",
    "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_import_id	string	Required	Unique identifier for the agent. This can be associated to agents in Assembled with the agent associations endpoint.
time	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/:agent_id/state

Example request

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

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

Example response

    {
      "agent_states": [
        {
          "agent_import_id": "michael@dundermifflin.com",
          "state": "online",
          "start_time": 1549065600,
          "platform": "api"
        },
      ]
    }

Retrieves the current status of the specified agent.

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_import_id": "michael@dundermifflin.com",
    "agent_id": "<uuid>"
  }'

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

Parameters:

Field	Type	Required	Description
agent_import_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,
  "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	timestamp, in seconds
end_time	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,
  "description": null,
  "agent_id": "<uuid>",
  "type_id": "<uuid>"
}

Creates an activity with the specified parameters. Valid IDs for agents can be retrieved from the agent 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	timestamp, in seconds	Required
end_time	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,
      "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	One of create, update, or delete. Note that update and delete are currently in beta. Contact us at support@assembled.com to be notified of updates.
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,
      "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	timestamp, in seconds	Required
end_time	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,
      "agent_id": "<uuid>",
      "type_id": "<uuid>"
    },
    ...
  },
}

Deletes all activities that match the specified parameters. Valid IDs for agents can be retrieved from the agent 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	timestamp, in seconds	Required	The start of the deletion window.
end_time	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.

Conversations

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

Conversation object

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

Field	Type	Required	Description
created_at	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", or "chat".
status	string	Required	One of: "open", "pending", or "solved".
queue	uuid	Optional	Unique identifier for the corresponding queue.
first_responded_at	timestamp, in seconds	Optional	Time the conversation was first responded to by an agent.
solved_at	timestamp, in seconds	Optional	Time the conversation was solved or closed.
assignee_import_id	string	Optional	Third-party identifier for the agent currently assigned to the conversation.

POST /v0/conversations/bulk

Example request

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

Creates or overwrites a conversation with the specified parameters.

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	timestamp, in seconds	Time of creation, in Unix time.
updated_at	timestamp, in seconds	Time of last update, in Unix time.

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	timestamp, in seconds
end_time	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	timestamp, in seconds	Required
end_time	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.

POST /v0/forecasts/bulk

Example request

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

Example response

{
  "forecasts": [
    {
      "id": "<uuid>",
      "start_time": 1562223600,
      "end_time": 1562259600,
      "channel": "chat",
      "queue": "<uuid>",
      "value": 42.0
    },
    ...
  ]
}

Creates or overwrites a forecast with the specified parameters.

Bulk Request Parameters:

Field	Type	Required	Description
forecasts	list[Forecast]	Required	See documentation for the Forecast object.

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	timestamp, in seconds
end_time	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	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	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=1549065600&end_time=1549066500" \
  -X POST \
  -u sk_live_abc123:

Example response

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

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

Parameters:

Field	Type	Required	Description
start_time	timestamp, in seconds	Required
end_time	timestamp, in seconds	Required	Together with start_time, this determines the interval for which requirements will be retrieved.
requirement_types	list[uuid]	Optional	Filter results to a specific set of requirement types.

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.

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 2019-06-20.

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