NAV
http cURL

Introduction

Welcome to Accelo's Public REST API documentation. Here you will find resources and information to help you use the API.

Developer Forum - Connect with other developers on our developer forum. Use this space to ask any questions and report errors in the documentation.

Registering your Application

Before doing anything, you will need to register your application with Accelo. This is done from your deployment under "Configuration" → "API" → "Register Application". Accelo currently offers three types of applications:

Note: An application can only be registered with one type. If your application requires multiple types you will need to register multiple applications

Once registered, your application will be given a client_id and client_secret, which are required to authenticate.

Accessing Resources

For example, base URI for a company called "Planet Express":

https://planet-express.api.accelo.com/api/v0

Your Accelo deployment will be given a unique deployment (or hostname), from this we can form the URI for each resource, which will have a form like:

https://{deployment}.api.accelo.com/api/v0

All resources may be called from this base URI:

https://{deployment}.api.accelo.com/api/v0/{resource}

For example, accessing the "Staff" resource of "Planet Express":

https://planet-express.api.accelo.com/api/v0/staff

Keep in mind, for an installed or web application we will want to use the end-user's deployment, not the API's deployment. Note, all authorization endpoints are accessed through the OAuth2.0 base URI, which is different from the resource base URI, see the authentication section for more information.

Cipher Suites

In order to maintain security for Accelo and our customers, we may need to stop using old cipher suites; this could cause problems for users utilising older SSL/TLS libraries. Before doing so we will ensure that this will not affect the majority of our users, and will work with those that would be impacted.

See the following documentation for technical details, as of 2023 we are using ELBSecurityPolicy-FS-1-2-Res-2020-10.

Response and Request Structure

Sample request to return a list of staff as XML:

GET https://{deployment}.api.accelo.com/api/v0/staff.xml

By default, all resource requests return JSON (application/json). You may also request the response in XML or YAML by either setting the Accept-Type header to text/xml or text/x-yaml, or by appending the extension type to the end of the request resource.

Sample response with no suppression:

{
    "meta" : {
        "more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok",
        "status" : "ok",
        "message" : "Everything executed as expected."
    },
    "response" : { "..." }
}

Sample failed response, here we requested a company by an id that doesn't exist:

{
  "response": null,
  "meta": {
    "message": "The request could not be interpreted. This can be caused by missing or invalid data. Please ensure that the resource you are requesting actually exists.",
    "more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#invalid_request",
    "status": "invalid_request"
  }
}

The Meta Object

Each request made will return two objects, a meta object, and a response object. The response object contains the requested response data. The meta object contains the following:

Field Name Description
status A string representing the result of the request.
message An explanation of the status
more_info A URL where more information regarding the current status may be found.
response code HTTP status. Only visible when suppressing http status with _suppress_http_status=yes. See here for a list of possible response codes.

Sample response with _suppress_message=yes and _suppress_http_status=yes

{
    "meta" : {
         "status" : "ok",
         "response_code" : 200
    },
    "response" : { "..." }
}

The following parameters may be used to suppress parts, or all, of the meta response:

Name Description
_suppress_message Suppresses message and more_info.
_suppress_http_status Forces HTTP status to 200 and stores the actual status in response_code
_suppress_meta Suppresses all meta data. This is useful if you wish to purely utilize HTTP headers.

They make take values of either "1" or "yes", for example to suppress all meta we could use _suppress_meta=yes or _suppress_meta=1.

Default and Required Fields

A resource will only return a small number of fields by default, these fields will be in bold in the resource's table of fields and linked objects. Similarly, POST request will generally require values for some fields, these fields will be in bold within the endpoint's description.

The following parameter may be used to hide the default fields that would be returned in the response:

Name Description
_hide_defaults Hides the default fields from the response. This is useful to reduce the size of the payload to just the fields you need.

Overriding the Request Method

We understand that certain types of requests are not always available to the client. In response to this we allow you to override the request method using the _method parameter, this can take one of four values:

Value Description
get Override the request type to be GET.
put Override the request type to be PUT.
post Override the request type to be POST.
delete Override the request type to be DELETE.

For example, each of the following deletes the company with id 10:

DELETE /companies/10
GET /companies/10?_method=delete
POST /companies/10?_method=delete

JSON Content Types

Requests may also be sent as JSON. This can greatly simplify the client side implementation as it offers filters and fields that translate well to programmatic structures. This may also be necessary when you wish to search or filter using non-alphanumeric characters e.g "@", "." or special or accented characters e.g. "à", "ç", "ö".

Parsing _fields as JSON

Translating "_fields" from query to json, query: _fields=status(color),username,company(_ALL)

Equivalent JSON "_fields" object:

  "_fields": "status(color), username, company(_ALL)"

When sending JSON data with your request, the "_fields" key should hold a string of the desired fields and linked objects, separated by a comma. For example, the query _fields=status would be equivalent to including "_fields": "status" in the JSON body. The same method is used to request additional objects and their fields as for queries, the "_ALL" value also works as for queries..

Parsing _filters as JSON

Example, converting a query list of filters to JSON:
_filters=id(12,13),date_created_after(1498175480), rate_charged_greater_than(10),order_by_desc(status)

Equivalent JSON "_filters" object

"_filters": {
  "id": [12, 13],
  "date_created_after": [1498175480],
  "rate_charged_greater_than": [10],
  "order_by_desc": ["status"]
}

Filters are sent through JSON bodies using the _filters key, which hold a hash of keys (filter names) and values (the values to be filtered). For example applying the filter _filters=id(12,13),status(3,1) would be equivalent to including in the value of "_filters" the pair "id": [12,13], "status": [3,1]. This basic key-value pairing works for all filters outside of object filters.

Example object filter query and json. Here we are using the against and referrer filters of issues.

_filters=against(company(312,466),job(998)),referrer(prospect(42))
{
  "_filters": {
    "against": [{
      "company": [312,466],
      "job": [998],
    }],
    "referrer": [{
      "prospect": [42]
    }]
  }
}

There are two ways to generate object filters though JSON bodies. The first is by simply building them from the corresponding basic filters, for example the filter against(company(32)) is equivalent to against_type(company),against_id(32), which can be parsed into JSON as shown above. The other is to build a nested JSON object of the form "<object_filter>": [{ "<object_type>": ["<object id>"] }].

Parsing _search as JSON

Parsing a search through _search in JSON is simply a matter of assigning a string to be searched to the key "_search". For example searching for a contact with name "Hubert Farnsworth" may be done in a query through _search=(Hubert+Farnsworth), or in a JSON request by adding "_search": "Hubert Farnsworth".

Rate Limiting

Meta object for a 429 response:

{
  "message": "Rate limit exceeded for planet-express.api.accelo.com",
  "status": "too_many_requests",
  "more_info": "api.accelo.com/docs/#rate-limiting"
}

Requests to the API will be limited to 5000/hour per deployment, this is to protect the quality of the service offered by the API. Authentication or authorization requests (those made to /oauth2 endpoints) will not be limited and will not be counted against this limit. Requests made after exceeding this limit will return a 429 error.

The following headers have also been added to track usage rates:

Header Type Description
X-RateLimit-Reset unix ts The time at which the current rate limit window resets.
X-RateLimit-Remaining int Number of requests remaining in the current rate limit window.
X-RateLimit-Limit int Maximum number of requests allowed in each rate limit window.

Configuring Responses

There are several tools available to configure the response from the API:

Pagination

Accelo has the capacity to hold tens of thousands of resources. So, without being careful we could have a hard time returning the required resources. Thankfully, the API also supports pagination to help us work through a resource list. The available parameters are:

Argument Description
_page The page of result to retrieve. For example to retrieve the first page you would use _page=0, and for the 5th page, _page=4. The default is 0
_limit The max number of resources to return. When combined with _page, this is the number of requests returned per page. Default is 10, max is 100
_offset The resource to return from. Default is 0, this will be overridden if _page is set.

Requesting Additional Fields and Linked Objects

Requesting companies with the "website" and "phone" fields, as well as the linked "postal_address" object and its "city" field:

GET /companies HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_fields=website,phone,postal_address(city)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/companies \
    -H 'authorization: Bearer {access_token}' \
    -d '_fields=website,phone,postal_address(city)'

By default, each resource returns only the minimal required fields, these are displayed in the table describing the object. To request additional fields we can use the _fields parameter. For example, the company object has additional fields website and phone, to display these in a request response we would add _fields=website,phone to our request. The keyword _ALL may be used to return all optional fields.

For linked objects (those marked as "unsigned or object") the _fields parameter may be used to request the linked object by adding parenthesis to the field. For example, the company object contains a link to an address object under the postal_address field, to return this object with its default fields we add _fields=postal_address(). Requesting optional fields from a linked object is done by including the fields within these parenthesis, for example if we wanted the city field from within the postal_address we would use _fields=postal_address(city), here the _ALL keyword would return all optional fields from the postal_address object. If a linked object is request without the parenthesis, e.g. _fields=postal_address then the unique identifier for the object will be returned. This process also supports nesting, for example if we wish to return the country object from within the postal_address object here we would use _fields=postal_address(country()).

Breadcrumbs give identifying information on the parent object(s) of the object requested. They may be requested through _fields=breadcrumbs. Requesting breadcrumbs will return an array of breadcrumb objects, these contain the following fields:

Field Type Description
id unsigned The unique identifier of the parent object.
table string The type of the parent object.
title string The title of the parent object.

For example if a job is created against a company, then the job will have a single breadcrumb containing information on the company. If a task is then created against that job the task will have two breadcrumbs, one identifying the job and another identifying the company. Breadcrumbs are always displayed in ascending order, so the direct parent will be displayed first, then its parent, an so on.

Searching

Some requests support the use of the _search parameter to search through certain fields and display only results satisfying the search. For example, the GET /contacts request supports this filter over the firstname, surname,mobile and email, so _search=kurt+wagner would display any contacts where "kurt" and "wagner" is found in the first name, surname, mobile or email. Another available search method is through the search filter.

Filtering

Most API endpoints support a _filters parameter that allows you to filter the response. The supported filters will be listed for each endpoint, in general there are several types of filters:

Filters may take any number of arguments, new arguments may be separated by a comma. Appending _not to any filter will return results that DO NOT satisfy the filter, e.g. standing_not(active) would return only results whose standing is not 'active'. Any number of filters may be combined in a single request.

For example if we wanted to find all activities that were NOT created against a job we would use _filters=engagement_table_not(job).

Basic Filters

Example request, filter activities by those owned by a staff member:

GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=owner_type(staff)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/activities \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=owner_type(staff)'

These simply filter resources with certain fields for certain values, generally they are requested simply by <field>(<value>). For examples, activities support basic filters on the owner_type and owner_id fields, so for example if we wanted to search for activities owned by the staff member with id 17 we would use _filters=owner_type(staff),owner_id(17).

Date Filters

Filter activities by those created after 2017-03-22 00:00:00 (UTC)

GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=date_created_after(1490140800)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/activities \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=date_created_after(1490140800)'

Many endpoints contain fields representing dates, such as date_created under activities. Date fields are expressed as unix timestamps (for brevity we will just use the shorter "unix ts"). The API supports filtering for many of these "date_fields" through the following filters:

Filter Description
<date_field>_before(<date>) Filter by results whose value of <date_field> is less than the <date> value (expressed as a unix ts).
<date_fields>_after(<date>) Filter by results whose value of <date_field> is greater than the <date> value (expressed as a unix ts).

Range Filters

Filter activities with and id greater than 17:

GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=id_greater_than(17)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/activities \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=id_greater_than(17)'

These are similar to Date Filters except they operate on non-date fields. For a given "field" there are four range filters defined:

Filter Description
<field_name>_greater_than(<value>) Filter by results that have a value for <field> greater than <value>.
<field_name>_less_than(<value>) Filter by results that have a value for <field_name> less than <value>.
<field_name>_greater_than_or_equal(<value>) Filter by results that have a value for <field_name> greater than or equal to <value>.
<field_name>_less_than_or_equal(<value>) Filter by results that have a value for <field_name> less than or equal to <value>.

Order Filters

Filter activities by descending order of id:

GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=order_by_desc(id)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/activities \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=order_by_desc(id)'

These change of the order in which the response is displayed, they are not strictly filters in that they will not exclude any objects from the response, but they are called using _filters so we shall list them here. By default a response will be sorted in ascending order of the id of the objects requested. For a given "field" there are two order filters defined:

Filter Description
order_by_asc(<field>) Order the results in ascending value of <field>.
order_by_desc(<field>) Order the results in descending value of <field>.

Empty Filters

Filter contracts with an empty date_expires:

GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=empty(date_expires)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/activities \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=empty(date_expires)'

These filter resources which have no value for the given field, the format is empty(<field_name>). For example, the date_expires field for contract supports this filter, so _filters=empty(date_expires) would display all contracts without an expiry date.

Object Filters

Filter activities owned by "staff/17"

GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=owner(staff(17))
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/activities \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=owner(staff(17))'

These are an extension of basic filters that allow for more compact filtering over entire objects, they take both an object and an id as arguments. For example, activities support object filtering on the "owner" object. As we saw previously we could specify activities by a certain staff member using _filters=owner_type(staff),owner_id(17) we may achieve the same using the owner object filter on activities, _filters=owner(staff(17)).

As with other filters, additional arguments for both fields may be added and separated by a comma, for example _filters=owner(staff(17,13),affiliation(22) would show all activities owned by the staff with id 17 or 13, or owned by the affiliation with id 22.

Search Filters

Filter contacts by "kurt wagner"

GET /contacts HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=search(kurt wagner)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/contacts \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=search(kurt wagner)'

This filter is similar to the searching parameter and supports the same requests available to that parameter. Automatically this filter will append an AND between multiple search requirements. Search terms are separated by , or any space. Some characters e.g. (,) and , will be ignored using this filter whereas these are accepted by _search. It will search through the available fields and only return results that satisfy the search. This filter expands on the searching parameter by allowing the use of _OR. For example, the GET /contacts request supports search over firstname, surname, mobile, and email so if we wanted to find contacts with "kurt" or "wagner" in any of the listed fields we could use _filters=_OR(search(kurt),search(wagner)).

Combining Filters

Filter by activities owned by "staff/17" and created after 2017-03-22 00:00:00 (UTC) and not against a job

GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_filters=owner(staff(17)),date_created_after(1490140800),against_type_not(job)
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/activities \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=owner(staff(17)),date_created_after(1490140800),against_type_not(job)'

Any combination of filters may be used to filter response, this is achieved by separating them with a comma. More flexible filter combinations may be achieved through the _AND and _OR keywords. For example, if we wanted to search for activities owned by the specific staff OR created after a given date we could use _filters=_OR(staff(17),date_created_after(1490140800)). One _AND can be nested inside an _OR for greater filtering flexibility. For example, if we wanted all activities created by the given staff member, or after a given date and before another date we could use _filters=_OR(staff(17),_AND(date_created_after(1490140800),date_created_before(1500140800))). Nested _OR keywords are not supported.

If the same filter is used more than once in a combination only the final instance of the filter will be used. For example _filters=_OR(staff(10),staff(11)) will just filter by staff with id 11, here the simple filter _filters=staff(10,11) should be used.

Only a single _AND can be defined inside the filters param.

Authentication

Accelo's API uses the OAuth 2.0 protocol and provides routines that cover web, service and installed application's authorization and authentication. It supports authorization code grants and client credential grants as necessary between the available API applications.

Please read OAuth 2.0's final version specification for more information on the protocol.

Generally, accessing an Accelo resource protected by OAuth2.0 takes three steps:
1. Authorize
2. Acquire token
3. Access resource

Before access to a token is granted authorization is achieved for a limited range of requests using the client_id and client_secret which can be found through your Accelo toolbox and are given upon registering your API. To gain an access token your application must first be authorized by the end user, once authorized we are able to send a token request to the OAuth endpoint. We will go through this process for each of the application types support by Accelo.

OAuth2.0 URI

Example OAuth2.0 base URI for planet express:

https://planet-express.api.accelo.com/oauth2/v0

The OAuth2.0 base URI is different to the base URI for Accelo resources, in general this base URI will be found at:

https://{deployment}.api.accelo.com/oauth2/v0

This URI is used to authorize and access tokens.

Scope

For example, to request permission to read all information and write only to companies and contacts:

scope=read(all),write(companies,contacts)

For example, to request permission to read and write to contacts and staff:

scope=write(contacts,staff)

The range of access permissions for a given token is provided by the scope parameter. Currently, the following scopes are available:

read({resource}) - Read only access to data related to the {resource} object, which may be any resource. read(all) gives read only access to all data the user owns or has access to. To provide read access to any collection of resources, {resource_1},{resource_2},... you can simply concatenate, read({resource_1},{resource_2},...)

write({resource}) - Read and write access related to the resource specified. write(all) gives read and write access to all data the user owns or has access to. As for read access, write access for a collection of resources is given via concatenation.

The scope field is optional in all requests that use it, and defaults to read(all).

OAUTH2.0 Endpoints

There are three endpoints off the OAUTH2.0 URI, they are /authorize, /token, and revoke. These endpoints support the following requests:

Request Description
GET | POST /authorize Request authorization from a user.
POST /token Request an access token using a grant code or refresh token.
POST /revoke Revoke and access token.

We will cover handling the responses on a case-by-case basis for each application type, as the responses vary between them. Note that authorization and token requests should always be encoded, for the purposes of demonstration, our examples are not.

Redirect URIs

Redirect URIs are used in the authorization of web and installed applications, these are the URIs to which the end- user's response to authentication requests are sent. Redirect URIs for an application may be registered through the api control panel. You may register many callback URIs for a web application, but only one for an installed application.

Authentication Without a Token

Authenticating an application before you have been granted an access token is done using HTTP Basic authorization. The format is {client_id}:{client_secret} encoded in base64. For example if your client id is 5ba17c78ao@planet-express.accelo.com and your client secret is zTfFgiyQCVDFk-1EtUerVLRk1is6LgL6 then you would authorize with the header:

Authorization: Basic NWJhMTdjNzhhb0BwbGFuZXQtZXhwcmVzcy5hY2NlbG8uY29tOnpUZkZnaXlRQ1ZERmstMUV0VWVyVkxSazFpczZMZ0w2.

For convenience we will just write {client_credentials}

Service Applications

These are not run from the end user's deployment, and hence do not need to be authorized by the user, so authorization and accessing a token is are combined into one step for these application.

Token Acquisition for Service Applications

Example token request for the Planet Express deployment, here {client_credentials} is client_id:client_secret encoded in base64, as described above.

POST /oauth2/v0/token HTTP/1.1
Host: planet-express.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic {client_credentials}

grant_type=client_credentials
scope=read(staff)
curl X- POST https://planet-express.api.accelo.com/oauth2/v0/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'authorization: Basic {client_credentials}' \
  -d 'grant_type=client_credentials' \
  -d 'scope=read(staff)'

The token endpoint:

https://{deployment}.api.accelo.com/oauth2/v0/token

Please note, access and refresh tokens should never be transmitted without being encoded. Further note, all token requests require authorization using HTTP Basic as outlined above.

The /token endpoint to request a token. Since end-user authorization is not required, HTTP basic is used instead, the format as outlined above. For service applications this request supports the following parameters:

Parameters Type Description
grant_type string This must be set to client_credentials for this request.
scope string The scope of access desired for the application. See the OAuth2 URI for possible values.
expires_in unsigned The lifetime in seconds of the access token. e.g, the value "3600" expresses that the token will expire in one hour from the time the token was created. This defaults to 30 days.

A successful request will contain the following fields:

Example successful response:

{
  "access_token": "Ck9ma73_db",
  "expires_in": "2592000",
  "token_tpye": "Bearer",
  "..."
}
Response Type Description
access_token string Credential used to access Accelo's protected resources.
token_type string For service applications this will have the value "bearer".
expires_in unsigned The lifetime in seconds of the access token.
deployment string The deployment to which the token belongs.
deployment_name string A proper name for the deployment
deployment_uri The full uri of the deployment.
account_id string A unique identifier for the Accelo account belonging to the deployment used.
account_details hash The details of the user for whom the token has been generated. This contains user information as well as a user_access has containing the user's permissions for each resources, and a user_defined_title hash containing a list of resource names as defined by the user on the deployment, and a locale hash containing information on the currency used by the user.

Web Applications

Web applications require the end-user to authorize an application before it can make any requests. Hence token acquisition requires two steps:
1. Authorization of the application
2. TokenAcquisition

Keep in mind for these applications that the host is the deployment for the user and not the web application's deployment host.

Authorization for Web Applications

The authorize endpoint URI:
https://{deployment}.api.accelo.com/oauth2/v0/authorize

Authorization Request for Web Applications

Example authorization request:

POST /oauth2/v0/authorize HTTP/1.1
Host: planet-express.api.accelo.com
Content-Type: application/x-www-form-urlencoded

client_id=a17c78ao@planet-express.accelo.com
response_type=code
scope=read(companies,contacts),write(staff)
redirect_uri=https//planet-express.com/oauth-callback
curl -X POST https://planet-express.api.accelo.com/oauth2/v0/authorize \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=a17c78ao@planet-express.accelo.com' \
  -d 'response_type=code' \
  -d 'scope=read(companies,contacts),write(staff)' \
  -d 'redirect_uri=https//planet-express.com/oauth-callback'

Authorization is achieved through the authorize endpoint. For authorizing web applications, the endpoint takes the following parameters:

Parameter Type Description
client_id string The application's client ID as listed on the API control panel.
response_type string This must be set to code for this request.
scope string The scope of access desired for the application. See the OAuth2.0 URI for possible values.
redirect_uri string If included this must match one of the redirect URIs provided when you registered your application.
state string This is any string you see fit. The state parameter will be sent back to you as a receipt. For example, a randomly generated number to act as a nonce to mitigate cross-site-request re-forgery attacks. Or, a path to redirect the user to once they are returned to your callback.

A successful request will send the end-user a prompt similar to the following:

alt text

The result of the end-user's response will be sent to the provided redirect_uri

Authorization Response for Web Applications

The response sent to the redirect_uri may contain the following parameters:

Parameter Type Description
code string The authorization code to be used to request a token. This is only sent upon the end-user giving approval for your app.
state string The state value sent in the request. This is only sent if a state is provided in the request, see above for information on this .
error string Error status when there has been an error in the request. This is only sent if the request was not approved. See the OAUTH2.0 URI for a list of potential statuses
error_description string A human readable explanation on why the error may have occurred. This is only sent if there is an error.

Token Acquisition for Web Applications

Please note, access and refresh tokens should never be transmitted without encryption. Further note, all token requests require authoriztion using HTTP Basic as outlined previously

Example token request:

POST /oauth2/v0/token HTTP/1.1
Host: planet-express.api.accelo.com
Authorization: Basic {client_credentials}

grant_type=authorization_code
code=frLA0s1m_D
redirect_uri=https://planet-express.com/oauth-callback
curl -X POST https://planet-express.api.accelo.com/oauth2/v0/token \
  -H 'authorization: Basic {client_credentials}' \
  -d 'grant_type=authorization_code' \
  -d 'code=frLA0s1m_D' \
  -d 'redirect_uri=https://planet-express.com/oauth-callback'

Once you have an authorization code from a successful authorization request you may exchange it for an access and refresh token. The token request requires that you authenticate using HTTP Basic Authorization as explained here . Token request are sent through the /token endpoint, for web application request this endpoint supports the following parameters:

Parameter Type Description
grant_type string This must be set to authorization_code for this request.
code string The authorization code obtained from the authorization process
redirect_uri string If a redirect_uri was provided when authorizing this must be the redirect_uri provided. Otherwise, this must be one of the redirect URIs provided when you registered your application.
expires_in unsigned The lifetime in seconds of the access token. e.g, the value "3600" expresses that the token will expire in one hour from the time the token was created. This defaults to 30 days.

A successful response will contain the following fields:

Example successful request:

{
  "access_token": "Ck9ma73_db",
  "refresh_token": "VYfb63__vf",
  "token_type": "Bearer",
  "expires in": 2592000,
  "..."
}

Example failed response, here our authorization code has expired:

{
  "error": "invalid_grant",
  "error_description": "Grant was not found (possibly expired)."
}
Name Type Description
access_token string The token used to access resources.
refresh_token string A refresh token which may be exchanged for a fresh token.
token_type string The type of token returned.
expires_in unsigned The lifetime in seconds of the access token.
error string For potential errors see the OAUTH2.0 URI
error_description string as for above, see here

Note that an invalid (that is, not one of the one those registered, or not matching that provided when authorizing ) URI will return a "Grant was not found (possibly expired)." error

Installed Applications

Similarly to web applications, to gain a token for installed applications you must first have the end-user authorize the application, so again the two steps are:
1. Authorize the application 2. Token Acquisition

Keep in mind for these applications that the host is the deployment for the user and not the installed application's deployment host.

Authorization for Installed Applications

The Authorization Request for Installed Applications

Example authorization request:

POST /oauth2/v0/authorize HTTP/1.1
Host: planet-express.api.accelo.com

client_id=9749c33f@planet-express.accelo.com
response_type=code
scope=read(companies,contacts),write(staff)
curl -X POST https://planet-express.api.accelo.com/oauth2/v0/authorize \
  -d 'client_id=9749c33f@planet-express.accelo.com'
  -d 'response_type=code'
  -d 'scope=read(companies,contacts),write(staff)'

This is done through the /authorize endpoint. For authorizing installed applications we have the following parameters:

Parameter Type Description
client_id string The applications client ID as listed on the API control panel.
response_type string This must be set to code for this request
scope string The scope of access desired for the application. See the OAuth2.0 URI for possible values.
expires_in unsigned The lifetime in seconds of the access token. e.g, the value "3600" expresses that the token will expire in one hour from the time the token was created. This defaults to 30 days.

A successful request will send the end-user a prompt similar to the following:

alt text

Authorization Response for Installed Applications

If the user returns to the application and enters the pin, this will be the authorization code to be exchanged for a token.

Token Acquisition for Installed Applications

Please note, access and refresh tokens should never be transmitted without encryption. Further note, all token requests require authoriztion using HTTP Basic as outlined previously

Example token request:

POST /oauth2/v0/token HTTP/1.1
Host: planet-express.api.accelo.com
Authorization: Basic {client_credentials}

grant_type=authorization_code
code=750332955
curl -X POST https://planet-express.api.accelo.com/oauth2/v0/token \
  -H 'authorization: Basic {client_credentials}' \
  -d 'grant_type=authorization_code' \
  -d 'code=750332955'

Returning again to the /token endpoint, authenticating using HTTP Basic, for installed applications the request accepts the following parameters.

Parameter Type Description
grant_type string This must be set to authorization_code for this request.
code string The authorization code obtained from the user in the authorization process
redirect_uri string If included, this must be the redirect URI provided when you registered your application.
expires_in unsigned The lifetime in seconds of the access token. e.g, the value "3600" expresses that the token will expire in one hour from the time the token was created. This defaults to 30 days.

For installed applications, as with web applications, a refresh token is included in the response. Also included in the response are:

Revoking a Token

Sample request:

POST /oauth2/v0/revoke HTTP/1.1
HOST: planet-express.api.accelo.com
Authorization Bearer: {access_token}

token={access_token_to_be_revoked}
curl -X POST https://planet-express.api.accelo.com/oauth2/v0/revoke \
    -d 'client_secret=a17c78ao@planet-express.accelo.com' \
    -d 'client_id=Mj.44Rkg' \
    -d 'token={access_token_to_be_revoked}'

POST /oauth2/revoke

Token revocation may be necessary when read/write permissions are no longer required e.g. on log-out, authorization on this request may either be done through Basic authorization as outlined previously, or by including the client_id and client_secret within the query parameters. This request takes the following parameters:

Field Name Type Description
token string The token to be revoked, must have been issued to the client making the request.
client_id string The client id of the application as shown on the deployment. Include this if you are not using HTTP Basic authorization in the header.
client_secret string The client secret of the application as shown on the deployment. Include this if you are not using HTTP Basic authorization in the header.

A successful request will return an "ok" status.

Refreshing a Token

Example token request using refresh token:

POST /oauth2/v0/token HTTP/1.1
Host: planet-express.api.accelo.com
Authorization: Basic {client_credentials}

token_type=refresh_token
refresh_token=VYfb63__vf
curl -X POST https://planet-express.api.accelo.com/oauth2/v0/token \
  -H 'authorization: Basic {client_credentials}' \
  -d 'token_type=refresh_token' \
  -d 'refresh_token=VYfb63__vf'

For installed and web applications if you still have a valid token, you may request a new token using the refresh token that came with it. This request uses the /token endpoint and accepts the following parameters:

Parameters Type Description
grant_type string This must be set to refresh_token for this request.
refresh_token string The refresh token that was sent with your current token.

The response to this request will contain an access token and refresh token. Please note that service applications do not use refresh_tokens, if a new token is wanted you will need to generate a new one.

Token Information

https://{deployment}.api.accelo.com/api/v0/tokeninfo

Example request:

GET /api/v0/tokeninfo HTTP/1.1
HOST: planet-express.api.accelo.com
Authorization: Bearer {access_token}
curl -X get https://planet-express.api.accelo.com/api/v0/tokeninfo \
  -H 'authorization: Bearer {access_token}'

To obtain the information of any access token the /tokeninfo endpoint is used. Note this endpoint is not located in .../oauth2/v0 but rather /api/v0. It takes only a single parameter:

Parameter Type Description
_bearer_token string The token for which you would like information of. Default is the token used to authenticate the request.

The response will contain the following:

Name Type Description
email string Email of the user assigned to the token.
expiry_date unix ts An expiry date time stamp assigned to the token.
firstname string First name of the user assigned to the token.
surname string Surname of the user assigned to the token.
deployment string Deployment prefix assigned to the token.
locale object Locale currency symbol and timezone assigned to the token.
staff_id unsigned int The id of the staff assigned to the token.

Using the Token to Access Resources

Sample accessing a company resource using access token query:

GET http://planet-express.api.accelo.com/api/v0/companies/1?_bearer_token=Ck9ma73_db

Same request using preferred header method:

GET /api/v0/companies/1 HTTP/1.1
Host: planet-express.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer Ck9ma73_db
curl -X get https://planet-express.api.accelo.com/api/v0/companies/1 \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'authorization: Bearer {access_token}'

Once you have access to your token you may use it to access endpoints. This can be done by either including it as a query parameter as _bearer_token, or as a HTTP Authorization: Bearer header. For security reasons the latter is preferred. Note that including both of these will return an error.

Lockout

Example lockout response.

{
  "more_info": "https://api.accelo.com/docs/#status-codes",
  "status": "too_many_failed_logins",
  "message": "User is locked out by their IP due to too many failed
              authentication attempts. Please use the 'Retry-After'
              header for accessing the locked delay in seconds."
}

In order to ensure API usability, a limit exists on the number of times a user can fail to authenticate with the Public API. A user is limited to 100 failed authentication attempts within a 5 minute period. If this limit is exceeded, the user will be 'locked out'. Any attempt to authenticate during this 'lockout' period will restart the 5 minute timer.

Once the lockout period has expired, you should be able to continue to use the API as normal.

Endpoints

Activities

Activities hold communications to and from your Accelo deployment, such as client communication, meetings, and notes. See the support documentation for more information on activities.

Resource URI:
api/v0/activities

The Activity object is complex and contains some special objects:

The Activity Object

Sample activity object:

{
  "subject": "Support Request via Accelo The website has become unresponsive",
  "nonbillable": "0",
  "class": "1",
  "rate_charged": "0.00",
  "time_allocation": "0",
  "against_id": "32",
  "date_created": "1495762476",
  "against_type": "request",
  "date_ended": null,
  "staff": "14",
  "task": "0",
  "activity_priority": "3",
  "owner_id": "14",
  "parent": "activities/0",
  "details": "Request from jack.black@jack-and-co.com",
  "against": "request/32",
  "body": "Your home page is timing out?",
  "visibility": "all",
  "id": "1053",
  "owner": "staff/14",
  "thread": "activities/1053",
  "owner_type": "staff",
  "rate": "0",
  "date_logged": "1495762476",
  "billable": "0",
  "date_modified": "1495762476",
  "date_started": null,
  "confidential": 0,
    "scheduled": 'no'
}

The activities object contains the following fields:

Field Type Description
id unsigned The activity's unique identifier.
subject string String describing the content of the activity.
confidential boolean (0 or 1) The flag indicates whether the activity has been marked as confidential to the current user. Confidential activities are returned but the content of the subject and body is replaced with a confidential placeholder. You can use this flag to determine whether or not the content has been covered up. If 1, then it has been replaced and the subject and body will be something like "Confidential activity sent to: Bob, Alice". Otherwise 0 indicates the body and subject are returned in full. Don't confuse this with the "visibility" attribute.
parent_id unsigned The unique identifier of the parent activity, returns "0" if the activity has no parent.
thread string If the activity is part of the response set to another activity, this will be a string describing the original activity, as outlined below e.g. "activity/346". Otherwise this will be the current activity.
parent string API URI of the parent activity object of the request activity, returns "/activities/0" if the activity has no parent. Example "/activities/347"
thread_id unsigned The unique identifier of the thread activity.
against_type string The type of the object that the activity is against.
against_id unsigned The unique identifier of the object the activity is against.
against string API URI of the object the activity is against.
owner_type string The type of the owner object of the activity.
owner_id unsigned The unique identifier of the owner object of the activity.
owner string API URI of the object representing the owner of the activity.
medium string The activity medium.
body string The main plaintext content of the activity.
preview_body string A preview of the plaintext body. This is the first 250 characters only.
html_body string The main content of the activity as HTML. For example, for plain text activities, newlines will be replaced with line breaks (<br>). For rich text activities, complete HTML will be returned.
visibility string The activity visibility.
details string Additional details assigned to an activity. For meetings and postals this is used to store the location/address. For calls this is used to store the number.
date_created unix ts The date the activity was created.
date_started unix ts The date the activity was started. For meetings this is the scheduled start date of the meeting, for other activities it is the date time was logged, returns null otherwise.
date_ended unix ts For meetings, the scheduled end date of the meeting.
date_logged unix ts Read only takes the value of date_started, if this is not set then it takes the value of date_created.
date_modified unix ts The date the event was last modified.
billable unsigned Amount of billable time logged for the activity, in seconds.
nonbillable unsigned Amount of non-billable time logged for the activity, in seconds.
staff unsigned or object The staff member that has logged time on the event.
class unsigned or object Deprecated, please use activity_class
activity_class unsigned or object The activity's class. The default is "1".
priority unsigned or object Deprecated, please use activity_priority
activity_priority unsigned or object The priority of the activity.
task unsigned or object The task the activity is against. Returns null if there is no task against the activity.
time_allocation unsigned or object The time allocation for the activity.
rate unsigned or object The rate charged for any billable time logged against the activity.
rate_charged unsigned The rate at which billable time was charged, this is part of the rate object.
tag array of objects A list of tags associated with the activity.
scheduled select Either 'yes' or 'no', whether the activity is scheduled.
standing select The standing of the activity, may be one of "unapproved", "approved", "invoiced", "locked", or empty.
invoice_id unsigned The unique identifier of the invoice the activity is attached to, if any.
contract_period_id unsigned The unique identifier of the contract period the activity is attached to, if any.
is_billable bool Either 1 or 0, whether billable time can be logged on the activity.
permissions object An object containing a list of permissions for the current user on the activity.

Activity Medium

Activities are communicative objects, e.g. notes and emails. The type of communication is described by the "medium", Accelo currently supports five types of media for activities:

Name Description
Note Notes are internal messages as well as a way to log time.
Email Emails to contacts or colleagues.
Meeting Allows you to invite contacts or colleagues to a meeting.
Call Useful for recording the notes from a phone call.
Postal Log information about letters or packages you have sent to contacts, such as package tracking numbers.

Activity Visibility

Activities also have a visibility associated with them, which determines how they are viewed by others. The visibility of an activity can be set to one of three values:

Visibility Description
Private Only you can see this Activity. Completely hides all traces of an activity from other users.
Confidential Hides full content of this activity and replaces with the word "Confidential". Other users see that a Confidential Activity has occurred on the date but will see no other details.
All Displays full content of this activity to all users.

The Activity Class

Classes are an additional field for further describing Activities, you may add or remove classes from your deployment through the configuration menu, this process is outlined in the Accelo support documentation. By default your Accelo deployment will have three classes:

Class Description
Client Work For activities related to client projects.
Sales For activities related to sales or account management.
Internal For activities related to improving business processes, or business administration activities.

The class object for activities will contain the following:

Sample JSON of an activity class:

"class": {
  "id": "1",
  "title": "Client Work",
  "parent": "0",
  "status": "active"
}
Field Type Description
id unsigned A unique identifier for the class.
title string A name for the class.
parent unsigned The unique identifier of the parent class, if there is no parent class this will be "0".
status select The status of the class, either "active" or "inactive".

Note: This object does not support the _ALL argument with _fields

The Activity Priority

Sample JSON of an activity priority:

{
  "id": "3",
  "title": "Medium",
  "level": "3"
}

The activity priority describes the urgency of a given activity, it contains the following:

Field Type Description
id unsigned A unique identifier for the priority.
title string A name for the priority.
level integer A number representing the urgency, by default 1 is "extreme", 5 is "none"

Note: This object does not support the _ALL argument with _fields

Activity Threads and Parents

Activity threads and parents:

              |------activities/57
activities/56 |
              |------activities/59------activities/62

Naturally, we expect these communicative objects to build off each other, for example a single email may be responded to by several other emails, which may in turn have their own responses. To keep track of these we use the thread and parent objects. The thread object tracks the original activity in the thread the current activity is in response to, and the parent object tracks the activity that the current activity is in direct response to.

We will describe these with an example. Imagine an email is sent out as activities/56, then this email is responded to by two new emails activities/57 and activity/59, imagine further that the email activities/59 is responded to by another email, activities/62. In this case, each activity will have a thread of activities/56, activities/57 and activities/59 will have a parent of activities/56, and activities/62 will have a parent of activities/59.

The Activity Thread Object

Sample JSON of an activity thread object:

"id": 1041,
"event_text": "created a note",
"activities": [
  {
    "subject": "Time Entry",
    "id": "1041"
  }
],
"total_activities": "1"

Activity threads are described by the thread object, this contains the following:

Field Type Description
id unsigned The unique activity_id of the original activity in the thread.
event_text string A description of the original activity in the thread, for example "created a note" or "sent an email".
activities array An array containing the most recent activity in the thread.
total_activities integer A count of the number of activities in the thread.

Activity Interactions

In the context of activities, an interaction is a recipient or sender of an activity, this will either be a staff, affiliation or contact object. An activity can have several interactions; an email may be sent to several staff members and/or affiliations. The form of interactions, and the way they are handled vary depending on the context, thus we deal with each case individually:

  1. Interactions with a list of activities
  2. List of interactions with a single activity

The Time Allocation Object

When an activity includes logging time the time logged is described by the time allocation object, this contains the following:

Field Type Description
id unsigned A unique identifier for the time allocation.
against string The object the time is logged against, in the form "{object}/{object_id}".
standing string The standing of the logged time.
billable integer The amount of billable time logged, in seconds.
nonbillable integer The amount of nonbillable time logged, in seconds.
charged decimal The rate charged for billable work.
comments string Any comments made against the logged time.
date_locked unix ts The date the activity was locked, that is, when the logged time was approved for invoicing.
date_created unix ts The date the time was logged.

Get Activity

GET /activities/{activity_id}

Sample request:

GET /api/v0/activities/41 HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}

_fields=against,owner
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/activities/41 \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d '_fields=against,owner'

If successful, this request returns an activity identified by its activity_id.

Configuring the Response

this request supports requesting additional fields and linked objects from the activity object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the activity with its default fields and any additional fields requested through _fields.

Sample response, excluding meta:

{
  },
  "response": {
    "subject": "Update on last week's work",
    "id": "41",
    "owner": "staff/22",
    "against": "affiliations/69"
  }
}

List Activities

GET /activities

Sample request:

GET /api/v0/activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}

_fields=body,staff(),medium
_filters=date_created_after(1485495266),order_by_desc(id)
_limit=2
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/activities
  -H 'authorization: Bearer {access_token}' \
  -H 'content_type: application/x-www-form-urlencoded' \
  -d '_fields=body,staff(),medium' \
  -d '_filters=date_created_after(1485495266),order_by_desc(id)' \
  -d '_limit=2'

This request will return a list of activities on the Accelo deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the activity object using the _fields parameter. This request also supports ' breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
parent_id
thread_id
against_type
against_id
owner_id
owner_type
medium
visibility
staff Filter by the staff_id of any staff who have logged time against the activities.
class Deprecated, please use activity_class
activity_class Filter by the class_id of the activities.
priority Deprecated, please use activity_priority
activity_priority Filter by the priority_id of the activities.
task Filter by the task_id of any tasks the activities are against.
time_allocation Filter by the time_allocation_id.
Date Filters

Sample response:

{
  "meta":{
    "status": "ok",
    "message": "Everything executed as expected.",
    "more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok"
  },
"response":[
  {
    "subject:": "Progress with our New Client",
    "id": "1003",
    "body": "",
    "staff": {
      "id": "14",
      "surname": "Hughes",
      "firstname": "Matthew"
    },
    "medium": "note"
  },
  {
    "subject:": "Discussing Our Project",
    "id": "998",
    "body": "",
    "staff": {
      "id": "14",
      "surname": "Hughes",
      "firstname": "Matthew"
    },
    "medium": "email"
  }
]
}

This request supports date filters over the following fields:

Filter Name
date_created
date_started
date_ended
date_logged
date_modified
Order Filters

This request supports order filters over the following fields:

Filter Name
date_started
date_created
date_ended
date_modified
id
billable
nonbillable
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
against_id
thread Range over the thread_id.
owner Range over the owner_id.
staff Range over the staff_id.
priority Deprecated, please use activity_priority
activity_priority Range over the priority_id.
class Range over the class_id.
task Range over the task_id.
Object Filters

This request supports object filters over the following linked object:

Filter Name Description
owner Filter by activities owned by these objects.
against Filter by activities against these objects.

Handling the Response

The response will be a List of activities with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters or filters used.

Handling Interacts

Sample response, here we are looking at the interactions of a single activity.

"response": {
  "affiliations": [
    {
      "email": "matthew--hughes@hotmail.com",
      "id": "98",
      "mobile": null
    }
  ],
  "staff": [
    {
      "id": "14",
      "surname": "Hughes",
      "firstname": "Matthew"
    }
  ],
  "activities": [
    {
      "id": "1015",
      "subject": "A test email",
      "interacts": [
        {
          "type": "to",
          "owner_name": "Hubert Farnsworth",
          "date_actioned": "1493254821",
          "email": "hfarnsworth@plentexpress.com",
          "id": "2052",
          "owner_type": "affiliation",
          "owner_id": "98"
        },
        {
          "owner_id": "14",
          "id": "2053",
          "email": "matthewhughes934@gmail.com",
          "owner_type": "staff",
          "date_actioned": "1493254821",
          "owner_name": "Matthew Hughes",
          "type": "from"
        }
      ]
    }
  ]
},

We can investigate the interactions associated with a list of activities via the special field interacts. Given a list of activities, we may investigate the associated interactions by including _fields=interacts. Note: if this field is requested the structure of the response is altered. The response will contain three arrays, one labeled "activities", one labeled "staff", and one labeled "affiliations". The objects in the "activities" array will be activity objects with the addition of an array labeled "interacts". Each interact here contains the following:

Field Type Description
id unsigned int Unique identifier for the interact.
date_actioned unix ts The date the interact actioned the activity (if actioned)
type string The type of the interaction, one of: "creator", "from" "to", "cc", "bcc", "attendee", "did_not_attend"
owner_id unsigned int The owner's unique id. This will correspond to the id of either a staff or affiliation object.
owner_type string The type of owner, either "staff" or "affiliation".
owner_name string The firstname and surname of the owner.
email string The e-mail associated with the owner.

That is, each activity has an interaction where each interaction identifies an owner (either a staff or affiliation) and recipient(s), if available. The arrays "staff" and "affiliations" contain these owners or recipients, so we can readily identify who interacted with a given activity, and how.

Count Activities

Sample request, here we request the response as xml

GET /api/v0/activities/count.xml HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://al-interns.api.accelo.com/api/v0/activities/count.xml \
  -H 'authorization: Bearer {access_token}'

GET /activities/count

Sample response:

<data>
    <response count="1013" />
</data>

This request will return a count of activities in a list defined by any available searches or filters. With no searches or filters this will be a count of all activities on the deployment. This request returns a single field

Field Type Description
count unsigned int A count of the activities listed.

List Interactions

GET /api/v0/activities/{activity_id}/interacts HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/activities/{activity_id}/interacts \
  -H 'authorization: Bearer {access_token}'

GET /activities/{activity_id}/interacts

This request returns an array of activity interactions for the activity identified.

Sample response:

"response": {
  "staff": [
    {
      "interact": {
        "date_actioned": "1493254821",
        "type": "from",
        "id": "2053"
      },
      "firstname": "Matthew",
      "surname": "Hughes",
      "id": "14"
    }
  ],
  "contacts": [
    {
      "surname": "Farnsworth",
      "id": "94",
      "email": "hfarnsworth@planetexpress.com",
      "mobile": null,
      "interact": {
        "date_actioned": "1493254821",
        "type": "to",
        "id": "2052"
      },
      "firstname": "Hubert"
    }
  ]
}

Configuring the Response

This request supports requesting additional fields and linked objects from the staff and contact objects using the _fields parameter.

Handling the Response

The response will contain two arrays:

Name Description
staff Array of staff objects that have an interaction against the activity.
contacts Array of contact objects that have an interaction against the activity.

The staff and contact objects returned will contain their default fields, plus any fields added via the _fields parameter, as well as an interact object containing:

Field Type Description
id unsigned The unique identifier of the interaction.
date_actioned unix ts The date the interact actioned the activity (if actioned)
type string The type of the interaction, one of: "creator", "from" "to", "cc", "bcc", "attendee", "did_not_attend"

Note this request returns a contact object, rather than affiliation object as in the case of GET /activities?_fields=interacts. These objects are closely linked, please see the section for either object to view a description of this relationship.

Count Interactions

Sample request:

GET /api/v0/activities/{activity_id}/interacts/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
curl -X -get \
  https://{deployment}.api.accelo.com/api/v0/activities/{activity_id}/interacts/count \
  -H 'authorization: Bearer {access_token}'

GET /activities/{activity_id}/interacts/count

Sample response

"response": {
  "count": "2"
}

This request will return a count of activity threads in a list defined by any available searches or filters. With no searches or filters this will be a count of all interactions against the activity. This request returns a single field:

Field Type Description
count unsigned int A count of the activity interactions listed against the activity identified.

Get Time Allocated

Sample Request:

GET /activities/allocations

GET /api/v0/activities/allocations HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/activities/allocations \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

This request returns information on timed logged and the value charged against a collection of activities.

Sample response:

"response": {
  "nonbillable": "3600",
  "billable": "1660",
  "charged": "21.26"
}

Configuring the Response

An aggregation that returns the sum of time allocation information from a set of activities. To filter the activities consumed, you may use the same filters supported by GET /activities.

Handling the Response

The response will contain the following fields describing the allocations for the activities:

Field Type Description
billable unsigned Total billable time, in seconds, for all activities found.
unbillable unsigned Total unbillable time, in seconds, for all activities found.
charged double The total charged for all billable hours.

Update an Activity

PUT /activities/{activity_id}

Sample request, we wish to update and return the priority field:

PUT /api/v0/activities/{activity_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}

priority=4
_fields=activity_priority()
curl -X put \
  https://{deployment}.api.accelo.com/api/v0/activities/1002 \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'priority_id=3' \
  -d '_fields=activity_priority()'

This request will update, and return, the identified activity.

Configuring the Activity

The following fields from the activity object may be updated through this request:

Field Conditions
subject Updating this is only possible if the user executing the request is the owner.
body Updating this is only possible if the user executing the request is the owner.
visibility Updating this is only possible if the user executing has an interaction with the activity.
details Additional details assigned to an activity.
priority_id The unique identifier of the priority to be linked to the activity.
class_id* The unique identifier of the class to be linked to the activity.
message_id A custom message id to be given to the activity.
date_started Seconds since UTC
date_ended Seconds since UTC
date_due Seconds since UTC
nonbillable* The amount of nonbillable time, in seconds. Requires the user has the can_edit_time permission under the permission object.
billable* The amount of billable time, in seconds. Requires the user has the can_edit_billable permission under the permission object, and that the activity is billable (see the is_billable flag on the activity).

* when the medium is 'email' only these fields may be updated

Sample response:

"response": {
  "subject": "A note on my schedule",
  "id": "1002",
  "activity_priority": {
    "title": "Low",
    "id": "4"
  }
}

Configuring the response

This request supports requesting additional fields and linked objects from the activity object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, updated activity with its default fields and any additional fields requested through _fields.

Create an Activity

POST /activities

Sample request, here we send the data as json:

POST /api/v0/activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "against_id": "14"
  "against_type": "staff"
  "subject": "Conference Schedule Update"
  "priority_id": "1"
}

curl -X post \
  https://{deployment}.api.accelo.com/api/v0/activities \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/json' \
  -d '{
    "against_id": "14"
    "against_type": "staff"
    "subject": "Conference Schedule Update"
    "priority_id": "1"
  }'

This request will create, and return, a new activity on the deployment.

Configuring the Activity

Values for the following fields may be set through this request.

Field Notes
subject Activity's subject that will appear in the title of the activity.
against_id The id of the against_table object, the activity is linked against.
against_type The object the activity is linked against. This can be: affiliation, contract, contract_period, invoice, issue, job, prospect, request, task or staff.
body The content of the activity.
medium Type of activity to create. This can be: 'note', 'meeting', 'email', or 'call'. This will default to note.
owner_type The activity can be owned by a staff member or an affiliation. The owner defaults to the current user
owner_id Owner's id. i.e, the staff or affiliation id of owner_table.
visibility Defaults to private, unless the request is executed as the Accelo Support user.
details Additional details assigned to an activity. For meetings and postals this is used to store the location/address. For calls this is used to store the number.
priority_id The unique identifier of the priority to be linked to the new activity.
class_id The unique identifier of the class to be linked to the new activity.
thread_id The unique identifier of the thread to be linked to the new activity.
task_id The unique identifier of the task to be linked to the new activity.
parent_id The unique identifier of the parent activity of the new activity.
message_id A custom message id to be given to the new activity.
date_started Seconds since UTC
date_ended Seconds since UTC
date_due Seconds since UTC
file A file you would like to add as an attachment to the new activity (Requires "multi-part/form-data")
send_invites Only applicable if medium is set to "meeting". Either "true" or "false", whether invitations are enabled or not. Defaults to "false".
nonbillable Requires the owner is a staff member.
billable As above, but also requires the activity is against an issue, job, milestone, contract, or period
block_send 1 or 0, whether to block sending the activity. Defaults to 0, so the activity will be sent if it is eligible.

Including "to", "cc" and "bcc" Interactions

Sample json request segment to add interactions. In this case we would create an activity to staff with id 10, cc'ing affiliations 13 and 14 and bcc'ing the email recipient "bcc-recipient@affinitylive.com".

{
  "..."
  "to": {
    "staff": [10]
  },
  "cc": {
    "affiliation": [13,14]
  },
  "bcc": {
    "emails": ["bcc-recipient@affinitylive.com", "fred@freddy.com"]
  }
}

We can create interactions with our activity by sending our request as JSON (see the introduction for information on sending JSON requests) and including the following objects:

Object Name Description
to Anyone to whom the activity is directed.
cc Anyone to whom the activity should be cc'd.
bcc Anyone to whom the activity should be bcc'd

Each object accepts a staff or affiliation (identified by their id) or a general email. (Note: When using a general email, no interact object will be created.)

Logging time

In order to log time when creating an activity visibility must be set to all. The owner_id of the activty and who the time will be logged against will default to the current user. You can changed this by setting the owner_type and owner_id.

Logging time against a task

To log an activity against a task, you should pass in the task's against_id and against_type as the new activity's against_id and against_type. Essentially you are creating an activity against the object the task is against.

Configuring the Response

This request supports requesting additional fields and linked objects from the activity object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the new activity with its default fields and any additional fields requested through _fields

Create a Report

POST /activities/reports

Sample request

POST /api/v0/activities/reports HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/json
Authorization: Bearer {access_token}

{
  "activity_id": "14"
  "body": "The details of the report"
  "nonbillable": "3600"
}
curl -X post \
  https://{deployment}.api.accelo.com/api/v0/activities/reports \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/json' \
  -d '{
      "activity_id": "14"
      "body": "The details of the report"
      "nonbillable": "3600"
  }'

This request will create and return a new report against a scheduled activity

Configuring the Report

Values for the following fields may be set through this request.

Fields Notes
activity_id The activity the report will be created against. This activity must be scheduled.
body The content of the report.
billable Amount of billable time logged for the activity, in seconds.
nonbillable Amount of non-billable time logged for the activity, in seconds.
notify_staff_attendees Flag of '1' or '0', to indicate notifying involved staff members.

Logging time

The user executing this request will be used as the owner of the report. Hence, any billable or nonbillable time set with this request will be logged for this user.

Configuring the Response

This request supports requesting additional fields and linked objects from the activity object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the new report with the subject, activity_id, and the confidential flag. Any additional fields available to the activity object may be requested through _fields.

Delete Activity

Sample Request:

DELETE /api/v0/activities/{activity_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
curl -X delete \
  https://{deployment}.api.accelo.com/api/v0/activities/{activity_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /activities/{activity_id}

This request will delete the activity identified by its activity_id. This request takes no parameters and returns no resources.

List Activity Threads

Sample Request:

GET /api/v0/activities/threads HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
curl -X get \
  http://{deployment}.api.accelo.com/api/v0/activities/threads \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

GET /activities/threads

This request returns a list of activity threads.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the activity object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Sample response of a single thread:

{
  "activities": [
    {
      "subject": "Redesign update",
      "id": "280"
    }
  ],
  "event_text": "replied by email",
  "id": 278,
  "total_activities": "3"
}
Filter Name Notes
against_type Return only threads whose original activity was against an object of this type. If this is provided, against_id must also be provided.
against_id Return only threads whose original activity was against an object with this id. If this is provided, against_type must also be provided.
staff_involved Filter by the staff_id the staff member(s) who have interacted with activities within the thread.
scope Takes either "internal" or "external" as arguments, whether the thread is external, such as emails from clients, or internal, such as notes.
Date Filters

This request supports date filters over the following fields:

Filter Name Notes
date_logged_after Filter by threads that have activities with date_logged after this time.
date_logged_before Filter by threads that have activities with date_logged before this time.

Handling the Response

The response will be a list of activity threads, displayed according to any pagination parameters or searches used. The activity listed under the activities array of the thread will be displayed with its default fields and any additional fields requested through _fields.

Count Activity Threads

Sample Request:

GET /api/v0/activities/threads/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  http://{deployment}.api.accelo.com/api/v0/activities/threads/count \
  -H 'authorization: Bearer {access_token}'

GET /activities/threads/count

This request will return a count of activity threads in a list defined by any available searches or filters. With no searches or filters this will be a count of all activity threads. This request returns a single field:

Field Type Description
count unsigned A count of the number of activity threads listed.

List Activities in a Thread

Sample request:

GET /api/v0/activities/threads/280 HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}

_fields=thread,parent
curl -X get \
  http://{deployment}.api.accelo.com/api/v0/activities/threads/280 \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d '_fields=thread,parent'

GET /activities/threads/{thread_id}

This request returns a list of activities in a thread, identified by its thread_id. This request may be configured and handled in the same way as GET /activities.

Sample response:

"thread": {
  "event_text": "replied by email",
  "total_activities": "3",
  "activities": [
    {
      "thread": "activities/278",
      "parent": "activities/279",
      "subject": "Redesign update",
      "id": "280"
    },
    {
      "id": "279",
      "parent": "activities/278",
      "subject": "Redesign update",
      "thread": "activities/278"
    },
    {
      "id": "278",
      "thread": "activities/278",
      "subject": "Redesign update",
      "parent": "activities/0"
    }
  ],
  "id": "278"
}

This request returns a list of activities in a thread, identified by its thread_id. This request may be configured and handled in the same way as GET /activities.

List Activity Classes

Sample Request:

GET /api/v0/activities/classes HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
curl -X get \
  http://{deployment}.api.accelo.com/api/v0/activities/classes \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

GET /activities/classes

This request returns a list of activity classes.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the activity class using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Sample response of a single class:

{
  "parent": "3",
  "id": "5",
  "standing": "active",
  "title": "Internal"
}
Filter Name Notes
id Return only the class with this id.
title Filter by the title of the class.
parent Return only classes whose parent class is of this id.
standing Takes either "active" or "inactive" as arguments.

Handling the Response

The response will be a list of activity classes, displayed according to any pagination parameters or searches used. The activity classes listed will be displayed with its default fields and any additional fields requested through _fields.

Get Activity Class

Sample Request:

GET /api/v0/activities/classes/{class_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  http://{deployment}.api.accelo.com/api/v0/activities/classes/{class_id} \
  -H 'authorization: Bearer {access_token}'

GET /activities/classes/{class_id}

Returns a single activity class for the given class id.

Count Activity Classes

Sample Request:

GET /api/v0/activities/classes/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  http://{deployment}.api.accelo.com/api/v0/activities/classes/count \
  -H 'authorization: Bearer {access_token}'

GET /activities/classes/count

This request will return a count of activity classes in a list defined by any available searches or filters. With no searches or filters this will be a count of all activity classes. This request returns a single field:

Field Type Description
count unsigned A count of the number of activity classes listed.

Addresses

Resource URI:
/api/v0/adddresses

The Addresses endpoint stores the address information of companies and contacts on the Accelo deployment.

The Address Object

Sample address object:

{
    "postal": "yes",
    "short": "San Francisco, 94107, CA, United States",
    "zipcode": "94107",
    "title": "US Headquarters",
    "full": "880 Harrison St., San Francisco, 94107, CA, United States",
    "id": "17",
    "city": "San Francisco",
    "state": "15",
    "country": "2",
    "physical": "yes",
    "street1": "880 Harrison St.",
    "street2": "Suite 302"
}

The address object contains the following:

Name Type Description
id unsigned The address' unique identifier.
full string The full address, including street, city, state and country. For example "880 Harrison St., San Francisco, 94107, CA, United States".
title string A custom name given to the address. For example "US Headquarters".
street1 string The first line of the street address. For example "880 Harrison St."
street2 string The second line of the street address. For example "Suite 302".
city string The city of the address. For example "San Francisco".
zipcode string The zipcode of the address. For example 94107.
state unsigned or object The state the address is located in.
country unsigned or object The country the address is located.
postal string This will be either "yes" or "no", if this address is a postal address or not.
physical string This will be either "yes" or "no", if this address is a physical address of not.

The Country Object

JSON country object for the USA:

{
  "id": "2",
  "title": "United States",
  "prefix": "1",
  "suffix": "us",
  "postcode_name": "Zipcode",
  "state_name": "State",
  "state_required": "1",
  "postcode_required": "1"
}

JSON country object for Australia:

{  
  "title": "Australia",
  "postcode_required": "1",
  "suffix": "au",
  "state_required": "1",
  "state_name": "State",
  "prefix": "61",
  "postcode_name": "Postcode",
  "id": "1"
}

This object contains the details of a country. It is made up of the following fields:

Field Type Description
id unsigned The country's unique identifier.
title string The full name of the country.
prefix string The country's international calling prefix.
suffix string A short abbreviation for the country.
postcode_name string A string representing how the things we Australians call "postcodes" are referred to in the country.
state_name string A string representing how the things us Australians call "states" are referred to in the country.
state_required boolean Whether a state needs to be specified for addresses in this country.
postcode_required boolean Whether a postcode needs to be specified for addresses in this country.

The State Object

JSON object for NSW, Australia:

{
  "id": "1",
  "title": "New South Wales",
  "abbreviation": "NSW",
  "country_id": "1",
  "ordering": "0",
  "timezone": "Australia/Sydney"
}

JSON object for California, USA

{
  "title": "California",
  "timezone": "America/Los_Angeles",
  "country_id": "2",
  "ordering": "5",
  "abbreviation": "CA",
  "id": "15"
}

This object contains the details of a state within a given country. It is made up of the following fields:

Field Type Description
id unsigned The state's unique identifier within its country. For example for NSW "1", for California "15".
title string The full name of the state. For example "New South Wales", "California".
abbreviation string A short abbreviation of the state's name. For example "NSW", "CA".
country_id unsinged The unique identifier of the country to which the state belongs. For example "1", "2"
ordering unsigned The state's order as displayed on the Accelo deployment.
timezone string The name of the timezeone the state obeys. For example "Australia/Sydney", "Europe/London".

Postal and Physical Addresses

An address in Accelo may be physical or postal or both. For example, a company may have an office that is both a physical and postal address, but also have a post office box that is only a postal address.

The Address Object

Example JSON of full address object:

{
  "physical": "yes",
  "street1": "880 Harrison St.",
  "country": "2",
  "full": "880 Harrison St., San Francisco, 94107, CA, United States",
  "city": "San Francisco",
  "postal": "yes",
  "short": "San Francisco, 94107, CA, United States",
  "state": "15",
  "street2": "Suite 302",
  "title": "US Headquarters",
  "zipcode": "94107",
  "id": "17"
}

Get Address

Sample Request:

GET api/v0/addresses/1 HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

_fields=country(),state
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/addresses/{address_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d '_fields=country(),state'

GET /addresses/{address_id}

Sample response:

 "response" :
    {
       "country" : {
          "title" : "Australia",
          "id" : "1"
       },
       "id" : "1",
       "full" : "6/221 Crown St, Wollongong, 2500, NSW, Australia",
       "state" : "1"
    },
 "meta" : {
    "status" : "ok",
    "message" : "Everything executed as expected."
 }

This request will return the address identified by its address_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the address object through the _fields parameter.

Handling the Response

The response will be a single address object containing the default fields and any other fields included via the _fields parameter.

List Addresses

Sample request:

GET /api/v0/addresses HTTP/1.1
Host: {deployment}.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/addresses \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

GET /addresses

This request returns a list of addresses on the Accelo deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
against_type
against_id
physical
postal
country_id
state_id
zipcode Filter over the postcode field.
Range Filters

This request supports range filters over the following fields:

Filter Name
id
against_id
Order Filters

This request supports order filters over the following fields:

Filter Name
id
title
suffix
prefix

Handling the Response

The response will be a list of addresses with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters or filters used.

Count Addresses

Sample request:

GET /api/v0/addresses/count HTTP/1.1
Host: {deployment}.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/addresses/count
  -H 'authorization: Bearer {access_token}'

GET /addresses/count

This request will return a count of addresses in a list defined by any available searches or filters. With no searches or filters this will be a count of all address on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the addresses listed.

List Addresses Against an Object

Sample request:

GET /api/v0/{object}/{object_id}/addresses HTTP/1.1
Host: {deployment}.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get
  https://{deployment}.api.accelo.com/api/v0/{object}/{object_id}/addresses \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

GET /{object}/{object_id}/addresses

This request returns all addresses against the object of type {object} and unique identifier {object_id}. This request supports the following object types:

  1. Company
  2. Contacts

For example, the request GET /companies/39/addresses would return all addresses registered with the company with id 39.

Configuring the Response

This request may be configured as GET /addresses

Handling the Response

The response will be a list of addresses against the identified object with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters or filters used.

Update an Address

PUT /addresses/{address_id}

PUT /api/v0/addresses/{address_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

country_id=Australia
state=NSW
street1=221 Crown St
city=Wollongong
postcode=2500
physical=yes
curl -X put
  https://{deployment}.api.accelo.com/api/v0/addresses/{address_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'
  -d 'country_id=Australia'
  -d 'state=NSW'
  -d 'street1=221 Crown St'
  -d 'city=Wollongong'
  -d 'postcode=2500'
  -d 'physical=yes'

This request updates and returns an address on the Accelo deployment specified by its unique {address_id}.

Configuring the Address

The following fields may be updated through this request:

Field Notes
state The name of the state of province.
state_id The unique identifier of the state of province. This must point to a valid state, if you do not know the state_id please use the state parameter.
country The name of the country.
country_id The unique identifier of the country. This must point to a valid country, if you do not know the country_id please use the country parameter.
title
street1
street2
city
zipcode/postcode
postal
physical

Configuring the Response

This request supports requesting additional fields and linked objects from the address object using the _fields parameter.

Handling the Response

The response will be the single updated address object with its default fields and any fields added through the _fields parameter.

Create an Address

Sample request:

POST /api/v0/addresses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X post
  https://{deployment}.api.accelo.com/api/v0/addresses \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

POST /addresses

This request will create a new address and return it.

Configuring the Address

The address may be configured in the same manner as PUT /addresses/{address_id}, with the addition of the following fields:

Field Type Description
against_type string The type of object the address is against, must be a company or contact.
against_id unsigned The unique identifier of the object the address is against.
overwrite boolean Whether to overwrite the address if the address to be created already exists.

Configuring the Response

This request supports requesting additional fields and linked objects from the address object using the _fields parameter.

Handling the Response

The response will be the single updated address object with its default fields and any fields added through the _fields parameter.

Create an Address Against an Object

Sample request:

POST /api/v0/{object}/{object_id}/addresses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X post
  https://{deployment}.api.accelo.com/api/v0/{object}/{object_id}/addresses \
  -H 'authorization: Bearer {access_token}' \
  -H 'content_type: application/x-www-form-urlencoded'

POST /{object}/{object_id}/addresses

This request performs the same action as POST /addresses, this request however does not require the fields against_type and against_id.

Affiliations

Resources URI:
/api/v0/affiliations

Affiliations map the connections between contacts and companies; an affiliation contains the information on a single contact's link to a company.

They are necessary because one contact may be linked to a company in more than one way, and also a contact may be linked to two or more companies. An affiliation contains the contact object, the company object, as well as contact details for the contact in that particular role.

For example we may have a contact who works as an engineer for one company (imaginatively, call it company A), and an advisor for another company (company B). Then there will be two affiliation objects, both with the same contact object, however, one will have the company object of Company A, and the other of Company B. Furthermore, the contact information (mobile, email etc.) for each affiliation may be different, one will hold the contact information for an engineer working at Company A, the other for an advisor working at Company B.

The Affiliation Object

Sample affiliation JSON object:

{  
  "staff_bookmarked": "0",
  "company": "40",
  "physical_address": "33",
  "position": "CEO",
  "date_modified": "1489507383",
  "postal_address": "33",
  "standing": "active",
  "date_last_interacted": "1489453228",
  "mobile": "(682)401-6327",
  "fax": "",
  "email": "joe@example.com",
  "contact": "95",
  "phone": "12345678",
  "affiliation_status": "0",
  "id": "99",
  "portal_access": "1",
  "communication": "1",
  "invoice_method": "email"
}

The Affiliation object contains the following:

Name Type Description
id unsigned The unique identifier for the affiliation.
mobile string The mobile number of the contact in the role of this affiliation.
email string The email address of the contact in the role of this affiliation.
fax string The fax number of the contact in the role of this affiliation.
position string The contact's position in the company. For example "CEO", "Software Engineer", "Advisor".
phone string The phone number of the contact in the role of this affiliation.
postal_address unsigned or object The postal address of the contact in the role of this affiliation.
physical_address unsigned or object The physical address of the contact in the role of this affiliation.
company unsigned or object The company that the contact is affiliated with.
contact unsigned or object The contact the affiliation is against.
affiliation_status unsigned The contact's status in the role of this affiliation.
standing string The standing of the contact's status. See the status object.
date_modified unix ts The latest date that this affiliation was modified.
date_last_interacted unix ts The latest date that there was interaction with this affiliation.
staff_bookmarked boolean Whether the current user has bookmarked the affiliation.
portal_access boolean Whether the affiliation has been granted access to the Client Portal.
communication boolean Whether or not communications, such as updates, newsletters etc. are sent to this affiliation.
invoice_method string The method the affiliation wishes to receive an invoice.

Get Affiliation

Sample request:

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/affiliations/{affiliation_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'
GET /api/v0/affiliations/{affiliation_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

GET /affiliations/{affiliation_id}

This request returns an affiliation specified by their unique id.

Configuring the Response

This request supports requesting additional fields and linked objects from the affiliation object using the _fields parameter.

Handling the Response

If successful, the response will be a single affiliation object containing the default fields and any additional fields requested by _fields.

List Affiliations

Sample request:

GET /api/v0/affiliations HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

_fields=company(),position
_filters=date_modified_after(1494596024)
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/affiliations \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d '_fields=company(),position' \
  -d '_filters=date_modified_after(1494596024)'

GET /affiliations

This request returns a list of affiliation objects on the deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
email
standing
status Filter by the status_id of the affiliations.
postal_address Filter by the address_id of the postal addresses of the affiliations.
physical_address Filter by the address_id of the physical addresses of the affiliations.
company Filter by the company_id of the affiliations.
contact Filter by the contact_id of the affiliations.
contact_number Filter over phone, fax, and mobile.
invoice_method
portal_access
communication
Date Filters

This request supports date filters over the following fields:

Filter Name Notes
date_created The date that the affiliated contact was created.
date_last_interacted The date that the affiliation was last interacted with.
date_modified The date that the affiliation was last modified.
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
status Order by the status_id of the affiliations.
standing
date_modified
date_created
date_last_interacted
fullname Order by the full name of the affiliation, that is "firstname surname".
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
country Range over the country_id of the affiliations.
physical_address Range over the address_id of the physical address of the affiliations.
postal_address Range over the address_id of the postal address of the affiliations.
contact Range over the contact_id of the affiliations.
status Range over the status_id of the affiliations.

Sample response:

"response": [
  {
    "id": "98",
    "company": {
      "name": "Planet Express",
      "id": "39"
    },
    "position": "CEO",
    "mobile": "",
    "email": "hfanrsworth@planetexpress.com"
  },
  {"..."}
]
Searching

This request supports the use of the _search parameter to search over the following fields:

Field Name Notes
firstname
surname
fax
phone
mobile
email

Handling the Response

The response will be a list of affiliations with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters or searches used.

Count Affiliations

Sample request:

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/affiliations/count \
  -H 'authorization: Bearer {access_token}'
GET /api/v0/affiliations/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

GET /affiliations/count

This request will return a count of affiliations in a list defined by any available searches or filters. With no searches or filters this will be a count of all affiliations on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the affiliations listed.

Get an Affiliation's Status

Sample request:

GET /api/v0/affiliations/{affiliation_id}/status HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/affiliations/{affiliation_id}/status \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

GET /affiliations/{affiliation_id}/status

This request returns the status of an affiliation specified by its affiliation_id.

Sample response:

"response": {
  "id": "1",
  "title": "Active"
}

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a status object for the specified affiliation with its default fields and any additional fields requested through _fields.

Get Affiliation Status

Sample Request:

GET /api/v0/affiliations/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/affiliations/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}' \

GET /affiliations/statuses/{status_id}

This request returns the affiliation status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be an affiliation status object for the specified status with its default fields and any additional fields requested through _fields.

List Affiliation Statuses

Sample Request:

GET /api/v0/affiliations/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/affiliations/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}' \

GET /affiliations/statuses

This request returns a list of affiliation statuses on the deployment.

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the affiliation status object through the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Count Affiliation Statuses

Sample Request:

GET /api/v0/affiliations/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/affiliations/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /affiliations/statuses/count

This request will return a count of affiliation statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all affiliation statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed affiliation statuses.

Update an Affiliation

PUT /api/v0/affiliations/{affiliation_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_fields=physical_address
physical_address_id=17
postal_address_id=17
curl -X put \
  https://{deployment}.api.accelo.com/api/v0/affiliations/{affiliation_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d '_fields=physical_address' \
  -d 'physical_address_id=17' \
  -d 'postal_address_id=17'

PUT /affiliations/{affiliation_id}

This request will update and return an affiliation identified by its affiliation_id.

Configuring the Affiliation.

The following fields may be updated via this request.

Field Name Notes
country_id Must point to a valid country.
physical_address_id Must point to a valid address.
postal_address_id Must point to a valid address.
phone
fax
mobile
email
position
status_id Must point to a valid status.
standing
communication Must be "yes" or "no", whether or not communications, such as updates, newsletters etc. are sent to this affiliation.
invoice_method e.g. "email", "fax" or "postal", the method by which invoices should be sent.

Sample response:

"response":{
  "id": "22",
  "email": "joe@example.com",
  "mobile": "",
  "physical_address": {
    "id": "17",
    "full": "880 Harrison St., San Francisco, 94107, CA, United States"
  }  
}

Configuring the Response

This request supports requesting additional fields and linked objects from the affiliation object using the _fields parameter.

Handling the Response

The response will be the single updated affiliation object, with its default fields and any additional fields requested through _fields

Create an Affiliation

POST /api/v0/affiliations/ HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X post \
  https://{deployment}.api.accelo.com/api/v0/affiliations \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \

POST /affiliations

This request will create a new affiliation between a company and contact (to be specified in the request), and return it.

Configuring the Affiliation

This request supports setting the following fields:

Field Name Notes
company_id Must point to a valid company. This is the company the new affiliation will point to.
contact_id Must point to a valid contact. This is the contact the new affiliation will point to.
country_id Must point to a valid country.
physical_address_id Must point to a valid address.
postal_address_id Must point to a valid address.
phone
fax
mobile
email
position
status_id Must point to a valid status.
standing
communication Must be "yes" or "no", whether or not communications, such as updates, newsletters etc. are sent to this affiliation, default "no".
invoice_method e.g. "email", "fax" or "postal", the method by which invoices should be sent.

Configuring the Response

This request supports requesting additional fields and linked objects from the affiliation object using the _fields parameter.

Handling the Response

The response will be the single, new, affiliation object, with its default fields and any additional fields requested through _fields

Delete an Affiliation

DELETE /api/v0/affiliations/{affiliation_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X delete \
  https://{deployment}.api.accelo.com/api/v0/affiliations/{affiliation_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /affiliations/{affiliation_id}

This request will delete the affiliation identified by its affiliation_id. This request takes no parameters and return no resources.

List an Affiliation's Profile Field Values

See the profiles section for a sample request

GET /affiliations/{affiliation_id}/profiles/values

This request returns a list of profile field values of an affiliation, specified by its affiliation_id. This is the request GET/{object}/{object_id}/profiles/values, where the object is "affiliations" whose id is {affiliation_id}.

List Affiliation Profile Field Values

See the profiles section for a sample request

GET /affiliations/profiles/values

This request returns a list of all profile field values on affiliations. This is the request GET /{object}/profiles/values, where the object is "affiliations".

List Affiliation Profile Fields

See the profiles section for a sample request

GET /affiliations/profiles/fields

This request returns a list of profile fields available for affiliations. This is the request GET /{object}/profiles/fields where the object is "affiliations".

Update a Profile Field Value on an Affiliation

See the profiles section for a sample request

PUT /affiliations/{affiliation_id}/profiles/values/{profile_value_id}

This request updates and returns a profile field value, specified by its profile_value_id of a particular affiliation, identified by its affiliation_id. This is the request PUT/{object}/{object_id}/profiles/values/{profile_value_id} where the object is "affiliations", and whose id is {affiliation_id}.

Set a Profile Field Value on an Affiliation

See the profiles section for a sample request

POST /affiliations/{affiliation_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for an affiliation, specified by its affiliation_id. This is the request POST /{object}/{object_id}/profiles/fields/{profile_field_id} where is object is "affiliations" and whose id is {affiliation_id}

List Available Progressions on an Affiliation

See the progressions section for a sample request

GET /affiliations/{affiliation_id}/progressions

This request returns a list of available progressions for an affiliation identified by its affiliation_id. This is the request GET /{object}/{object_id}/progressions where the object is "affiliations" whose id is {affiliation_id}

Auto Run a Progression on an Affiliation

See the progressions section for a sample request

[PUT | POST] /affiliations/{affiliation_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress the status of an affiliation, specified by its affiliation_id. This is the request [PUT|POST]/{object}/{object_id}/progressions/{progression_id/auto} where the object is "affiliations" whose id is {affiliation_id}.

Assets

Endpoint URI:
/api/v0/assets

Assets are flexible objects within Accelo, they can represent almost any asset or object you want. For example, you may wish to store information on the computers owned by your company, or the prices of advertising media offered by external companies. For more information see the support documentation.

The Asset Object

The asset object contains the following:

Sample JSON asset:

{
  "address": "14",
  "against_id": "39",
  "asset_type_id": "2",
  "manager_id": "14",
  "id": "2",
  "affiliation": "98",
  "asset_type": "2",
  "title": "Latest Laptop",
  "date_created": "1492651877",
  "manager": "14",
  "affiliation_id": "98",
  "standing": "inactive",
  "against_type": "company",
  "address_id": "14"
}
Field Type Description
id unsigned The unique identifier for the asset.
title string The name given to the asset.
latest_asset_link object The most recent asset link made on the asset.
standing string The standing of the asset, see the status object for more information.
date_created unix ts The date the asset was created.
against_type string A string representing the object the endpoint is against.
against_id unsigned The unique identifier of the object the asset is created against.
asset_type unsigned or object The type of the asset. Asset types can be created and edited from your Accelo deployment, see the assets module page for more information.
asset_type_id unsigned The unique identifier given to this asset type.
affiliation unsigned or object The affiliation associated with the asset (if any).
affiliation_id unsigned The unique identifier of the affiliation associated with the asset.
manager unsigned or object The staff assigned to manage the asset (if any).
manager_id unsigned The unique identifier of the staff assigned to manage the asset.
address unsigned or object The physical address associated with this asset (if any).
address_id unsigned The unique identifier of the physical address assigned to the asset.

Sample JSON asset link:

{
  "linked_object_type": "job",
  "asset_link_id": 1,
  "linked_object_title": "#2215 Client web upgrade",
  "asset_id": 2,
  "linked_object_id": 2215,
  "description": "Laptop will be used on this remote project!",
  "linked_object_breadcrumbs": [
      {
          "title": "MonnDesigns",
          "id": "88213",
          "table": "company"
      }
  ]
}

An asset may be linked to an issue, job, prospect, or contract. If an asset is linked to an object, the link is described by the asset_link object. This contains the following:

Field Type Description
asset_id unsigned The unique identifier for the asset linked.
linked_object_id unsigned The unique identifier of the object the asset is linked to.
linked_object_title string The name of the object the asset is linked to.
linked_object_type string The type of object the asset is linked to.
asset_link_id unsigned the unique identifier of the asset link.
linked_object_breadcrumbs array An array of breadcrumbs associated with the linked object.
description string (optional) A description of the asset's link to the object.
start_date unix ts (optional) The date the asset link was started.
end_date unix ts (optional) The date the asset link was ended.

If any of the fields labeled optional above are empty, they will not be displayed.

The Asset Type

Sample JSON asset type:

{
  "ordering": "0",
  "has_affiliation": "1",
  "has_manager": "1",
  "title": "Server",
  "has_address": "1",
  "id": "2",
  "standing": "active",
  "object_link_fields": {}
}
Field Type Description
id unsigned A unique identifier for the asset type.
title string The title of the asset type.
object_link_fields hash A hash of asset object link fields.
standing string The standing of the asset type.
has_manager binary Whether the asset type has a manger assigned to it.
has_affiliation binary Whether the asset type has an affiliation assigned to it.
has_address binary Whether the asset type has an address assigned to it.
ordering unsigned An integer representing the asset type's ordering on the deployment.

Sample json object link fields object:

  "object_link_fields": {
      "contract": {
          "include_end_date": 0,
          "include_start_date": 0,
          "include_description": 1
      },
      "prospect": {
          "include_end_date": 0,
          "include_description": 1,
          "include_start_date": 0
      },
      "issue": {
          "include_end_date": 0,
          "include_description": 1,
          "include_start_date": 0
      },
      "job": {
          "include_start_date": 1,
          "include_description": 1,
          "include_end_date": 1
      }
  }

These contain information on the properties of assets of a given type linked to a given object. The object contains a hash of each of the object types an asset can be linked to, issues, jobs, prospects, and contracts. Each of these hashes contain the following fields:

Field Type Description
include_description bool Whether asset links for assets of this type have a description.
include_start_date bool Whether asset links for assets of this type have a start date.
include_end_date bool Whether asset links for assets of this type have an end date.

Get Asset

GET /assets/{asset_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/assets/{asset_id} \
  -H 'authorization: Bearer {access_token}'

GET /assets/{asset_id}

This request will return a single asset, specified by its unique identifier.

Configuring the Response

This request supports requesting additional fields and linked objects from the asset object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will contain the single asset object with its default fields and any others included via the _fields parameter.

List Assets

Sample Request:

GET /assets/ HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/assets \
  -H 'authorization: Bearer {access_token}'

GET /assets

This request will return a list of assets on the Accelo deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the asset object using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
standing
type_id
affiliation_id
manager_id
address_id
against_type
against_id
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
Order Filters

This request supports order filters over the following fields:

Filter Name
id
date_created
standing
Range Filters

This request supports range filters over the following fields:

Filter Name
id
standing
type_id
affiliation_id
manager_id
address_id
Object Filters

This request supports the following object filters:

Filter Name Notes
against Filter by assets against these objects.
Searching

This supports the _search parameter to search over the following fields:

Filter Name
title

Handling the Response

The response will be a list of asset objects with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters or searches used.

Count Assets

Sample Request:

GET /assets/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/assets/count \
  -H 'authorization: Bearer {access_token}'

GET /assets/count

This request will return a count of assets in a list defined by any available searches or filters. With no searches or filters this will be a count of all assets on the deployment. This request does not return a response object, just a single value:

Field Type Description
response unsigned int A count of the assets listed.

Get Asset Type

Sample request:

GET /assets/types/{type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/assets/types/{type_id} \
  -H 'authorization: Bearer {access_token}'

GET /assets/types/{type_id}

This request returns a single asset type specified by its type_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the asset type object using the _fields parameter.

Handling the Response

The response will be the single asset type with its default fields and any additional fields requested through _fields.

List Asset Types

Sample request:

GET /assets/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/assets/types \
  -H 'authorization: Bearer {access_token}'

GET /assets/types

This request returns a list of asset types.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the asset type using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Field Name
id
standing
Order Filters

This request supports order filters over the following fields:

Filter Name
id
standing
title
Range Filters

This request supports range filters over the following fields:

Filter Name
id
Searching

This request supports the use of the _search parameter to search over the following fields:

Field Name
title

Handling the Response

The response will be a list of asset types with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters or searches used.

Sample request:

GET /api/v0/assets/links HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/assets/links \
  -H 'authorization: Bearer {access_token}`

This request returns an array of asset links and an array of the linked assets.

Configuring the Response

Any additional parameters requested will be applied to the returned asset links.

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

All fields of the asset link object are displayed by default.

Basic Filters

This request supports the following basic filters:

Filter
asset_link_id
asset_id
Object Filters

This request supports object filters over the following objects:

Object
linked_object
Date Filters

This request supports the following date filters:

Filter
date_start
date_end
Order Filters

This request supports the following order filters:

Filter
asset_link_id
date_start
date_end
Range Filters

This request supports the following range filters:

Filter
asset_link_id

Handling the Response

The response will contain an array, "assets", of asset with their default fields with the removal of the latest_asset_link field, and the addition of the breadcrumbs field. The response will also contain an array, "asset_links" of asset links with all their fields, and displayed according to any pagination parameters or filters used.

Sample Request:

POST /api/v0/asset/{asset_id}/links
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X POST \
  https://{deployment}.api.accelo.com/api/v0/assets/{asset_id}/links \
  -H 'authorization: Bearer {access_token}

POST /assets/{asset_id}/links

POST /assets/links

This request creates and returns an asset link between an asset and an object from one of the supported types.

The following parameters may be sent to set the fields in the asset link:

Parameter Type Notes
asset_id unsigned Only to be sent if no asset_id was sent as part of the URL
linked_object_id unsigned The unique identifier of the object the asset is to be linked to.
linked_object_type string The type of object the asset is to be linked to. Should be one of the supported objects listed for asset links.
Description string
end_date unix ts
start_date unix ts

Handling the Response

The response will be the newly created asset link.

Sample Request:

DELETE /api/v0/assets/link/{link_id}
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -x DELETE \
  https://{deployment}.api.accelo.com/api/v0/assets/links/{asset_link_id} \
  -H 'authorization: Bearer {access_token}

DELETE /assets/links/{asset_link}

This request deletes an asset link (and not the asset) specified by its asset_link_id. This request takes no parameters and returns no resources.

Update an Asset

Sample request:

PUT /api/v0/assets/{asset_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X PUT \
  https://{deployment}.api.accelo.com/api/v0/assets/{asset_id} \
  -H 'authorization: Bearer {access_token}' \

PUT/assets/{asset_id}

This request updates and returns an asset, specified by its asset_id

Configuring the Asset

The following fields from the asset object may be updated with this request:

Field Notes
title

Configuring the Response

This request supports requesting additional fields and linked objects from the asset through the _fields parameter.

Handling the Response

The response will be the single, updated asset with its default fields and any additional fields requested through _fields

List Asset Extension Fields

See the extension section for an example

GET /assets/extensions/fields

This request returns a list of extension fields available for any asset. This is the request GET/{object}/extensions/fields, where the object is "assets".

List an Asset's Extension Field Values

See the extension section for an example

GET /assets/{asset_id}/extensions/values

This request returns a list of extension values for an asset, specified by its asset_id. This is the request GET /{object}/{object_id}/extensions/values, where the object is "assets", and whose id is asset_id.

List all Extension Field Values on Assets

See the extension section for an example

GET /assets/extensions/values

This request returns a list of extension field values on assets This is the request GET /{object}/extensions/values, where the object is "assets".

Update an Extension Field Value on an Asset

See the extension section for an example

PUT /assets/{asset_id}/extensions/values/{extension_value_id}

This request updates the value of an extension field value, specified by its extension_value_id, of an asset, specified by its asset_id. This is the request PUT{object}/{object_id}/extensions/values/{extension_value_id}, where the object is "asset", and whose id is asset_id

Set an Extension Field Value on an Asset

See the extension section for an example

POST /assets/{asset_id}/extensions/fields/{extension_field_id}

This request sets and returns the value of an extension field, specified by its extension_field_id, of an asset , specified by its asset_id. This request is the request POST/{object}/{object_id}/extensions/fields/{extension_field_id} where our object is "assets" whose id is asset_id.

Companies

Resource URI: /api/v0/companies

Companies are the entries in Accelo to note the companies with whom you interact. These can range from partners and vendors to your actual customers, and can even include you! These Client entries also act as the central repository for all information related to that group, including correspondence, project and sales updates, and contact information for their employees. See the support documentation for more information on accessing and using companies on your deployment.

The Company Object

Example company object:

{
  "date_modified": "1495671183",
  "phone": "61448824724",
  "status": "3",
  "name": "A Fresh New Company",
  "id": "45",
  "date_last_interacted": "1495675655",
  "comments": "This is a fresh new company",
  "date_created": "1495669367",
  "staff_bookmarked": "0",
  "standing": "active",
  "default_affiliation": "12",
  "postal_address": "31",
  "fax": null,
  "website": "www.example.com"
}
Field Type Description
id unsigned The company's unique identifier.
name string The name of the company.
custom_id string The custom id for the company.
website string The company's website.
phone string A contact phone number for the company.
fax string A fax number for the company.
date_created unix ts The date the company was created on the Accelo deployment.
date_modified unix ts The date the company was last modified on the Accelo deployment.
date_last_interacted unix ts The date the company was last modified on the Accelo deployment.
comments string Any comments or notes made against the company.
standing string The standing of the company, from its status.
status unsigned or object The company's status.
postal_address unsigned or object The postal address of the company.
staff_bookmarked bool Whether the company has been bookmarked by the current user.
default_affiliation unsigned The affiliation_id of the main affiliation associated with this company.

The Manager Object

Example manager object with default fields:

{
  "surname": "Hughes",
  "id": "14",
  "relationship_id": "28",
  "firstname": "Matthew"
}

A company may be managed by a staff member, this management relationship is described by the manager object, which contains the fields of a staff object, with the following addition:

Field Type Description
relationship_id unsigned A unique identifier for the relationship between the company and manager.

The Company Segmentation Object

Example company segmentation:

{
  "value": "Small (5-14 staff)",
  "title": "Size",
  "values": [
    "Small (5-14 staff)"
  ],
  "id": "2"
}

Segmentations, are fields to group companies, contacts, and affiliations. For example, some segmentations for a company may be:

Segmentation Description
Industry Which industry does the company operate in.
Size Roughly, how many staff does the company have.
Source How did this company become known to us.

The Company Segmentation is a special object available via companies which gives details on the segmentations, and their values, for a given company. This object contains:

Field Type Description
id unsigned The unique identifier for this segmentation.
title string The title for this segmentation. For example "Industry" or "size"
value string The value(s) for this segmentation, separated by commas. For example "transport,utilities".
values array An array of the values for this segmentation.

Get Company

Sample Request:

GET /api/v0/companies/{company_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/{company_id} \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}

This request returns a single company from the Accelo deployment, identified by its company_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the company object

Handling the Response

The response will contain a company object with its default fields and any additional fields requested via the _fields parameter.

List Companies

Sample Request:

GET /api/v0/companies HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/ \
  -H 'authorization: Bearer {access_token}'

GET /companies

This request returns a list of companies from the Accelo deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the company object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
status Filter over the status_id.
standing
default_affiliation Filter over the affiliation_id of the default affiliation.
postal_address Filter over the postal_address_id.
manager_id Filter by the staff_id of the staff set as manager of the company.
contact_number Filter over phone and fax.
custom_id Filter over the custom_id.
website
Date Filters

This request date filters over the following fields:

Filter Name
date_created
date_modified
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
id
date_created
date_modified
date_last_interacted
name
standing
status Order by the status_id.
custom_id
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
affiliation
standing
status Range over the status_id.
custom_id
country
Searching

This request supports the _search parameter to search over the following fields:

Field Name Notes
website
name
phone
fax

Handling the Response

The response will be a list of company objects with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Companies

Sample Request:

GET /api/v0/companies/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/count \
  -H 'authorization: Bearer {access_token}'

GET /companies/count

This request will return a count of companies in a list defined by any available searches or filters. With no searches or filters this will be a count of all companies on the deployment. This request returns a single field:

Field Type Description
count unsigned int A count of the companies listed.

List Recent Companies

Sample Request:

GET /api/v0/companies/recent HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/recent \
  -H 'authorization: Bearer {access_token}'

GET /companies/recent

Equivalent request:

GET /companies?_filters=order_by_desc(date_created)

GET /api/v0/companies/recent HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

This request returns the most recently created companies on the Accelo deployment. This request is equivalent to requesting all companies and ordering in descending order of date_created.

Configuring the Response

This request accepts the same parameters and filters as GET /companies, although it will always be ordered in descending order of date_created

Handling the Response

This request will return a list of company objects with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

List Latest Modified Companies

Sample Request:

GET /api/v0/companies/newest HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/newest \
  -H 'authorization: Bearer {access_token}'

GET /companies/newest

Equivalent Request:

GET /companies?_filters=order_by_desc(date_modified)

GET /api/v0/companies/newest HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

This request returns the most recently changed companies on the Accelo deployment. This request is equivalent to requesting all companies and ordering in descending order of date_modified.

Configuring the Response

This request accepts the same parameters and filters as GET /companies, although it will always be ordered in descending order of date_modified

Handling the Response

This request will return a list of company objects with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Get a Company's Status

Sample Request:

GET /api/v0/companies/{company_id}/status HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/{company_id}/status \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/status

This request returns the status of a company identified by its company_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling The Response

The response will be a single status object with its default fields and any additional fields requested via _fields.

List Company Statuses

Sample Request:

GET /api/v0/companies/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/statuses \
  -H 'authorization: Bearer {access_token}'

GET /companies/statuses

This returns a list of company statuses.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling The Response

The response will be an array of status objects with their default fields and any additional fields requested via _fields.

Get Company Status

Sample Request:

GET /api/v0/companies/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}'

GET /companies/statuses/{status_id}

This request returns the company status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a company status object for the specified status with its default fields and any additional fields requested through _fields.

List Company Statuses

Sample Request:

GET /api/v0/companies/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/statuses \
  -H 'authorization: Bearer {access_token}'

GET /companies/statuses

This request returns a list of company statuses on the deployment.

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the company status object through the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Count Company Statuses

Sample Request:

GET /api/v0/companies/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/companies/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /companies/statuses/count

This request will return a count of company statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all company statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed company statuses.

Get Main Contact

Sample Request:

GET /api/v0/companies/{company_id}/contact HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/contact \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/contact

This request returns the main contact of a company identified by its {company_id}. This is the contact associated with the company's default_affiliation.

Configuring the Response

This request supports requesting additional fields and linked objects from the contact object using the _fields parameter.

Handling the Response

The response will be a single contact with its default fields and any other additional fields requested via _fields.

List Contacts Against a Company

Sample Request:

GET /api/v0/companies/{company_id}/contacts HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/contacts \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/contacts

This request returns a list of contacts for a company identified by its {company_id}.

Configuring the Response

This request may be configured and handled as per GET /contacts

Count Contacts on a Company

Sample Request:

GET /api/v0/companies/{company_id}/contacts/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/contacts/count \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/contacts/count

This request returns a count of a list of contacts associated with a company specified by its {company_id}. With no searches or filters this will be a count of all contacts associated with the company. This request returns a single field:

Field Type Description
count unsigned int A count of the contacts listed against the company

List Managers

Sample Request:

GET /api/v0/companies/{company_id}/managers HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/managers \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/managers

This request returns a list of managers of a company specified by its company_id.

Configuring the Response

This request may be configured and handled a per GET /staff

List A Company's Segmentations

Sample Request:

GET /api/v0/companies/{company_id}/segmentations HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/segmentations \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/segmentations

GET /api/v0/companies/{company_id}/segmentations HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

This request returns a list of company segmentations for a company identified by its company_id. This request takes no parameters and returns a list of segmentations.

Sample response:

{
  "meta": {
    "status": "ok",
    "more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok",
    "message": "Everything executed as expected."
  },
  "response": [
    {
      "title": "Industry",
      "values": [
        "Transport"
      ],
      "id": "1",
      "value": "Transport"
    },
    {
      "id": "2",
      "value": "Small (5-14 staff)",
      "values": [
        "Small (5-14 staff)"
      ],
      "title": "Size"
    }
  ]
}

Update a Company

Example request:

PUT /api/v0/companies/{company_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

comments=This%20is%20a%20fresh%20new%20company
_fields=comments
curl -X put \
  https://{deployment}.api.accelo.com/api/v0/companies/{company_id} \
  -H 'authorization: Bearer {acces_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'comments=This%20is%20a%20fresh%20new%20company' \
  -d '_fields=comments'

PUT /companies/{company_id}

This request updates and returns a company identified by its company_id.

Configuring the Company

The following fields from the company object may be updated through this request:

Field
website
phone
fax
comments
name

Configuring the Response

This request supports requesting additional fields and linked objects from the company object using the _fields parameter.

Handling the Response

This request returns the single updated company object, with its default fields and any additional fields requesting through _fields.

Create a Company

Sample request:

POST /api/v0/companies/{company_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

website=www.example.com
name=A%20Fresh%20New%20Company
standing=active
profile.12=09-17
curl -X post \
  https://{deployment}.api.accelo.com/api/v0/companies \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'website=www.example.com' \
  -d 'name=A%20Fresh%20New%20Company' \
  -d 'standing=active' \
  -d 'profile.12=09-17'

POST /companies

This request creates a new company on the Accelo deployment, and returns it.

Configuring the Company

Values for the following fields from the company object may be sent with this request:

Field Notes
name
parent_id
status_id
standing If you also send a status_id, this will be overwritten by the standing of the status linked.
website
phone
fax
comments
custom_id custom_id will only show when you have custom id enabled on the web app
Setting Profile Field Values

Profile field values may be set when you create a company, for a given profile value identified by [profile_value_id you may update it through the field "profile.{profile_value_id}".

Configuring the Response

This request supports requesting additional fields and linked objects from the company object using the _fields parameter.

Handling the Response

This request returns the created company object, with its default fields and any additional fields requesting through _fields.

Add a Manager

Sample Request:

POST /api/v0/companies/{company_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

manager_id=14
curl -X post \
  https://{deployment}.api.accelo.com/api/v0/companies \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'manager_id=14'

POST /companies/{company_id}/managers/add

This request adds a manager, identified by their unique staff_id, as a manager to a company, identified by its unique company_id. The request returns a list of managers of this company on the Accelo deployment.

Configuring the Manager

The following fields may be sent with this request:

Field Type Description
manager_id unsigned The staff_id of the staff member to be set as the manager of the company.
nature select Nature of the new relationship. Must be "professional","confidential" or "private". Defaults to "professional", see the support documentation for more information on manager relationships.

Configuring the Response

This response may be configured and handled in the same way as GET /companies/{company_id}/managers.

Remove a Company

Sample Request:

DELETE /api/v0/companies/{company_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/companies/{company_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /companies/{company_id}

This request will remove a company, specified by its company_id, from the Accelo deployment. This request takes no parameters and returns no resource.

Remove a Manager

Sample Request:

DELETE /api/v0/companies/{company_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

relationship=23
curl -X post \
  https://{deployment}.api.accelo.com/api/v0/companies \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'relationship_id=23'

DELETE /companies/{company_id}/managers/delete

This request returns a staff member, identified via the relationship_id of their manager object, from the role of manager of a company, identified by its company_id. The manager_id is not used to identify the manager as a manager can have multiple relationships with the same company. Hence this request takes a single parameter:

Parameter Description
relationship_id The relationship_id of the manager to be removed.

Handling the Response

This response returns a list of manager (staff members) for the given company.

List a Company's Profile Field Values

See the profiles section for a sample request

GET /companies/{company_id}/profiles/values

This request returns a list of profile field values of a company, specified by its company_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "companies" and whose id is {company_id}.

List all Profile Field Values on a Company

See the profiles section for a sample request

GET /companies/profiles/values

This request returns a list of all profile field values on companies. This is the request GET /{object}/profiles/values, where the object is "companies".

List Company Profile Fields

See the profiles section for a sample request

GET /companies/profiles/fields

This request returns a list of profile fields available for companies. This is the request GET /{object}/profiles/fields where the object is "companies".

Update a Profile Field Value on a Company

See the profiles section for a sample request

PUT /companies/{company_id}/profiles/values/{profile_value_id}

This request updates and returns a profile field value, specified by its profile_value_id of a particular company, identified by its company_id. This is the request PUT/{object}/{object_id}/profiles/values/{profile_value_id} where the object is "company", and whose id is {company_id}.

Set a Profile Field Value on a Company

See the profiles section for a sample request

POST /companies/{company_id}/profiles/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a company, specified by its company_id. This is the request POST /{object}/{object_id}/profiles/fields/{profile_field_id} where is object is "companies" and whose id is {company_id}

List Available Progressions on a Company

See the progressions section for a sample request

GET /companies/{company_id}/progressions

This request returns a list of available progressions for a company identified by its company_id. This is the request GET /{object}/{object_id}/progressions where the object is "companies" whose id is {company_id}

Auto Run a Progression on a Company

See the progressions section for a sample request

[PUT|POST] /companies/{company_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress the status of a company, specified by its company_id. This is the request [PUT|POST]/{object}/{object_id}/progressions/{progression_id/auto} where the object is "companies" whose id is {company_id}.

List Addresses against a Company

Sample Request:

GET /companies/{company_id}/addresses

This request returns a list of addresses associated with a company, specified by its company_id. This is the request GET /{object}/{object_id}/addresses where the object is "companies" and whose id is {company_id}.

Create an Address against a Company

Sample Request:

POST /companies/{company_id}/addresses

This request creates a address against a company, specified by its company_id. This is the request POST /{object}/{object_id}/addresses where the object is "companies" and whose id is {company_id}.

List a Company's Resource Collections

See the resources (attachments) section for an example

GET /companies/{company_id}/collections

This request returns a list of collections against a company, specified by its company_id. This is the request GET /{object}/{object_id}/collections where the object is "companies" and whose id is {company_id}.

Upload a Resource (Attachment) to a Collection on a Company

See the resources (attachments) section for an example

POST /companies/{company_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of a company specified by its company_id. This is the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "companies" and whose id is {company_id}.

Contacts

Resource URI: /api/v0/contacts

Contacts are the Accelo entries for individual people. Contact entries Provide a central location where you can view all correspondence involving them. A contact is not directly associated with a company but it is with an affiliation. To create a contact against a given company, you should first create the contact and then the affiliation for the new contact against the company.

The Contact Object

The contact object contains the following fields and linked objects:

Field Type Description
id unsigned The unique identifier for the contact.
firstname string The contact's first name.
surname string The contact's surname.
mobile string The contact's mobile number. Deprecated please use the affiliation object to store and lookup contact information of a contact.
email string The contact's email address. Deprecated as for "mobile".
username string The contact's Accelo username.
middlename string The contact's middle name.
title string The contact's preferred title. For example "Ms", "Mr", "Dr".
timezone string The contact's timezone.
date_created unix ts The date the contact was added on the Accelo deployment.
date_modified unix ts The date the contact was last modified.
date_last_interacted unix ts The most recent date of interaction with the contact.
comments string Any comments or notes made against the contact.
default_affiliation unsigned The unique identifier of the default affiliation associated with the contact.
contact_status unsigned or object The status of the contact.
standing string The contact's standing, this is part of the status object. For example "active", "potential".

Get Contact

Sample Request:

GET /api/v0/contacts/{contact_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/{contact_id} \
  -H 'authorization: Bearer {access_token}'

GET /contacts

This request returns a single contact, identified by their contact_id.

Configuring the Request

This request supports requesting additional fields and linked objects from the contact object using the _fields parameter.

Handling the Response

The response will contain a single contact object with its default fields, and any additional fields requested through _fields.

List Contacts

Sample Request:

GET /api/v0/contacts/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/ \
  -H 'authorization: Bearer {access_token}'

GET /contacts

This request returns a list of contacts on the Accelo deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting any extra fields or linked objects from the contacts object object via the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Field Notes
id
email
title
standing
affiliation Filter by the default_affiliation_id.
status
username
contact_number Filter over phone, fax, and mobile.
Date Filters

This request supports date filters over the following fields:

Field
date_created
date_modified
date_last_interacted

Order Filters

This request supports order filters over the following fields:

Filter Name
id
fullname
firstname
username
surname
title
contact_status_id
standing
date_modified
date_created
date_last_interacted

Range Filters

This request supports range filters over the following fields:

Field Notes
id
status
country Filter by the country_id of the default affiliation of the contact.

Searching

This request supports the use of the _search parameter over the following fields:

Field Notes
firstname
surname
email

Handling the Response

This request will return a list of contacts containing their default fields and any additional field requested by _fields, and displayed according to any pagination parameters, filters or searches used.

Count Contacts

Sample Request:

GET /api/v0/contacts/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/count \
  -H 'authorization: Bearer {access_token}'

GET /contacts/count

This request will return a count of contacts in a list defined by any available searches or filters. With no searches or filters this will be a count of all contacts on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed contacts.

List Recent Contacts

Sample Request:

GET /api/v0/contacts/recent HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/recent \
  -H 'authorization: Bearer {access_token}'

GET /contacts/recent

Equivalent request:

GET /contacts?_filters=order_by_desc(date_created)

This request returns a list of contacts on the Accelo deployment sorted by the most recently created, that is, in descending order of the their date_created.

Configuring the Response

This request accepts the same parameters and filters as GET /contacts, although it will always be ordered in descending order of date_created.

Handling the Response

This request will return a list of contacts displayed according to any parameters used, and with their default fields plus and additional fields requested by _fields, and sorted in descending order of date_created.

List Recently Modified Contacts

Sample Request:

GET /api/v0/contacts/newest HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/newest \
  -H 'authorization: Bearer {access_token}'

GET /contacts/newest

Equivalent request:

GET /contacts?_filters=order_by_desc(date_created)

This request returns a list of contacts on the Accelo deployment sorted by most recently modified, that is, in descending order of date_modified.

Configuring the Request

This request accepts the same parameters and filters as GET /contacts, although it will always be ordered in descending order of date_modified.

Handling the Response

This request will return a list of contacts displayed according to any parameters used, and with their default fields plus and additional fields requested by _fields, and sorted in descending order of date_modified.

Update a Contact

Sample Request:

PUT /api/v0/contacts/{contact_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/{contact_id} \
  -H 'authorization: Bearer {access_token}'
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /contacts/{contact_id}

This request updates and returns a contact in the Accelo deployment, identified by its contact_id. Recall that affiliations hold contact information (address, phone numbers etc.) for a contact, so if you wish to update these fields, or do not see the field you are after here, you may need to look at the affiliation object.

Configuring the Contact

This request allows updating the following fields in the contact object:

Field Type Notes
firstname string
middlename string
surname string
username string The contact's new username, this must be a unique username, otherwise an invalid request will be returned.
password string The contact's new password for the Accelo deployment. This field is write only.
title string
comments string
status unsigned Must point to a valid status_id, otherwise an invalid request will be returned.
standing string Please only send one of status or standing, it both are sent the standing of the linked status object will dominate anything sent through this field.

Configuring the Response

This request supports requesting additional fields and linked objects through the _fields parameter.

Handling the Response

The response will be the single, updated contact object, with its default fields and any additional fields requested through _fields.

Create a Contact

Sample Request:

POST /api/v0/contacts/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/ \
  -H 'authorization: Bearer {access_token}'
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /contacts

This request adds a new contact to the Accelo deployment and returns it. This is a sort of hybrid request, as it also creates an affiliation to associate the contact with a company.

Configuring the Contact

This request accepts all fields from the PUT \contacts request, with the firstname and surname fields being required, as well as the following fields from the affiliation object:

Field Type Notes
company_id unsigned Must point to a valid company. This is the company the new affiliated contact will be associated with.
country_id unsigned Must point to a valid country
physical_address_id unsigned Must point to a valid address.
postal_address_id unsigned Must point to a valid address.
phone string The contact's phone number in their role in the associated company. For example, their work number.
fax string As for phone but a fax number.
email string As for phone but an email address. Must be a valid email address.
position string The contact's position in the associated company.
communication string As in the affiliation object
invoice_method string As in the affiliation object

Configuring the Response

This request supports requesting additional fields and linked resources from the contact object using the _fields parameter.

Handling the Response

This request will return the single new contact, with its default fields and any additional fields requested through _fields

Deactivate a Contact

Sample Request:

DELETE /api/v0/contacts/{contact_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/{contact_id} \
  -H 'authorization: Bearer {access_token}'
  -H 'Content-Type: application/x-www-form-urlencoded'

DELETE /contacts/{contact_id}

Equivalent request:

PUT /contact/{contact_id}?standing=inactive

This request sets a contact on the Accelo deployment, identified by its contact_id, to inactive. This request does NOT delete the contact, a user can only be removed from the web deployment, see the support documentation for information. This request accepts no parameters and only returns the meta object.

List Addresses Against a Contact

Sample Request:

PUT /api/v0/contacts/{contact_id}/addresses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/{contact_id}/addresses \
  -H 'authorization: Bearer {access_token}'
  -H 'Content-Type: application/x-www-form-urlencoded'

GET /contacts/{contact_id}/addresses

This is simply the GET /{object}/{object_id}/addresses request, where {object} is company and {object_id} is the {company_id}.

Create an Address Against a Contact

Sample Request (TODO):

POST /contacts/{contacts_id}/addresses

This request creates and returns an address against a contact specified by its contact_id. This is the request POST /{object}/{object_id}/addresses where the object is "addresses" whose id is {contact_id}.

Get a Contact's Status

Sample Request:

GET /contacts/{contact_id}/status

This request returns the status of a contact on the Accelo deployment, identified by their contact_id.

Configuring the Request

This request supports requesting additional fields and linked objects from the status using the _fields parameter.

Handling the Response

This request returns a single status with its default fields and any additional fields requested through _fields.

Get Contact Status

Sample Request:

GET /api/v0/contacts/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/contacts/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}' \

GET /contacts/statuses/{status_id}

This request returns the contact status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a contact status object for the specified status with its default fields and any additional fields requested through _fields.

List Contact Statuses

Sample Request:

GET /api/v0/contacts/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contacts/statuses \
  -H 'authorization: Bearer {access_token}'

GET /contacts/statuses

This request returns a list of contact statuses on the deployment.

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the contact status object through the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Count Contact Statuses

Sample Request:

GET /api/v0/contacts/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/contacts/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /contacts/statuses/count

This request will return a count of contact statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all contact statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed contact statuses.

List Contact Segmentations

Sample Request:

GET /contacts/{contact_id}/segmentations

This request returns a list of segmentations for a contact specified by its contact_id. This request supports no parameters and returns a list of segmentations.

List a Contact's Profile Field Values

See the profiles section for a sample request

GET /contacts/{contact_id}/profiles/values

This request returns a list of profile values of a contact, specified by its contact_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "contacts", and whose id is contact_id.

List all Profile Field Values on a Contact

See the profiles section for a sample request

GET /contacts/profiles/values

This request returns a list of all profile field values on contacts. This is the request GET /{object}/profiles/values, where the object is "contacts".

List Contact Profile Fields

See the profiles section for general usage.

GET /contacts/profiles/fields

This request returns a list of profile fields available for contacts.

Update a Profile Field Value on a Contact

See the profiles section for general usage.

PUT /contacts/{contact_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular contact, specified by its contact_id.

Set a Contact's Profile Field Value

See the profiles section for a sample request

POST /contacts/{contact_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a contact, specified by its contact_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "contacts", and whose value is contact_id.

List Available Progressions on a Contact

See the progressions section for a sample request

GET /contacts/{contact_id}/progressions

This request returns a list of available progressions for a contact, specified by its contact_id. This is the request GET /{object}/{object_id}/progressions where the object is "contacts" whose id is contact_id.

Auto Run a Progression on a Contact

See the progressions section for a sample request

PUT|POST /contacts/{contact_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress a contact, specified by its contact_id. This is the request [POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto where the object is "contact" whose id is contact_id.

List a Contact's Resource Collections

See the resources (attachments) section for an example

GET /contacts/{contact_id}/collections

This request returns a list of collections against a contact, specified by its contact_id. This is the request GET /{object}/{object_id}/collections where the object is "contacts" and whose id is {contact_id}.

Upload a Resource (Attachment) to a Collection on a Contact

See the resources (attachments) section for an example

POST /contacts/{contact_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of a contact specified by its contact_id. This is the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "contacts" and whose id is {contact_id}.

Contracts (Retainers)

Resource URI:
/api/v0/contracts

Contracts (also known as retainers) are objects for managing recurring client work, maintenance quotas, or periodic invoicing - such as license fee. A contract is created against a company/client record (that is, an affiliation), and work is tracked against the contract through periods. You can configure your contract to automatically create periods at certain intervals, and invoice up-front for a fixed amount or at the end of the period for the work done. See the support documentation for more information on contracts/retainers.

The contracts model integrates flawlessly with the the issues and jobs modules so that you can even allocate work from those into a contract period. Contracts can also be linked to service items, allowing for easy handling of things like tax codes and ledger codes.

The Contract Object

Example contract:

{
  "id": "1",
  "date_last_interacted": "1493265142",
  "send_invoice": "none",
  "job": null,
  "against_id": "39",
  "against_type": "company",
  "type": "1",
  "period_template_id": "2",
  "date_expires": "1495591200",
  "deployment": "1495325400",
  "auto_renew": "no",
  "title": "A new contract",
  "standing": "active",
  "manager": "14",
  "renew_days": "0",
  "date_created": "1493265142",
  "date_started": "1493258400",
  "company": "39",
  "status": "2",
  "billable": "98",
  "date_period_expires": "1493776800",
  "value": "0.00",
  "against": "companies/39",
  "notes": "This contract was created against a company",
  "affiliation": "98",
  "staff_bookmarked": "1",
}

The contract object contains the following fields and linked objects:

Field Type Description
id unsigned A unique identifier for the contract.
title string A title for the contract.
period_template_id unsigned The unique identifier of the period_template. See the support documentation for information on period templates.
date_created unix ts The date the contract was created on the Accelo deployment.
date_started unix ts The date the contract was started.
date_expires unix ts The date the contract expires.
date_period_expires unix ts The date the current period ends.
against string The API URI for the object the contract is against. For example "contact/94".
against_id unsigned The unique identifier of the object the contract is against.
against_type string The type of object the contract is against. For example "contact".
value decimal The total value of this contract.
auto_renew string Either "yes" or "no", whether the contract auto renews.
renew_days string Number of days before the current period expires to renew.
send_invoice string Type of invoice to be sent on renewal, if any. Can be "none", "email", "fax" or "postal".
notes string Any notes made against the contract.
staff_bookmarked bool Whether the current user has favourited the contract.
owner_affiliation unsigned or object The affiliation the contract is owned by. This replaces the deprecated "affiliation" object, please avoid requesting both objects at once.
billable_affiliation unsigned The unique id for the billable affiliation.
type unsigned or object The type of the contract, contract types may be configured on the deployment. Deprecated, please use contract_type.
contract_type unsigned or object The contract type of the contract.
manager unsigned or object The staff member managing this contract.
status unsigned or object The status of the contract.
standing string The standing of the contract, this is part of the status object. For example "active", "cancelled".
job unsigned or object The job the contract is against, if any.
company unsigned or object The company the contract is against, if any.

The Contract Period

Example contract period object:

{
  "allowance_type": "unlimited_hours",
  "budget_type": "pre-paid",
  "duration_type": "fixed",
  "date_created": "1493265142",
  "rate_id": "11",
  "date_commenced": "1493258400",
  "rollover": "no",
  "contract": "contracts/1",
  "standing": "opened",
  "service_item_id": "1",
  "contract_budget": "1",
  "id": "1",
  "rate_type": "object",
  "date_expires": "1493776800",
  "contract_id": "1",
  "date_closed": null
}

The contract period is a duration of time to track and invoice a contract. The contract_period object contains the following:

Field Type Description
id unsigned A unique identifier for the period.
date_created unix ts The date the period was created.
date_commenced unix ts The date the period commenced.
date_expires unix ts The date the period expires.
date_closed unix ts The date the period was closed.
budget_type select The budget or billing type. May be either "pre-paid" or "post-paid".
allowance_type select The prepaid allowance for the period. May be either "unlimited hours", "fixed hours", or "fixed value".
rate_type select Whether activities linked to the period should use the rate defined by the object they are against, or the rate defined by the contract. May be either "contract" or "object".
rate_id unsigned The unique identifier of the rate object of the period.
service_item_id unsigned The unique identifier of the service item linked to the contract. See the support documentation for information on service items.
duration_type select The type of the period duration. May be either "fixed" or "unlimited".
rollover select Whether an expiring period should roll unused allowance into the next period. Either "yes" or "no".
standing string The standing of the period. For example "opened", "closed".
contract string The API URI of the contract the period belongs to.
contract_id unsigned The unique identifier of the contract the period belongs to.
contract_budget unsigned or object The id or object of the budget assigned to the period.

The Contract Type

Example contract type object:

{
  "period_template_id": "1",
  "title": "Default",
  "auto_renew": "no",
  "parent": "0",
  "renew_days": "0",
  "id": "1"
}

For ease of use and automation, different contract templates can be set up on the Accelo deployment. These templates are covered by the contract type which contains the following:

Field Type Description
id unsigned A unique identifier for the contract type.
title string A title for the contract type.
parent unsigned The unique identifier for the parent contract. Value is "0" if there is no parent.
standing string The standing of the contract upon creation. For example "pending", "active".
ordering unsigned The ordering of the contract type on the Accelo deployment.
auto_renew string As in the contracts object.
renew_days string As in the contracts object.
send_invoice string As in the contracts object.
period_template_id unsigned As in the contracts object.

This object does not support the _ALL argument under _fields.

Note: The type field is deprecated, please request the contract type through the contract_type field, which contains the following additional fields:

Field Type Description
invoice_template_id unsigned The unique identifier of the invoice template used for this contract type.
service_tax_id unsigned The unique identifier of the service tax used for this contract type.
service_tax_ledger_id unsigned The unique identifier of the service tax ledger used for this contract type.
auto_complete_task boolean Either "1" or "0" whether this contract type is set to autocomplete tasks.

The Contract Budget

Example contract budget object:

{
  "id": "1",
  "value": "25.00",
  "product_charged": "30.00",
  "time_charged": "24.00",
  "time": "1000",
  "against_type": "contract_period",
  "against_id": "10"
}
Field Type Description
id unsigned A unique identifier for the contract budget.
value string The financial value of the budget (sum of all values within budget). This requires full financial access.
product_charged string The financial value charged for the budget's product(s) (sum of all product charges within budget). This requires full financial access.
time_charged string The financial value charged for the budget's time (sum of all time charges within budget). This requires full financial access.
time unsigned The time spent in seconds on the budget (sum of all time within budget).
against_type string The type of object this budget is against. e.g, "contract_period".
against_id unsigned The id of the object this budget is against.

Get Contract

Sample Request:

GET /api/v0/contracts/{contract_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}
  -H 'authorization: Bearer {access_token}'

GET /contracts/{contract_id}

This request returns a single contract from the Accelo deployment, specified by its contract_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the contract object using the _fields parameter. This request also supports breadcrumbs .

Handling the Response

The response will be a single contract object, with its default fields and any additional fields requested by _fields.

List Contracts

Sample Request:

GET /api/v0/contracts HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts
  -H 'authorization: Bearer {access_token}'

GET /contracts

This request returns a list of contracts from the Accelo deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting any extra fields or linked objects from the contracts object via the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
type Filter against the type_id. Deprecated, please use contract_type.
contract_type Filter against the contract_type_id.
manager Filter against the staff_id of the manager.
billable_affiliation Filter against the affiliation_id of the billable affiliation.
owner_affiliation Filter against the affiliation_id of the owner affiliation.
status Filter against the status_id.
against_id
against_type
is_related_to_issue Filter contracts related to an issue (or list of issues), identified by its issue_id.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
date_started
date_expired
date_period_expires
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
id
date_created
date_started
date_expires
date_period_expires
standing Order by the string field standing.
status Order by the status_id
title
date_last_interacted
Range Filters

this request supports range filters over the following fields:

Filter Name Notes
id
type Range by type_id. Deprecated, please use contract_type.
contract_type Range by the contract_type_id.
billable Range by the company_id of the billable company.
affiliation Range by affiliation_id.
manager Range by the staff_id of the manager of the contract.
against_id
status Range by status_id.
value
renew_days
period_template Range by period_template_id.
service_tax Range by service_tax_id from the service item linked to the contract, if any.
service_ledger Rage by service_ledger_id.from the service item linked to the contract, if any.
Object Filters

This request supports the following object filters:

Filter Name Description
against Filter by contracts against these objects.

Searching

This request supports the use of the _search parameter over the following fields:

Field
title

Handling the Response

The response will be a list of contract objects containing the default fields and any additional field requested by _fields, and displayed according to any pagination parameters or filters used.

Count Contracts

Sample Request:

GET /api/v0/contracts/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/count
  -H 'authorization: Bearer {access_token}'

GET /contracts/count

This request will return a count of contracts in a list defined by any available searches or filters. With no searches or filters this will be a count of all contracts on the deployment. This request does not return a response object, just a single value:

Field Type Description
response unsigned A count of the listed contracts.

Get Contract Period

Sample Request:

GET /api/v0/contracts/{contract_id}/periods/{period_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}/periods/{period_id}
  -H 'authorization: Bearer {access_token}'

GET /contracts/periods/{period_id}

This request returns a single contract period object from the Accelo deployment.

Configuring the Response

This request supports requesting additional fields and linked objects from the contract period object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

This response will be a single contract period object, with its default fields and any additional fields requested via _fields.

List Contract Periods

Sample Request:

GET /api/v0/contracts/{contract_id}/periods HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}/periods
  -H 'authorization: Bearer {access_token}'

GET /contracts/{contract_id}/periods

This request returns a list of contract periods for a contract, specified by its contract_id.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting extra fields or linked objects from the contract_period object using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
budget_type
allowance_type
rate_type
rate Filter over the rate_id.
service_item Filter over the service_item_id.
duration_type
rollover
standing
contract Filter over the contract_id.
contract_budget Filter by the id of the budget assigned to the period.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
date_commenced
date_expires
date_closed
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
contract Range over the contract_id.
rate Range over the rate_id.
rate_charged Range over the rate at which billable time is charged for activities against this contract.
budget Range over the budget_id.
service_item Range over the service_item_id.
Order Filters

This request supports order filtering over the following fields:

Filter Name
id
date_created
date_commenced
date_expires
date_closed

Handling the Response

The response will be a list of contract objects containing the default fields and any additional fields requested by _fields, and displayed according to any pagination parameters or filters used.

List Contract Types

Sample Request:

GET /api/v0/contracts/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/types
  -H 'authorization: Bearer {access_token}'

GET /contracts/types

This request returns a list of contract types on the Accelo deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the contract type object using the _fields parameter.

Basic filters

This request supports basic filters over the following fields:

Field
id
standing
auto_renew
parent
send_invoice
period_template_id
invoice_template_id
service_tax_id
service_ledger_id
Order Filters

This request supports order filters over the following fields:

Field
id
title
standing
ordering
Range Filters

This request supports range filters over the following fields:

Field
id
renew_days
Empty Filters

This request supports empty filters over the following fields:

Field
title
Searching

This request the use of the _search parameter to search over the following fields:

Field
title

Handling the Response

This request will return a list of contract types containing the default fields and any additional fields request by _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Contract Types

Sample Request:

GET /api/v0/contracts/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/types/count
  -H 'authorization: Bearer {access_token}'

GET /contracts/types/count

This request returns a count of contract types in a list defined by any available searches or filters. With no searches or filters this will be a count of all contract types on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed contract types.

Get Contract Type

Sample Request:

GET /api/v0/contracts/types/{type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/types/{type_id}
  -H 'authorization: Bearer {access_token}'

GET /contracts/types/{type_id}

This request returns a single contract type object identified by its contract_type_id.

Configuring the Request

This request supports requesting extra fields or objects from the contract type object through the _fields parameter.

Handling the Response

The response will contain the single contract type with its default fields, and any additional fields requested through _fields.

Get Contract Status

Sample Request:

GET /api/v0/contracts/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/contracts/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}' \

GET /contracts/statuses/{status_id}

This request returns the contract status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a contract status object for the specified status with its default fields and any additional fields requested through _fields.

List Contract Statuses

Sample Request:

GET /api/v0/contracts/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/statuses \
  -H 'authorization: Bearer {access_token}'

GET /contracts/statuses

This request reutrns a list of contract statuses on the deployment.

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the contract status object through the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Count Contract Statuses

Sample Request:

GET /api/v0/contracts/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/contracts/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /contracts/statuses/count

This request will return a count of contract statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all contract statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed contract statuses.

Close a Contract Period

Sample Request:

PUT /api/v0/contracts/periods/{period_id}/close HTTP/1.1
HOST: {deployment.api.accelo.com}
Authorization: Bearer {access_token}
curl -X PUT \
  https://{deployment}.api.accelo.com/api/v0/contracts/periods/{period_id}/close \
  -H 'authorization: Bearer {access_token}

[PUT | POST] /contracts/periods/{period_id}/close

This request closes and returns a contract period, see the support documentation for information on closing contract periods. The response may be configured as per get contract period.

Take Care: This request doesn't just set the standing to 'closed', but will replicate the actions taken when you close a contract period via the Web App, including closing tickets/issues if the contract is set to auto complete.

Reopen a Contract Period

Sample Request:

PUT /api/v0/contracts/periods/{period_id}/open HTTP/1.1
HOST: {deployment.api.accelo.com}
Authorization: Bearer {access_token}
curl -X PUT \
  https://{deployment}.api.accelo.com/api/v0/contracts/periods/{period_id}/open \
  -H 'authorization: Bearer {access_token}

[PUT | POST] /contracts/periods/{period_id}/open

This request reopens and returns a previously close contract period. The response may be configured as pre get contract period.

List Available Progressions on a Contract

See the progressions section for a sample request

GET /contracts/{contract_id}/progressions

This request returns a list of available progressions for an contract, specified by its contract_id. This is the request GET /{object}/{object_id}/progressions where the object is "contracts" whose id is {contract_id}.

Auto Run a Progression on a Contract

See the progressions section for a sample request

[POST|PUT] /contracts/{contract_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress an contract, specified by its contract_id. This is the request [POST|PUT] /{object}/{object_id}/progressions/{progression_id}/auto where the object is "contracts" whose id is {contract_id}.

List a Contract's Resource Collections

See the resources (attachments) section for an example

GET /contracts/{contract_id}/collections

This request returns a list of collections against a contracts, specified by its contract_id. This is the request GET /{object}/{object_id}/collections where the object is "contracts" whose id is {contract_id}.

Upload a Resource (Attachment) to a Collection on a Contract

See the resources (attachments) section for an example

POST /contracts/{contract_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of a contracts, specified by its contract_id. This is the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "contracts" whose id is {contract_id}.

List a Contract's Profile Field Values

See the profiles section for a sample request

GET /contracts/{contract_id}/profiles/values

This request returns a list of profile field values of a contracts, specified by its contract_id. This is the request
GET/{object}/{object_id}/profiles/values, where the object is "contracts" whose id is {contract_id}.

List all Profile Field Values on Contracts

See the profiles section for a sample request

GET /contracts/profiles/values

This request returns a list of all profile field values on contracts. This is the request GET /{object}/profiles/values, where the object is "contracts".

List Contract Profile Fields

See the profiles section for a sample request

GET /contracts/profiles/fields

This request returns a list of profile fields available for any contract. This is the request GET /{object}/profiles/fields, where the object is "contracts".

List Contract Extension Fields

See the extension section for an example

GET /contracts/extensions/fields

This request returns a list of extension fields available for an contract, specified by its contract_id. This is the request GET /{object}/extensions/fields, where the object is "contracts".

List all Extensions Field Values on Contracts

See the extension section for an example

GET /contracts/extensions/values

This request returns a list of extension field values on contracts. This is the request GET /{object}/extensions/values, where the object is "contracts".

List a Contract's Extension Field Values

See the extension section for an example

GET /contracts/{contract_id}/extensions/values

This request returns a list of extension values for an contract, specified by its contract_id. This is the request GET /{object}/{object_id}/extensions/values, where the object is "contracts", and whose id is the contract_id.

Update an Extension Field Value on a Contract

See the extension section for an example

PUT /contracts/{contract_id}/extensions/values/{extension_value_id}

This request updates the value of an extension field value, specified by its extension_value_id, of a contract, specified by its contract_id. This is the request PUT{object}/{object_id}/extensions/values/{extension_value_id}, where the object is "contracts", and whose id is contract_id

Set an Extension Value on a Contract

See the extension section for an example

POST /contracts/{contract_id}/extensions/fields/{extension_field_id}

This request sets and returns the value of an extension field, specified by its extension_field_id, of an contract, specified by its contract_id. This request is the request POST/{object}/{object_id}/extensions/fields/{extension_field_id} where our object is "contracts" whose id is contract_id.

Contributors

Resource URI: /api/v0/contributors

Contributors are third party contacts who are involved in your client's work. You can easily keep them in the loop on any project or issue by making them a contributor. See the support documentation for more information on contributors. Contributors link Staff or Affiliations to work like Jobs or issues.

The Contributor Object

Example contributor object:

{
 "id": "2",
 "against_id": "7",
 "type_id": "1",
 "against_type": "prospect",
 "description": "Description of work the contributor will do",
 "auto_cc": "0",
 "status_id": null,
 "standing": "active",
 "object_type": "affiliation",
 "object_id": "159"
}

The contributor object contains the following:

Field Type Description
id unsigned A unique identifier for the contributor.
description string The description of the contributor.
standing select The status of the contributor.
status_id unsigned The id of the status associated with the contributor.
against_type string The object the contributor was created against.
against_id unsigned The unique identifier for the object the contributor was created against.
object_type string The type of object linked by the contributor.
object_id unsigned The unique id of the object linked by the contributor.
contributor_type_id unsigned The id of the contributor.
contributor_type unsigned or object The id of or whole contributor type object for the contributor.
auto_cc boolean Whether the contributor will be Auto-CC'd on correspondence.

The Contributor Type Object

Example contributor type object:

"response": {
    "id": "1",
    "title": "Advisor",
    "default_status_id": "2",
    "has_status": "1",
    "auto_cc": "1",
    "default_standing": "active",
    "standing": "active",
    "ordering": "0"
  }

The contributor type object contains the following:

Field Type Description
id unsigned A unique identifier for the contributor.
title string The title of the type
default_status_id unsigned The identifier for the default status of this contributor type.
has_status boolean Whether the contributor type has a status.
auto_cc boolean Whether the contributors of this type will be Auto-CC'd on correspondence.
default_standing string The default standing for this contributor type. Related to the default_status_id.
standing string The current standing for this contributor type. Related to has_status.
ordering unsigned The contributor types order as displayed in the web application.

Get Contributor

Sample Request:

GET /api/v0/contributors/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contributors/{id} \
  -H 'authorization: Bearer {access_token}'

GET /contributors/{id}

This request returns a single contributor, specified by its id.

Configuring the Response

This request supports requesting additional fields and linked objects from the contributor using the _fields parameter.

Handling the Response

The response will be the single requested contributor with its default fields and any additional fields requested through _fields.

List Contributors

Sample Request:

GET /api/v0/contributors HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contributors \
  -H 'authorization: Bearer {access_token}'

GET /contributors

This request returns a list of contributors on the deployment.

Configuring the Request

Pagination

This request accepts all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
standing
status_id
contributor_type_id
against_type
against_id
object_id
object_type
auto_cc
Order Filters

This request supports order filters over the following fields:

Filter Name
id
contributor_type_id
standing
status_id
against_id
auto_cc
Range Filters

This request supports range filters over the following fields:

Filter Name
id
against_id
object_id
contributor_type_id
Searching

This request supports the _search parameter to search over the following fields:

Filter Name
description

Handling the Response

The response will be a list of contributors on the deployment, with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Contributors

Sample Request:

GET /api/v0/contributors/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contributors/count \
  -H 'authorization: Bearer {access_token}'

GET /contributors/count

This request will return a count of contributors in a list defined by any available searches of filters. With no searches or filters this will be a count of all contributors on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of contributors listed.

Get Contributor Type

Sample Request:

GET /api/v0/contributors/types/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contributors/types/{id} \
  -H 'authorization: Bearer {access_token}'

GET /contributors/types/{id}

This request returns a single contributor type, specified by its id.

Configuring the Response

This request supports requesting additional fields and linked objects from the contributor type using the _fields parameter.

Handling the Response

The response will be the single requested contributor type with its default fields and any additional fields requested through _fields.

List Contributor Types

Sample Request:

GET /api/v0/contributors/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contributors/types \
  -H 'authorization: Bearer {access_token}'

GET /contributors/types

This request returns a list of contributor types on the deployment.

Configuring the Request

Pagination

This request accepts all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
title
default_status_id
default_standing
Order Filters

This request supports order filters over the following fields:

Filter Name
ordering

Handling the Response

The response will be a list of contributor types on the deployment, with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Contributor Types

Sample Request:

GET /api/v0/contributors/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contributors/types/count \
  -H 'authorization: Bearer {access_token}'

GET /contributors/types/count

This request will return a count of contributor types in a list defined by any available searches of filters. With no searches or filters this will be a count of all contributors types on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of contributor types listed.

Divisions

Resource URI:
/api/v0/divisions

Divisions allow you manage contacts, companies, and staff under different details, rates, or identities. See the support documentation for more information.

The Division Object (Beta)

Sample division JSON object:

{
    "title": "Support",
    "standing": "active",
    "ordering": "0",
    "id": "1"
}

The division object contains the following:

Name Type Description
id unsigned The unique identifier of the division
title string The title of the division.
standing select Either "active" or "inactive", the standing of the division.
ordering unsigned The division's ordering as displayed on the deployment.

Get Division (Beta)

Sample request:

curl -X get \
    https://{deployment}.api.accelo.com/api/v0/divisions/{division_d} \
    -H 'authorization: Bearer {access_token} \
    -d '_fields=standing'
GET /api/v0/divisions/{division_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

_fields=standing

GET /division/{division_id}

This request returns a division specified by its unique identifier.

Configuring the Response

This request supports requesting additional fields and linked objects from the division object using the _fields parameter.

Handling the Response

The response will be a single division with its default fields and any additional fields requested through _fields.

List Divisions (Beta)

Sample request:

curl -X get \
    https://deployment.api.accelo.com/api/v0/divisions \
    -H 'authorization: Bearer foobar'
    -d '_fields=_ALL'
    -d '_filters=standing(active)'
GET /api/v0/divisions HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

GET /divisions

This request returns a list of divisions on the deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
Order Filters

This request supports order filters over the following fields:

Field
id
ordering
Searching

This request supports the use of the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of divisions with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Divisions (Beta)

Sample request:

curl -X get \
    https://deployment.api.accelo.com/api/v0/divisions/count \
    -H 'authorization: Bearer foobar'
    -d '_fields=_ALL'
    -d '_filters=standing(active)'
GET /api/v0/divisions/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

GET /divisions/count

This request will return a count of divisions in a list defined by any available searches or filters. With no searches or filters this will be a count of all divisions on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the divisions listed.

Expenses

Resource URI:
/api/v0/expenses

In the Accelo API, expenses are against objects, such as jobs, or issues. For example, an expense may be the cost of some training materials, or the cost of travel expenses for a staff member.

The Expenses Object

Sample expense:

{
  "reimbursable": "no",
  "resource": "3",
  "type": "2",
  "quantity": "1.0000",
  "activity_id": "1052",
  "against_type": "job",
  "submitter_id": "14",
  "against_id": "2",
  "id": "2",
  "standing": "submitted",
  "approver_id": "22",
  "title": "Lunch meeting",
  "submitter": "14",
  "billable": "no",
  "price": "78.0000",
  "unit_cost": "78.0000",
  "date_incurred": "1495634400",
  "approver": "22",
  "activity": "1052",
  "type_id": "2"
}

The expense object contains the following fields and linked objects:

Field Type Description
id unsigned A unique identifier for the expense.
title string A title for the expense.
unit_cost decimal The cost for one of the expense.
quantity decimal The quantity of the expense.
standing string The standing of the expense. For example "submitted", "invoiced".
price decimal The cost charged to a customer for one of the expense.
date_incurred unix ts The date the expense was incurred.
activity_id unsigned The unique identifier for the activity against the expense; the id for the note sent to the approver.
type_id unsigned The unique identifier for the type of expense.
approver_id unsigned The unique identifier of the staff member assigned to approve the expense.
submitter_id unsigned The unique identifier of the staff member who submitted the expense.
against_id unsigned The unique identifier of the object the expense is against.
against_type string The type of object the expense is against.
billable string Whether the expense is billable. May be either "yes" or "no".
reimbursable string Whether the expense is reimbursable. May be either "yes" or "no".
approver unsigned or object The staff object of the approver of the expense.
submitter unsigned or object The staff object of the submitter of the expense.
type unsigned or object The expense type object of the expense. Deprecated, please use expense_type.
expense_type unsigned or object The expense type object of the expense.
activity unsigned or object The activity object of the activity against the expense.
resource unsigned or object The resource object (attachment) associated with the expense.

The Expense Type

Sample expense type:

{
  "ledger_id": "3",
  "standing": "active",
  "title": "Food",
  "id": "2"
}

Similarly to contracts, expenses have types associated with them. Expense types may be set up on the Accelo deployment (see the support documentation for information). This expense type object contains the following:

Field Type Description
id unsigned A unique identifier for the type.
title string A name for the type.
standing string The standing of the expense when created.
ledger_id unsigned The unique identifier of the billing ledger associated with this expense type. See the support documentation for information on ledgers.

Note: The type field is deprecated, please request the expense type through the expense_type field, which contains the following additional fields:

Field Type Description
tax_id unsigned The unique identifier of the tax object associated with the expense type.
expense_type_ledger unsigned or object The unique identifier of the ledger associated with the expense type.

Get Expense

Sample Request:

GET /api/v0/expenses/{expense_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses/{expense_id} \
  -H 'authorization: Bearer {access_token}'

GET /expenses/{expense_id}

This request returns a single expense object specified by its expense_id.

Configuring the Request

This request supports requesting additional objects and fields from the expenses object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be a single expense object with its default fields and any additional fields requesting through _fields.

List Expenses

Sample Request:

GET /api/v0/expenses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses \
  -H 'authorization: Bearer {access_token}'

GET /expenses

This request returns a list of expenses on the Accelo deployment.

Configuring the Request

Pagination

This request supports all the pagination parameters:

Additional Fields and Linked Objects

This request also supports requesting extra fields or linked objects of the expenses object using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
type Filter over the type_id. Deprecated, please use expense_type.
expense_type Filter over the expense_type_id.
submitter Filter over the submitter_id.
approver Filter over the approver_id.
against_type
against_id
Date Filters

This request supports date filters over the following fields:

Filter Name
date_incurred
Order Filters

This requesting supports order filters over the following fields:

Filter Name
id
date_incurred
title
standing
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
type Range over type_id. Deprecated, please use expense_type.
expense_type Range over the expense_type_id.
submitter Range over submitter_id.
approver Range over approver_id.
quantity
unit_cost
cost Range over the total cost, that is unit_cost times quantity.
Object Filters

This request supports the following object filters:

Filter Description
against Filter by expenses against these objects.
Searching

This request supports the use of the _search parameter to search over the following fields:

Field
title

handling the Response

This request will return a list of expenses containing the default fields and any additional fields request by _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Expenses

Sample Request:

GET /api/v0/expenses/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses/count \
  -H 'authorization: Bearer {access_token}'

GET /expenses/count

This request will return a count of expenses in a list defined by any available searches or filters. With no searches or filters this will be a count of all expenses on the deployment. This request returns a single field:

Type Description
count unsigned A count of the listed expenses.

Get Expense Type

Sample Request:

GET /api/v0/expenses/types/{type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses/types/{type_id} \
  -H 'authorization: Bearer {access_token}'

GET /expenses/types/{type_id}

This request returns a single expenses type object, specified by its type_id.

Configuring the Response

This request supports requesting extra fields and linked objects from the expenses type object using the _fields parameter.

handling the Response

The response will be a single expense type object with its default fields, and any additional fields requested through _fields.

List Expense Types

Sample Request:

GET /api/v0/expenses/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses/types \
  -H 'authorization: Bearer {access_token}'

GET /expenses/types

This request returns a list of types of expenses on the Accelo deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters:

Additional Fields and Linked Objects

This request supports requesting extra fields and linked objects from the expense type object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
standing
ledger_id
tax_id
Order Filters

This request supports order filters over the following fields:

Filter Name
id
title
standing
Range Filters

This request supports range filters over the following fields:

Filter Name
id
Empty Filters

This request supports empty filters over the following fields:

Field
title
Searching

This request the use of the _search parameter to search over the following fields:

Field
title

handling the Response

The response will contain a list of expense types with their default fields, and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Expense Types

Sample Request:

GET /api/v0/expenses/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses/types/count \
  -H 'authorization: Bearer {access_token}'

GET /expenses/types/count

This request returns a count of expense types in a list defined by any available searches or filters. With no searches or filters this will be a count of all expense types on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of expense types listed.

Update an Expense

Sample Request:

PUT /api/v0/expenses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /expenses/{expense_id}

This request updates and returns an expense, identified by its expense_id.

Configuring the Expense

The following fields from the expense object may be updated through this request:

Field Name
title
quantity
billable
reimbursable
type_id
unit_cost
date_incurred
resource_id

Configuring the Response

This request supports requesting additional fields and linked objects from the expense object using the _fields parameter. This request also supports breadcrumbs.

handling the Response

The response will be the single updated expense object with its default fields, and any additional fields requested through _fields.

Create an Expense

Sample Request:

POST /api/v0/expenses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /expenses

This request creates and returns an expense object.

Configuring the Expense

The following fields from the expense object may be set with this request:

Field Name Notes
title
against_id
against_type
unit_cost
quantity
type_id
price If not included, this will default to unit_cost.
date_incurred
billable
reimbursable
file Allows you to upload a file with the expense (i.e. a receipt in the form of an image or PDF). If this value is set then it must be POSTed with multipart/form-data.
resource_id The unique identifier of a resource (attachment) to be sent with the expense. Note: you may only pass one of resource_id or file.

Configuring the Response

This response supports requesting extra fields and linked objects from the expenses object through the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The request will return the single new expense object with its default fields, and any additional fields requested through _fields.

Delete an Expense

Sample Request:

DELETE /api/v0/expenses/{expense_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/expenses/{expense_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

DELETE /expenses/id

This request removes an expense from the deployment. It takes no parameters and returns no resources.

List Available Progressions on an Expense

See the progressions section for a sample request

GET /companies/{expense_id}/progressions

This request returns a list of available progressions for an expense identified by its expense_id. This is the request GET /{object}/{object_id}/progressions where the object is "companies" whose id is {expense_id}

Auto Run a Progression on an Expense

See the progressions section for a sample request

[PUT|POST] /companies/{expense_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress the status of an expense, specified by its expense_id. This is the request [PUT|POST] /{object}/{object_id}/progressions/{progression_id/auto} where the object is "companies" whose id is {expense_id}.

Extensions (Custom Fields)

Resource URI:
/api/v0/extensions

Extensions, also known as Custom Fields, are similar to profiles. The main difference is in their availability. A given profile may be available to all types of a particular object, for example any type of issues, or even across a range of objects. Conversely, an extension is available to only one type of one object at at time, see also the support documentation. Extensions may be set up through the Accelo deployment, see the support documentation for information on setting them up. Currently the following objects support extensions through the API:

Similarly to profiles, extensions are described by extension fields and extension values, which store the information of values of an extension field.

The Extension Field Object

Sample extension field:

{
  "link_type": "job",
  "default_value": "national",
  "lookup_type": null,
  "field_type": "fixed_select",
  "field_name": "Project Work Location",
  "link_type_id": "1",
  "information": "Will the work be carried out internationally?",
  "options": [
    "national",
    "international"
  ],
  "exported": "no",
  "ordering": "0",
  "id": "9",
  "required": "no",
  "important": "no",
  "archived": "no"
}

These are objects describing the custom field on the deployment, they contain the following:

Field Type Description
id unsigned A unique identifier for the extension.
field_name string A name for the extension.
field_type select The type of extension, may be either "text", "textbox", "int", "date", "date_time", "float", "certify", "fixed_select", "flexible_select", "multi_select", "lookup", "currency", "hyperlink", or "contributor".
link_type_id unsigned The unique identifier of the type of object this extension is linked to. For example, if "link_type" is job, this will be the id of the job type that this extension can appear under.
link_type string The type of object the extension is linked to.
ordering int The extension's order on the Accelo deployment.
required select Either "yes" or "no", whether this extension is required for the object it is linked to.
archived select Either "yes" or "no", whether this extension is no longer in use and has been archived.
exported select Either "yes" or "no", whether this extension is exported when the linked object is exported.
important select Either "yes" or "no", whether this extension has been marked as "important" on the Accelo deployment.
default_value dynamic The default value for the field, the type will depend on the field_type.
lookup_type string When field_type is lookup, this will contain the type of object for the lookup.
information string Any extra information about the extension.

The Extension Value Object

Example extension field value:

{
  "value": "one, two",
  "id": "1684",
  "is_sensitive": "0",
  "field_description": null,
  "link_type": "job",
  "date_modified": "1528787815",
  "link_type_id": "5",
  "field_type": "multi_select",
  "is_important": "1",
  "field_id": "111",
  "field_name": "Configuration Values",
  "values": [
    "one",
    "two"
  ],
  "is_exported": "0",
  "link_id": "1197",
  "modified_by": "44",
  "default_value": ""
}

These describe the value of a given extension field, identified by the field_id. This object contains the following:

Field Type Description
id unsigned A unique identifier for the extension value.
field_type string The field_type of the related extension field.
file_name string The name of the related extension field.
value dynamic The value for the extension, the type will depend on the field_type of the related extension field. If field_type is "lookup" then this will be the title of the linked object. If field_type is "contributor" it will be the name of the affiliation or staff who is the contributor. If it's a "multi_select" this will be all the selected values joined by a comma e.g. "one, two" for ["one", "two"]
values* array When the field type is "multi_select", this will contain an array of the selected values. e.g, ["one", "two"]
field_id unsigned The unique identifier of the related extension field.
link_id unsigned The unique identifier of the object the profile value is against.
link_type string The type of object the related extension field is linked to.
link_type_id unsigned The unique identifier of the type of object the related extension is linked to.
date_modified unix ts The date this extension value was last modified.
modified_by unsigned or object The staff member who last modified this extension value.
default_value dynamic The default value of the related extension field.
is_sensitive bool Whether this value can only be viewed by people with "sensitive" permissions for the link_type object. See the support documentation for information on setting permissions.
is_important bool Whether the related extension field is marked as "important".
is_exported bool Whether the related extension field is "exported".
value_id unsigned If field_type is "lookup" or "contributor" this will be the ID of the lookup object (e.g, the company id) or the contributor id
value_type string If field_type is "lookup" or "contributor" this will be the type of lookup object (e.g, "company") or "contributor"
field_description string Any extra information about the extension field used by the value.
default_value dynamic The default value for the extension field use by the value, the type will depend on the field_type.
field_name string The name of the extension field used by the value.

* The values field is only returned when the field_type is "multi_select". When it's "multi_select", it's returned by default.

List Extension Fields

Sample Request:

GET /api/v0/contracts/extensions/fields HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/extensions/fields
  -H 'authorization: Bearer {access_token}'

GET /{object}/extensions/fields

This request request returns a list of extension fields available for the given object

Configuring the Response

Pagination

This request supports all of the pagination parameters

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the extension field object using the _fields parameter.

Handling the Response

The response will be a list of extension field object with their default fields, and any additional fields requested using _fields.

List Objects Extension Values

Sample Request:

GET /api/v0/contracts/{contract_id}/extensions/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}/extensions/values
  -H 'authorization: Bearer {access_token}'

GET /{object}/{object_id}/extensions/values

This request returns a list of extension field values for the given object identified by its object_id.

Configuring the Response

Pagination

This request supports all of the pagination parameters

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the extension value object using the _fields parameter.

Handling the Response

The response will be a list of extension field values with their default fields, and any additional fields requested through _fields.

List Extension Values

Sample Request:

GET /api/v0/contracts/extensions/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/contracts/extensions/values
  -H 'authorization: Bearer {access_token}'

GET /{object}/extensions/values

This request returns a list of extension field values for the given object.

Configuring the Response

Pagination

This request supports all of the pagination parameters

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the extension value object using the _fields parameter.

Update an Extension Field Value

Sample Request, here we are updating the value of an extension field value of "jobs/56" to be "international":

PUT /api/v0/jobs/56/extensions/values/4 HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

value=international
curl -X put \
  https://{deployment}.api.accelo.com/api/v0/jobs/56/extensions/values/4 \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'
  -d 'value=international'

PUT /{object}/{object_id}/extensions/values/{extension_value_id}

This request updates and returns a extension values, specified by its extension_value_id, of a particular object, specified by its object_id, of a particular type, specified by object.

Configuring the Extension Value

This request updates the value of an extension value, since this object is dynamic the field we send will depend on the type of value:

Field Type Description
value_int int If field_type is "integer", update the value with this integer.
value_date unix ts If field_type is "date", "date_time", or "certify", update the value with this string.
value_id int If field_type is "lookup" or "contributor", update the value with this integer, representing an object id.
value_type string If 'field_type' is "lookup", update the value_type with this string.
value string If field_type is none of the above, update the value with this string.

Configuring the Response

This request supports requesting additional fields and linked objects from the extension value object using the _fields parameter.

Handling the Response

This request will return the single, updated extension value object with its default fields, and any additional fields requesting through _fields.

Set an Extension Field Value

Sample Request, here we are setting a value for an extension field value for "jobs/12":

PUT /api/v0/jobs/59/extensions/fields/12 HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

value=international
curl -X put \
  https://{deployment}.api.accelo.com/api/v0/jobs/59/extensions/fields/12 \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'
  -d 'value=international'

POST /{object}/{object_id}/extensions/fields/{extension_field_id}

This request sets and returns an extension value. for an extension field, specified by its extension_field_id. The object whose profile field is to be updated is identified by object and object_id

Configuring the Extension Value

This request accepts the same fields as the previous request, that is, it takes only the relevant value field(s). These fields are required for this request.

Configuring the Response

This request supports requesting additional fields and linked objects from the extension value object using the _fields parameter.

Handling the Response

This request will return the newly created extension value object with its default fields and any additional fields requested using _fields.

Filters

Resource URI:
/api/v0/filters

Filters are available on the Accelo deployment that allow you to search through the resources on the deployment. These filters may be customized and saved on the deployment, see the support documentation for more information. Currently these filters are supported through the API on the following objects:

The Filter Object

Example filter object:

{
  "object_type": "affiliation",
  "shared": "yes",
  "staff_id": "14",
  "staff": "14",
  "title": "Custom filter on affiliations",
  "id": "1"
}

This object stores information on the filter, such as who created it, and which type of resource it is used on. It contains the following:

Field Type Description
id unsigned A unique identifier for the filter.
title string A name for the filter.
object_type string The object type the filter may be used on. For example "affiliations".
shared select Either "yes" or "no", whether the filter is selected to be shared on the Accelo deployment.
staff_id unsigned The unique identifier of the staff member who made the filter.
staff unsigned or object The staff member who created the filter.

List Filters

Sample Request:

GET /api/v0/filters HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/filters \
  -H 'authorization: Bearer {access_token}'

GET /filters

This request returns a list of saved filters on the Accelo deployment. This list will not include any filters created by other users which have not been shared.

Configuring the Response

Pagination

This request supports the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects through the fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
shared
staff Filter by staff_id.
object_type
Order Filters

This request supports order filters over the following fields:

Filter Name
id
title
shared
Range Filters

This request supports range filters over the following fields:

Filter Name
id

Handling the Response

The response will be a list of filter objects containing their default values, and any additional values requested through _fields, and displayed according to any pagination parameters or filters used.

List Filters Against an Object

Sample Request:

GET /api/v0/{object}/filters HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/{object}/filters \
  -H 'authorization: Bearer {access_token}'

GET /{object}/filters

This request returns a list of filters saved against a particular object, specified by object. This list will not include any filters created by other users which have not been shared.

Configuring the Response

Pagination

This request supports the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects through the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
shared
staff Filter by staff_id.
Order Filters

This request supports order filters over the following fields:

Filter Name
id
title
shared
Range Filters

This request supports range filters over the following fields:

Filter Name
id

Handling the Response

The response will be a list of filter objects saved against the given object, containing their default values, and any additional values requested through _fields, and displayed according to any pagination parameters or filters used.

Update a Filter

Sample Request:

PUT /api/v0/filters/{filter_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/filters/{filter_id} \
  -H 'authorization: Bearer {access_token}'

PUT|POST /filters/{filter_id}

This request allows you to update a saved filter on the Accelo deployment.

Configuring the Filter

The following fields from the filter object may be updated with this request:

Filter Name
title
shared

Configuring the Response

This request supports requesting additional fields and linked objects from the filter object using the _fields parameter.

handling the Response

The response will be the single, updated filter object containing its default fields, and any additional fields requested via _fields

Run a Filter

Sample Request:

GET /api/v0/filters/{filter_id}/run HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/filters/{filter_id}/run \
  -H 'authorization: Bearer {access_token}'

GET /filters/{filter_id}/run

This request allows you to run, and see the output of, a filter.

Configuring the Response

Pagination

This request accepts the following pagination parameters:

Filter Name
_limit
Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects through the _fields parameter. This parameter will be applied to whatever object the filter is used for, that is, the object_type.

Handling the Response

The response will be a list of objects that are of type object_type, with their default fields, and any additional fields requested through _fields, and displayed according to the value of _limit set.

Groups

Groups allow you to categorize your staff for bulk assignments and access controls. See the support documentation for more information.

The Group Object (Beta)

Sample JSON group object:

{
    "parent_id": "0",
    "id": "2",
    "standing": "active",
    "title": "Support"
}

The group object contains the following:

Field Type Description
id unsigned The unique identifier for the group.
title string The title of the group.
parent_id unsigned The unique identifier of the parent group, if no parent then this is "0".
standing select One of "active" or "inactive", the standing of the group.

Get Group (Beta)

Sample Request

curl -X get \
    https://{deployment}.api.accelo.com/api/v0/groups/{group_id} \
    -H 'authorization: Bearer {access_token}' \
    -d '_fields=standing'
GET /api/v0/groups/{group_id} HTTP/1.1
Host: https://{deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: www/x-form-urlencoded

_fields=standing

GET /groups/{group_id}

This request returns a group specified by its unique group_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the group object using the _fields parameter.

Handling the Response

The response will be a single group with its default fields and any additional fields requested through _fields.

List Groups (Beta)

Sample Request

curl -X get \
    https://{deployment}.api.accelo.com/api/v0/groups \
    -H 'authorization: Bearer {access_token}' \
    -d '_fields=standing' \
    -d '_filters=parent_id(3)'
GET /api/v0/groups HTTP/1.1
Host: https://{deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: www/x-form-urlencoded

_fields=standing
_filters=parent_id(3)

GET /groups

This request returns a list of groups on the deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the group object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Field Description
id
title
staff_id Filter group(s) to which the staff member with this id belongs.
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of group objects with the default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Groups (Beta)

Sample Request

curl -X get \
    https://{deployment}.api.accelo.com/api/v0/groups/count \
    -H 'authorization: Bearer {access_token}' \
    -d '_filters=standing(active)'
GET /api/v0/groups/count HTTP/1.1
Host: https://{deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: www/x-form-urlencoded

_fields=standing
_filters=standing(active)

GET /groups/count

This request will return a count of groups in a list defined by any available searches or filters. With no searches or filters this will be a count of all requests on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of groups satisfying the query.

Holidays (Beta)

A user's holidays are available through the API as the "holiday" object.

The Holiday Object (Beta)

Sample holiday:

{
    "id": "2",
    "duration_seconds": null,
    "date_end": "1432216800",
    "staff_id": "1041",
    "date_start": "1432130400",
    "staff": "1041",
    "title": "OOO - Sister's Graduation"
}

The holiday object contains the following:

Field Type Description
id unsigned The unique identifier for the holiday.
staff_id unsigned The unique identifier of the staff who belongs to the holiday.
date_start unix ts The date the holiday is set to start.
title string A name for the holiday
date_end unix ts The date the holiday is set to end. Note: only one of date_end and duration_seconds should have a value.
duration_seconds int The length of the holiday, in seconds. Note: only one of date_end and duration_seconds should have a value.
staff() object The staff member who belongs to the holiday.

Get Holiday (Beta)

GET /holidays/{holiday_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/holidays/{holiday_id} \
    -H 'authorization: Bearer {access_token} \

GET /holidays/{holiday_id}

This request returns a single holiday, specified by its holiday_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the holiday object using the _fields parameter.

Handling the Response

The response will be a single holiday with its default fields and any additional fields requested through _fields.

List Holidays (Beta)

GET /holidays/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/holidays/ \
    -H 'authorization: Bearer {access_token} \

GET /holidays/

This request returns a list of holidays.

Configuring the Response

Pagination

This request supports all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the holiday object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
staff_id
Date Filters

This request supports date filters over the following fields:

Field
date_start
date_end
Range Filters

This request supports range filters over the following fields:

Field
id
staff_id
date_start
date_end
duration_seconds
Order Filters

This request supports order filters over the following fields:

Field
id
staff_id
date_start
date_end
title
duration
Empty Filters

This request supports the following empty filters:

Filter
date_end
duration_seconds
Searching

This request supports the _search to search over the following fields:

Field
title

Handling the Response

The response will be a list of holidays with their default fields and any additional fields requested through _fields, and displaying according to any pagination parameters, filters, or searches used.

Count Holidays (Beta)

GET /holidays/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deployment}.api.accelo.com/api/v0/holidays/count \
    -H 'authorization: Bearer {access_token} \

GET /holidays/count

This request returns a count of holidays in a list defined by any available searches or filters. With no searches or filters this will be a count of all holidays on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of holidays listed.

Update Holiday (Beta)

PUT /holidays/{holiday_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X PUT \
    https://{deployment}.api.accelo.com/api/v0/holidays/{holiday_id} \
    -H 'authorization: Bearer {access_token} \

PUT /holidays/{holiday_id}

This request updates and returns a holiday specified by its holiday_id.

Configuring the Holiday

The following fields from the holiday object may be updated through this request, (date fields may be sent as unix timestamps, or in ISO8601 format):

Field
title
staff_id
date_start
date_end
duration_seconds

Note: you may only update one of date_end or duration_seconds.

Configuring the Response

The response may be configuring as per Get Holiday

Handling the Response

The response will be the single, updated holiday with its default fields and any additional fields requested through _fields.

Create Holiday (Beta)

POST /holidays/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X POST \
    https://{deployment}.api.accelo.com/api/v0/holidays/ \
    -H 'authorization: Bearer {access_token} \

POST /holidays

This request creates and returns a holiday.

Configuring the Holiday

The following fields may be set through this request, (date fields may be sent as unix timestamps, or in ISO8601 format):

Field
title
date_start
date_end
duration_seconds
staff_id

Note: only one of date_end or duration_seconds is required; both cannot be sent.

Handling the Response

The response may be configuring as per Get Holiday

Handling the Response

The response will be the new holiday with its default fields and any additional fields requested through _fields.

Delete Holiday (Beta)

DELETE /holidays/{holiday_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X DELETE \
    https://{deployment}.api.accelo.com/api/v0/holidays/{holiday_id} \
    -H 'authorization: Bearer {access_token} \

DELETE /holidays/{holiday_id}

This request removes a holiday from the deployment, identified by their staff_id. This request takes no parameters and returns no resources.

Invoices

Resource URI:
/api/v0/invoices

These are invoices for any work done. See the support documentation for more information on invoices.

The Invoice Object

Example invoice object:

{
  "date_modified": "1493864641",
  "outstanding": "210.00",
  "tax": "10.00",
  "modified_by": "14",
  "creator_id": "14",
  "id": "75",
  "date_due": "1495074035",
  "currency_id": "0",
  "amount": "200.00",
  "contact": "98",
  "affiliation_id": "98",
  "owner_id": "14",
  "subject": "My Test Invoice",
  "notes": "Some Customer Description/Notes",
  "date_raised": "1493864435",
  "created_by": "14",
  "invoice_number": null,
  "affiliation": "98"
}

The invoice object contains the following:

Field Type Description
id unsigned A unique identifier for the invoice.
amount decimal The value of the invoice, less any tax.
subject string The title of the invoice
against_type string The object the invoice was created against.
against_id unsigned The unique identifier for the object the invoice was created against.
notes string Any notes made on the invoice.
invoice_number integer If the invoice has been pushed to an accounting system (e.g. Xero, Quickbooks Online, Saasu, etc.), then this will be the invoice number generated by this system.
currency_id unsigned The unique identifier for the currency used on the invoice.
owner_id unsigned The unique identifier for the staff member labeled as the owner on the deployment.
tax decimal The value of any tax on the invoice.
outstanding decimal The value of the invoice left unpaid, including taxes.
modified_by unsigned The unique identifier of the staff member who last modified the invoice.
date_raised unix ts The date the invoice was raised.
date_due unix ts The date the invoice is due.
date_modified unix ts The date the invoice was last modified.
contact unsigned or object The contact to whom the invoice is to be billed.
affiliation_id unsigned The unique identifier for the affiliation the invoice is raised against.
affiliation unsigned or object The affiliation against whom the invoice is raised.
creator_id unsigned The unique identifier for the staff member who created the deployment.
created_by unsigned or object The staff member who created the invoice.

The Line Item (Beta)

Example line item:

{
    "id": "42",
    "quantity": "1.000000",
    "ordering": "0",
    "type": "service",
    "tax": "2730.00",
    "invoice_line_item_ledger": "6",
    "ledger_id": "6",
    "tax_id": "1",
    "invoice_line_item_tax": "1",
    "description": "The initial kick-off, 40% of total cost",
    "rate": "27300.000000",
    "invoice_id": "5736",
    "total": "30030"
}

Each line in an invoice is described by a line item object. This object contains the following:

Field Type Description
id unsigned A unique identifer for the line item.
type select The type of the item, either "material", "service", or "expense".
quantity decimal The quantity of the item to be invoiced.
rate decimal The price charged per unit of the item.
total decimal The total price for the line, including tax.
tax decimal The value of tax on the line item.
invoice_id unsigned The unique identifier of the invoice the line is part of.
ledger_id unsigned The unique identifier of the ledger the invoice item is attached to.
tax_id unsigned The unique identifier for the tax associated with the item.
description string A description of the invoice line.
ordering unsigned The order the line is displayed on the invoice.
line_item_ledger unsigned or object The ledger the invoice item is attached to.
line_item_tax unsigned or object The tax code associated with the invoice item.

Get Invoice

Sample Request:

GET /api/v0/invoices/{invoice_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/invoices/{invoice_id} \
  -H 'authorization: Bearer {access_token}'

GET /invoices/{invoice_id}

This request returns a single invoice, specified by its invoice_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the invoice object using the _fields parameter.

Handling the Response

The response will be the single requested invoice with its default fields and any additional fields requested through _fields.

List Invoices

Sample Request:

GET /api/v0/invoices HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/invoices \
  -H 'authorization: Bearer {access_token}'

GET /invoices

This request returns a list of invoices on the deployment.

Configuring the Request

Pagination

This request accepts all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
invoice_number
Date Filters

This request supports date filters over the following fields:

Filter Name
date_raised
date_due
date_modified
Order Filters

This request supports order filters over the following fields:

Filter Name
id
date_raised
date_due
date_modified
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
amount
tax
outstanding
created_by Range by the staff_id of the creator.
affiliation Range by affiliation_id.
modified_by Range by the staff_id of the person to last modify the invoice.
Searching

This request supports the _search parameter to search over the following fields:

Filter Name
subject
invoice_number

Handling the Response

The response will be a list of invoices on the Deployment, with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Invoices

Sample Request:

GET /api/v0/invoices/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/invoices/count \
  -H 'authorization: Bearer {access_token}'

GET /invoices/count

This request will return a count of invoices in a list defined by any available searches or filters. With no searches or filters this will be a count of all invoices on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of invoices listed.

List an Invoice's Profile Field Values

See the profiles section for a sample request

GET /invoices/{invoice_id}/profiles/values

This request returns a list of profile values of an invoice, specified by its invoice_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "invoices", and whose id is {invoice_id}.

List all Profile Field Values on an Invoice

See the profiles section for a sample request

GET /invoices/profiles/values

This request returns a list of all profile field values on invoices. This is the request GET /{object}/profiles/values, where the object is "invoices".

List Invoices Profile Fields

See the profiles section for a sample request

GET /invoices/profiles/fields

This request returns a list of profile fields available for invoices. This is the request GET /{object}/profiles/fields where the object is "invoices".

Update a Profile Value on an Invoice

See the profiles section for a sample request

PUT /invoices/{invoice_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular invoice, specified by its invoice_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "invoices", and whose value is {invoice_id}.

Set a Profile Value on an Invoice

See the profiles section for a sample request

POST /invoices/{invoice_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for an "invoice", specified by its invoice_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "invoices", and whose value is {invoice_id}.

Get Line Item (Beta)

Sample Request:

GET /api/v0/invoices/line_items/{line_item_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/invoices/line_items/{line_item_id} \
  -H 'authorization: Bearer {access_token}'

GET /invoices/line_items/{line_item_id}

This request returns a line item specified by its line_item_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the line item object using the _fields parameter.

Handling the Response

The request will return the single invoice line item with its default fields and any additional fields requested through _fields.

List Line Items (Beta)

Sample request:

GET /api/v0/invoices/line_items/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/invoices/line_items \
  -H 'authorization: Bearer {access_token}'

This request returns a list of invoice line item.

Configuring the Response

Pagination

This request supports all of the standard pagination parameters

Additional Fields and Linked objects

This request supports requesting additional fields and linked objects from the line item object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
invoice_id
ledger_id
tax_id
Order Filters

This request supports the following order filters:

Filter
id
invoice_id
ledger_id
tax_id
quantity
rate
total
ordering
Range Filters

This request supports range filters over the following fields:

Filter
id
invoice_id
ledger_id
tax_id
quantity
rate
total
Searching

This request supports the _search parameter to search over the following fields:

Field
description

Handling the Response

The response will contain a list of invoice line items with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Line Items (Beta)

Sample request:

GET /api/v0/invoices/line_items/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/invoices/line_items/count \
  -H 'authorization: Bearer {access_token}'

GET /invoices/line_items/count

This request will return a count of line items in a list defined by any available searches or filters. With no searches or filters this will be a count of all line items on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of line items listed.

Issues (Tickets)

Resource URI: /api/v0/issues

Issues (also known as "Tickets") are used for when you need to track billable time against a client, but don’t need the complexity of a full Project and its workflow and components. For example, issues may be used to track support cases where you’re diagnosing and fixing a problem and don’t know beforehand the specific steps which will be required to resolve the Issue. See the support documentation for more information on these objects.

The Issue Object

Example issue object:

{
  "assignee": "14",
  "title": "Issue with public field",
  "referrer_type": null,
  "affiliation": "98",
  "date_submitted": "1493872605",
  "date_modified": "1553728167",
  "resolution_detail": "I fixed the field, it now displays as expected.",
  "staff_bookmarked": "1",
  "against": "companies/39",
  "contract": "1",
  "billable_seconds": "1400",
  "submitted_by": "14",
  "against_type": "company",
  "date_due": "1493906400",
  "contact": "98",
  "date_closed": "1495683190",
  "standing": "closed",
  "object_budget": "8",
  "date_started": "1493820000",
  "class": "19",
  "resolved_by": "14",
  "date_last_interacted": "1493872783",
  "resolution": "8",
  "closed_by": "14",
  "date_resolved": "1495683190",
  "referrer_id": null,
  "custom_id": "",
  "status": "4",
  "opened_by": "14",
  "type": "1",
  "description": "A public field is showing as public",
  "against_id": "39",
  "id": "7",
  "company": "39",
  "issue_priority": "1",
  "date_opened": "1493872605"
}

The issue object contains the following:

Field Type Description
id unsigned A unique identifier for the issue.
title string A name for the issue
custom_id string The custom ID for the issue. Only issues whose type allows custom IDs will have a value for this field.
description string A description of the issue.
against string The API URI of the object this issue is against.
against_type string A string representing the type of object this issue is against.
against_id unsigned The unique identifier of the object this issue is against.
type unsigned or object The issue type of this issue. Deprecated, please use issue_type.
issue_type unsigned or object The issue type of this issue.
affiliation unsigned or object The affiliation associated with this issue.
class unsigned or object The issue class of this issue.
priority unsigned or object Deprecated please use issue_priority
issue_priority unsigned or object The priority of the issue.
resolution unsigned or object The resolution type used by the issue, if it has been resolved.
resolution_detail string A description of the resolution, if resolved.
status unsigned or object The status of the issue.
standing string The standing of the issue, taken from the issue status.
date_submitted unix ts The date the issue was submitted
submitted by unsigned or object The staff member who submitted the issue.
date_opened unix ts The date the issue was opened.
opened_by unsigned or object The staff member who opened the issue.
date_resolved unix ts If resolved, the date the issue was resolved.
resolved_by unsigned or object The staff member who resolved the issue.
date_closed unix ts If closed, the date the issue was closed.
closed_by unsigned or object The staff member who closed the issue.
date_due unix ts The due date for the issue.
date_last_interacted unix ts The date the issue was last interacted with.
date_modified unix ts The date the issue was last modified.
referrer_type string If the issue was created from the deployment as a "related issue" to an object, this will be the object's type.
referrer_id unsigned The unique identifier of this related object.
staff_bookmarked boolean Whether the current viewer has bookmarked the issue.
billable_seconds unsigned The amount of billable time, in seconds, on the issue.
company unsigned or object If against_type is company, the company the issue is against.
assignee unsigned or object The staff assigned to the issue.
contract unsigned or object If the issue is assigned a contract (retainer), this will return the contract object.
issue_object_budget unsigned or object The object budget associated with the issue.
object_budget unsigned or object Deprecated please use issue_object_budget.

The Issue Priority

Example priority object:

{
  "title": "Extreme",
  "id": "1",
  "color": "Red",
  "factor": "5"
}

Issue priorities help you keep track of what needs to be done. They may be set up from the deployment, see the support documentation for information. They contain the following:

Field Type Description
id unsigned A unique identifier for the priority.
title string A name for the priority.
color select The color of the priority when displayed on the deployment. The colors, in order of increasing urgency a "grey", "blue", "green", "orange", "red".
factor unsigned A number representing the urgency of the priority. 5 is "Extreme", 1 is "None".

The Issue Status

Example issue status object:

{
  "standing": "open",
  "start": "yes",
  "color": "yellow",
  "ordering": "2",
  "title": "Open",
  "id": "2"
}

Statuses may be used to track the progress of an issue. These statuses may be configured from the deployment, see the support documentation for more information. The status objects contain the following

Field Type Description
id unsigned A unique identifier for the status.
title string A name for the status.
standing string A string describing the standing of the issue.
color string The color of the status shown on the deployment.
start select Either "yes" or "no", whether an issue may be created with this status.
ordering unsigned A number describing the order of the status on the deployment.

The Issue Type

Example issue type object:

{
  "notes": "Issue type for support issues.",
  "standing": "active",
  "title": "Support",
  "id": "2",
  "parent": "0"
}

Issue types let you sort your issues according to the type of work the entail. Issue types may be set up and edited from the deployment, see the support documentation for more information.

Field Type Description
id unsigned A unique identifier for the issue type.
title string A name for the issue type.
notes string Notes about the issue type.
parent unsigned The unique identifier of the parent issue type. If there is no parent has the value "0"
standing select Either "active" or "inactive", the standing of the issue type.
budget select Either "yes" or "no", whether issues under this type are billable.
ordering unsigned A number describing the type's ordering on the deployment.
default_issue_class unsigned or Object The default issue class for issues created with this type.
default_issue_priority unsigned or Object The default issue_priority for issues created with this type.

Note: the type field is deprecated, please request the issue type object through the issue_type field, which contains the following additional fields:

Field Type Description
default_class_id unsigned The unique identifier of the default issue class for this type of issue. Default is null.
has_custom_id boolean Either "1" or "0", whether the issue type uses custom ids.

The Issue Resolution

Example issue resolution:

{
  "standing": "active",
  "title": "Support Resolution",
  "id": "8",
  "parent": "7",
  "report": "Use this resolution when resolving support issues.",
  "description": "I fixed the field, it now displays as expected."
}

Issue resolutions track how certain issues are resolved and may be set up on the deployment, see the support documentation for more information. The issue resolution contains the following:

Field Type Descriptions
id unsigned A unique identifier for the issue resolution.
title string A name for the issue resolution.
parent unsigned The unique identifier of the parent resolution, it there is no parent this has value "0".
description string A generic description of the resolution, may be changed for a given issue.
report string A fixed description of the resolution.
standing select Either "active" or "inactive", the standing of the resolution.

The Issue Class

Example issue class:

{
  "standing": "active",
  "description": "For issues pertaining to our website",
  "parent": "0",
  "title": "Website",
  "id": "2"
}

Issue classes help to classify symptoms or characteristics of an issue. They can be set up from the deployment, see the support documentation for information. Ticket classes contain the following:

Field Type Description
id unsigned A unique description for the class.
title string A name for the class.
description string A description of the class.
parent unsigned The unique identifier of the parent class, if there is no parent this has value "0".
standing select Either "active" or "inactive", the standing of the class.

Get Issue

Sample Request:

GET /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
  -H 'authorization: Bearer {access_token}'

GET /issues/{issue_id}

This request returns a single issue, identified by its issue_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the issue object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single requested issue with its default fields, and any additional fields requested through _fields.

List Issues

Sample Request:

GET /api/v0/issues HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues \
  -H 'authorization: Bearer {access_token}'

GET /issues

This request returns a list of issue objects on the deployment.

Pagination

This request supports the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the issues object using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
custom_id
referrer_type
referrer_id
against_id
against_type
status Filter by the status_id of the issue.
type Filter by the type_id of the issue. Deprecated, please use issue_type.
issue_type Filter by the issue_type_id.
affiliation Filter by the affiliation_id of the issue.
class Filter by the class_id of the issue.
priority Deprecated, please use issue_priority
issue_priority Filter by the priority_id of the issue.
resolution Filter by the resolution_id of the issue.
submitted_by Filter by the staff_id of the submitter.
opened_by Filter by the staff_id of the user who opened the issue.
closed_by Filter by the staff_id of the user who closed the issue.
resolved_by Filter by the staff_id of the user who resolved the issue.
assignee Filter by the staff_id of the assignee.
contract Filter by the contract_id of any linked contracts.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_opened
date_submitted
date_started
date_due
date_closed
date_modified
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
id
date_opened
date_submitted
date_started
date_due
date_closed
date_resolved
date_last_interacted
date_modified
title
standing
status Order by the status_id
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
reopened_count Range over the number of times the issue has been reopened.
rate_charged
against_id
billable_seconds
assignee Range over the staff_id of assignees.
type Range over the type_id. Deprecated, please use issue_type.
issue_type Range over issue_type_id.
affiliation Range over the affiliation_id.
class Range over the class_id.
resolution Range over the range_id.
priority Deprecated, please use issue_priority
issue_priority Range over the priority_id.
submitted_by Range over the staff_id of submitters.
opened_by Range over the staff_id of staff members who opened issues.
resolved_by Range over the staff_id of staff members who resolved issues.
closed_by. Range over the staff_id of staff members who closed issues.
status Range over the status_id.
rate Range over the rate_id of the rate charged.
contract Range over the contract_id of contracts linked to issues.
Object Filters

This request supports the following object filters:

Filter Name Description
against Filter by issues against these objects.
referrer Filter by issues referred by these objects.
Searching

This request supports using the _search function to search over the following fields:

Field
subject

Handling the Response

This request will return a list of issues containing the default fields and any additional fields request by _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Issues

Sample Request:

GET /api/v0/issues/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/count \
  -H 'authorization: Bearer {access_token}'

GET /issues/count

This request will return a count of issues in a list defined by any available searches or filters. With no searches or filters this will be a count of all issues on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the issues listed.

List Recent Issues

Sample Request:

GET /api/v0/issues/recent HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/recent \
  -H 'authorization: Bearer {access_token}'

GET /issues/recent

This request returns a list of issues on the deployment sorted by most recently submitted, that is, in descending order of date_submitted.

Configuring the Request

This request accepts the same parameters and filters over the same fields as the GET /issues request, although it will always be ordered in descending order of date_submitted.

Handling the Response

This request will return a list of contacts displayed according to any parameters used, and with their default fields plus any additional fields requested by _fields, and ordered in descending order of date_submitted.

List Issue Statuses

Sample Request:

GET /api/v0/issues/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/statuses \
  -H 'authorization: Bearer {access_token}'

GET /issues/statuses

This request returns a list of issue statuses on the deployment.

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the issue status object through the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

This request will return a list of issue statuses with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters or searches used.

Get Issue Type

Sample request:

GET /api/v0/issues/types/{issue_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/issues/types/{issue_type_id} \
  -H 'authorization: Bearer {access_token}'

GET /issues/types/{issue_type_id}

This request returns an issue type specified by its unique id.

Configuring the Response

This request supports request additional fields and linked objects from the issue type using the _fields parameter.

Handling the Response

The response will contain a single issue type with its default fields and any additional fields requested through _fields.

List Issue Types

Sample Request:

GET /api/v0/issues/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/types \
  -H 'authorization: Bearer {access_token}'

GET /issues/types

This request returns a list of issue types on the deployment. The _filters parameter is set to standing_not(inactive) by default.

Configuring the Response

Pagination

This request supports the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the issue type object using the _fields parameter. Note this request does not support the _ALL argument for this parameter.

Handling the Response

The response will be a list of issue types with their default fields and any additional fields requested through _fields.

Basic Filters

This request supports the following basic filters:

Filter
id
standing
budget
default_class_id
parent
Order Filters

This request supports order filters over the following fields:

Field
id
title
standing
ordering
Range Filters

This request supports range filters over the following fields:

Field
id
Searching

This request supports the _search parameter to search over the following fields:

Field
title

List Issue Classes

Sample Request:

GET /api/v0/issues/classes HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/classes \
  -H 'authorization: Bearer {access_token}'

GET /issues/classes

This request returns a list of issue classes on the deployment.

Configuring the Response

This request supports requesting additional fields and linked objects from the issue class object using the _fields parameter. Note this request does not support the _ALL argument for this parameter.

Handling the Response

The response will be a list of issue types with their default fields and any additional fields requested through _fields.

Get Issue Resolution

Sample request:

GET /api/v0/issues/resolutions/{resolution_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/issues/resolutions/{resolution_id} \
  -H 'authorization: Bearer {access_token}' \

GET/issues/resolutions/{resolution_id}

This request returns a single issue resolution, specified by its resolution_id.

Configuring the Response

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the issue resolution using the _fields parameter.

Handling the Response

The response will be the single issue resolution with its default fields, and any additional fields requested through _fields.

List Issue Resolutions

Sample request:

GET /api/v0/issues/resolutions HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/issues/resolutions \
  -H 'authorization: Bearer {access_token}' \

GET/issues/resolutions

Returns a list of issue resolutions.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the issue resolution using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Description
id
standing
parent_id
Order Filters

This request supports the following order filters:

Filter Description
id
standing
title
Range Filters

This request supports range filters over the following fields:

Field
id
Empty Filters

This request supports empty filters over the following fields:

Field
title
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of issue resolutions with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Issue Resolutions

Sample request:

GET /api/v0/issues/resolutions/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/issues/resolutions/count \
  -H 'authorization: Bearer {access_token}' \

GET/issues/resolutions/count

This request returns a count of issue resolutions in a list defined by any available filters or searches. With no searches or filters this will be a count of all issue resolutions on the deployment. This request returns a single field:

Field Type Description
count Unsigned A count of issue resolutions listed

List Tasks Against an Issue

Sample Request: GET /issues/{issue_id}/tasks

GET /api/v0/issues/{issue_id}/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/tasks \
  -H 'authorization: Bearer {access_token}'

This request returns a list of tasks against an issue specified by its issue_id.

Configuring the Response

This response may be configuring in the same way as GET /tasks

Handling the Response

This response may be handled in the same way as GET /tasks

Update an Issue

Sample Request:

PUT /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /issues/{issue_id}

This request updates and returns an issue object, identified by its issue_id.

Configuring the Issue

The following fields from the issue object may be updated through this request:

Notes
title
description
against_id Note: If supplied, you must also supply an against_type.
against_type Note: If supplied, you must also supply an against_id.
class_id Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes.
affiliation_id
date_started
date_due
assignee A staff_id, must point to a valid staff member. The staff will be assigned and informed of this assigned issue.
priority_id The priority object's id. For available priorities see GET /issues/priorities
status_id Must point to a valid issue status. Should not be sent in conjunction with standing, otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses. If you have a status_id, please use this instead of standing. standing will be used to guess the status, thus, status_id is more precise. Warning this will bypass any progressions and should only be used deliberately when automating tasks.
standing The standing you want to change the issue to (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). Warning this will bypass any progressions and should only be used deliberately when automating tasks.
resolution_id The identifier of the issue resolution. The resolution will only show if the issue's standing is resolved. This must point to a valid resolution, you may retrieve a list of resolutions through GET /issues/resolutions.
resolution_detail The details of any resolution. To clear the resolution_detail you may send this field with no value.
contract_id The id of the contract the issue is under, if this field is empty, the contract_id will be unset. This must point to a related contract, you can use the is_related_to_issue filter on GET /contracts to find related contracts.

Configuring the Response

This request supports requesting additional fields and linked objects from the issue object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single updated issue with its default fields and any additional fields requested through _fields.

Create an Issue

Sample Request:

POST /api/v0/issues/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/ \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /issues

This request creates and returns an issue.

Configuring the Issue

Values for the following fields from the issue object may be set through this request:

Notes
title
type_id Must point to a valid issue type. You may retrieve a list of types through GET /issues/types.
against_type Must be a valid type of object.
against_id Must point to a valid object of type against_type.
standing Must be a valid standing. (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). If you have a status_id, please use this instead of standing. standing will be used to guess the status, thus, status_id is more precise.
status_id Must point to a valid issue status. Should not be sent in conjunction with standing, otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses.
affiliation_id
date_started
date_due
description
class_id Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes
assignee A staff_id, must point to a valid staff member.
priority_id The priority object's id. For available priorities see GET /issues/priorities

Configuring the Response

This request supports requesting additional fields and linked resources from the issue object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the created issue with its default fields and any additional fields requested through _fields.

Delete an Issue

Sample Request:

DELETE /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
  -H 'authorization: Bearer {access_token}' \

DELETE /issues/{issue_id}

This request removes an issue from the deployment, specified by its issue_id. This request takes no parameters and returns no resources.

List Issue Priorities

GET /issues/priorities

This request returns a list of priorities available for issues.

Get Issue Priority

GET /issues/priorities/{priority_id}

Returns a single priority for the given priority id.

Count Issue Priorities

GET /issues/priorities/count

Returns the number of issue priorities.

List an Issue's Profile Field Values

See the profiles section for a sample request

GET /issues/{issue_id}/profiles/values

This request returns a list of profile values of an issue, specified by its issue_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "issues", and whose id is {issue_id}.

List all Profile Field Values on Issues

See the profiles section for a sample request

GET /issues/profiles/values

This request returns a list of all profile field values on issues. This is the request GET /{object}/profiles/values, where the object is "issues".

List Issue Profile Fields

See the profiles section for a sample request

GET /issues/profiles/fields

This request returns a list of profile fields available for issues. This is the request GET /{object}/profiles/fields where the object is "issues".

Update a Profile Value on an Issue

See the profiles section for a sample request

PUT /issues/{issue_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular issue,specified by its issue_id. This is the request PUT/{object}/{object_id}/profiles/values/{profile_value_id} where the object is "issues", and whose id is the {issue_id}.

Set a Profile Value on an Issue

See the profiles section for a sample request

POST /issues/{issue_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for an issue, specified by its issue_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "issues", and whose value is {issue_id}.

List Issue Extension Fields

See the extension section for an example

GET /issues/extensions/fields

This request returns a list of extension fields available for an issue, specified by its issue_id. This is the request GET /{object}/extensions/fields, where the object is "issues".

List an Issue's Extension Field Values

See the extension section for an example

GET /issues/{issue_id}/extensions/values

This request returns a list of extension values for an issue, specified by its issue_id. This is the request GET /{object}/{object_id}/extensions/values, where the object is "issues", and whose id is the {issue_id}.

List all Extension Field Values on Issues

See the extension section for an example

GET /issues/extensions/values

This request returns a list of extension field values on issues. This is the request GET /{object}/extensions/values, where the object is "issues".

Update an Extension Field Value on an Issue

See the extension section for an example

PUT /issues/{issue_id}/extensions/values/{extension_value_id}

This request updates the value of an extension field value, specified by its extension_value_id, of an issue, specified by its issue_id. This is the request PUT{object}/{object_id}/extensions/values/{extension_value_id}, where the object is "issues", and whose id is {issue_id}

Set an Extension Field Value on an Issue

Sample Request:

POST /issues/{issue_id}/extensions/fields/{extension_field_id}

This request sets and returns the value of an extension field, specified by its extension_field_id, of an issue, specified by its issue_id. This request is the request POST/{object}/{object_id}/extensions/fields/{extension_field_id} where our object is "issues" whose id is issue_id.

List Available Progressions on an Issue

See the progressions section for a sample request

GET /issues/{issue_id}/progressions

This request returns a list of available progressions for an issue, specified by its issue_id. This is the request GET /{object}/{object_id}/progressions where the object is "issues" whose id is {issue_id}.

List All Progressions For Issues

GET /issues/progressions

This request returns all progressions available for issues.

This returns a list of progressions with the following fields added to the response.

Field Type Description
issue_status unsigned or object The issue status of the issue.
issue_type unsigned or object The issue type that the progression is for.
Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
issue_type_id
Boolean Filters

this request also supports a special kind of filter, the boolean filter. These filters take boolean arguments, the supported filters are:

Filter Name Notes
on_create Filter whether the progression can be run on create

Auto Run a Progression on an Issue

See the progressions section for a sample request

[POST|PUT] /issues/{issue_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress an issue, specified by its issue_id. This is the request [POST|PUT] /{object}/{object_id}/progressions/{progression_id}/auto where the object is "issues" whose id is {issue_id}.

List an Issue's Resource Collections

See the resources (attachments) section for an example

GET /issues/{issue_id}/collections

This request returns a list of resource collections against an issue, specified by its issue_id. This is the request GET /{object}/{object_id}/collections where the object is "issues" and hose id is {issue_id}.

Upload a Resource (Attachment) to a Collection on an Issue

See the resources (attachments) section for an example

POST /issues/{issue_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of an issue specified by its issue_id. This is the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "issues" whose id is {issue_id}.

Jobs (Projects)

Resource URI:
api/v0/jobs

Jobs (or Projects) help you to plan, delegate and track client and internal projects. Projects can be as simple or complex as you like, see the support documentation for more information.

The Job Object

Example job object:

{
  "date_modified": "1495681796",
  "modified_by": "14",
  "status": "5",
  "staff_bookmarked": "1",
  "type": "3",
  "job_type": "3",
  "against": "companies/65",
  "date_completed": null,
  "against_id": "39",
  "against_type": "company",
  "company": "39",
  "id": "2",
  "date_due": "1495245600",
  "rate": "3",
  "date_created": "1495238402",
  "standing": "active",
  "date_started": "1495245600",
  "title": "New Logo Design",
  "paused": "0",
  "date_last_interacted": "1495686301",
  "manager": "7",
  "rate_charged": "125.00",
  "date_commenced": "1494209132",
  "affiliation": "77",
  "custom_id": "TIM#42"
}

The jobs object contains the following:

Field Type Description
id unsigned A unique identifier for the job.
title string A name for the job.
against_type string The type of object the job is against.
against_id unsigned The unique identifier of the object the job is against.
against string The API URI of the object the job is against, that is,against_type and against_id concatenated with a "/".
custom_id string The custom id for this job.
paused integer The number of days the jobs has been paused.
staff_bookmarked boolean Whether the current user has bookmarked the job on the deployment.
date_created unix ts The date the project was created.
date_modified unix ts The date the project was last modified.
date_commenced unix ts The date the job started, that is, when its status moved from "setup" to "active"
date_started unix ts The date the job is scheduled to start.
date_due unix ts The date the job is scheduled to be completed.
date_completed unix ts The date the job was completed.
date_last_interacted unix ts The date the job was last interacted with.
type unsigned or object The job type object of the job. Deprecated, please use job_type.
job_type unsigned or object The job type associated with the job.
rate unsigned or object The rate object associated with the job.
rate_charged decimal The rate charged for billable work, this is part of the rate object.
status unsigned or object The status associated with the job
standing string The standing of the project. This is part of the status.
manager unsigned or object The staff manager managing the job.
modified_by unsigned or object The staff member who last modified the job.
company unsigned or object The company against the job, if any.
affiliation unsigned or object The affiliation against the job.
job_object_budget unsigned or object The object budget associated with the job.
job_contract unsigned or object The contract associated with the job, if any.
job_object_schedule unsigned or object The object schedule linked to the job.

The Job Type

Example job type:

{
  "id": "3",
  "title": "Internal",
  "standing": "active",
  "ordering": "0"
}

You may set up and configure different job types to suit your business processes, general information on types can be found in the support documentation. For jobs, the type object contains the following:

Field Type Description
id unsigned A unique identifier for the job type.
title string A name for the job type.
standing select Either "active" or "inactive", the standing of the job type.
ordering integer An integer representing the type's order as displayed on the deployment.

Note: Requesting the job type object via type() is deprecated, please instead request it via job_type(), this object will have an additional field:

Field Type Description
has_custom_id boolean Either "1" or "0", whether the job type has a custom id.

Get Job

Sample Request:

GET /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
  -H 'authorization: Bearer {access_token}'

GET /jobs/{job_id}

This request returns a single job, specified by its job_id.

Configuring the Response

This request supports requesting additional fields and linked resources from the job object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single job with its default fields and any additional fields requested through _fields.

List Jobs

Sample Request:

GET /api/v0/jobs HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs \
  -H 'authorization: Bearer {access_token}'

GET /jobs

This request returns a list of jobs on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Object

This request supports requesting additional fields and linked objects from the jobs object using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
against_id
against_type
paused
type Filter by the type_id of the job. Deprecated, please use job_type.
job_type Filter by the job_type_id.
manager Filter by the staff_id of the job manager.
modified_by Filter by the staff_id of the last staff member to modify the job.
status Filter by the status_id.
rate Filter by the rate_id.
affiliation Filter by the affiliation_id.
custom_id
Date Filters

This request supports date filters over the following fields:

Filter Name
dated_created
date_modified
date_started
date_commenced
date_due
date_completed
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
date_started
date_created
date_commenced
date_due
date_completed
date_modified
date_last_interacted
id
title
standing
status Order by the status_id.
custom_id
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
against_id
type Range by the type_id. Deprecated, please use job_type.
job_type Range by the job_type_id.
manager Range by the staff_id of the manager of the job.
affiliation Range by the affiliation_id.
modified_by Range by the staff_id of the last staff member to modify the job.
status Range by the status_id.
rate Range by the rate_id.
rate_charged
contract Range by the contract_id of any contract associated with the job.
plan_modified_by Range by the staff_id of the last staff member to modify the job plan.
custom_id
Object Filters

This request supports the following object filters:

Filter Description
against Filter by jobs against these objects.
Searching

This request supports the _search filter to search over the following fields:

Field
title

Handling the Response

The response will be a list of job objects containing the default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters or searches used.

Count Jobs

Sample Request:

GET /api/v0/jobs/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/count \
  -H 'authorization: Bearer {access_token}'

GET /jobs/count

This request will return a count of jobs in a list defined by any available searches or filters. With no searches or filters this will be a count of all jobs on the deployment. This request returns a single field:

Field Type Value
count unsigned A count of jobs listed.

List Recent Jobs

Sample Request:

GET /api/v0/jobs/recent HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/recent \
  -H 'authorization: Bearer {access_token}'

GET /jobs/recent

This request returns a list of job on the deployment, sorted by the most recently created, that is in descending order of date_created.

Configuring the Response

The response to this response may be configured as per GET /jobs, although any order filters used will have no impact on the response.

Handling the Response

This request will return a list of job objects on the deployment with their default fields and any additional fields requested through _fields, displayed in descending order of date_created and according to any pagination parameters, filters, or searches used.

List Latest Modified Jobs

Sample Request:

GET /api/v0/jobs/newest HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/newest \
  -H 'authorization: Bearer {access_token}'

GET /jobs/newest

This request returns a list of jobs on the deployment, sorted by the most recently modified, that is, in descending order of date_modified.

Configuring the Response

The response to this response may be configured as per GET /jobs, although any order filters used will have no impact on the response.

Handling the Response

This request will return a list of job objects on the deployment with their default fields and any additional fields requested through _fields, displayed in descending order of date_modified and according to any pagination parameters, filters, or searches used.

Get Job Type

Sample request:

GET /api/v0/jobs/types/{job_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_fields=standing,has_custom_id
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/jobs/types/{job_type_id} \
  -H 'authorization: Bearer {access_token}' \
  -d '_fields=standing,has_custom_id'

GET /jobs/types/{job_type_id}

This request returns a job type specified by its unique id.

Configuring the Response

This request supports requesting additional fields and linked objects from the job type object using the _fields parameter.

Handling the Response

The response will contain a single job type with its default fields and any additional fields requested through _fields.

List Job Types

Sample request:

GET /api/v0/jobs/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_fields=standing,has_custom_id
_filters=standing(active)
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/jobs/types \
  -H 'authorization: Bearer {access_token}' \
  -d '_fields=standing,has_custom_id' \
  -d '_filters=standing(active)'

GET /jobs/types

This request returns a list of job types.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the job type using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
standing
Order Filters

This request supports order filters over the following fields:

Field
id
title
standing
Range Filters

This request supports range filters over the following fields:

Field
id
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of job types with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Get Job Status

Sample Request:

GET /api/v0/jobs/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}'

GET /jobs/statuses/{status_id}

This request returns the job status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a job status object for the specified status with its default fields and any additional fields requested through _fields.

List Job Statuses

Sample request:

GET /api/v0/jobs/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/jobs/statuses \
  -H 'authorization: Bearer {access_token}' \

GET/jobs/statuses

This request returns a list of job statuses.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Notes
id
title
standing
color
Order Filters

This request supports order filters over the following fields:

Filter Notes
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of statuses with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Job Statuses

Sample Request:

GET /api/v0/jobs/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/jobs/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /jobs/statuses/count

This request will return a count of job statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all job statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed job statuses.

List Job Milestones

Sample Request:

GET /api/v0/jobs/{job_id}/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id}/milestones \
  -H 'authorization: Bearer {access_token}'

GET /jobs/{job_id}/milestones

This request returns a list of milestones of a job, specified by its job_id. This request is handled and configured in the same way as GET /milestones.

Update a Job

Sample Request:

PUT /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /jobs/{job_id}

This request updates and returns a job, specified by its job_id.

Configuring the Job

The following fields from the job object may be updated with this request:

Filter Name Notes
title
engagement_table The against_type for the job
engagement_id The against_id for the job.
manager_id The staff_id of the staff member to be assigned manager.
status_id MUST point to a valid job status.
contract_id The contract_id of a contract to be linked to the job
affiliation_id The affiliation_id of an affiliation to be linked to the job.
rate_id
rate_charged
date_due
date_created

Configuring the Response

This request supports requesting additional fields and linked resources from the jobs object through the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, updated job with its default fields and any additional fields requested through _fields.

Create a Job

Sample Request:

POST /api/v0/jobs/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/\
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /jobs

This request creates and returns a new job.

Configuring the Job

The following fields may be set through this request:

Filter Name Notes
against_type The against_type for the job.
against_id The against_id for the job.
manager_id The staff_id of the staff member to be assigned manager. This MUST point to a valid staff.
type_id* MUST point to a valid job type.
title
rate_id
status_id MUST point to a valid job status.
contract_id The contract_id of a contract to be linked to the job.
affiliation_id The affiliation_id of an affiliation to be linked to the job.
rate_charged
date_due
date_started
date_created If this is not sent it will default to the current time.
is_billable If the job is billable or nonbillable

Configuring the Response

This request supports requesting additional fields and linked resources from the jobs object through the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, created job with its default fields and any additional fields requested through _fields.

Delete a Job

Sample Request:

DELETE /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /jobs/{job_id}

This request deletes a job from the deployment, specified by its job_id. This request takes no arguments and returns no resources.

List a Job's Profile Field Values

See the profiles section for a sample request

GET /jobs/{job_id}/profiles/values

This request returns a list of profile values of a job, specified by its job_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "jobs", and whose id is {job_id}.

List all Profile Field Values on a Job

See the profiles section for a sample request

GET /jobs/profiles/values

This request returns a list of all profile field values on jobs. This is the request GET /{object}/profiles/values, where the object is "jobs".

List Jobs Profile Fields

See the profiles section for a sample request

GET /jobs/profiles/fields

This request returns a list of profile fields available for jobs. This is the request GET/{object}/profiles/fields where the object is "jobs".

Update a Profile Value on a Job

See the profiles section for a sample request

PUT /jobs/{job_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular job, specified by its job_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "jobs", and whose value is {job_id}.

Set a Profile Value on a Job

See the profiles section for a sample request

POST /jobs/{job_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a "job", specified by its job_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "jobs", and whose value is {job_id}.

List Job Extension Fields

See the extension section for an example

GET /jobs/extensions/fields

This request returns a list of extension fields available for any job. This is the request GET /{object}/extensions/fields, where the object is "jobs".

List a Job's Extension Field Values

See the extension section for an example

GET /jobs/{job_id}/extensions/values

This request returns a list of extension values for a job, specified by its job_id. This is the request GET /{object}/{object_id}/extensions/values, where the object is "jobs", and whose id is the job_id.

List all Extension Field Values on Jobs

See the extension section for an example

GET /jobs/extensions/values

This request returns a list of extension field values on jobs. This is the request GET /{object}/extensions/values, where the object is "jobs".

Update an Extension Field Value on a Job

See the extension section for an example

PUT /jobs/{job_id}/extensions/values/{extension_value_id}

This request updates the value of an extension field value, specified by its extension_value_id, of a job, specified by its job_id. This is the request PUT{object}/{object_id}/extensions/values/{extension_value_id}, where the object is "jobs", and whose id is job_id

Set an Extension Field Value on a Job

Sample Request:

POST /jobs/{job_id}/extensions/fields/{extension_field_id}

This request sets and returns the value of an extension field, specified by its extension_field_id, of a job, specified by its job_id. This request is the request POST/{object}/{object_id}/extensions/fields/{extension_field_id} where our object is "jobs" whose id is job_id.

List Available Progressions on a Job

See the progressions section for a sample request

GET /jobs/{jobs_id}/progressions

This request returns a list of available progressions for a job, specified by its job_id. This is the request GET /{object}/{object_id}/progressions where the object is "jobs" whose id is job_id.

Auto Run Progression on a Job

See the progressions section for a sample request

[POST|PUT] /jobs/{jobs_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress a job, specified by its jobs_id. This is the request [POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto where the object is "jobs" whose id is job_id.

List a Job's Resource Collections

See the resources (attachments) section for an example

GET /jobs/{job_id}/collections

This request returns a list of resource collections against a job, specified by its job_id. This is the request GET /{object}/{object_id}/collections where the object is "jobs" and hose id is {job_id}.

Upload a Resource (Attachment) to a Collection on a Job

See the resources (attachments) section for an example

POST jobs/{job_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of a job specified by its job_id. This is the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "jobs" whose id is {job_id}.

Ledgers

Accelo supports account ledgers, it also allows account ledger integration with certain online accounting systems (e.g. Xero). These account ledgers are described by the API through the ledger object. For information on viewing, adding and syncing account ledgers from your deployment, please see the support documentation.

The Ledger Object (Beta)

Example ledger

{
    "code": "200",
    "comment": "Ledger to be used for sales",
    "id": "1",
    "title": "Sales",
    "standing": "active",
    "parent_id": "0"
    }

The ledger object contains the following:

Field Type Description
id unsigned The unique identifier of the ledger.
title string The ledger's title.
code string The account ledger code
parent_id unsigned The unique identifier of the parent ledger, defaults to "0" is there is no parent
standing select The standing of the ledger, either "active" or "inactive".
comment string Comments on the ledger

Get Ledger (Beta)

GET /api/v0/ledgers/{ledger_id} HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/ledgers/{ledger_id} \
    -H 'authorization: Bearer {access_token}'

GET /ledgers/{ledger_id}

This request returns a ledger identified by its unique ledger_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the ledger object using the _fields parameter.

Handling the Response

The response wil be the single ledger with its default fields and any additional fields requested through _fields.

List Ledgers (Beta)

GET /api/v0/ledgers HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/ledgers/ \
    -H 'authorization: Bearer {access_token}'

GET /ledgers

This request returns a list of ledgers.

Configuring the Response

Pagination

This request supports all the standard pagination parameters.

Additional fields and Linked Objects

This request supports requesting additional fields and linked objects from the ledger object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
code
parent_id
standing
Order Filters

This request supports the following order filters:

Filter
id
code
parent_id
standing
title
Range Filters

This request supports the following range filters:

Filter
id
parent_id
Searching

This request supports the _search parameter to search over the following fields:

Field
title
code

Handling the Response

The response will be a list of ledgers with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Ledgers (Beta)

GET /api/v0/ledgers/count HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/ledgers/count \
    -H 'authorization: Bearer {access_token}'

GET /ledgers/count

This request will return a count of ledgers in a list defined by any available searches or filters. With no searches or filters this will be a count of all ledgers on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of ledgers listed.

Milestones

Resource URI:
/api/vo/milestones

Milestones are the steps on the road to a Job's (Project's) completion. They define the schedule of the job, and contain the budget for their respective portion of the job. For information on accessing milestones through the deployment, see the support documentation, milestones may also be imported through the deployment, see again the support documentation for information.

Deleting, creating, and updating milestones is only available through the deployment on the project planning screen, see the support documentation for more information.

The Milestone Object

Example milestone object:

{
  "date_modified": "1494912868",
  "date_completed": "1494911355",
  "status": "4",
  "date_due": "1495072800",
  "id": "1",
  "description": "Initial planning",
  "standing": "complete",
  "date_created": "1494286008",
  "job": "2",
  "rate": "3",
  "title": "A milestone",
  "date_started": "1494208800",
  "object_budget": "12",
  "milestone_object_budget": "12",
  "rate_charged": "125.00",
  "ordering": "1",
  "parent": "0",
  "manager": "21",
  "date_commenced": "1494286232"
}

The milestone object contains the following:

Field Type Description
id unsigned A unique identifier for the milestone.
title string A name for the milestone.
description string A description of the milestone.
ordering integer An integer representing the milestone's ordering on the deployment.
parent unsigned The unique identifier of the parent milestone. If there is not parent this has the value "0".
date_created unix ts The date the milestone was created.
date_modified unix ts The date the milestone was last modified.
date_started unix ts The date the milestone is scheduled to start.
date_commenced unix ts The date the milestone was started, that is, when the standing was changed from "pending".
date_due unix ts The date the milestone is scheduled to be completed.
date_complete unix ts The date the milestone was completed.
job unsigned or object The job (project) the milestone has been created for.
manager unsigned or object The staff member assigned to manage the project.
status unsigned or object The status of the milestone.
standing string The standing of the milestone. This is part of the status object
rate unsigned or object The rate associated with the milestone.
rate_charged decimal The rate charged for billable work within this milestone. This is part of the rate object.
milestone_object_budget unsigned or object The object budget associated with the milestone.
object_budget unsigned or object Deprecated please use milestone_object_budget.
milestone_object_schedule unsigned or object The object schedule linked to the milestone.

Get Milestone

Sample Request:

GET /api/v0/milestones/{milestone_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones/{milestone_id} \
  -H 'authorization: Bearer {access_token}'

GET /milestones/{milestone_id}

This request returns a single milestone, identified by its milestone_id.

Configuring the Response

This request supports requesting additional fields and linked resource from the milestone object using the _fields parameter.

Handling the Response

The response will be the single milestone with its default fields and any additional fields requested through _fields.

List Milestones

Sample Request:

GET /api/v0/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones \
  -H 'authorization: Bearer {access_token}'

GET /milestones

This request returns a list of milestones on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports request additional fields and linked objects from the milestone object using the _fields.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
ordering
job Filter by the job_id.
parent Filter by the milestone_id of the parent milestone.
manager Filter by the staff_id of the manager.
rate Filter by the rate_id.
object_budget Filter by the object_budget_id.
status Filter by the status_id.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_modified
date_created
date_started
date_commenced
date_due
date_completed
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
job Range by the job_id.
manager Range by the staff_id of the manager.
status Range by the status_id.
modified_by Range by the staff_id of the last staff to modify the milestone.
rate Range by the rate_id.
rate_charged
Searching

This request supports the _search parameter to search over the following fields:

Filter Name
title

Handling the Response

The response will be a list of milestones containing their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Milestones

Sample Request:

GET /api/v0/milestones/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones/count \
  -H 'authorization: Bearer {access_token}'

GET /milestones/count

This request will return a count of milestones in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestones on the deployment. This request does not return a response object, just a single value:

Field Type Description
response unsigned A count of milestones listed.

Get Milestone Status

Sample Request:

GET /api/v0/milestones/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/milestones/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}' \

GET /milestones/statuses/{status_id}

This request returns the milestone status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a milestone status object for the specified status with its default fields and any additional fields requested through _fields.

List Milestone Statuses

Sample Request:

GET /api/v0/milestones/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones/statuses \
  -H 'authorization: Bearer {access_token}'

GET /milestones/statuses

This request returns a list of milestone statuses on the deployment.

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the milestone status object through the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Count Milestone Statuses

Sample Request:

GET /api/v0/milestones/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/milestones/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /milestones/statuses/count

This request will return a count of milestone statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestone statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed milestone statuses.

List a Milestone's Profile Field Values

See the profiles section for a sample request

GET /milestones/{milestone_id}/profiles/values

This request returns a list of profile values of a milestone, specified by its milestone_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "milestones", and whose id is milestone_id.

List all Profile Field Values on a Milestone

See the profiles section for a sample request

GET /milestones/profiles/values

This request returns a list of all profile field values on milestones. This is the request GET /{object}/profiles/values, where the object is "milestones".

List Milestone Profile Fields

See the profiles section) for a sample request

GET /milestones/profiles/fields

This request returns a list of profile fields available for milestones. This is the request GET /{object}/profiles/fields where the object is "milestones".

Update a Profile Field Value on a Milestone

See the profiles section for a sample request

PUT /milestones/{milestone_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular milestone, specified by its milestone_id. This is the request PUT/{object}/{object_id}/profiles/values/{profile_value_id} where the object is "milestones", and whose id is the milestone_id.

Set a Profile Field Value on a Milestone

See the profiles section for a sample request

POST /milestones/{milestone_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a milestone, specified by its milestone_id. This is the request POST /{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "milestones", and whose value is milestone_id.

List Available Progressions on a Milestone

See the progressions section for a sample request

GET /milestones/{milestone_id}/progressions

This request returns a list of available progressions for a milestone, specified by its milestone_id. This is the request GET /{object}/{object_id}/progressions where the object is "milestones" whose id is milestone_id.

Auto Run a Progression on a Milestone

See the progressions section for a sample request

PUT|POST /milestones/{milestone_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress a milestone, specified by its milestone_id. This is the request [POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto where theobject is "milestone" whose id is milestone_id.

Object Budgets

Resource URI:
api/v0/object_budgets

Object budgets are budgets against a specific object, for example a budget against an issue or a milestone. They are able to track the time and money spent by staff and on services, as well as expenses and the cost of materials.

The Object Budget

Example object budget:

{
  "charged": "45.84",
  "service_time": "0",
  "material_price_subtotal": "56.10",
  "service_time_estimate": "0",
  "service_price_subtotal_estimate": "425.00",
  "billable": "1320",
  "expense_price": "0.00",
  "material_cost_subtotal": "35.50",
  "remaining_subtotal": "180",
  "object_table": "job",
  "service_price_subtotal": "0.00",
  "charged_subtotal": "70.84",
  "logged": "1500",
  "object_id": "2",
  "logged_subtotal": "2100",
  "is_billable": "yes",
  "billable_subtotal": "1920",
  "material_cost": "35.50",
  "id": "11",
  "service_price_estimate": "0.00",
  "nonbillable": "180",
  "service_price": "0.00",
  "material_price": "56.10",
  "service_time_subtotal_estimate": "10800",
  "nonbillable_subtotal": "180"
}

The object budget resource contains the following:

Field Type Description
id unsigned A unique identifier for the object budget.
against_type string The type of object the object budget is against.
against_id unsigned The unique identifier of the object the object budget is against.
object_table string The type of object the object budget is against. Deprecated please use "against_type".
object_id unsigned The unique identifier of the object the object budget is against.Deprecated please use "against_type".
object string The API URI of the object the object budget is against. This is "{against_type}/{against_id}"
is_billable select Either "yes" or "no", whether time logged against the object is billable.
service_time_estimate integer The estimated total time for services against the object, in seconds.
service_time integer The total time logged for services against the object, in seconds.
service_time_subtotal_estimate integer The estimated total time for services against the object and its children, in seconds.
service_price_estimate decimal An estimate for the total price of services against the object.
service_price decimal The total price of services against the object.
service_price_subtotal_estimate decimal An estimate for the total price of services against the object and all of its children.
service_price_subtotal decimal The total price of services against the object and all of its children.
expense_price decimal The total prices of expenses for the object.
material_cost decimal The total cost of materials for the object.
material_cost_subtotal decimal the total cost of materials for the object and all its children.
material_price decimal The total price of materials for the object.
material_price_subtotal decimal The total price of materials for the object and all its children.
billable integer The total billable time logged against the object, in seconds.
billable_subtotal integer The total billable time logged against the object and all its children, in seconds.
nonbillable integer The total nonbillable time logged against the object, in seconds.
nonbillable_subtotal integer The total nonbillable time logged against the object and all its children, in seconds.
logged integer The total time logged against the object, in seconds. That is, the sum of billable and nonbillable.
logged_subtotal integer The total time logged against the object and all its children, in seconds.
charged decimal The total cost charged against the object.
charged_subtotal decimal The total cost charged against the object, and all its children.
remaining_subtotal decimal If object_table is tasks the remaining budget for the task, otherwise the sum of the remaining subtotal of all the object's children's.

The Item Template Object

Example template object:

{
    "code": "260",
    "cost": "0.0000",
    "cost_rate_id": null,
    "description": "Other Revenue GST on Income",
    "expense_type_ledger": "20",
    "id": "8",
    "ledger_id": "20",
    "line_item_ledger": "20",
    "price": "0.0000",
    "price_rate_id": null,
    "quantity": "1.0000",
    "standing": "active",
    "tax_id": "12",
    "title": "Other Revenue GST on Income",
    "type": "service"
}

These are templates for expenses, materials, and services. These templates allow you to easily add items to your budgets. The template object contains:

Field Type Description
id unsigned A unique identifier for the template.
title string The title of the template.
description string A description of the template.
price decimal The sale price.
type select Either 'expense', 'material', or 'service', the type of item described by the template.
code string The code given for the template
standing select Either 'active' or 'inactive', the standing of the template.
quantity decimal The default quantity used with this template.
cost Decimal The cost (or purchase price) of the template.
cost_rate_id unsigned The id of the cost rate associated with the template (if any).
cost_tax_id unsigned The id of the cost tax (or purchase tax) associated with the template.
cost_ledger_id unsigned The id of the cost ledger (or purchase ledger) associated with the template.
price decimal The sale price of the template.
price_rate_id unsigned The id of the price rate associated with the template (if any).
tax_id unsigned The id of the sale tax associated with the template.
ledger_id unsigned Then id of the sale ledger associated with the template.
line_item_ledger unsigned or object The ledger associated with the template.
expense_type_ledger unsigned or object Where type is expense, the ledger associated with the template.
cost_tax unsigned or object The cost tax (or purchase tax) associated with the template.
cost_ledger unsigned or object The cost ledger (or purchase ledger) associated with the template.

The Material Object

Example material object:

{
    "against_id": "201",
    "against_type": "milestone",
    "budget_item_template": "0",
    "budget_item_template_id": "0",
    "cost": "24.0000",
    "date_created": "1457523796",
    "id": "10",
    "material_item_ledger": "0",
    "material_item_ledger_id": null,
    "ordering": "0",
    "price": "0.9900",
    "quantity": "1.0000",
    "tax_id": null,
    "title": "Design Tools",
    "contract_period_id": null,
}

These describe instances of material templates as items on a budget. These contain the following:

Field Type Description
id unsigned A unique identifier for the material.
title string A title for the material.
against_type string The type of object the material has be added against.
against_id unsigned The id of the object the material has been added against.
quantity decimal The quantity of the material added.
cost decimal The cost (or purchase price) of the material.
price decimal The sale price of the material
date_created unix ts The date the material was created.
material_ledger_id unsigned The unique identifier of the ledger used by the material.
material_template_id unsigned The unique identifier of the item template the material is based off.
tax_id unsigned The unique identifier of the tax on the material.
material_ledger unsigned or object The ledger used by the material.
material_template unsigned or object The item template the material is based off.
ordering unsigned A number describing the order the material is displayed.
contract_period_id unsigned The unique identifier for the contract period the material is linked to.

The Service Object

Example service object:

{
    "against_id": "22",
    "against_type": "contract",
    "budget_item_template": "8",
    "budget_item_template_id": "8",
    "id": "92",
    "service_item_ledger": "20",
    "service_item_ledger_id": "20",
    "tax_id": "12"
}

These describe instances of service templates as items on a budget. These contain the following:

Field Type Description
id unsigned A unique identifier for the service.
against_type string The type of object the service has been added against.
against_id unsigned The id of the object the service has been added against.
service_ledger_id unsigned The unique identifier of the ledger used by the service.
service_template_id unsigned The unique identifier of the template used by the service.
tax_id unsigned The unique identifier of the tax used by the service.
service_ledger unsigned or object The ledger used by the service.
service_template unsigned of object The template used by the service.

Get Object budget

Sample Request:

GET /api/v0/object_budgets/{object_budget_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/object_budgets/{object_budget_id} \
  -H 'authorization: Bearer {access_token}'

GET /object_budgets/{object_budget_id}

This request returns an object budget identified by its object_budget_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the object budget using the _fields parameter.

Handling the Response

The response will be the single object budget with its default fields and any additional fields requested through _fields.

List Object Budgets

Sample Request:

GET /api/v0/object_budgets HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/object_budgets \
  -H 'authorization: Bearer {access_token}'

GET /object_budgets

This request returns a list of object budgets on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the object budget using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
against_id
against_type
Order Filters

This request supports the following order filters:

Filter Name
id
Object Filters

This request supports the following object filters:

Filter Name
against

Handling the Response

The response will be a list of object budgets with their default fields and any additional fields requested through _fields, and displayed according to any pagination requests used.

Count Object Budgets

Sample Request:

GET /api/v0/object_budgets/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/object_budgets/count \
  -H 'authorization: Bearer {access_token}'

GET /object_budgets/count

This request will return a count of object budgets in a list defined by any available searches or filters. With no searches or filters this will be a count of all object budgets on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of object budgets listed.

List Item Templates

Sample request:

GET /api/v0/object_budgets/templates HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/templates \
  -H 'authorization: Bearer {access_token}' \

GET /object_budgets/templates

This request returns a list of item templates on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the item template object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name Notes
id
type
standing
ledger_id
cost_ledger_id
cost_tax_id
tax_id
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
price
cost
Order Filters

This request supports the following order filters:

Filter Name Notes
id
cost
title
price
standing
Empty Filters

This request supports empty filters over the following fields:

Filter Name Notes
title
Searching

This request supports the _search parameter to search over the following fields:

Field
title
description
code

Handling the Response

The response will be a list of item templates with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

List Materials

Sample request:

GET /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
  -H 'authorization: Bearer {access_token}' \

GET /object_budgets/materials

This request returns a list of materials on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the material object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name Notes
id
against_id
against_type
material_ledger_id
material_template_id
quantity
cost
price
tax_id
contract_period_id
Date Filters

This request supports date filters over the following fields:

Filter Name Notes
date_created
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
cost
price
quantity
Order Filters

This request supports the following order filters:

Filter Name Notes
id
quantity
price
cost
date_created
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of materials with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

List Services

Sample request:

GET /api/v0/object_budgets/services HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/services \
  -H 'authorization: Bearer {access_token}' \

GET/object_budgets/services

This request returns a list of services on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the service object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name Notes
id
against_id
against_type
service_template_id
service_ledger_id
tax_id
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
Object Filters

This request supports the following object filters:

Filter Name Notes
against
Order Filters

This request supports the following order filters:

Filter Name Notes
id

Handling the Response

The response will be a list of services with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Update a Material

Sample request:

PUT /api/v0/object_budgets/materials/{material_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

quantity=10
price=20
curl -X PUT \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/materials/{material_id} \
  -H 'authorization: Bearer {access_token}' \
  -d 'quantity=10'
  -d 'price=20'

PUT /object_budgets/materials/{material_id}

This request updates and returns the material with the given material_id

Configuring the Response

The following fields may be used to update the material:

Field Name Notes
title
quantity
price
cost
template_id

Configuring the Response

This request supports requesting additional fields and linked objects from the material object using the _fields parameter.

Handling the Response

The response will be the update material with its default fields and any additional fields requested through_fields.

Create a Material

Sample request:

POST /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

authorization: Bearer {access_token}
against_type=contract_period
against_id=123
title=Shovels for digging
quantity=12
cost=10
price=2
template_id=4
curl -X POST \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
  -H 'authorization: Bearer {access_token}' \
  -d 'against_type=contract_period' \
  -d 'against_id=123' \
  -d 'title=Shovels for digging' \
  -d 'quantity=12' \
  -d 'cost=10' \
  -d 'price=2' \
  -d 'template_id=4'

POST /object_budgets/materials

This request creates and returns a material.

Configuring the Response

The following fields may be set when creating the material:

Field Name Notes
against_type Supports: 'job', 'issue', 'milestone', 'contract_period'
against_id
title
quantity
price
cost
template_id

Handling the Response

The response will be the newly created material with its default fields and any additional fields requested through_fields.

Object Schedules

An object schedule is a schedule against a specific object. For example, the schedule on a given task.

The Object Schedule

Sample JSON object:

{
  "date_planned_due": "1362618000",
  "against_id": "24",
  "date_planned_start": "1362358800",
  "id": "113",
  "against_type": "task"
}

The object schedule budget contains the following

Field Type Description
id unsigned A unique identifier for the object schedule.
against_id unsigned The unique identifier of the object the schedule is against.
against_type string The type of object the schedule is against.
date_planned_start unix ts The planned start date.
date_planned_due unix ts The planned due date.
date_predicted_start unix ts The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations.
date_predicted_end unix ts The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations.
date_commenced unix ts The actual commenced date.
date_completed unix ts The actual completed date.
date_user_estimated_start unix ts The date the assignee has scheduled to start the work.
date_user_estimated_due unix ts The date the assignee has scheduled to complete the work.
date_targeted_start unix ts The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations.
date_targeted_due unix ts The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations.
date_fixed_start unix ts The fixed start date.
date_fixed_due unix ts The fixed deadline for the due date.

There are no endpoints associated with this object.

Payments

Resource URI
/api/v0/payments

Payments made, for example against an invoice, are stored under the payments object through the API. Attached to these payments are methods, receipts, and the currency used.

The Payment Object (Beta)

Sample payment object:

{
    "payment_method": "2",
    "receipt_id": "28945",
    "id": "30507",
    "currency_id": "0",
    "direction": "credit",
    "created_by_staff_id": "1055",
    "method_id": "2",
    "amount": "79.00",
    "against_id": "31347",
    "date_created": "1496887498",
    "payment_currency": "0",
    "against_type": "account_invoice",
    "payment_receipt": "28945"
}

The payment object contains the following:

Field Type Description
id unsigned The unique identifier of the payment.
receipt_id unsigned The unique identifer of the receipt associated with the payment.
amount decimal The amount paid through the payment.
currency_id unsigned The unique identifier of the currency used.
method_id unsigned The unique identifier of the payment method.
against_id unsigned The unique identifier of the object the payment is against.
against_type string The type of object the payment is against.
date_created unix ts The date the payment was created.
created_by_staff_id unsigned The unique identifier of the staff member who entered the payment.
direction select Either "debit" or "credit", defaults to "credit".
payment_currency unsigned or object The currency used for the payment.
payment_method unsigned or object The method of the payment.
payment_receipt unsigned or objects The receipt for the payment.

The Payment Receipt Object (Beta)

Sample receipt object:

{
    "owner_type": "staff",
    "owner_id": "1055",
    "id": "28945",
    "affiliation_id": "152348",
    "amount": "79.00",
    "date_received": "1496887498"
}

Where a payment object stores the information on a payment made against a single object, a receipt may be issued for a single payment, or a collection of payments. For information on accessing receipts from the deployment and receiving receipts from an integrated accounting system see the support documentation. The receipt object contains the following:

Field Type Description
id unsigned The unique identifier of the receipt.
amount decimal The amount the receipt is for.
affiliation_id unsigned The unique id of the affiliation associated with the receipt.
owner_id unsigned The unique identifier of the owner.
owner_type select Either "staff" or "contact", the type of owner of the receipt.
date_received unix ts The date the receipt was received.

The Payment Method Object (Beta)

Sample payment method object:

{
    "id": "2",
    "title": "Visa",
    "standing": "active"
}

The payment method describes the different methods payment may be given, for example via cash or via mastercard. Payments from online billing systems should automatically update the method, see the support documentation for more information. The payment method object contains the following:

Field Type Description
id unsigned A unique identifier for the method.
title string A name for the method.
standing select Either "active" or "inactive", the standing of the method.

The Currency Object (Beta)

Sample currency object:

{
    "rate": "1",
    "id": "1",
    "symbol": "$",
    "title": "Australian Dollars",
    "code": "AUD"
}

The different currencies that may be handled by your deployment are stored in the currency object, this contains the following:

Field Type Description
id unsigned A unique identifier for the currency.
title string A name for the currency.
code string A short code for the currency.
symbol character The symbol used for the currency.
rate decimal The rate, generally pulled from an external accounting system.

Get Payment (Beta)

Sample request, list payments against a specific invoice:

GET /payments/{payment_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
filters=against(account_invoice(133))
curl -X GET \
    https://{deplyoment}.api.accelo.com/payments/{payment_id} \
    -H 'authorization: Bearer {access_token}' \
    -d 'filters=against(account_invoice(133))

GET /payments/{payment_id}

This request returns a payment identified by its unique payment_id.

Configuring the Response

This request supports requesting additional fields and linked object from the payment object using the _fields parameter.

Handling the Response

The response will be the single payment object with its default fields and any additional fields requested through _fields.

List Payments (Beta)

Sample request:

GET /payments/ HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/payments/ \
    -H 'authorization: Bearer {access_token}'

GET /payments

This request returns a list of payments on the deployment.

Configuring the Response

Pagination

This request supports all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked object from the payment object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
currency_id
method_id
receipt_id
created_by_staff_id
against_id
against_type
Date Filters

This request supports date filters over the following fields:

Field
date_created
Order Filters

This request supports the following order filters:

Filter
id
currency_id
method_id
receipt_id
created_by_staff_id
amount
date_created
direction
against_id
Range Filters

This request supports the following range filters:

Filter
id
currency_id
method_id
receipt_id
created_by_staff_id
amount
against_id
Object Filters

This request supports the following object filters:

Filter Description
against Filter by the object the payment is against.

Handling the Response

The response will be a list of payments with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters or filters used.

Count Payments (Beta)

Sample request:

GET /payments/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/payments/count \
    -H 'authorization: Bearer {access_token}'

GET /payments/count

This request will return a count of payments in a list defined by any available searches or filters. With no searches or filters this will be a count of all payments on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of payments listed.

Profiles

Profile fields are objects used for tracking extra information from your Accelo deployment. See the support documentation for further information about profile fields. Currently, custom profile fields are supported on the following objects:

The Profile Field Object

Example profile field:

{  
  "link_type": "company",
  "required": "no",
  "parent_id": "0",
  "description": "These are the companies opening hours in the form \"HH-HH\", use 24h time.",
  "id": "12",
  "lookup_type": null,
  "confidential": "no",
  "field_name": "Opening Hours",
  "restrictions": "all",
  "field_type": "text",
  "exported": "no"
}

These are objects describing the custom fields on the deployment, they contain the following:

Field Type Description
id unsigned A unique identifier for the profile field.
field_name string A name for the profile field.
field_type select The type of the profile field. This can be "text", "integer", "decimal", "date", "date_time", "currency", " lookup", "structure", "select", "multi_select", or "hyperlink".
parent_id unsigned The unique identifier of the parent profile field. If there is no parent this has a value of "0".
link_type string The type of object this profile field is against. For example "contact".
required select Either "yes" or "no", whether this profile field is required for the object it is against.
restrictions select Who is able to edit the value of this field. May be one of "all", "edit", "process", "admin". For example, if set to "process", only users with "process" permission for custom fields will be able to edit this field. See the support documentation for information on setting permissions.
exported select Either "yes" or "no", whether this profile field will be included when you export the against object.
lookup_type string When field_type is "lookup", this will contain the lookup type, e.g. "company".
options array When field_type is either "select" or "multi_select" this will contain the possible values.
confidential select Either "yes" or "no", whether this is a confidential profile field. These are profile fields viewable only within confidential relationships, see the support documentation for more information.
description string A description of the profile field.

The Profile Value Object

Example profile value object:

{
  "value_type": null,
  "id": "128",
  "field_type": "multi_select",
  "value": "one, two",
  "values": ["one", "two"],
  "date_modified": "1495669367",
  "field_name": "Implementation Phases",
  "field_id": "12",
  "modified_by": "14",
  "link_type": "issues",
  "link_id": "45"
}

These are objects describing a value of a given profile field, identified by the field_id, they contain the following:

Field Type Description
id unsigned A unique identifier for the profile field value.
field_type string The profile field type for this value, see the profile field object for possible values.
field_name string The name for the profile field.
value_type string For fields of type lookup this is the type of the lookup object. For example "company", "contact". Otherwise it is null.
value dynamic The value of the profile field. The type will change according to the field_type, for example if the field type is "date" this will be a unix ts. If it's a "multi_select" this will be all values joined by a comma. e.g, "one, two" for ["one", "two"]
values* array When the field type is "multi_select", this will contain an array of the selected values. e.g, ["one", "two"]
date_modified unix ts The date this profile field value was last modified.
modified_by unsigned or object The staff member who last modified this profile field value.
field_id unsigned The unique identifier of the profile field this value is for.
link_type string The object the profile value was created against.
link_id unsigned The unique identifier of the object the profile value is against.

* The values field is only returned when the field_type is "multi_select". When it's "multi_select", it's returned by default.

List Profile Fields

Sample Request:

GET /api/v0/{issues}/profiles/fields HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/issues/profiles/fields \
  -H 'authorization: Bearer {access_token}'

GET /{object}/profiles/fields

This request returns a list of profile fields available for the given object.

Configuring the Response

This request supports requesting additional fields and linked objects from the profile field object using the _fields parameter.

Handling the Response

This response will be a list of profile fields with their default fields, and any additional fields requested through _fields.

List Object Profile Values

Sample Request:

GET /api/v0/issues/{issue_id}/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/profiles/values \
  -H 'authorization: Bearer {access_token}'

GET /{object}/{object_id}/profiles/values

This request returns a list of profile values for the given object of identified by object_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the profile value object using the _fields parameter.

Handling the Response

This response will be a list of profile values with their default fields, and any additional fields requested through _fields.

List Profile Values

Sample Request:

GET /api/v0/issues/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/profiles/values \
  -H 'authorization: Bearer {access_token}'

GET /{object}/profiles/values

This request returns a list of profile values for the given object.

Configuring the Response

Pagination

This request supports all of the pagination parameters

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the profile value object using the _fields parameter.

Basic Filter

This request supports basic filters over the following fields:

Filter Name
unified
field_id
link_id
link_type

Order Filters

This request supports order filters over the following fields:

Filter Name
field_id
link_id
link_type
value_type
date_modified

Range Filters

This request supports range filters over the following fields:

Filter Name
field_id
link_id

Searching

This request supports the _search parameter to search over the following fields:

Filter Name
title

Update a Profile Value

Example, a business has changed its opening hours:

curl -X put \
  https://{deployment}.api.accelo.com/api/v0/companies/{company_id}/profiles/values/128 \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'value=09-18'

PUT /{object}/{object_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular object, specified by its object_id, of a particular type, specified by object.

Configuring the Profile Value

This request updates the value of a profile value, since this object is dynamic the field we send will depend on the type of value:

Field Name Type Description
value_int int If field_type is "integer", update the value with this integer.
value_date string If field_type is "date", update the value with this string. This field supports values as both unix timestamps and in ISO8601 form, for ease of readability we recommend ISO8601.
value_id integer If field_type is "lookup", update the value with this integer, representing an object id.
value_type string If field_type is "lookup", update the value_type with this string.
value string If field_type is none of the above, update the value with this string.

Configuring the Response

This request supports requesting additional fields and linked objects from the profile value object using the _fields parameter.

Handling the Response

The response will be the single, updated profile value with its default fields, and any additional fields requested through _fields.

Create a Profile Value

Example, a company has give us their business hours:

curl -X post \
  https://{deployment}.api.accelo.com/api/v0/companies/{company_id}/profiles/fields/{profiles_field_id}
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'value=16-20'

POST /{object}/{object_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id. The object whose profile field is to be update is identified by object_id and object.

Configuring the Profile Value

This request accepts the same fields as the previous request, that is, it takes only the relevant value field(s). The relevant value field is required for this request.

Configuring the Response

This request supports requesting additional fields and linked objects from the profile value object using the _fields parameter.

Handling the Response

The response will be the newly created profile value with its default fields, and any additional fields requested through _fields.

Progressions

Progressions allow you and your team to intelligently move records between statuses. The Public API currently supports automatic progressions, which skip over details requiring user interaction. These automatic progressions are currently supported over the following resources:
1. tasks
2. companies
3. jobs
4. prospects
5. issues
6. milestones
7. affiliations
8. contracts
9. contacts
10. expenses

NOTE: For a user to perform an interaction on a progression they MUST have the process permission or be a manager (or assignee for tasks) of the object. The list progression actions endpoint will NOT return progressions on objects that do not meet these requirements.

See the support documentation for information on progressions, including how to define new progressions on your deployment.

The Progression Object

Example progression object:

{
  "standing": "paused",
  "color": "pink",
  "title": "Paused",
  "id": "8"
}

The progressions object contains the following fields and linked objects:

Field Type Description
id unsigned A unique identifier for the progression.
title string A name for the progression.
status object The status the progression will move to. Note, the status object here does not contain the start field.

The Progression History

The history of progressions taken by an object (equivalently, the history of statuses that it has taken) is tracked via the progression history. Each of these objects tracks the status the object was moved to, by whom, and when. These objects contain:

Field Type Description
id unsigned A unique identifier for the history object
to_id unsigned The id of the status the object was progressed to.
to_title string The title of the status the object was progressed to.
against_type string The type of object the progression was made against.
against_id unsigned The unique identifier of the object the progression was made against.
modified_by unsigned The unique identifier of the staff who progressed the object.
date_modified unix ts The date the object was progressed.

Using Progressions

Progressions may be used to perform an automatic status update, this is a three step process:
1. Determine which status progressions are available for the given object, this is achieved by a GET request which retrieves a list of available progressions.
2. From this list identify the appropriate progressions for your action, keep track of the progression_id.
3. Use this progression id in a POST request to run a status update.

List Available Progressions

Example request:

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/jobs/{job_id}/progressions \
  -H 'authorization: Bearer {access_token}'

GET /{resource}/{resource_id}/progressions

This request returns a list of progressions available for a given resource, which may be one of the types above, specified by its unique resource id.

Handling the Response

This request will return a list of progressions available for the object given, displayed in ascending order of their progression_id.

List Progression History

Sample request:

GET /api/v0/progressions/history HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/progressions/history \
  -H 'authorization: Bearer {access_token}' \

GET/progressions/history

This request returns a list of progression history objects.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the progression history object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Description
id
against_type
against_id
modified_by
Order Filters

This request supports the following order filters:

Filter Description
id
date_modified
Range Filters

This request supports range filters over the following fields:

Field Description
id
Object Filters

This request supports the following object filters:

Filter Name Description
against Filter by histories against these objects.
Date Filters

This request supports date filters over the following fields:

Filter Name Description
date_modified

Handling the Response

The response will be a list of progression history objects with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Get Progression History

Sample request:

GET /api/v0/progressions/history/{progression_history_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/progressions/history/{progression_history_id} \
  -H 'authorization: Bearer {access_token}' \

GET/progressions/history/{progression_history_id}

This request returns a single progression history object specified by its unique id.

Count Progression Histories

Sample request:

GET /api/v0/progressions/history/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/progressions/history/count \
  -H 'authorization: Bearer {access_token}' \

GET/progressions/history/count

This request will return a count of progression histories in a list defined by any available searches or filters. See GET /progressions/history for a list of available filters. With no searches or filters this will be a count of all progression histories. The response contains a single fie

Field Type Description
count Unsigned A count of progression histories listed

Auto Run a Progression

Example request, we wish to move our job to "complete" from the above request we found that the progression with id "8" will do this:

curl -X post \
  https://{deployment}.api.accelo.com/api/v0/progressions/8/auto \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded'

[POST|PUT] /{resource}/{resource_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress the status of the object, specified by its unique id. The object may be any one of those listed above.

Handling the Response

The response will contain the single updated object. Please see the appropriate resource endpoint for handling and configuring the response.

Prospects (Sales)

Resource URI:
api/v0/prospects

Prospects (also known as Sales) are a way to keep track of your sales and deals. See the support documentation for more information on the full potential of these, and also information on setting up and configuring them via the deployment.

The Prospect Object

Example prospects object

{
  "affiliation": "75",
  "progress": "0.2500",
  "staff_bookmarked": "0",
  "status": "2",
  "comments": "Lets get these shoes out the door",
  "manager": "2",
  "date_created": "1494293760",
  "contact": "75",
  "date_actioned": "1494252000",
  "success": "no",
  "id": "9",
  "value": "1000.00",
  "type": "1",
  "value_weighted": "20",
  "standing": "active",
  "date_due": "1494424800",
  "date_last_interacted": "1494263000",
  "title": "Super Sonic Shoes (SSS)",
  "prospect_probability": "5",
  "weighting": "3"
}

The prospect object contains the following:

Field Type Description
id unsigned A unique identifier for the prospect.
title string A name for the prospect.
date_created unix ts The date the prospect was created.
date_actioned unix ts The date the prospect was actioned.
date_due unix ts The due date for the prospect.
date_last_interacted unix ts The date the prospect was last interacted with.
date_modified unix ts The date the prospect was last modified.
weighting integer A rating of the prospect, this is on a scale of 1-5, with 5 being the highest rating.
value decimal The currency value of the prospect.
success select Either "yes" or "no", whether the sale has been successfully completed, or won.
comments string Comments, description etc. of the Prospect.
progress decimal A decimal representation of the "progress %" associated with the current standing of the prospect. See the support documentation on setting up progressions for information on this field.
value_weighted integer A value incorporating the progress and weighting values to describe the prospect.
staff_bookmarked boolean Whether the current user has bookmarked the prospect on the deployment.
won_by_id unsigned The id of the staff who won the prospect. 'null' if the prospect has not been won.
cancelled_by_id unsigned The id of the staff who cancelled the prospect. 'null' if the prospect has not been cancelled.
abandoned_by_id unsigned The id of the staff who abandoned the prospect. 'null' if the prospect has not been abandoned.
contact unsigned or object The contact associated with the prospect
manager unsigned or object The staff assigned to manage the prospect.
type unsigned or object The prospect type. Deprecated, please use prospect_type.
prospect_type unsigned or object The prospect type of the prospect.
status unsigned or object The status of the prospect.
standing string The standing of the prospect, this is part of the status object
prospect_probability unsigned or object The prospect probability of the prospect.
affiliation unsigned or object The affiliation associated with the prospect.

The Prospect Type

Example prospect type object:

{
  "title": "Partner",
  "id": "1",
  "parent": "0",
  "ordering": "3",
  "standing": "active"
}

You may group prospect using prospect types to reflect the different actions taken on different types of prospect. See the support documentation for information on prospect types. The prospect type contains the following:

Field Type Description
id unsigned A unique identifier for the prospect type.
title string A name for the prospect type.
parent unsigned The unique identifier of the parent prospect type. If there is no parent this has the value "0".
standing select The standing of the prospect type, may be either "active" or "inactive".
ordering integer An integer representing the prospect type's ordering as displayed on the deployment.

The Prospect Probability

Prospect probabilities are customizable fields you may use to reflect how likely you are to win a sale. See the support documentation for more information. The prospect probability contains the following:

Field Type Description
id unsigned A unique identifier for the prospect probability.
title string A name for the prospect probability.
value integer The value assigned to the prospect probability.
ordering integer An integer representing the prospect probability's ordering as displayed on the deployment.

The Prospect Status

Example Prospect Status object:

{
  "standing": "active",
  "start": "yes",
  "ordering": "1",
  "id": "2",
  "title": "Qualified",
  "color": "yellow"
}

Prospect Statuses may be used to track the progress of a Prospect. These may be configured on the deployment, see the support documentation for more information. The status object contains the following:

Field Type Description
id unsigned A unique identifier for the status.
title string A name for the status.
standing string A string describing the standing of the prospect.
color string The color of the status shown on the deployment.
start select Either "yes" or "no", whether an prospect may be created with this status.
ordering unsigned A number describing the order of the status on the deployment.

Get Prospect

Sample Request:

GET /api/v0/prospects/{prospect_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id} \
  -H 'authorization: Bearer {access_token}'

GET /prospects/{prospect_id}

This request returns a single prospect, identified by its prospect_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the prospect object using the _fields parameter.

Handling the Response

The response will be the single prospect with its default fields and any additional fields requested via _fields.

List Prospects

Sample Request:

GET /api/v0/prospects HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects \
  -H 'authorization: Bearer {access_token}'

GET /prospects

This request returns a list of prospects on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the prospects object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
weighting
success
affiliation Filter by the affiliation_id.
manager Filter by the staff_id of the manager.
type Filter by the type_id. Deprecated, please use prospect_type.
prospect_type Filter by the prospect_type_id.
status Filter by the status_id.
prospect_probability Filter by the prospect_probability.
company Filter by the company_id.
won_by_id Filter by the id of the staff who won the prospect.
cancelled_by_id Filter by the id of the staff who cancelled the prospect.
abandoned_by_id Filter by the id of the staff who abandoned the prospect.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
dated_actioned
date_due
date_modified
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
date_actioned
date_created
date_due
date_last_interacted
date_modified
title
id
status Order by the status_id.
standing
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
weighting
value
progress
value_weighted
affiliation Range over the affiliation_id.
manager Range over the staff_id of the manager.
type Range over the type_id. Deprecated, please use prospect_type.
prospect_type Range over the prospect_type_id.
status Range over the status_id.
Searching

This request supports the _search parameter to search over the following fields:

Filter Name
title

Handling the Response

This request will return a list of prospects with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Prospects

Sample Request:

GET /api/v0/prospects/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/count \
  -H 'authorization: Bearer {access_token}'

GET /prospects/count

This request will return a count of prospects in a list defined by any available searches or filters. With no searches or filters this will be a count of all prospects on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the prospects listed.

Get Prospect Status

Sample Request:

GET /api/v0/prospects/{prospect_id}/status HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id}/status \
  -H 'authorization: Bearer {access_token}'

GET /prospects/{prospect_id}/status

This request returns the prospect status of a prospect, identified by its prospect_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the prospect status object using the _fields parameter.

Handling the Response

The response will be the single prospect status with its default fields and any additional fields requested through _fields.

List Prospect Statuses

Sample Request:

GET /api/v0/prospects/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/statuses \
  -H 'authorization: Bearer {access_token}'

GET /prospects/statuses

This request returns a list of statuses for prospects on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of prospect statuses with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

List Prospect Types

Sample Request:

GET /api/v0/prospects/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/types \
  -H 'authorization: Bearer {access_token}'

GET /prospects/types

This request returns a list of prospect types on the deployment. The _filters parameter is set to standing_not(inactive) by default.

Configuring the Request

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the prospect type object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
standing
Order Filters

This request supports order filters over the following fields:

Field
id
title
standing
ordering
Range Filters

This request supports range filters over the following fields:

Field
id
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of prospect types with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters used.

Get Prospect Probability

Sample Request

GET /api/v0/prospects/probabilities/{probability_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/probabilities/{probability_id} \
  -H 'authorization: Bearer {access_token}'

GET /prospects/probabilities/{probability_id}

This request returns the given probability specified by its probability_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the prospect probability using the _fields parameter.

Handling the Response

The response will be the single prospect probability with its default fields and any additional fields requested through _fields.

List Prospect Probabilities

Sample Request

GET /api/v0/prospects/probabilities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/probabilities \
  -H 'authorization: Bearer {access_token}'

GET /prospect/probabilities

This request returns a list of all probabilities on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the probability object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
value
Order Filters

This request supports the following order filters:

Filter Name
title
ordering
value
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of prospect probabilities with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Prospect Probabilities

Sample Request

GET /api/v0/prospects/probabilities/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/probabilities/count \
  -H 'authorization: Bearer {access_token}'

GET /prospects/probabilities/count

This request will return a count of prospect probabilities in a list defined by any available searches of filters. With no searches of filters this will be a count of all prospects on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the probabilities listed.

Update a Prospect

Sample Request:

PUT /api/v0/prospects/{prospect_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id} \
  -H 'authorization: Bearer {access_token}'
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /prospects/{prospects_id}

This request updates and returns a prospect, specified by its prospect_id.

Configuring the Prospect

The following fields may be updated through this request:

Field Type Notes
title string
comments string
value decimal
success select If provided, must be one of 'yes' or 'no'.
affiliation_id int MUST point to a valid affiliation. Updating this may relocate the prospect to a new company.
staff_id int Update the staff_id of the manager. MUST point to a valid staff.
date_due unix ts or ISO8601 String
weighting int Must be between 0 and 5.
progress int Must be between 0 and 100.
probability_id int
status_id int Must point to a valid prospect status. Warning This will bypass any progressions and should only be used deliberately when automating tasks. Please use progressions otherwise.

See the prospect object for more information on these fields.

Configuring the Response

This request supports requesting additional fields and linked objects from the prospect object using the _fields parameter.

Handling the Response

The response will be the single, updated prospect object with its default fields and any additional fields requested through _fields.

Create a Prospect

Sample Request:

POST /api/v0/jobs HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

title='New Prospect'
affiliation_id=1421
type_id=3
curl -X POST \
  https://{deployment}.api.accelo.com/api/v0/jobs/ \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'title=New Prospect' \
  -d 'affiliation_id=1421' \
  -d 'type_id=1'

POST /prospects

This request creates and returns a new prospect

Configuring the Prospect

All fields available when updating a prospect may also be set here, with the following additions:

Field Type Notes
title string
affiliation_id int Must point to a valid affiliation.
type_id int Must point to a valid prospect type.
status_id int The starting status for the progression. Defaults to the status with the lowest ordering. Note this will skip any progressions.

Handling the Response

The response will be the newly created prospect with its default fields and any additional fields requested through _fields

Delete a Prospect

Sample Request:

DELETE /api/v0/prospects/{prospect_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
curl -X delete \
  https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /prospects/{prospect_id}

This request will delete the prospect identified by its prospect_id. This request takes no parameters and returns no resources.

List a Prospect's Profile Field Values

See the profiles section for a sample request

GET /prospects/{prospect_id}/profiles/values

This request returns a list of profile values of a prospect, specified by its prospect_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "prospects", and whose id is prospect_id.

List all Profile Field Values on a Prospect

See the profiles section for a sample request

GET /prospects/profiles/values

This request returns a list of all profile field values on prospects. This is the request GET /{object}/profiles/values, where the object is "prospects".

List Prospect Profile Fields

See the profiles section for a sample request)

GET /prospects/profiles/fields

This request returns a list of profile fields available for prospects. This is the request GET /{object}/profiles/fields where the object is "prospects".

Update a Profile Field Value on a Prospect

See the profiles section for a sample request

PUT /prospects/{prospect_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular prospect, specified by its prospect_id. This is the request PUT/{object}/{object_id}/profiles/values/{profile_value_id} where the object is "prospects", and whose id is the prospect_id.

Set a Profile Field Value on a Prospect

See the profiles section for a sample request

PUT|POST /prospects/{prospect_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a prospect, specified by its prospect_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "prospects", and whose value is prospects_id.

List Prospect Extension Fields

See the extension section for an example

GET /prospects/extensions/fields

This request returns a list of extension fields available for any prospect. This is the request GET/{object}/extensions/fields, where the object is "prospects".

List a Prospect's Extension Field Values

See the extension section for an example

GET /prospects/{prospect_id}/extensions/values

This request returns a list of extension values for a prospect, specified by its prospect_id. This is the request GET /{object}/{object_id}/extensions/values, where the object is "prospects", and whose id is prospect_id.

List all Extension Field Values on Prospects

See the extension section for an example

GET /prospects/extensions/values

This request returns a list of extension field values on prospects. This is the request GET /{object}/extensions/values, where the object is "prospects".

Update an Extension Field Value on a Prospect

See the extension section for an example

PUT /prospects/{prospect_id}/extensions/values/{extension_value_id}

This request updates the value of an extension field value, specified by its extension_value_id, of a prospect, specified by its prospect_id. This is the request PUT{object}/{object_id}/extensions/values/{extension_value_id}, where the object is "prospect", and whose id is prospect_id

Set an Extension Field Value on a Prospect

Sample Request:

POST /prospects/{prospect_id}/extensions/fields/{extension_field_id}

This request sets and returns the value of an extension field, specified by its extension_field_id, of a prospect , specified by its prospect_id. This request is the request POST/{object}/{object_id}/extensions/fields/{extension_field_id} where our object is "prospects" whose id is prospect_id.

List Available Progressions on a Prospect

See the progressions section for a sample request

GET /prospects/{prospect_id}/progressions

This request returns a list of available progressions for a prospect, specified by its prospect_id. This is the request GET /{object}/{object_id}/progressions where the object is "prospects" whose id is prospect_id.

Auto Run a Progression on a Prospect

See the progressions section for a sample request

PUT|POST /prospects/{prospect_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress a prospect, specified by its prospect_id. This is the request [POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto where the object is "prospect" whose id is prospect_id.

List a Prospect's Resource Collections

Sample Request:

GET /prospects/{prospect_id}/collections

This request returns a list of resource collections against an prospect, specified by its prospect_id. This is the request GET /{object}/{object_id}/collections where the object is "prospects" and hose id is {prospect_id}.

Upload a Resource (Attachment) to a Collection on a Prospect

Sample Request:

POST /prospects/{prospect_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of an prospect specified by its prospect_id. This is the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "prospects" whose id is {prospect_id}.

Purchases

Object URI:
/api/v0/purchases

Track the purchases made when completing a job, issue or contract. More information can be found on the support documentation

The Purchase Object

The purchase object contains the following fields:

Field Type Description
id unsigned The unique identifier for the purchase.
title string The title of the purchase.
owner_id unsigned The identifier of the staff who owns the purchase. Defaults to "0".
creator_id unsigned The identifier of the staff who created the invoice. Defaults to "0".
affiliation_id unsigned The identifier of the affiliation associated with the purchase. Defaults to "0".
amount decimal The monetary amount of the purchase. Defaults to "0.00".
tax decimal The tax on the purchase. Defaults to "0.00".
total decimal The total value of the purchase: amount + tax. Defaults to "0.00".
date_purchased unix ts The date of the purchase. Defaults to "0".

Get Purchase

GET /purchases/{purchase_id}

Sample request:

GET /api/v0/purchases/{purchase_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
CURL -X get \
    https://{deployment}.api.accelo.com/api/v0/purchases/{purchase_id} \
    -H 'authorization: Bearer {access_token}'

This request returns a purchase identified by its purchase_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the purchase object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the purchase with its default fields and any additional fields requested through _fields.

List Purchases

GET /purchases

GET /api/v0/purchases/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
CURL -X get \
    https://{deployment}.api.accelo.com/api/v0/purchases/ \
    -H 'authorization: Bearer {access_token}'

This request returns a list of purchases on the deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

This request also supports requesting additional fields and linked objects from the purchase object using the _fields parameter, as well as breadcrumbs.

Basic Filters

This request supports the following basic filters:

Filter
id
owner_id
creator_id
affiliation_id
Date Filters

This request supports the following date filters:

Filter
date_purchased
Order Filters

This request supports order filters over the following fields:

Field
amount
tax
total
id
owner_id
creator_id
affiliation_id
Range Filters

This request supports range filters over the following fields:

Field
amount
tax
total
id
owner_id
creator_id
affiliation_id
Searching

This request supports the _search parameter to search over teh following fields:

Field
title

Handling the Response

The response will be a list of purchases with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Purchases

GET /purchases/count

GET /api/v0/purchases/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
CURL -X get \
    https://{deployment}.api.accelo.com/api/v0/purchases/count \
    -H 'authorization: Bearer {access_token}'

This request will return a count of purchases in a list defined by any available searches or filters. With no searches or filters this will return a count of all purchases on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the purchases listed.

List a Purchase's Profile Field Values

See the profiles section for a sample request

GET /purchases/{purchase_id}/profiles/values

This request returns a list of profile field values on a purchase specified by its purchase_id. This is the request GET/{object}/{object_id}/profiles/values, where the object is "purchases" whose id is {purchase_id}

List all Profile Field Values on Purchases

See the profiles section for a sample request

GET /purchases/profiles/values

This request returns a list of all profile field values on purchases This is the request GET /{object}/profiles/values, where the object is "purchases".

List Purchase Profile Fields

See the profiles section for a sample request

GET /purchases/profiles/fields

This request returns a list of profile fields available for any purchase This is the request GET /{object}/profiles/fields, where the object is "purchases".

Quotes

Resource URI:
/api/v0/quotes

Quotes in Accelo allow you to generate and edit your quotes and proposals. See the support documentation for information on quotes.

The Quote Object

Example quote object:

{
  "created_by": "14",
  "conclusion": "<p><b>Looking forward to starting.</b></p>",
  "service_time_total": "3600",
  "created_by_staff_id": "14",
  "status_id": "1",
  "notes": "Here are some notes",
  "date_expiry": null,
  "title": "Website Redesign",
  "portal_access": "0",
  "affiliation": "98",
  "service_price_total": "300.50",
  "manager": "14",
  "status": "1",
  "terms": "<p><i>These are some terms and conditions</i></p>",
  "against": "prospects/9",
  "introduction": "<h1>We're quite happy to perform the work.</h1>",
  "contact": "98",
  "material_price_total": "41.10",
  "affiliation_id": "98",
  "total_price": "341.60",
  "manager_id": "14",
  "date_created": "1494311070",
  "standing": "draft",
  "against_id": "9",
  "against_type": "prospect",
  "id": "3"
}

The quote object contains the following:

Field Type Description
id unsigned A unique identifier for the quote.
title string A name for the quote.
against_type string The type of object the quote is against.
against_id unsigned The unique identifier of the object the quote is against.
against string The API URI of the object the quote is against.
notes string Additional notes on the quote.
portal_access boolean Whether the quote has been published with a client portal link.
affiliation_id unsigned The unique identifier of the affiliation associated with the quote.
affiliation unsigned or object The affiliation associated with the quote
date_created unix ts The date the quote was created.
date_expiry unix ts The date the quote is set to expire.
manager_id unsigned The unique identifier of the staff member who is set to manage the quote.
manager unsigned or object The staff member who is assigned to manage the quote.
status_id unsigned the unique identifier of the quote status of the quote.
status unsigned or object The quote status
standing string The standing of the quote. This is part of the status object.
created_by_staff_id unsigned The unique identifier of the staff member who created the quote.
created_by unsigned or object The staff member who created the quote.
introduction string HTML for a the introduction of the published quote.
conclusion string HTML for the conclusion of the published quote.
terms string HTML for the terms and conditions of the published quote.
service_price_total decimal The total price for all services associated with the quote.
service_time_total integer The total time, in seconds, of services for the quote.
material_price_total decimal The total price for all materials associated with the quote.
total_price decimal The total price of the quote; service_price_total + material_price_total

Get Quote

Sample Request:

GET /api/v0/quotes/{quote_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/quotes/{quote_id} \
  -H 'authorization: Bearer {access_token}'

GET /quotes/{quote_id}

This request returns a single quote, identified by its quote_id.

Configuring the Response

This request supports requesting additional fields and linked resources from the quote object using the _fields parameter.

Handling the Response

The response will be the single quote object with its default fields and any additional fields requested through _fields.

List Quotes

Sample Request:

GET /api/v0/quotes HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/quotes \
  -H 'authorization: Bearer {access_token}'

GET /quotes

This request returns a list of quotes on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Resources

This request supports requesting additional fields and linked resources from the quote object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
affiliation Filter by affiliation_id.
manager Filter by the manager_id.
status Filter by the status_id.
against_type
against_id
created_by Filter by the created_by_staff_id.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
date_expiry
Order Filters

This request supports order filters over the following fields:

Filter Name
id
date_created
date_expiry
service_price_total
service_time_total
material_price_total
total_price
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
against_id
manager Range by the manager_id.
affiliation Range by the affiliation_id.
status Range by the status_id.
created_by Range by the created_by_staff_id.
service_price_total
service_time_total
material_price_total
total_price
Object Filters

This request supports the following object filters:

Filter Description
against Filter by quotes against these objects.
Searching

This request supports the _search request over the following fields:

Field
title

Handling the Response

The response will be a list of quotes with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Quotes

Sample Request:

GET /api/v0/quotes/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/quotes/count \
  -H 'authorization: Bearer {access_token}'

GET /quotes/count

This request will return a count of quotes in a list defined by any available searches or filters. With no searches or filters this will be a count of all quotes on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the quotes listed

Update a Quote

Sample Request:

PUT /api/v0/quotes/{quote_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/quotes/{quote_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /quotes/{quote_id}

This request updates and returns a quote, identified by its quote_id.

Configuring the Quote

The following fields from the quote object may be updated with this request:

Filter Name Notes
title
affiliation_id
manager_id
date_expiry
notes
introduction
conclusion
terms_and_conditions Update the HTML of the terms of the published quote.
client_portal_access Update the portal_access field.

Configuring the Response

This request supports requesting additional fields and linked objects from the quote object using the _fields parameter.

Handling the Response

The response will be the single, updated quote with its default fields and any additional fields requested through _fields

Create a Quote

Sample Request:

POST /api/v0/quotes HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/quotes \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /quotes

This request creates and returns a quote.

Configuring the Quote

This request accepts the same fields as PUT /quotes/{quote_id}, with the addition of the following required fields:

Filter Name
title
against_id
against_type

Configuring the Response

This request supports requesting additional fields and linked objects from the quote object using the _fields parameter.

Handling the Response

The response will be the single, created quote object with its default fields and any additional fields requested through _fields.

Get Quote Status

Sample Request:

GET /api/v0/quotes/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/quotes/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}' \

GET /quotes/statuses/{status_id}

This request returns the quote status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a quote status object for the specified status with its default fields and any additional fields requested through _fields.

List Quote Statuses

Sample Request:

GET /api/v0/quotes/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/quotes/statuses \
  -H 'authorization: Bearer {access_token}'

GET /quotes/statuses

This request returns a list of statuses for quotes on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The request will return a list of quote statuses with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Quote Statuses

Sample Request:

GET /api/v0/quotes/statuses/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/quotes/statuses/count \
  -H 'authorization: Bearer {access_token}'

GET /quotes/statuses/count

This request will return a count of quote statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all quote statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed quote statuses.

List Resource Collections

See the resources (attachments) section for an example

GET /quotes/{quote_id}/collections

This request returns a list of resource collections against an quote, specified by its quote_id. This is the request GET /{object}/{object_id}/collections where the object is "quotes" and hose id is {quote_id}.

Upload a Resource (Attachment)

See the resources (attachments) section for an example

POST /quotes/{quote_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of an quote specified by its quote_id. This is the request POST /{object}/{object_id}/collections/{collection_id}/resources where the object is "quotes" whose id is {quote_id}.

Rates

Resource URI:
/api/v0/rates

Rates define the hourly rate paid for work done. They may be set up and modified from the deployment, see the support documentation for information.

The Rate Object

Example rate object:

{
  "object": "staff,issue,job,milestone,contract_period",
  "standing": "active",
  "charged": "175.00",
  "title": "Consulting",
  "id": "6"
}

The rate object contains the following:

Field Type Description
id unsigned A unique identifier for the rate.
title string A name for the rate.
charged decimal The hourly rate for this rate.
standing select Either "active" or "inactive", the standing of the rate.
object string A list of objects this rate is applicable to.

Get Rate

Sample Request:

GET /api/v0/rates/{rate_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/rates/{rate_id} \
  -H 'authorization: Bearer {access_token}'

GET /rates/{rate_id}

This request returns a rate specified by its rate_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the rate object using the _fields parameter.

Handling the Response

The response will be the single rate with its default fields and any additional fields requested through _fields.

List Rates

Sample Request:

GET /api/v0/rates HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/rates \
  -H 'authorization: Bearer {access_token}'

GET /rates

This request returns a list of rates on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the rate object using the _fields parameter.

Handling the Response

The response will be a list of rates with the default fields and any additional fields requested through _fields, displayed according to any pagination parameters used.

Count Rates

Sample Request:

GET /api/v0/rates/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/rates/count \
  -H 'authorization: Bearer {access_token}'

GET /rates/count

This request will return a count of rates in a list defined by any available searches or filters. With no searches or filters this will be a count of all rates on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of rates listed.

Referrals

Resource URI: /api/v0/referrals

Referrals provide a link between an object and the object it was created from. An example of this would be a job that has been created from a prospect.

The Referral Object

Example referral object:

{
    "id": "29",
    "referrer_id": "88",
    "referrer_type": "job",
    "against_id": "84",
    "against_type": "issue",
    "updated_by": "1",
    "date_updated": "1448519478",
    "created_by": "2",
    "date_created": "1448519478",
}

The referrals object contains the following:

Field Type Description
id unsigned A unique identifier for the referral.
referrer_id unsigned The id of the object which made the referral.
referrer_type string The type of the object which made the referral. eg. 'prospect'.
against_id unsigned The id of the object which was created via referral.
against_type string The type of the object which was created via referral. eg. A 'job' which was created via a 'prospect'.
updated_by unsigned The id of the staff member who last updated this referral.
date_updated unix ts The date that this referral was last updated.
created_by unsigned The identifier of the user who created the referral.
date_created unix ts The date that the referral was created.

Get Referral

Sample Request:

GET /api/v0/referrals/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/referrals/{id} \
  -H 'authorization: Bearer {access_token}'

GET /referrals/{id}

This request returns a single referral, specified by its id.

Configuring the Response

This request supports requesting additional fields and linked objects from the referral using the _fields parameter.

Handling the Response

The response will be the single requested referral with its default fields and any additional fields requested through _fields.

List Referrals

Sample Request:

GET /api/v0/referrals HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/referrals \
  -H 'authorization: Bearer {access_token}'

GET /referrals

This request returns a list of referrals on the deployment.

Configuring the Request

Pagination

This request accepts all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
against_type
against_id
referrer_type
referrer_id
created_by
updated_by
probability
standing
Date Filters

This request supports date filters over the following fields:

Filter Name
created
updated
Order Filters

This request supports order filters over the following fields:

Filter Name
id
date_created
date_updated
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id

Handling the Response

The response will be a list of referrals on the Deployment, with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Referrals

Sample Request:

GET /api/v0/referrals/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/referrals/count \
  -H 'authorization: Bearer {access_token}'

GET /referrals/count

This request will return a count of referrals defined by any available searches of filters. With no searches or filters this will be a count of all referrals on the deployment. This request returns a single field.

Field Type Description
count unsigned A count of referrals listed.

Requests

Resource URI: /api/v0/requests

These allow you to track request from clients sent to your shared company addresses, such as "@support" or "@sales" addresses. See the support documentation for more information on requests.

The Request Object

Sample request object:

{
  "thread_id": "1039",
  "id": "31",
  "source": null,
  "standing": "pending",
  "request_priority": "1",
  "date_created": "1494823725",
  "date_modified" : "123456789",
  "type_id": "2",
  "claimer": "23",
  "body": "This is a support request, it is urgent!",
  "title": "Urgent support request",
  "priority_id": "1",
  "type": "2",
  "affiliation_id": "77",
  "lead_id": "0",
  "affiliation": "77",
  "claimer_id": "23"
}

The request object contains the following:

Field Types Description
id unsigned A unique identifier for the request.
title string A name for the request.
body string The body of the request.
standing select The standing of the request ,may be either "pending", "open", "converted", or "closed".
source string Either "email" or null, whether the source of the request was an external email.
lead_id unsigned A unique identifier for the sender, if they are a lead. If a request comes from an unknown sender they will be marked as a "lead".
thread_id unsigned The unique identifier of the activity thread the request is associated with.
date_created unix ts The date the request was created.
date_modified unix ts The date the request was last updated.
type_id unsigned The unique identifier of the request type.
type unsigned or object The request type.
priority_id unsigned The unique identifier of the request priority.
priority unsigned or object Deprecated, please use request_priority
request_priority unsigned or object The request priority.
claimer_id unsigned The unique identifier of the staff who has claimed the request.
claimer unsigned or object The staff member who has claimed the request.
affiliation_id unsigned The unique identifier of the affiliation associated with the request.
affiliation unsigned or object The affiliation associated with the request.

The Request Type

Example request type object:

{
  "unresolved_count": "21",
  "id": "2",
  "subscribed": 0,
  "status": "active",
  "title": "Support"
}

The request type object allows you to assign a type to each request, making them easier to track and categorize. By default there are two types "support" and "sales", you may set up as many different types as you like from your deployment, see the support documentation for more information. This object contains the following:

Fields Type Description
id unsigned A unique identifier for the request type.
title string A name for the request type.
standing select The standing of the request type, either "active" or "inactive".

The Request Priority

Issue priorities help you keep track of what needs to be done. They may be set up from the deployment, they contain the following:

Field Type Description
id unsigned A unique identifier for the priority.
title string A name for the priority.
color select The color of the priority when displayed on the deployment. The colors, in order of increasing urgency a "grey", "blue", "green", "orange", "red".
factor unsigned A number representing the urgency of the priority. 5 is "Extreme", 1 is "None".

Request Threads

Sample request thread:

{
  "title": "Urgent support request",
  "date_last_responded": 1494823725,
  "id": 31,
  "date_created": "1494823725",
  "number_of_activities": 1,
  "senders": [
    {
      "id": 77,
      "type": "affiliation"
    }
  ],
  "thread_id": 1039,
  "standing": "pending",
  "date_latest_external_interaction": 1494823725,
  "claimer": {
    "type": "staff",
    "id": 23
  },
  "type": {
    "id": 2,
    "type": "request_type"
  },
  "body": "This is a support request, it is urgent!",
  "affiliation": {
    "type": "affiliation",
    "contact": {
      "type": "contact",
      "id": 77
    },
    "id": 77,
    "company": {
      "id": 54,
      "type": "company"
    }
  }
}

Since request are communications made from the deployment, they each have an associated activity. We can then track the communication made on a request as a thread of activities, although we want a bit more information than is given in activity threads; the request thread contains the following:

Field Type Description
thread_id unsigned The unique activity_id of the original request.
id unsigned The id of the request.
title string As in the request object.
body string As in the request object.
standing select As in the request object.
number_of_activities integer The number of activities in the thread.
date_created unix ts as in the request object.
date_last_responded unix ts The date of the latest response to the request (from either the client or a staff member).
date_last_external_interaction unix ts the date of the last interaction on the request by a client.
claimer object An object describing the claimer of the request, this object contains a "type" field, describing the type of object, and an "id" field giving its identifier.
type object The request type of the request.
senders array An array of senders of the original request, each defined by a "type" an an "id".
affiliation object As in the request object.

Request Thread Unresponded Counts

Example object:

{
    "subscribed": 1,
    "unresolved_count": "22",
    "id": "2",
    "title": "Support",
    "status": "active"
}

These objects track the number of unresponded requests against each request type, they may be requested with request threads, see the list threads request. The unresponded counts object contains the following:

Field Type Description
id unsigned The unique identifier for the request type.
title string The name of the request type.
status string The standing of the request as in the type object.
unresolved_count unsigned A count of unresolved requests of the given type.
subscribed boolean Either "1" or "0", whether the user has subscribed to the given request type through their preferences.

Get Request

Sample Request:

GET /api/v0/requests/{request_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/requests/{request_id} \
  -H 'authorization: Bearer {access_token}'

GET /requests/{request_id}

This request returns a request specified by its request_id.

Configuring the Response

This request supports requesting additional fields and linked from the request object using the _fields parameter.

Handling the Response

The response will be the single request with its default fields and any additional fields requested through _fields.

List Requests

Sample Request:

GET /api/v0/requests HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/requests \
  -H 'authorization: Bearer {access_token}'

GET /requests

This request returns a list of requests on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the request object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
standing
affiliation Filter by affiliation_id.
type Filter by the type_id.
priority Deprecated, please use request_priority
request_priority Filter by the priority_id.
lead Filter by the lead_id.
claimer_id
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
date_modified
Order Filters

This request supports order filters over the following fields:

Filter Name
id
date_created
date_modified
Range Filters

This request supports range filters over the following fields:

Notes
id
type Range over the type_id.
progressed_by Range over the staff_id of the last staff member to progress the standing of the request.
lead Range over the lead_id.
affiliation Range over the affiliation_id.
priority Deprecated, please use request_priority
request_priority Range over the affiliation_id.

Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of requests with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used. s

Count Requests

Sample Request:

GET /api/v0/requests/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/requests/count \
  -H 'authorization: Bearer {access_token}'

GET /requests/count

This request will return a count of requests in a list defined by any available searches or filters. With no searches or filters this will be a count of all requests on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of requests listed.

List Request Threads

Sample Request:

GET /api/v0/requests/threads HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/requests/threads \
  -H 'authorization: Bearer {access_token}'

GET /requests/threads

This request returns a list of request threads on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
standing
request_type_id Filter by the type_id.
interact_from_staff Filter by the staff_id of staff who have interacted with the request.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
Boolean Filters

this request also supports a special kind of filter, the boolean filter. These filters take boolean arguments, the supported filters are:

Filter Name Notes
request_is_claimed Filter by whether or not a request is claimed.
show_inactive_type Whether or not to show requests from inactive types. By default these are not shown.
order_by_date_created Whether to order in ascending order of date_created.
order_by_desc_latest_external_interaction Whether to order in ascending order of date_last_external_interaction.
List Unresponded Counts

Sample request:

GET /api/v0/requests/threads  HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_include_unresponded_counts = 1
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/requests/threads \
  -H 'authorization: Bearer {access_token}' \
  -d '_include_unresponded_counts = 1'

This request also supports a flag, include_unresponded_counts which may be either '0' or '1'. If set to '1' this returns an additional array, unresponded_counts

Handling the Response

The response will be an array of request threads labeled "requests", and an array of linked objects labeled "linked_objects". The "linked_objects" array is an array of objects linked to the requests in the "requests" array. Any filters used will be applied to the elements of the "request" array.

List Request Types (Beta)

Sample Request:

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/requests/types \
  -H 'authorization: Bearer {access_token}' \
GET /api/v0/requests/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

GET /requests/types

This request returns a list of request_type objects, which contain the following:

Field Type Description
id unsigned A unique identifier for the object.
title string A title for the object.
status select Either "active" or "inactive" the status of the type.
unresolved_count integer A count of unresolved requests of this type on the deployment.
subscribed boolean 1/0 Whether the current user is subscribed to this request type.

Note this is different to the request type object.

Handling the Response

This request does not accept pagination, filtering, or searching. The response will be a list of request_type objects on the deployment.

Update a Request

Sample Request:

PUT /api/v0/requests HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/requests \
  -H 'authorization: Bearer {access_token}'
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /requests/{request_id}

This request updates and returns a request identified by its request_id.

Configuring the Request

Values for the following fields may be updated through this request:

Field Name
title
body
type_id
lead_id
affiliation_id
priority_id
source
standing
claimer_id

Configuring the Response

This request supports requesting additional fields and linked objects from the request object using the _fields parameter

Handling the Response

The response will be the single, updated request with its default fields and any additional fields requested through _fields.

Create a Request

Example request:

curl -post \
  https://al-interns.api.accelo.com/api/v0/requests \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'title=I%20request%20support%20your%20website' \
  -d 'body=how%20do%20I%20use%20it%3F' \
  -d 'type_id=2' \
  -d 'affiliation_company_name=Jack%20and%20Co.' \
  -d 'affiliation_company_phone=%2B13%203234%202324' \
  -d 'affiliation_contact_firstname=Jack' \
  -d 'affiliation_contact_surname=Black' \
  -d 'affiliation_email=jack.black%40jack-and-co.com' \
  -d 'affiliation_phone=64%20444%20444%20444'

Request using JSON:

curl -X post \
  https://al-interns.api.accelo.com/api/v0/requests \
  -H 'authorization: Bearer H3idpjeiXO9FaS4C5IA3phXnYQYCT5bVmJRXruVCcpb7PdApC5K8Rrss-mO17wPi' \
  -H 'content-type: application/json' \
  -d '{
      "type_id": 2,
      "title": "The website has become unresponsive",
      "body": "Your home page is timing out?",
      "affiliation": {
          "contact" : {
              "firstname": "Jack",
              "surname": "Black"
           },
           "company": {
               "name": "Jack and Co.",
               "phone": "+13 3234 2324"
           },
           "email": "jack.black@jack-and-co.com",
           "phone": "64 444 444 444"
      }
  }'

POST /requests

This request creates and returns a request. Since a request requires an affiliation, and request may not necessarily come from known contacts, using this request you may also create a contact/affiliation, see.

Configuring the Request

The following fields may be set through this request:

Field Name Notes
title
body
type_id
affiliation_id If an affiliation_id is not available please follow the proceeding steps.
priority_id
source May either be "email" or "null".
lead_id

Handling a Lack of Affiliation

If no affiliation data is available we will attempt to link the given data to a known affiliation, otherwise we will create one. There are three minimum sets of information we can use to create an affiliation:

  1. A firstname and a surname
  2. A firstname and a company name
  3. An email address

Given a Firstname and a Surname

If an affiliation exists which exactly matches these two names, we will link it. Otherwise, we will create a company and contact with the name "firstname surname", and then create an affiliation to link the two.

Given a Firstname and a Company Name

If there is no match the company name, a new company with this name will be used, then a contact under this company will be created using the firstname supplied, finally an affiliation will be created to link the two.

Given an Email Address

If there is no match, we will attempt to extract a name from the email provided. Next, a company will be made with the provided email as the name, then a contact will be made under this company, whose name would be the name extracted from the email. Finally an affiliation would link the two.

The following fields may be used to send this information:

Create a new request without an affiliation: The JSON method

{
    "type_id": 2,
    "subject": "The website has become unresponsive",
    "title": "Your home page is timing out?",
    "affiliation": {
        "contact" : {
            "firstname": "Jack",
            "surname": "Black"
         },
         "company": {
             "name": "Jack and Co.",
             "phone": "+13 3234 2324"
         },
         "email": "jack.black@jack-and-co.com",
         "phone": "64 444 444 444"
    }
}
Field Name
affiliation_email
affiliation_phone
affiliation_contact_id
affiliation_contact_firstname
affiliation_contact_surname
affiliation_company_id
affiliation_company_name
affiliation_company_phone

You may also send contact and company information as a JSON payload. Ensure that the content type is set to application/json in this case. For example here we have created a contact, company and affiliation in handling a request.

Configuring the Response

The request supports requesting additional fields and linked objects from the request object using the _fields parameter.

Handling the Response

The response will be the new, single, request with its default fields and any fields requested through _fields.

Resources (Attachments)

Resource URI:
api/v0/resources

Resources (or attachments) are files uploaded to the deployment. Collections are used to group resources on the deployment, they are similar to a folder system for resources.

The Resource Object

Example resource object:

{
  "id": "4",
  "title": "Quote 14 May 2015.pdf",
  "date_created": "1431565085",
  "mimetype": "application/pdf",
  "filesize": "13678"
}

The resource object contains the details on an uploaded file:

Field Type Description
id unsigned A unique identifier for the resource.
title string A name for the resource.
date_created unix ts The date the resource was uploaded.
mimetype string The MIME type of the resource. For example "application/pdf", "image/png".
filesize integer The size of the file in bytes.
collection_id unsigned The unique identifier of the collection the resources belongs to.
owner_type string The type of object that uploaded the resource.
owner_id unsigned The unique identifier of the object that uploaded the resource.

The Collection Object

Example collection object:

{
  "id": "48",
  "title": "1. Sign up quote"
}

The collection object describes a collection against a specific object, it contains the following:

Field Type Description
id unsigned A unique identifier for the collection.
title string A name for the collection.
against_type string The type of object the collection is against.
against_id unsigned The unique identifier of the object the collection is against.

Get Resource

Sample Request:

GET /api/v0/resources/{resource_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/resources/{resource_id} \
  -H 'authorization: Bearer {access_token}'

GET /resources/{resource_id}

This request returns a resource identified by its resource_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the resource objects using the _fields parameter.

Handling the Response

The response will be the resource with its default fields and any additional fields requested through _fields.

List Resources

Sample Request:

GET /api/v0/resources HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/resources \
  -H 'authorization: Bearer {access_token}'

GET /resources

This request returns a list of resources on the deployment.

Configuring the Response

Pagination

This request supports all the pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the resource object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
mimetype
activity_id Filter by the activity_id of the activity through which the resources was uploaded.
collection_id Filter by resources belonging to the collections with these IDs.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
Order Filters

This request supports order filters over the following fields:

Filter Name
id
title
filesize
mimetype
Object Filters

This request supports the following object filters:

Filter Name Notes
owner Filter by resources owned by these objects.
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of resources with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Resources

Sample Request:

GET /api/v0/resources/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/resources/count \
  -H 'authorization: Bearer {access_token}'

GET /resources/count

This request will return a count of resources in a list defined by any available searches or filters. With no searches or filters this will be a count of all resources on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of resources listed.

List Collections for an Object

Sample Request:

GET /api/v0/{object}/{object_id}/collections HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0{object}/{object_id}/collections \
  -H 'authorization: Bearer {access_token}'

GET /{object}/{object_id}/collections

This request returns a list of collections against an object, identified by its object_id.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Handling the Response

The response will be a list of collections with their default fields, and displayed according to any pagination filters used.

Upload a Resource to a Collection

Sample Sample Request:

POST /api/v0/companies/39/collections/83/resources
HOST: {deployment}.api.accelo.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer {access_token}

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="resource"; filename="example.pdf"
Content-Type: application/pdf


------WebKitFormBoundary7MA4YWxkTrZu0gW--
curl -X post \
  https://{deployment}.api.accelo.com/api/v0/companies/39/collections/83/resources \
  -H 'authorization: Bearer tM.G-I_F8jEn8oKzm.IvqWtq7gii4rHj.FBSKZr-RaABnRsYaF734afGRzXosjrY' \
  -H 'content-type: multipart/form-data' \
  -F 'resource=@/home/user/example.pdf'

POST /{object}/{object_id}/collections/{collection_id}/resources

This request uploads a file to a given collection, identified by its collection_id, of a particular object identified through object and object_id.

Configuring the Resource

The file may be uploaded using the following parameter:

Field Type Description
resource file The file to be uploaded.

Handling the Response

The response will contain the following fields:

Field Type Description
title string The name of the resource.
size integer The size of the attachment in bytes.
mimetype string The mime type of the attachment.

Download a Resource

Sample Request:

GET /api/v0/resources/{resource_id}/download HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/resources/{resource_id} \
  -H 'authorization: Bearer {access_token}'

GET /resources/{resource_id}/download

This request downloads a resource, identified by its resource_id. This request takes no parameters and returns only the file to be downloaded.

Segmentations

Resource URI:
/api/v0/segmentations

Segmentations or (Categories) organize and segment your Company list into different categories for better management and reporting, letting you shape Accelo to match just what your business needs. See the support documentation for more information.

The Segmentation Object

Example segmentation object:

{
      "link_type": "company",
      "id": "2",
      "leaf": "1",
      "title": "Size",
      "exclusive": "1",
      "required": "0",
      "standing": "active"
}

The segmentation object contains the following:

Field Type Description
id unsigned A unique identifier for the segmentation.
title string A name for the segmentation.
link_type string The object type that the segmentation is related to, may be 'company', 'affiliation' or 'contact'.
standing string The standing of the segmentation, may be "active" or "inactive".
required boolean Either Yes or No, whether this segmentation is required for the object it is against.
exclusive boolean Either Yes or No, whether this segmentation is limited to one value.
leaf boolean Either Yes or No, whether this segmentation is limited to only child options.

Get a Segmentation

Sample Request:

GET /api/v0/segmentation/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/segmentation{id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

GET /segmentations/{id}

This request gets and returns a single segmentation specified by its id.

Configuring the Response

This request supports requesting additional fields and linked items from the segmentation object using the _fields parameter.

Handling the Response

The response will be a single segmentation with its default fields and any additional fields requested through _fields.

List Segmentations

Sample Request:

GET /api/v0/segmentations HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/segmentations \
  -H 'authorization: Bearer {access_token}'

GET /segmentations

This request returns a list of segmentations for the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Resource

This request supports requesting additional fields and linked resources from the segmentation using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
link_type
standing
required
exclusive
leaf
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
id
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id

Handling the Response

The response will be a list of segmentations with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Segmentations

Sample Request:

GET /api/v0/segmentations/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/segmentations/count \
  -H 'authorization: Bearer {access_token}'

GET /segmentations/count

This request will return a count of segmentations in a list defined by any available searches or filters. With no searches or filters this will be a count of all segmentations on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the segmentations listed.

Signoffs

Resource URI:
/api/v0/signoffs

Signoffs in Accelo allow your clients to approve your work and make comments against attachments and work descriptions. See the support documentation for more information on signoffs.

The Signoff Object

Example Signoff Object:

{
    "against": "jobs/39",
    "requires": "any",
    "standing": "draft",
    "date_created": "1398651556",
    "date_updated": "1529619011",
    "html_body": "Finish creating those things",
    "standing_color": "yellow",
    "against_id": "39",
    "body": "Finish creating those things",
    "created_by_id": "40",
    "subject": "Creating things",
    "permissions": {
      "can_redraft": 0,
      "can_send": 1,
      "can_edit": 1
    },
    "date_expires": "1519822799",
    "preview_body": "Finish creating those things",
    "against_type": "job",
    "id": "1",
    "created_by": "40"
}

The signoff object contains the following:

Field Type Description
id unsigned A unique identifier for the signoff.
subject string A name for the signoff.
standing string The signoffs standing/status. Either "Draft", "Sent", "Approved" or "Declined".
requires string Whether the signoff requires "any" approvers or "all" approvers to approve the quote.
against string The API URL for the object the signoff is against e.g. "jobs/39".
date_created unix ts The date the signoff was created.
date_updated unix ts The date the signoff was last updated.
standing_colour string The colour associated with the signoffs current standing/status.
against_id unsigned The unique identifier of the object this signoff is against.
against_type string The type of object this signoff is against.
body string The main content for the signoff.
preview_body string A shortened form of the main content of the signoff
html_body string The main content of the signoff returned as HTML.
created_by unsigned or object The staff member who created this signoff.
created_by_id unsigned The unique identifier for the staff member who created this signoff.
permissions object An object containing the permissions for the current user on this signoff
date_expires unix ts The date the signoff becomes invalid.

The Recipient Object

A recipient is the contact or contributor that a signoff is sent to.

Example Recipient Object

    {
      "recipient": {
        "type": "affiliation",
        "name": "Fred",
        "id": "300",
        "email": "fred@email.com"
      },
      "response": "pending",
      "date_responded": "1516689196",
      "recipient_type": "affiliation",
      "recipient_id": "300",
      "signoff_id": "2",
      "approver": "1",
      "id": "6"
    }

The recipient object contains the following:

Field Type Description
id unsigned A unique identifier for the recipient.
signoff_id unsigned The identifier of the signoff this recipient is related to.
recipient_id unsigned The identifier of the recipient
recipient_type string The object type of the recipient e.g. 'affiliation' or 'staff'.
response string The response of the recipient to the signoff.
date_responded unix ts The date in which the recipient responded to the sign off.
recipient object An object describing more information about the recipient.
approver boolean Whether the user can approve the quote related to this signoff.

The Attachment Object

The attachment object represents one resource that is attached to a signoff.

Example Attachment Object

{
      "signoff_id": "2",
      "activity_id": "0",
      "id": "1",
      "resource": "316",
      "resource_id": "316",
      "standing": "active"
}

The attachment object contains the following:

Field Type Description
id unsigned A unique identifier for the attachment.
signoff_id unsigned The identifier for the signoff the attachment is related to.
resource_id unsigned The identifier for the resource that is attached.
standing string The standing/status for the attachment either 'active' or 'inactive'.
activity_id unsigned The identifier of the activity (if any) that the attachment is related to.

Get Signoff

Sample Request

GET /api/v0/signoffs/{signoff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/{signoff_id}} \
  -H 'authorization: Bearer {access_token}'

GET /signoffs/{signoff_id}

This request returns a single signoff using the _fields parameter.

Configuring the response

This request supports requesting additional fields and linked resources from the signoff object using the _fields parameter.

Handling the Response

The response will be the single signoff object with its default fields and any additional fields requested through _fields.

List Signoffs

Sample Request:

GET /api/v0/signoffs HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs \
  -H 'authorization: Bearer {access_token}'

GET /signoffs

This request returns a list of signoffs for the deployment.

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Resources

This request supports requesting additional fields and linked resources from the signoff object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
created_by
standing
requires
against_type
against_id
Date Filters

This request supports date filters over the following fields:

Filter Name
created
expires
updated
Order Filters

This request supports order filters over the following fields:

Filter Name
id
date_created
date_expires
date_updated
standing
subject
Empty Filters

This request supports empty filters over the following fields:

Field
subject
body
created_by
date_expires
date_updated
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
Object Filters

This request supports the following object filters:

Filter Description
against Filter by quotes against these objects.
Searching

This request supports the _search parameter to search over the following fields:

Field
subject

Count Signoffs

Sample Request:

GET /api/v0/signoffs/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/count \
  -H 'authorization: Bearer {access_token}'

GET /signoffs/count

This request will return a count of the signoffs in a list defined by any available searches or filters. With no searches or filters, this will be a count of all signoffs on the deployment. This request returns a single field.

Field Type Description
count unsigned A count of the signoffs listed.

Update Signoff

Sample Request:

PUT /api/v0/signoffs/signoff/{signoff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X put \
 https://{deployment}.api.accelo.com/api/v0/signoffs/signoffs/{signoff_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /signoffs/signoff/{signoff_id}

This request updates and returns a signoff, identified by its signoff_id.

Configuring the Signoff

The following fields from the signoff object may be updated with this request:

Field
body

Redraft a signoff

Sample Request:

POST /api/v0/signoffs/{signoff_id}/redraft HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X post \
 https://{deployment}.api.accelo.com/api/v0/signoffs/{signoff_id}/redraft \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /signoffs/{signoff_id}/redraft

This request allows a signoff to be re-drafted and returns the signoff, identified by its signoff_id.

Send a signoff

Sample Request:

POST /api/v0/signoffs/{signoff_id}/send HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X post \
 https://{deployment}.api.accelo.com/api/v0/signoffs/{signoff_id}/send \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /signoffs/{signoff_id}/send

This request allows a signoff to be sent and returns the sent signoff, identified by its signoff_id.

List Signoff Recipients

Sample Request:

GET /api/v0/signoffs/recipients HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/recipients \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

GET /signoffs/recipients

This request returns a list of all recipients for the deployment.

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Resources

This request supports requesting additional fields and linked resources from the recipient object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
signoff_id
recipient_type
recipient_id
response
approver
Date Filters

This request supports date filters over the following fields:

Filter Name
responded
Order Filters

This request supports order filters over the following fields:

Filter Name
id
date_responded
Range Filters

This request supports range filters over the following fields:

Filter Name
id
signoff_id
Empty Filters

This request supports empty filters over the following fields:

Field
date_responded

Count Signoff Recipients

Sample Request:

GET /api/v0/signoffs/signoffs/recipients/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/count \
  -H 'authorization: Bearer {access_token}'

GET /signoffs/recipients/count

This request will return a count of recipients in a list defined by any available searches or filters. With no searches or filters this will be a count of all recipients on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of recipients listed.

Get Signoff Recipient

Sample Request:

GET /api/v0/signoffs/recipients/{recipient_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/{recipient_id} \
  -H 'authorization: Bearer {access_token}'

GET /signoffs/recipients/{recipient_id}

This request returns a recipient identified by its recipient_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the recipient objects using the _fields parameter.

Handling the Response

The response will be the recipient with its default fields and any additional fields requested through _fields.

Create Signoff Recipient

Sample Request:

POST /api/v0/signoffs/recipients HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X post \
 https://{deployment}.api.accelo.com/api/v0/signoffs/recipients \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /signoffs/recipient

This request allows a recipient to be added to a signoff and returns a recipient. The following fields are set via this request.

Field Type Description
signoff_id unsigned The identifier of the signoff this recipient is related to.
recipient_id unsigned The identifier of the recipient
recipient_type string The object type of the recipient e.g. 'affiliation' or 'staff'.
approver string Whether the user can approve the quote related to this signoff. Must be one of 'yes' or 'no'.

Update Signoff Recipient

Sample Request:

PUT /api/v0/signoffs/recipients/{recipient_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X put \
 https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/{recipient_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /signoffs/recipients/{recipient_id}

This request allows the recipient of a quote to be updated and returns the recipient object, identified by their recipient_id. A recipient can only be edited if a user is the recipient and if the quote is in draft.

The following fields can be updated by this request:

Field Notes
approver
response You may only update your own response, and only if you are an approver.

Delete Signoff Recipient

Sample Request:

DELETE /api/v0/signoffs/recipients/{recipient_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X delete \
 https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/{recipient_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

DELETE /signoffs/recipients/{recipient_id}

This request allows the recipient of a quote to be deleted, identified by their recipient_id.

List Signoff Attachments

Sample Request:

GET /api/v0/signoffs/signoffs/attachments HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/attachments \
  -H 'authorization: Bearer {access_token}'

GET /signoffs/attachments

This request an list of attachment objects for the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting extra fields or linked objects from the attachment object using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
signoff_id
standing
resource_id
activity_id

Handling the Response

The response will be a list of containing the default fields and any additional fields requested by _fields, and displayed according to any pagination parameters or filters used.

Get Signoff Attachment

Sample Request:

GET /api/v0/signoffs/signoffs/attachments/{attachment_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/attachments/{attachment_id} \
  -H 'authorization: Bearer {access_token}'

GET /signoffs/attachments/{attachment_id}

This request returns an attachment specified by its attachment_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the attachment objects using the _fields parameter.

Handling the Response

The response will be the attachment with its default fields and any additional fields requested through _fields.

Count Signoff Attachments

Sample Request:

GET /api/v0/signoffs/signoffs/attachments/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/attachments/count \
  -H 'authorization: Bearer {access_token}'

GET /signoffs/attachments/count

This request will return a count of attachments in a list defined by any available searches or filters. With no searches or filters this will be a count of all attachments on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of attachments listed.

Upload Signoff Attachment

Sample Request:

POST /api/v0/signoffs/{signoff_id}/attachments HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="resource"; filename="example.pdf"
Content-Type: application/pdf


------WebKitFormBoundary7MA4YWxkTrZu0gW--
curl -X POST \
  https://{deployment}.api.local.accelo.com/api/v0/signoffs/1/attachments\
  -H 'authorization: Bearer {access_token}
  -H 'content-type: multipart/form-data'
  -F 'file=@example.pdf'

POST /signoffs/{signoff_id}/attachments

This request uploads a file as an attachment to the given signoff.

Configuring the Resource

The file may be uploaded using the following parameter:

Field Type Description
file file The file to be uploaded.

Handling the Response

The response will be the uploaded attachment with its default fields and any additional fields requests through _fields.

Update Signoff Attachment

Sample Request:

PUT /api/v0/signoffs/signoffs/attachments/{attachment_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/signoffs/attachments/{attachment_id} \
  -H 'authorization: Bearer {access_token}'

PUT /signoffs/attachments/{attachment_id}

This request updates an attachment identified by its attachment_id and returns the updated attachment object.

The fields able to be updated by this request are:

Field Notes
Status Updates the standing field

Skills

Resource URI:
/api/v0/skills

Skills are tags assigned to tasks or users which can then be used to appropriately assign work. See the support documentation for more information skills and how to use them on the deployment.

The Skill Object

Example skill object:

{
  "id": "4",
  "title": "Android"
}

The skills object contains the following:

Field Type Description
id A unique identifier for the skill.
title A name for the skill.

List Skills

Sample Request:

GET /api/v0/skills HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/skills \
  -H 'authorization: Bearer {access_token}'

GET /skills

This request returns a list of skills on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Resource

This request supports requesting additional fields and linked resources from the skill object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
title
Object Filters

This request supports the following object filters:

Filter Name Description
against Filter by skills applied to this object.
Searching

This request supports using the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of skills with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Skills

Sample Request:

GET /api/v0/skills/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/skills/count \
  -H 'authorization: Bearer {access_token}'

GET /skills/count

This request will return a count of skills in a list defined by any available searches or filters. With no searches or filters this will be a count of all skills on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the skills listed.

Create a Skill

Sample Request:

POST /api/v0/skills HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/skills \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /skills

This request creates and returns a skill.

Configuring the Skill

This request supports setting the following fields from the skill object:

Field Name
title

Configuring the Response

This request supports requesting additional fields and linked items from the skill object using the _fields parameter.

Handling the Response

The response will be the single, created skill with its default fields and any additional fields requested through _fields.

Staff

Resource URI:
/api/v0/staff

Staff (or users) are the users registered on the Accelo deployment. They are the company's Accelo users, admins, professionals, and collaborators

The Staff Object

The staff object contains the following

Field Type Description
id string A unique identifier for the staff member.
firstname string The staff member's first name.
surname string The staff member's surname.
standing select Either "active", "inactive", or "lockout", the standing of the staff member.
financial_level select Either "none", "time", or "all", the staff member's financial permission level.
title string A title for the member, for example "Mr", "Ms".
email string The staff member's email address.
mobile string The staff member's mobile number.
phone string The staff member's phone number.
fax string The staff member's fax number.
position string The staff member's position in the company.
username string The staff member's username on the deployment.
timezone string The staff member's timezone.
staff_rate decimal The staff member's billable rate. Not returned when requesting _ALL fields.
staff_cost_rate decimal The staff member's cost rate. Not returned when requesting _ALL fields.

The Staff Membership Object

This object tracks group membership for staff, each entry describes a link between a staff and a group.

Field Type Description
id unsigned A unique identifier for the membership.
group_id unsigned The id of the group the staff member is part of.
staff_id unsigned The id of the staff linked to the group.
staff unsigned or object The staff linked to the group.

Get Staff

Sample Request:

GET /api/v0/staff/{staff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/staff/{staff_id} \
  -H 'authorization: Bearer {access_token}'

GET /staff/{staff_id}

This requests returns a staff member, specified by their staff_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the staff object using the _fields parameter.

Handling the Response

The response is the single staff object with its default fields and any additional fields requested through _fields.

Get Current Staff

Sample Request:

GET /api/v0/staff/whoami HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/staff/whoami \
  -H 'authorization: Bearer {access_token}'

GET /staff/whoami

This request returns the staff object for the current staff member. It can be configured and handled in the same way as GET /staff/{staff_id}.

List Staff

Sample Request:

GET /api/v0/staff HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/staff \
  -H 'authorization: Bearer {access_token}'

GET /staff

This request returns a list of staff members on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the staff object using the _fields.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
email
standing
username
Range Filters

This request supports range filters over the following fields:

Filter Name
id
rate

Handling the Response

The response will be a list of staff objects with their default fields and any additional fields requested through _fields, displayed according to any pagination parameters or filters used.

Count Staff

Sample Request:

GET /api/v0/staff/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/staff/count \
  -H 'authorization: Bearer {access_token}'

GET /staff/count

This request will return a count of staff in a list defined by any available searches or filters. With no searches or filters this will be a count of all staff on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of staff members listed.

List Staff Memberships

Sample Request:

GET /api/v0/staff/memberships HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/staff/memberships \
    -H 'authorization: Bearer {access_token}'

GET /staff/memberships

This request returns a list of staff memberships on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the staff membership using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name Notes
id
staff_id
group_id
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
Order Filters

This request supports the following order filters:

Filter Name Notes
id

Handling the Response

The response will be a list of staff memberships with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Update a Staff Member

Sample Request:

PUT /api/v0/staff/{staff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/staff/{staff_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /staff/{staff_id}

This request updates and returns a staff member, identified by their staff_id.

Configuring the Staff

The following fields from the staff object may be updated with this Sample Request:

Field Name
firstname
surname
title
email
fax
phone
mobile
position

Configuring the Response

This request supports requesting additional fields and linked objects from the staff object using the _fields parameter.

Handling the Response

The response will be the update staff object with its default fields and any additional fields requested through _fields.

Create a Staff Member

Sample Request:

POST /api/v0/staff HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/staff \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /staff

This request creates and returns a new staff member.

Configuring the Staff

The following fields from the staff object may be set through this Sample Request:

Field Name Notes
username
password A password for the new staff member on the deployment.
firstname
surname
email
title
fax
phone
mobile
position

Configuring the Response

This request supports requesting additional fields and linked objects from the staff object using the _fields parameter.

Handling the Response

The response will be the single, updated staff object with its default fields and any additional fields requested through _fields.

Delete a Staff Member

Sample Request:

DELETE /api/v0/staff HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/staff \
  -H 'authorization: Bearer {access_token}'

DELETE /staff/{staff_id}

This request removes a staff member from the deployment, identified by their staff_id. This request takes no parameters and returns no resources.

List a Staff's Profile Field Values

See the profiles section for a sample request

GET /staff/{staff_id}/profiles/values

This request returns a list of profile values of a staff object, specified by its staff_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "staff", and whose id is staff_id.

List all Profile Field Values on a Staff

See the profiles section for a sample request

GET /staff/profiles/values

This request returns a list of all profile field values on staff. This is the request GET /{object}/profiles/values, where the object is "staff".

List Staff Profile Fields

See the profiles section for a sample request

GET /staff/profiles/fields

This request returns a list of profile fields available for any staff object. This is the request GET /{object}/profiles/fields where the object is "staff".

Update a Profile Field Value on a Staff

See the profiles section for a sample request

PUT /staff/{staff_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular staff object, specified by its staff_id. This is the request PUT/{object}/{object_id}/profiles/values/{profile_value_id} where the object is "staff", and whose id is the staff_id.

Set a Profile Field Value on a Staff

See the profiles section for a sample request

PUT|POST /staff/{staff_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a staff object, specified by its staff_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "staff", and whose value is staff_id.

Statuses

Statuses are used to track the progress of work. See the support documentation for more information. Since many resources on Accelo track various types and aspects of work, statuses are present in many different resources. Currently, statuses are supported on the following objects:

Status Objects

The status object contain the following:

Fields Type Description
id unsigned A unique identifier for the status.
title string A title for the status.
color string The color the status will appear in the Accelo deployment.
standing string The standing of the status. For example "active", "paused".
start string Either "yes" or "no", whether this status is available upon creation of the object.
ordering unsigned A number representing the status' order on the Accelo deployment.

Note that each resources keeps track of statuses separately, so a given status may not contain all the fields listed above, if this is the case we will state it in that resource's section.

Tags

Resource URI:
/api/v0/tags

Tags are keywords you my apply to a range of objects within Accelo, for example activities or jobs. They may both help describe the object, and make searching easier. See the support documentation for more information on tags and how to apply them.

The Tag Object

The tag object contains the following:

Fields Type Description
id unsigned A unique identifier for the tag.
name string A name for the tag.

List Tags

Sample Request:

GET /api/v0/tags HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tags \
  -H 'authorization: Bearer {access_token}'

GET /tags

This request returns a list of tags on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Resources

This request supports requesting additional fields and linked resources from the tag object using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
name
Object Filters

This request supports the following object filters:

Filter Name Description
against Filter by tags applied to this object.
Searching

This request supports the _search parameter to search over the following fields:

Field Name
name

Handling the Response

The response will be a list of tags with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Tags

Sample Request:

GET /api/v0/tags/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tags/count \
  -H 'authorization: Bearer {access_token}'

GET /tags/count

This request will return a count of tags in a list defined by any available searches or filters. With no searches or filters this will be a count of all tags on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of tags listed.

Create a Tag

Sample Request:

POST /api/v0/tags HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tags \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /tags

This request creates and returns a tag.

Configuring the Tag

The following fields from the tag object may be set with this request:

Field Name
name

Configuring the Response

This request supports requesting additional fields and linked objects from the tag object using the _fields parameter.

Handling the Response

The response will be the single, created tag with its default fields and any additional fields request through _fields.

Tasks

Resource URI:
/api/v0/tasks

Tasks are small units of work, they may be thought of as the type of work you would put on a "to-do" list. See the support documentation for more information on tasks and how to interact with them on the deployment.

The Task Object

Example task:

{
  "affiliation": "292",
  "against": "milestones/15",
  "against_id": "15",
  "against_type": "milestone",
  "assignee": "7",
  "billable": "3600",
  "budgeted": "0",
  "company": null,
  "contact": "292",
  "creator": "staff/7",
  "creator_id": "7",
  "creator_type": "staff",
  "custom_id": null,
  "date_accepted": "1362533400",
  "date_commenced": "1362533400",
  "date_completed": "1374208724",
  "date_created": "1362533400",
  "date_due": "1374199200",
  "date_modified": "1532347231",
  "date_started": "1362531600",
  "description": null,
  "id": "24",
  "issue": null,
  "job": null,
  "logged": "3600",
  "manager": "7",
  "milestone": "15",
  "nonbillable": "0",
  "object_budget": "113",
  "rate_charged": "175.00",
  "rate_id": "6",
  "remaining": "0",
  "staff_bookmarked": "0",
  "standing": "complete",
  "status": "5",
  "task_job": null,
  "task_object_budget": "113",
  "task_object_schedule": "113",
  "task_object_schedule_id": "113",
  "task_priority": "1",
  "task_status": "5",
  "task_type": "1",
  "title": "SEO Audit",
  "type": "1"
}

The task object contains the following:

Field Type Description
id unsigned A unique identifier for the task.
title string A name for the task.
description string A description of the task.
billable integer The total billable time logged against the task, in seconds.
nonbillable integer The total nonbillable time logged against the task, in seconds
logged integer The total time logged against the task, in seconds.
budgeted integer The total time budgeted, or estimated, for the task, in seconds
remaining integer The amount of budgeted time left, in seconds.
staff_bookmarked boolean Whether the current user has bookmarked the task in the deployment.
date_created unix ts The date the task was created.
date_started unix ts The date the task is is scheduled to start.
date_commenced unix ts The date the task was started; when its standing was progressed to "started".
date_accepted unix ts The date the task was accepted.
date_due unix ts The date the task is due to be completed.
date_completed unix ts The date the task was completed.
date_modified unix ts The date the task was last modified.
against_type string The type of object the task is against.
against_id unsigned The unique identifier of the object the task is against.
against string The API URI of the object the task is against. That is "against_type/against_id".
creator_type string The type of object that created the task.
creator_id unsigned The unique identifier of the object that made the task.
creator string The API URI of the object that made the task. That is "creator_type"/"creator_id".
assignee unsigned or object The staff member assigned to the task.
type unsigned or object The task type of the task. Deprecated, please use task_type.
task_type unsigned or object The task type of the task.
status unsigned or object The status of the task. Deprecated, please use task_status.
task_status unsigned or object The status of the task.
standing string The standing of the task, this is contained in the status object.
manager unsigned or object The staff member assigned to manager the task.
contact unsigned or object The contact associated with the against object, if any.
affiliation unsigned or object The affiliation associated with the against object, if any.
company unsigned or object The company object the task is against, if any.
issue unsigned or object The issue object the task is against, if any.
job unsigned or object The job object the task is against, if any. Deprecated, please use task_job
task_job unsigned or object The job object the task is against, if any.
milestone unsigned or object The milestone object the task is against, if any.
task_object_budget unsigned or object The object budget linked to the task, if any.
task_object_schedule unsigned or object The object schedule linked to the task.
task_object_schedule_id unsigned The id of the object schedule linked to the task.
task_priority unsigned or object The priority of the task.
rate_id unsigned The unique identifier of the rate object of the task.
rate_charged decimal The rate charged for billable work within this task. This is part of the rate object.
ordering unsigned An integer representing the task's order on the against object, only if the task is against a job or milestone
skills array[object] The skills assigned to the task.

The Task Priority

Task priorities help you prioritize your task. They may be set up from the deployment, see the support documentation for information. They contain the following:

Field Type Description
id unsigned A unique identifier for the task priority.
title string A title for the task priority.
icon select The icon of the priority when displayed on the deployment. The icons, in order of decreasing urgency a critical_priority, high_priority, normal_priority, low_priority, none_priority.
level unsigned A number representing the urgency of the priority. 1 is "Critical", 5 is "None"

The Task Type

Task types allow you to assign type labels to tasks. The task type contains the following:

Field Type Description
id unsigned A unique identifier for the task type.
title string A title for the task type.
standing Select Either "active" or "inactive", the standing of the task type.
ordering unsigned An integer representing the task type's order on the deployment.

Note: This object does not support the _ALL argument when request with _fields.

The Task Metadata

The metadata object associated with tasks is a list of the following:

Task Metadata Managers

This is a list of staff members managing tasks on the deployment, the object has the following fields:

Field Type Description
id unsigned The unique identifier of the staff member.
name string The staff member's full name (first name and surname).
email string The staff member's email address.
Task Metadata Assignees

This is a list of staff members assigned to tasks on the deployment. The object contains the same fields as the managers metadata object

Task Metadata Against

This is a list of object types that have tasks listed against them on the deployment, this object contains the following:

Field Type Description
id string An identifier to identify the object within the API. For example "prospect".
name string A name for the object. For example "Sale".
Task Metadata Status

This is a list of status objects available to tasks on the deployment. Note that this is a status object without the start field.

Get Task

Sample Request:

GET /api/v0/tasks/{task_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks/{task_id} \
  -H 'authorization: Bearer {access_token}'

GET /tasks/{task_id}

This request returns a single task, identified by its task_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the task object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single task object with its default fields and any additional fields requested through _fields.

List Tasks

Sample Request:

GET /api/v0/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks \
  -H 'authorization: Bearer {access_token}'

GET /tasks

This request returns a list of tasks on the deployment.

Configuring the Response

Pagination

This request supports the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the task object using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
assignee Filter by the staff_id of the assignee.
manager Filter by the staff_id of the manager.
status Filter by status_id.
standing
against_type
against_id
custom_id
child_of_job Filter by the job_id of the job the task, or its against object, is against. This allows you to find tasks under a certain job, even when they are not created directly against that job, for example if they are created against a milestone under the job.
rate_id
rate_charged
Date Filters

This request supports date_filters over the following fields:

Filter Name
date_created
date_started
date_commenced
date_accepted
date_completed
date_modified
date_due
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
billable
nonbillable
budgeted
remaining
against_id
creator_id
assignee Range over the staff_id of the assignee.
type Range over type_id. Deprecated, please use task_type.
task_type Range over the task_type_id.
status Range over status_id.
manager Range over the staff_id of the manager.
contact Range over the contact_id of the associated contact.
rate_charged
Order Filters

This request supports order filters over the following fields:

Filter Name Notes
id
date_created
date_started
date_commenced
date_accepted
date_completed
date_modified
date_due
task_priority
title
standing
status Order by the status_id.
rate_charged
ordering The order of the tasks on their against object, if the against object is a job or milestone
Object Filters

This request supports the following object filters:

Filter Name Description
against Filter by tasks against these objects.
creator Filter by tasks created by these objects.
Searching

This request supports the _search parameter to search over the following fields:

Field
description
title

Handling the Response

The response will be a list of tasks with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Tasks

Sample Request:

GET /api/v0/tasks/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks/count \
  -H 'authorization: Bearer {access_token}'

GET /tasks/count

This request will return a count of tasks in a list defined by any available searches or filters. With no searches or filters this will be a count of all tasks on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of tasks listed.

List Task Priorities

Sample Request:

GET /api/v0/tasks/priorities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks/priorities \
  -H 'authorization: Bearer {access_token}'

GET /tasks/priorities

This request returns a list of priorities available for tasks.

Get Task Status

Sample Request:

GET /api/v0/tasks/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}'

GET /tasks/statuses/{status_id}

This request returns the task status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a task status object for the specified status with its default fields and any additional fields requested through _fields.

List Task Statuses

Sample Request:

GET /api/v0/tasks/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks/statuses \
  -H 'authorization: Bearer {access_token}'

GET /tasks/statuses

This request returns a list of statuses available for tasks on the deployment.

Configuring the Response

Pagination

This request supports the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the statuses object using the _fields parameter. Note, this request does not support the _ALL argument. Note, the status object for tasks does not contain the start field.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color
Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering
Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of statuses with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters or searches used.

Count Task Statuses

Sample Request:

GET /api/v0/tasks/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
  https://{deployment}.api.accelo.com/api/v0/tasks/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /tasks/statuses/count

This request will return a count of task statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all task statuses on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of the listed task statuses.

List Meta Data

Sample Request:

GET /api/v0/tasks/meta HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks/meta \
  -H 'authorization: Bearer {access_token}'

GET /tasks/meta

This request returns a list of metadata objects for tasks on the deployment. That is, a list of lists.

Handling the Response

The response will be a list of task managers, task assignees, against objects, and statuses.

Update a Task

Sample Request:

PUT /api/v0/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /tasks/{task_id}

This request updates and return a task on the deployment.

Configuring the Task

The following fields from the task object may be updated through this Sample Request:

Field Name
title
description
assignee_id
affiliation_id
manager_id
priority_id
type_id
rate_id
rate_charged
date_due
remaining

Configuring the Response

This request supports requesting additional fields and linked resources from the task object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, updated task with its default fields and any additional fields requested through _fields.

Create a Task

Sample Request:

POST /api/v0/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/tasks \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /tasks

This request creates and returns a task.

Configuring the Task

The following fields from the task object may be set with this Sample Request:

Field Name Notes
title
against_id Must point to a valid object.
against_type Must point to a valid object type.
date_started
description
status_id The status_id for the initial status. You may retrieve a list of statuses for tasks if required.
manager_id The staff_id for the staff to be assigned manager.
assignee_id The staff_id for the staff to be assigned to the task.
affiliation_id The affiliation_id for the affiliation to be associated with the task.
date_due
priority_id The priority object's id. For available priorities see GET /tasks/priorities
remaining The field budgeted will be automatically updated with this value upon creation.
rate_id Only available if the task is against a "job" or "milestone". The rate_id of the rate for this task.
rate_charged Only available if the task is against a "job" or "milestone". The rate charged for work on this task, as a decimal.
is_billable Only available if the task is against a "job" or "milestone". Whether this task is billable, may either by "yes" or "no".

Configuring the Response

This request supports requesting additional fields and linked objects from the task object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, created task with its default fields and any additional fields requested through _fields.

List Available Progressions on a Task

See the progressions section for a sample request

GET /tasks/{task_id}/progressions

This request returns a list of available progressions for a task, specified by its task_id. This is the request GET /{object}/{object_id}/progressions where the object is "tasks" whose id is task_id.

Auto Run a Progression on a Task

See the progressions section for a sample request

PUT|POST /tasks/{task_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress a task, specified by its task_id. This is the request [POST|PUT] /{object}/{object_id}/progressions/{progression_id}/auto where the object is "task" whose id is task_id.

Auto Progress a Task to Start or End

Requests:

PUT|POST /tasks/{task_id}/progressions/start
PUT|POST /tasks/{task_id}/progressions/done

These requests will auto progress the status of a task, identified by its task_id to "start" or "done", respectively.

Taxes

The different account tax codes are stored by Accelo in the tax object. For information on these, and instructions on interacting with them through the deployment please see the support doucmentation

The Tax Object (Beta)

Example tax:

{
    "rate": "0.10000",
    "id": "6",
    "standing": "active",
    "title": "GST on Capital"
}

The tax object contains the following:

Field Type Description
id unsigned A unique identifier for the tax.
title string A name for the tax.
standing select The standing of the tax, either "active" or "inactive".
rate decimal The rate the tax is charged.

Get Tax (Beta)

GET /api/v0/taxes/{tax_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/taxes/{tax_id} \
    -H 'authorization: Bearer {access_token}

GET /taxes/{tax_id}

This request returns a tax object specified by its tax_id

Configuring the Response

This request supports requesting additional fields and linked objects from the tax object using the _fields parameter.

Handling the Response

The response will be the single tax object with its default fields and any additional fields requested through _fields.

List Taxes (Beta)

GET /api/v0/taxes HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/taxes \
    -H 'authorization: Bearer {access_token}

GET /taxes

This request returns a list of taxes.

Configuring the Response

Pagination

This request supports all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the tax object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
standing
Order Filters

This request supports the following order filters:

Filter
id
standing
title
Range Filters

This request supports the following range filters:

Filter
id

Handling the Response

The response will be a list of taxes with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters or filters used.

Count Taxes (Beta)

GET /api/v0/taxes/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/taxes/count \
    -H 'authorization: Bearer {access_token}

GET /taxes/count

This request will return a count of taxes in a list defined by any available searches or filters. With no searches or filters this will be a count of all taxes on the deployment. This request returns a single field:

Field Type Description
count unsigned A count of taxes listed.

Time Externals

Resource URI: /api/v0/time_externals

Time Externals are imported appointments from calendars such as Google, Exchange, or Outlook. Once they are imported and turned into activities you can use them on your schedule and entries on your timesheet. See the support documentation for more information on time externals.

The Time External Object

Example time external object:

{
    "id": "2",
    "staff_id": "7",
    "title": "Budget Meeting",
    "description": "Discuss next quarter's budget",
    "date_created": "1362707577",
    "date_modified": "1362707577",
    "date_started": "1362772800",
    "date_ended": "1362776400",
}

The contains the following:

Field Type Description
id unsigned A unique identifier for the time external.
staff_id unsigned The unique identifier for the staff member
title string The title of the appointment.
description string A description of the appointment.
date_created unix ts The date the appointment was created.
date_modified unix ts The last date the appointed was modified.
date_started unix ts The start date and time of the appointment.
date_ended unix ts The end date and time of the appointment.

Get Time External

Sample Request:

GET /api/v0/time/externals/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/time/externals/{id} \
  -H 'authorization: Bearer {access_token}'

GET /time/externals/{id}

This request returns a single time external, specified by its id.

Configuring the Response

This request supports requesting additional fields and linked objects from the time external using the _fields parameter.

Handling the Response

The response will be the single requested time external with its default fields and any additional fields requested through _fields.

List Time Externals

Sample Request:

GET /api/v0/time/externals HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/time/externals \
  -H 'authorization: Bearer {access_token}'

GET /time/externals

This request returns a list of time externals on the deployment.

Configuring the Request

Pagination

This request accepts all the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects using the _fields parameter.

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
staff_id
Order Filters

This request supports order filters over the following fields:

Filter Name
id
staff_id
date_created
date_modified
date_started
date_ended
Range Filters

This request supports range filters over the following fields:

Filter Name
id
staff_id
Searching

This request supports the _search parameter to search over the following fields:

Filter Name
title
description

Handling the Response

The response will be a list of time externals on the Deployment, with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Time Externals

Sample Request:

GET /api/v0/time/externals/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/time/externals/count \
  -H 'authorization: Bearer {access_token}'

GET /time/externals/count

This request will return a count of time externals in a list defined by any available searches of filters. With no searches or filters this will be a count of all time externals on the deployment. This request returns a single field.

Field Type Description
count unsigned A count of time externals listed.

Delete a Time External

Sample Request:

DELETE /api/v0/time/externals/{time_external_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/time/externals/{time_external_id} \
  -H 'authorization: Bearer {access_token}' \

DELETE /time/externals/{time_externals_id}

This request removes an external appointment from the deployment and deletes it from any given timesheet or schedule it is linked to, specified by its time_external_id.

Convert a Time External to an Activity

Sample Request:

POST /time/externals/{time_external_id}/convert_to_meeting HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/time/externals/{time_external_id}/convert_to_meeting \
  -H 'authorization: Bearer {access_token}' \

POST /time/externals/:time_external_id/convert_to_meeting

This request will convert the external into an activity as a meeting. This request requires a valid engagement_table and engagement_id for the activity to be created against. It will also create a second activity as a report on the meeting. This is the process to converting the external appointment as a workable entry to use in Accelo.

Timers

Resource URI:
/api/v0/timers

Timers are used to log time through Accelo. See the support documentation for more information on these objects, and how to access them on the deployment.

NOTE: Timer endpoints all operate from the current user and because of this are not available to service applications. If this restriction impacts your business model, please contact support and we will consider opening certain timer access up to service applications by requiring a staff id. It also means that a user will only be able to view or edit timers that they own.

The Timer Object

The timer object contains the following:

Field Type Description
id unsigned A unique identifier for the timer.
subject string A name for the timer.
seconds integer How long the timer has been running for, in seconds.
status select Either "stopped" or "running", whether the timer is running.
against_type string The type of object the timer is against.
against_id unsigned The unique identifier of the object the timer is against.
against_title string The title of the object the timer is against.
staff_id unsigned The unique identifier of the staff member running the timer.
staff unsigned or object The staff member running the timer.

Get Timer

Sample Request:

GET /api/v0/timers/{timer_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers/{timer_id} \
  -H 'authorization: Bearer {access_token}'

GET /timers/{timer_id}

This request returns a timer identified by its timer_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the timer object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the timer with its default fields and any additional fields requested through _fields.

List Timers

Sample Request:

GET /api/v0/timers HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers \
  -H 'authorization: Bearer {access_token}'

GET /timers

This request returns a list of timers on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the timer objects using the _fields parameter. This request also supports breadcrumbs.

Basic Filters

This request supports basic filters over the following fields:

Filter Name Notes
id
staff Filter by the staff_id.
status
Range Filters

This request supports range filters over the following fields:

Filter Name Notes
id
against_id
staff Range by the staff_id.

Handling the Response

The response will be a list of timers with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters or filters used.

Update a Timer

Sample Request:

POST /api/v0/timers/{timer_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers/{timer_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /timers/{timer_id}

This request updates and returns a timer identified by its timer_id.

Configuring the Timer

The following fields from the timer objects may be updated through this Sample Request:

Field Name Notes
subject
against_type
against_id
seconds Can only be updated for stopped timers.

Configuring the Response

This request supports requesting additional fields and linked objects from the timer object using the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response is the single, updated timer with its default fields and any additional fields requested through _fields

Create a Timer

Sample Request:

POST /api/v0/timers HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /timers

This request creates and returns a timer.

Configuring the Timer

The following fields may be set through this Sample Request:

Field Name Notes
subject
against_id
against_type
seconds
auto_start May be either "1" or "0", whether the timer starts upon creation. If it starts, it will stop any current timers. The default is "0".

Configuring the Response

This request supports requesting additional fields and linked objects from the timer object through the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, created, timer with its default fields and any additional fields requested through _fields

Delete a Timer

Sample Request:

DELETE /api/v0/timers/{timer_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers/{timer_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /timers/{timer_id}

This request deletes a timer, specified by its timer_id. It takes no parameters and returns no resources.

Pause a Timer

Sample Request:

PUT /api/v0/timers/{timer_id}/pause HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers/{timer_id}/pause \
  -H 'authorization: Bearer {access_token}'

PUT|POST /timers/{timer_id}/pause

This request pauses and returns a timer identified by its timer_id. This request may be handled, and configured, in the same way as GET /timers/{timer_id}

Start a Timer

Sample Request:

PUT /api/v0/timers/{timer_id}/start HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers/{timer_id}/start \
  -H 'authorization: Bearer {access_token}'

PUT|POST /timers/{timer_id}/start

This request starts and returns a timer identified by its timer_id. This request may be handled, and configured, in the same way as GET /timers/{timer_id}

Cancel a Timer

Sample Request:

PUT /api/v0/timers/{timer_id}/cancel HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/timers/{timer_id}/cancel \
  -H 'authorization: Bearer {access_token}'

PUT|POST /timers/{timer_id}/cancel

This is request behaves the same as DELETE /timers/{timer_id}.

User

This resource contains information about the current user, their deployment, and access token.

The User Object

The user object contains the same fields as the staff object, as well as the following:

Field Type Description
user_titles hash A key-value object containing the user defined plural and singular for each object type.
user_access hash A key-value object containing manages, add, view, and admin permissions for the different types of objects.
locale hash A key-value object containing the user's timezone and currency symbol preferences.

GET /user

This request returns a user object, it takes no parameters.

Webhooks

Resource URI: api/v0/webhooks

Webhooks allow you to build integrations that subscribe to specific Accelo events. Once an event is triggered, we will HTTP POST a payload to your registered callback URL containing event meta data and a resource URL. The resource URL can be used by your application to query the individual resource that fired the event. This is commonly referred to as Notification Webhooks.

There's currently no limit on webhooks and they can be installed per deployment from an individual users account using the webhooks control panel. See our blog for more information, and how to access webhooks on the deployment. We do enforce a 10 second timeout rule. If your trigger URL takes more than 10 seconds to respond to webhook delivery, we will cancel the request. If this occurs too many times, we will delete your webhook subscription automatically.

Webhook Subscriptions

Webhook Events

When subscribing to webhooks you choose an event that you would like to receive payloads for. Each event corresponds to a certain set of actions on a per object basis. The available events are:

event_id Description
assign_task Any time a task assignee changes.
unassign_task Any time a task is unassigned.
create_task Any time a task is created.
create_invoice_pdf Anytime an invoice PDF is created.
create_purchase_pdf Any time a purchase PDF is created.
create_quote Anytime a new quote is created
create_request Any time a new request is created.
update_request_status Any time a request status changes.
create_issue Any time an issue is created.
update_issue Any time an issue is updated.
create_contact Any time a contact is created.
update_contact Any time a contact is updated.
delete_activity (Beta) Any time an activity is deleted.
Progression Webhooks

Progression webhooks allow you to subscribe to changing statuses for companies, contacts, prospects, jobs, issues and contracts. Currently you can only do this from the web application's administration page but there are plans to expose this functionality to the API.

Add Webhook Progression Button [Create Progression Action Button]

Add Webhook Progression Form [Create Progression Webhook Form]

Payloads

The payload sent to the callback URL will contain the following:

Field Type Description
id unsigned A unique identifier for the object changed.
resource_url string The full URL of the object changed.

Delivery Headers

As well as the information in the payload body, the headers of HTTP request sent to the payload URL will contain special headers:

Header Description
X-Accelo-Event The event_id of the event that triggered the delivery. For example "assign_task".
X-Hub-Signature HMAC hex digest of the payload using your configured subscriptions secret.

The Webhook Subscription

The webhook subscription object contains the following:

Field Type Description
content_type select Either "application/x-www-form-urlencoded" or "application/json", the content type POSTed to the trigger url.
event_id string One of the events listed above.
trigger_table string The type of object that triggers the subscription.
trigger_type string A string representing the type of trigger, either "create" or "update".
trigger_url string The callback, or payload URL to which the payload is sent.
user_deployment string The user's deployment in the form {deployment}.
user_id unsigned The current user's unique identifier, that is, their staff_id.

Webhook Subscription Types

Each webhook subscription is of a certain type, defined by the following fields from the webhook subscription object:

Field
event_id
event_title
trigger_table
trigger_type

Unsubscribing

Your integration can tell Accelo to automatically unsubscribe by responding with a HTTP Status Gone 410. The dispatcher will respect this and instantly remove the subscription that caused the webhook trigger. Alternatively you can use the delete subscription endpoint mentioned below.

List Webhook Subscriptions

Sample Request:

GET /api/v0/webhooks/subscriptions HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions \
  -H 'authorization: Bearer {access_token}'

GET /webhooks/subscriptions

This request returns a list of webhook subscriptions for the current user. This request takes no parameters.

List Webhook Subscription Types

Sample Request:

GET /api/v0/webhooks/subscriptions/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/types \
  -H 'authorization: Bearer {access_token}'

GET /webhooks/subscriptions/types

This request returns a list of available webhook subscription types. This request takes no parameters.

Create Webhook Subscription

Sample Request:

POST /api/v0/webhooks/subscriptions HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /webhooks/subscriptions

This request creates and returns a webhook subscription for the current user. This request takes no parameters to configure the response.

Configuring the Subscription

The following fields may be set through this Sample Request:

Notes
trigger_url
event_id
content_type
secret Optional secret that we will use to generate a HMAC hex digest of the payload. The digest will be included in the triggered requests "X-Hub-Signature" header.

Delete Webhook Subscription

Sample Request:

DELETE /api/v0/webhooks/subscriptions/{subscription_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/{subscription_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /webhooks/subscriptions/{subscription_id}

This request deletes a webhook subscription, identified by its subscription_id. It takes no parameters and returns no resources.

Trigger a Webhook Subscription

Sample Request:

POST /api/v0/webhooks/subscriptions/{subscription_id}/trigger HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/{subscription_id}/trigger \
  -H 'authorization: Bearer {access_token}' \

POST /webhooks/subscription/{subscription_id}/trigger

This request manually triggers a given subscription, identified by its subscription_id. This will queue the event to all other subscriptions and execute asynchronously. Use this if you want to trigger a subscription for an event for others, otherwise see dispatch a webhook subscription. This request takes the following parameter:

Field Type Description
object_id unsigned The unique identifier of the object, of type trigger_table, to trigger the subscriptions.

Handling the Response

This request returns nothing to the user.

Dispatch a Webhook Subscription

Sample Request:

POST /api/v0/webhooks/subscriptions/{subscription_id}/dispatch HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
 https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/{subscription_id}/dispatch \
  -H 'authorization: Bearer {access_token}' \

POST /webhooks/subscriptions/{subscription_id}/dispatch

This request manually dispatches a given subscription, identified by its subscription_id. This will dispatch synchronously, and unlike triggering, this will only execute the current subscription so other subscriptions of the event will not be affected. As this is performed synchronously you will get the HTTP status of the webhook result. This request takes the following parameter:

Field Type Description
object_id unsigned The unique identifier of the object, of type trigger_table to run the dispatch on.

Handling the Response

The response will contain a single field:

Field Type Description
status integer The http status of the webhook result.

Status Codes

The following statuses and codes may be returned.

ok

Code

200

Description

Everything executed as expected.

invalid_client

Code: 401

Description

Invalid client authentication, e.g. unknown client, no client authentication included, or unsupported authentication method.

Common Causes

invalid_grant

Code: 400

Description

The provided authorization grant is invalid.

Common Causes

duplicate

Code: 400

Description

Your write actions would cause a duplicate unique identifier. The response message should identify the offending field. If it odes not, please report it to us.

Common Causes

invalid_request

Code: 400

Description

We could not interpret your request. This is commonly seen when you forgot to include required parameters or attempt to request a resource that doesn't exist. For example /api/v0/monkeys or /api/v20000/companies would result in an 'invalid request'.

Common Causes

too_many_requests

Code: 429

Description

Your deployment has exceeded the maximum number of allowed requests for this hour. See rate limiting for more information.

server_error

Code: 500

Description

The request failed due to a server error and we were notified. Unfortunately these errors are 99% of the time out of your control. If you continue to see such an error, please notify us.

Common Causes

invalid_scope

Code: 400

Description

The request scope is invalid, unknown, malformed or exceeds the scope granted by the resource owner.

Common Causes

unsupported_grant_type

Code: 400

Description

The authorization grant type is not supported by the authorization server.

Common Causes

unauthorized client

Code: 401

Description

The authenticated client is not authorized to use this authorization grant type

Common Causes

invalid_permission

Code: 403

Description

The user is authenticated but does not have permission to perform the action

Change log

With the release of the new and easier to maintain documentation, we're going to do a much better job of tracking changes.

Note - Beta Changes: New objects or endpoints may be introduced with a (Beta) tag, which may last up to a month after introduction. While in beta these are subject to change without notice.

Tuesday 5th January 2020

The change log is back!

Features

Added an delete activity webhook. - This will initially be in beta.

Wednesday 11th April 2018

Misc

Added some extra documentation around _not filters.

Features

Updated the PUT /activities/{activity_id} endpoint:

New fields added to the Activity Object:

Additional changes:

Tuesday 6th February 2018

Misc

Features

The following endpoints have been added to activities:

The following endpoints have been added to issues:

The following issue endpoints have been updated:

The following webhook events have been added:

Deprecations

Bug Fixes

In addition to the username and password, the following fields are now required when creating a new staff member via POST /staff:

Friday 2nd February 2018

Features

Monday 22nd January 2018

Deprecations

Monday 15th January 2018

Deprecations

Features

Friday 22nd December 2017

Misc Updates

The following endpoints have been added:

Friday 13th October

Object Types

The following objects are to have their type object deprecated and replaced by a corresponding _type object:

Included in this change, the following endpoints have been added:

Friday 6th October

Rate Limiting

Rate limiting will be introduced into the API. We have added documentation describing what the limits will be once it is introduced.

Configuring the Response

This has been moved to its own section, configuring responses.

AND/OR Filtering

The API now supports combining filters using logical AND/OR operations.

Friday 22nd September

Progression Webhooks

Webhooks are now supported on progressions via progression webhooks. These are currently only supported via the Web App but there are plans to implement it via the API.

Purchases

Purchases are now accessible through the API. They are available through the purchase object and accessed via the new endpoints:

Groups

Groups may now be accessed through the API. They are available through the group object and accessed via the new endpoints:

Divisions

Divisions may now be accessed through the API. They are available through the division object and accessed via the new endpoints:

Request Types

A new endpoint for request types has also been added:

Wednesday 16th August

Close/Reopen Contract Periods

Contract periods may now be closed or reopened using the API, this is done through the two new endpoints:

New Fields for Activities

The following fields have been added to the activity object:

Friday 21st July

Holidays

User holidays may now be accessed through the API. As well as adding the holiday object, the following endpoints are now available:

We are rolling out asset links, which join an asset to another object, to the API. Currently the following new objects have been added:

As well as the following endpoints:

Invoices

We are also rolling out improvements to assets on the API. As part of these improvements we have added the following objects:

With the following new endpoints:

Future updates will include update, create and delete invoices.

Payments Ledgers and Taxes

Related to our asset improvements is the introduction of payments, ledgers, and taxes with the following endpoints:

Future updates will include update, create and delete payments.

Friday 16th June

New documentation

New filters

New fields