Each organisation on Assemble will have a unique URL that you will need to use in order to contact the Assemble API. This URL is made up of your organisation slug appended with goassemble.com.
https://{organisation-slug}.goassemble.com/api
If your organisation has set up a custom host mapping for your Assemble, you can optionally use this domain instead.
Each request to the Assemble API must contain the Accept header with the corresponding version you would like to access.
Currently, the only available API version is v3.
Accept: application/x.uvol.v3+json
Every request must contain a Accept header with the corresponding API version.
If the endpoint you are trying to request is authentication based, you must provide the Authorization header containing your authentication token. You can read more about generating a OAuth 2.0 access token here or about generating a JSON Web Token here.
If your authorisation token expires while sending a request to an authenticated endpoint, you will receive a 401 unauthorized response from the API. You must refresh your existing token before trying to re-send your request.
The response you receive from an endpoint will change depending on the status of the request.
If a request is successful, the endpoint will respond with a key named data. The data key may be an object or array of resources depending on the context of the endpoint.
{
"data": {
"id": 1,
"name": "Example"
}
}
If there is an error during your request, the contents of the response will be different.
Assemble API uses standard HTTP status codes to indicate the success or failure of the request. The body of the response will be standard throughout the API.
{
"message": "404 Not Found",
"status_code": 404
}
Some resources with large data set may return the results using a paging mechanism. You can control the paging mechanism by providing different query string parameters.
You can change which page a paginated endpoint responds with by manipulating the page query parameter. You can also change how many items are in the response by updating the limit query parameter.
Below, you can find an example of what a paginated response will look like:
{
"data": [
{id: 1}, {id: 2}, {id: 3}, {id: 4}...
]
"meta": {
"pagination": {
"total": 5664,
"count": 15,
"per_page": 15,
"current_page": 1,
"total_pages": 378,
"links": {
"previous": "https://{organisation-slug}.goassemble.com/api/users?page=1",
"next": "https://{organisation-slug}.goassemble.com/api/users?page=3"
}
}
}
}
Most resources will have additional data that can be included in the response if your request it.
The include query parameter accepts a comma separated string of resources that you would like to include.
For example, on the users endpoint will only include limited details by default. You can then include additional information by adding the include query parameter to the request.
https://{organisation-slug}.goassemble.com/api/users?include=addresses,phoneNumbers,emailAddresses
Includes are relative to the endpoint you are requesting which means you can use dot notation to ask for resources on other includes.
https://{organisation-slug}.goassemble.com/api/users?include=tasks,tasks.teams