NAV Navbar
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 / mailing list. 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.

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 /ouath2 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 50
_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 /activities 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/activities \
    -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,phones 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 _filter 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.

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 owner 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 express as unix timestamps (for brevity we will just use the shorter "unix ts"). The API supports filtering for may 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 instead of the above we wanted to search for activities owned by the specific staff OR created after the given date we could use _filters=_OR(staff(17),date_created_after(1490140800)). As expected, the original filter is equivalent to _filters=_AND(staff(17),date_created_after(1490140800)).These keywords may also be nested, 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(1490140800))).

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.

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.

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, or affiliation or contact object. An activity can have several interactions; an email may be sent to several staff members and an affiliation. 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 a 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. This will default to the current user's id.
against_type The object the activity is linked against. This can be: affiliation, annex, campaign, account_invoice, campaign_action, component, contract, contract_period, deployment, event, invoice, issue, job, membership, prospect, request, task or staff. This will default to 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 you are POSTing from a service application, in which case it defaults to all.
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"
  }
}

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.

Logging time

The billable and nonbillable attributes require that you supply a staff owner (owner_type and owner_id) otherwise no time allocation is created against the new activity. i.e, the user who the time belongs to.

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 /activity/{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"
}

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.

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/affiliation/{affiliation_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

GET /affiliation/{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/affiliation 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.
Date Filters

This request supports date filters over the following fields:

Filter Name
date_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 Affiliation 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 object for the affiliation specified.

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.

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 /affiliation/{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 /affiliation/{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 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 Segmentation Object

Example segmentation:

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

Segmentations, or categories, 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.

Segmentations may be managed through your Accelo deployment, see the support documentation for information. A segmentation contains the following fields:

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.
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
date_created
date_modified
name
standing
status Range over the status_id.
custom_id
Searching

This request supports the _searching 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 Company 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.

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 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 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
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 it 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.
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 it's 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 Contact 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.

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 it the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "contacts" and whose id is {contact_id}.

Contracts

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.

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/counts

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.

Close a Contract Period (Beta)

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 (Beta)

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 /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 Contract

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 it the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "companies" and whose id is {company_id}.

List a Contract's Profile Field Values

See the profiles section for a sample request

GET /contract/{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.
type_id unsigned The id of the type of contributor.
auto_cc boolean Whether the contributor will be Auto-CC'd on correspondence.

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
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
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
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.

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 it's 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 paramter 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 it's 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

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",
  "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.
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.

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
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
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}.

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"
}

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

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.
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.
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.
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.

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.

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
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. 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.

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 it's 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 it's 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.

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.

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"
}

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.

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
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"
}

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.

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 paramter 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