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:

• Installed Application
• Web Application
• Service Application

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
• Requesting Additional Fields and Linked Objects
• Searching
• Filtering

Pagination

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

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

Requesting Additional Fields and Linked Objects

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

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

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

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

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

Searching

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

Filtering

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

• Basic Filters
• Date Filters
• Range Filters
• Order Filters
• Empty Filters
• Object Filters
• Search Filters

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

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

Basic Filters

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

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

_filters=owner_type(staff)

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

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

Date Filters

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

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

_filters=date_created_after(1490140800)

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

Many endpoints contain fields representing dates, such as date_created under activities. Date fields are 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 we wanted to search for activities owned by the specific staff OR created after a given date we could use _filters=_OR(staff(17),date_created_after(1490140800)). One _AND can be nested inside an _OR for greater filtering flexibility. For example, if we wanted all activities created by the given staff member, or after a given date and before another date we could use _filters=_OR(staff(17),_AND(date_created_after(1490140800),date_created_before(1500140800))). Nested _OR keywords are not supported.

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

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

Authentication

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

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

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

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

OAuth2.0 URI

Example OAuth2.0 base URI for planet express:

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

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

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

This URI is used to authorize and access tokens.

Scope

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

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

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

scope=write(contacts,staff)

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

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

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

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

OAUTH2.0 Endpoints

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

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

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

Redirect URIs

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

Authentication Without a Token

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

Authorization: Basic NWJhMTdjNzhhb0BwbGFuZXQtZXhwcmVzcy5hY2NlbG8uY29tOnpUZkZnaXlRQ1ZERmstMUV0VWVyVkxSazFpczZMZ0w2.

For convenience we will just write {client_credentials}

Service Applications

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

Token Acquisition for Service Applications

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

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

grant_type=client_credentials
scope=read(staff)

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

The token endpoint:

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

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

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

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

A successful request will contain the following fields:

Example successful response:

{
  "access_token": "Ck9ma73_db",
  "expires_in": "2592000",
  "token_tpye": "Bearer",
  "..."
}

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

Web Applications

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

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

Authorization for Web Applications

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

Authorization Request for Web Applications

Example authorization request:

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

client_id=a17c78ao@planet-express.accelo.com
response_type=code
scope=read(companies,contacts),write(staff)
redirect_uri=https//planet-express.com/oauth-callback

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

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

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

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

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:

Authorization Response for Installed Applications

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

Token Acquisition for Installed Applications

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

Example token request:

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

grant_type=authorization_code
code=750332955

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

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

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

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

Revoking a Token

Sample request:

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

token={access_token_to_be_revoked}

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

POST /oauth2/revoke

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

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

A successful request will return an "ok" status.

Refreshing a Token

Example token request using refresh token:

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

token_type=refresh_token
refresh_token=VYfb63__vf

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

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

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

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

Token Information

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

Example request:

GET /api/v0/tokeninfo HTTP/1.1
HOST: planet-express.api.accelo.com
Authorization: Bearer {access_token}

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

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

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

The response will contain the following:

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

Using the Token to Access Resources

Sample accessing a company resource using access token query:

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

Same request using preferred header method:

GET /api/v0/companies/1 HTTP/1.1
Host: planet-express.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer Ck9ma73_db

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

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

Lockout

Example lockout response.

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

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

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

Endpoints

Activities

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

Resource URI:
api/v0/activities

The Activity object is complex and contains some special objects:

• Activity Medium
  
• Activity Visibility
  
• Activity Classes
  
• Activity Priorities
  
• Activity Threads and Parents
  
• Activity Interactions
• Time Allocations

The Activity Object

Sample activity object:

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

The activities object contains the following fields:

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

Activity Medium

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

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

Activity Visibility

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

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

The Activity Class

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

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

The class object for activities will contain the following:

Sample JSON of an activity class:

"class": {
  "id": "1",
  "title": "Client Work",
  "parent": "0",
  "status": "active"
}

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

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

The Activity Priority

Sample JSON of an activity priority:

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

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

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

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

Activity Threads and Parents

Activity threads and parents:

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

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

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

The Activity Thread Object

Sample JSON of an activity thread object:

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

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

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

Activity Interactions

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

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

The Time Allocation Object

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

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

Get Activity

GET /activities/{activity_id}

Sample request:

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

_fields=against,owner

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

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

Configuring the Response

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

Handling the Response

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

Sample response, excluding meta:

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

List Activities

GET /activities

Sample request:

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

_fields=body,staff(),medium
_filters=date_created_after(1485495266),order_by_desc(id)
_limit=2

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

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

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

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

Date Filters

Sample response:

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

This request supports date filters over the following fields:

Filter Name
date_created
date_started
date_ended
date_logged
date_modified

Order Filters

This request supports order filters over the following fields:

Filter Name
date_started
date_created
date_ended
date_modified
id
billable
nonbillable

Range Filters

This request supports range filters over the following fields:

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

Object Filters

This request supports object filters over the following linked object:

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

Handling the Response

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

Handling Interacts

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

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

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

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

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

Count Activities

Sample request, here we request the response as xml

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

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

GET /activities/count

Sample response:

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

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

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

List Interactions

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

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/activities/{activity_id}/interacts \
  -H 'authorization: Bearer {access_token}'

GET /activities/{activity_id}/interacts

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

Sample response:

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

Configuring the Response

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

Handling the Response

The response will contain two arrays:

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

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

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

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

Count Interactions

Sample request:

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

curl -X -get \
  https://{deployment}.api.accelo.com/api/v0/activities/{activity_id}/interacts/count \
  -H 'authorization: Bearer {access_token}'

GET /activities/{activity_id}/interacts/count

Sample response

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

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

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

Get Time Allocated

Sample Request:

GET /activities/allocations

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

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

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

Sample response:

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

Configuring the Response

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

Handling the Response

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

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

Update an Activity

PUT /activities/{activity_id}

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

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

priority=4
_fields=activity_priority()

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

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

Configuring the Activity

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

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

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

Sample response:

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

Configuring the response

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

Handling the Response

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

Create an Activity

POST /activities

Sample request, here we send the data as json:

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

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

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

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

Configuring the Activity

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

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

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

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

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

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

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

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

Logging time

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

Logging time against a task

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

Configuring the Response

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

Handling the Response

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

Create a Report

POST /activities/reports

Sample request

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

{
  "activity_id": "14"
  "body": "The details of the report"
  "nonbillable": "3600"
}

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

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

Configuring the Report

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

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

Logging time

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

Configuring the Response

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

Handling the Response

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

Delete Activity

Sample Request:

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

curl -X delete \
  https://{deployment}.api.accelo.com/api/v0/activities/{activity_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /activities/{activity_id}

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

List Activity Threads

Sample Request:

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

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

GET /activities/threads

This request returns a list of activity threads.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

Sample response of a single thread:

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

Filter Name	Notes
against_type	Return only threads whose original activity was against an object of this type. If this is provided, against_id must also be provided.
against_id	Return only threads whose original activity was against an object with this id. If this is provided, against_type must also be provided.
staff_involved	Filter by the staff_id the staff member(s) who have interacted with activities within the thread.
scope	Takes either "internal" or "external" as arguments, whether the thread is external, such as emails from clients, or internal, such as notes.

Date Filters

This request supports date filters over the following fields:

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

Handling the Response

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

Count Activity Threads

Sample Request:

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

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

GET /activities/threads/count

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

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

List Activities in a Thread

Sample request:

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

_fields=thread,parent

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

GET /activities/threads/{thread_id}

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

Sample response:

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

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

List Activity Classes

Sample Request:

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

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

GET /activities/classes

This request returns a list of activity classes.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

Sample response of a single class:

{
  "parent": "3",
  "id": "5",
  "standing": "active",
  "title": "Internal"
}

Filter Name	Notes
id	Return only the class with this id.
title	Filter by the title of the class.
parent	Return only classes whose parent class is of this id.
standing	Takes either "active" or "inactive" as arguments.

Handling the Response

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

Get Activity Class

Sample Request:

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

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

GET /activities/classes/{class_id}

Returns a single activity class for the given class id.

Count Activity Classes

Sample Request:

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

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

GET /activities/classes/count

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

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

Addresses

Resource URI:
/api/v0/adddresses

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

The Address Object

Sample address object:

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

The address object contains the following:

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

The Country Object

JSON country object for the USA:

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

JSON country object for Australia:

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

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

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

The State Object

JSON object for NSW, Australia:

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

JSON object for California, USA

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

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

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

Postal and Physical Addresses

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

The Address Object

Example JSON of full address object:

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

Get Address

Sample Request:

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

_fields=country(),state

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

GET /addresses/{address_id}

Sample response:

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

This request will return the address identified by its address_id.

Configuring the Response

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

Handling the Response

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

List Addresses

Sample request:

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

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

GET /addresses

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

Configuring the Response

Pagination

This request supports all the pagination parameters.

Basic Filters

This request supports basic filters over the following fields:

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

Range Filters

This request supports range filters over the following fields:

Filter Name
id
against_id

Order Filters

This request supports order filters over the following fields:

Filter Name
id
title
suffix
prefix

Handling the Response

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

Count Addresses

Sample request:

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

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

GET /addresses/count

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

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

List Addresses Against an Object

Sample request:

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

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

GET /{object}/{object_id}/addresses

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

1. Company
2. Contacts

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

Configuring the Response

This request may be configured as GET /addresses

Handling the Response

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

Update an Address

PUT /addresses/{address_id}

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

country_id=Australia
state=NSW
street1=221 Crown St
city=Wollongong
postcode=2500
physical=yes

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

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

Configuring the Address

The following fields may be updated through this request:

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

Configuring the Response

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

Handling the Response

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

Create an Address

Sample request:

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

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

POST /addresses

This request will create a new address and return it.

Configuring the Address

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

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

Configuring the Response

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

Handling the Response

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

Create an Address Against an Object

Sample request:

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

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

POST /{object}/{object_id}/addresses

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

Affiliations

Resources URI:
/api/v0/affiliations

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

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

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

The Affiliation Object

Sample affiliation JSON object:

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

The Affiliation object contains the following:

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

Get Affiliation

Sample request:

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

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

GET /affiliations/{affiliation_id}

This request returns an affiliation specified by their unique id.

Configuring the Response

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

Handling the Response

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

List Affiliations

Sample request:

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

_fields=company(),position
_filters=date_modified_after(1494596024)

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

GET /affiliations

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

Configuring the Response

Pagination

This request supports all of the pagination parameters

Basic Filters

This request supports basic filters over the following fields:

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

Date Filters

This request supports date filters over the following fields:

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

Order Filters

This request supports order filters over the following fields:

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

Range Filters

This request supports range filters over the following fields:

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

Sample response:

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

Searching

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

Field Name	Notes
firstname
surname
fax
phone
mobile
email

Handling the Response

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

Count Affiliations

Sample request:

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

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

GET /affiliations/count

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

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

Get an Affiliation's Status

Sample request:

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

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

GET /affiliations/{affiliation_id}/status

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

Sample response:

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

Configuring the Response

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

Handling the Response

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

Get Affiliation Status

Sample Request:

GET /api/v0/affiliations/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /affiliations/statuses/{status_id}

This request returns the affiliation status specified by its status_id.

Configuring the Response

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

Handling the Response

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

List Affiliation Statuses

Sample Request:

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

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

GET /affiliations/statuses

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

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color

Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering

Searching

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

Field
title

Count Affiliation Statuses

Sample Request:

GET /api/v0/affiliations/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /affiliations/statuses/count

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

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

Update an Affiliation

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

_fields=physical_address
physical_address_id=17
postal_address_id=17

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

PUT /affiliations/{affiliation_id}

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

Configuring the Affiliation.

The following fields may be updated via this request.

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

Sample response:

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

Configuring the Response

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

Handling the Response

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

Create an Affiliation

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

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

POST /affiliations

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

Configuring the Affiliation

This request supports setting the following fields:

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

Configuring the Response

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

Handling the Response

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

Delete an Affiliation

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

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

DELETE /affiliations/{affiliation_id}

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

List an Affiliation's Profile Field Values

See the profiles section for a sample request

GET /affiliations/{affiliation_id}/profiles/values

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

List Affiliation Profile Field Values

See the profiles section for a sample request

GET /affiliations/profiles/values

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

List Affiliation Profile Fields

See the profiles section for a sample request

GET /affiliations/profiles/fields

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

Update a Profile Field Value on an Affiliation

See the profiles section for a sample request

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

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

Set a Profile Field Value on an Affiliation

See the profiles section for a sample request

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

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

List Available Progressions on an Affiliation

See the progressions section for a sample request

GET /affiliations/{affiliation_id}/progressions

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

Auto Run a Progression on an Affiliation

See the progressions section for a sample request

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

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

Assets

Endpoint URI:
/api/v0/assets

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

The Asset Object

The asset object contains the following:

Sample JSON asset:

{
  "address": "14",
  "against_id": "39",
  "asset_type_id": "2",
  "manager_id": "14",
  "id": "2",
  "affiliation": "98",
  "asset_type": "2",
  "title": "Latest Laptop",
  "date_created": "1492651877",
  "manager": "14",
  "affiliation_id": "98",
  "standing": "inactive",
  "against_type": "company",
  "address_id": "14"
}

Field	Type	Description
id	unsigned	The unique identifier for the asset.
title	string	The name given to the asset.
latest_asset_link	object	The most 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.

The Asset Link

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.

Asset Object Link Fields

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.

List Asset Links

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.

Create Asset Link

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.

Configuring the Link

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.

Delete Asset Link

Sample Request:

DELETE /api/v0/assets/link/{link_id}
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

DELETE /assets/links/{asset_link}

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

Update an Asset

Sample request:

PUT /api/v0/assets/{asset_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

PUT/assets/{asset_id}

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

Configuring the Asset

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

Field	Notes
title

Configuring the Response

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

Handling the Response

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

List Asset Extension Fields

See the extension section for an example

GET /assets/extensions/fields

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

List an Asset's Extension Field Values

See the extension section for an example

GET /assets/{asset_id}/extensions/values

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

List all Extension Field Values on Assets

See the extension section for an example

GET /assets/extensions/values

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

Update an Extension Field Value on an Asset

See the extension section for an example

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

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

Set an Extension Field Value on an Asset

See the extension section for an example

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

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

Companies

Resource URI: /api/v0/companies

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

The Company Object

Example company object:

{
  "date_modified": "1495671183",
  "phone": "61448824724",
  "status": "3",
  "name": "A Fresh New Company",
  "id": "45",
  "date_last_interacted": "1495675655",
  "comments": "This is a fresh new company",
  "date_created": "1495669367",
  "staff_bookmarked": "0",
  "standing": "active",
  "default_affiliation": "12",
  "postal_address": "31",
  "fax": null,
  "website": "www.example.com"
}

Field	Type	Description
id	unsigned	The company's unique identifier.
name	string	The name of the company.
custom_id	string	The custom id for the company.
website	string	The company's website.
phone	string	A contact phone number for the company.
fax	string	A fax number for the company.
date_created	unix ts	The date the company was created on the Accelo deployment.
date_modified	unix ts	The date the company was last modified on the Accelo deployment.
date_last_interacted	unix ts	The date the company was last modified on the Accelo deployment.
comments	string	Any comments or notes made against the company.
standing	string	The standing of the company, from its status.
status	unsigned or object	The company's status.
postal_address	unsigned or object	The postal address of the company.
staff_bookmarked	bool	Whether the company has been bookmarked by the current user.
default_affiliation	unsigned	The affiliation_id of the main affiliation associated with this company.

The Manager Object

Example manager object with default fields:

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

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

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

The Company Segmentation Object

Example company segmentation:

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

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

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

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

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

Get Company

Sample Request:

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

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

GET /companies/{company_id}

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

Configuring the Response

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

Handling the Response

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

List Companies

Sample Request:

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

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

GET /companies

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

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

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

Date Filters

This request date filters over the following fields:

Filter Name
date_created
date_modified

Order Filters

This request supports order filters over the following fields:

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

Range Filters

This request supports range filters over the following fields:

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

Searching

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

Field Name	Notes
website
name
phone
fax

Handling the Response

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

Count Companies

Sample Request:

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

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

GET /companies/count

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

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

List Recent Companies

Sample Request:

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

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

GET /companies/recent

Equivalent request:

GET /companies?_filters=order_by_desc(date_created)

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

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

Configuring the Response

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

Handling the Response

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

List Latest Modified Companies

Sample Request:

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

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

GET /companies/newest

Equivalent Request:

GET /companies?_filters=order_by_desc(date_modified)

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

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

Configuring the Response

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

Handling the Response

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

Get a Company's Status

Sample Request:

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

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

GET /companies/{company_id}/status

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

Configuring the Response

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

Handling The Response

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

List Company Statuses

Sample Request:

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

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

GET /companies/statuses

This returns a list of company statuses.

Configuring the Response

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

Handling The Response

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

Get Company Status

Sample Request:

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

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

GET /companies/statuses/{status_id}

This request returns the company status specified by its status_id.

Configuring the Response

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

Handling the Response

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

List Company Statuses

Sample Request:

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

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

GET /companies/statuses

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

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color

Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering

Searching

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

Field
title

Count Company Statuses

Sample Request:

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

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

GET /companies/statuses/count

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

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

Get Main Contact

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/contact \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/contact

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

Configuring the Response

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

Handling the Response

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

List Contacts Against a Company

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/contacts \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/contacts

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

Configuring the Response

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

Count Contacts on a Company

Sample Request:

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

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

GET /companies/{company_id}/contacts/count

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

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

List Managers

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/managers \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/managers

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

Configuring the Response

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

List A Company's Segmentations

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/{company_id}/segmentations \
  -H 'authorization: Bearer {access_token}'

GET /companies/{company_id}/segmentations

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

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

Sample response:

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

Update a Company

Example request:

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

comments=This%20is%20a%20fresh%20new%20company
_fields=comments

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

PUT /companies/{company_id}

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

Configuring the Company

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

Field
website
phone
fax
comments
name

Configuring the Response

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

Handling the Response

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

Create a Company

Sample request:

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

website=www.example.com
name=A%20Fresh%20New%20Company
standing=active
profile.12=09-17

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

POST /companies

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

Configuring the Company

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

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

Setting Profile Field Values

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

Configuring the Response

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

Handling the Response

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

Add a Manager

Sample Request:

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

manager_id=14

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

POST /companies/{company_id}/managers/add

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

Configuring the Manager

The following fields may be sent with this request:

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

Configuring the Response

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

Remove a Company

Sample Request:

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

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

DELETE /companies/{company_id}

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

Remove a Manager

Sample Request:

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

relationship=23

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

DELETE /companies/{company_id}/managers/delete

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

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

Handling the Response

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

List a Company's Profile Field Values

See the profiles section for a sample request

GET /companies/{company_id}/profiles/values

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

List all Profile Field Values on a Company

See the profiles section for a sample request

GET /companies/profiles/values

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

List Company Profile Fields

See the profiles section for a sample request

GET /companies/profiles/fields

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

Update a Profile Field Value on a Company

See the profiles section for a sample request

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

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

Set a Profile Field Value on a Company

See the profiles section for a sample request

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

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

List Available Progressions on a Company

See the progressions section for a sample request

GET /companies/{company_id}/progressions

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

Auto Run a Progression on a Company

See the progressions section for a sample request

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

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

List Addresses against a Company

Sample Request:

GET /companies/{company_id}/addresses

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

Create an Address against a Company

Sample Request:

POST /companies/{company_id}/addresses

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

List a Company's Resource Collections

See the resources (attachments) section for an example

GET /companies/{company_id}/collections

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

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

See the resources (attachments) section for an example

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

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

Contacts

Resource URI: /api/v0/contacts

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

The Contact Object

The contact object contains the following fields and linked objects:

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

Get Contact

Sample Request:

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

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

GET /contacts

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

Configuring the Request

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

Handling the Response

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

List Contacts

Sample Request:

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

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

GET /contacts

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

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

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

Date Filters

This request supports date filters over the following fields:

Field
date_created
date_modified
date_last_interacted

Order Filters

This request supports order filters over the following fields:

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

Range Filters

This request supports range filters over the following fields:

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

Searching

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

Field	Notes
firstname
surname
email

Handling the Response

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

Count Contacts

Sample Request:

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

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

GET /contacts/count

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

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

List Recent Contacts

Sample Request:

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

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

GET /contacts/recent

Equivalent request:

GET /contacts?_filters=order_by_desc(date_created)

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

Configuring the Response

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

Handling the Response

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

List Recently Modified Contacts

Sample Request:

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

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

GET /contacts/newest

Equivalent request:

GET /contacts?_filters=order_by_desc(date_created)

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

Configuring the Request

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

Handling the Response

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

Update a Contact

Sample Request:

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

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

PUT /contacts/{contact_id}

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

Configuring the Contact

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

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

Configuring the Response

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

Handling the Response

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

Create a Contact

Sample Request:

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

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

POST /contacts

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

Configuring the Contact

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

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

Configuring the Response

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

Handling the Response

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

Deactivate a Contact

Sample Request:

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

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

DELETE /contacts/{contact_id}

Equivalent request:

PUT /contact/{contact_id}?standing=inactive

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

List Addresses Against a Contact

Sample Request:

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

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

GET /contacts/{contact_id}/addresses

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

Create an Address Against a Contact

Sample Request (TODO):

POST /contacts/{contacts_id}/addresses

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

Get a Contact's Status

Sample Request:

GET /contacts/{contact_id}/status

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

Configuring the Request

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

Handling the Response

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

Get Contact Status

Sample Request:

GET /api/v0/contacts/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contacts/statuses/{status_id}

This request returns the contact status specified by its status_id.

Configuring the Response

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

Handling the Response

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

List Contact Statuses

Sample Request:

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

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

GET /contacts/statuses

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

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color

Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering

Searching

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

Field
title

Count Contact Statuses

Sample Request:

GET /api/v0/contacts/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contacts/statuses/count

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

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

List Contact Segmentations

Sample Request:

GET /contacts/{contact_id}/segmentations

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

List a Contact's Profile Field Values

See the profiles section for a sample request

GET /contacts/{contact_id}/profiles/values

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

List all Profile Field Values on a Contact

See the profiles section for a sample request

GET /contacts/profiles/values

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

List Contact Profile Fields

See the profiles section for general usage.

GET /contacts/profiles/fields

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

Update a Profile Field Value on a Contact

See the profiles section for general usage.

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

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

Set a Contact's Profile Field Value

See the profiles section for a sample request

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

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

List Available Progressions on a Contact

See the progressions section for a sample request

GET /contacts/{contact_id}/progressions

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

Auto Run a Progression on a Contact

See the progressions section for a sample request

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

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

List a Contact's Resource Collections

See the resources (attachments) section for an example

GET /contacts/{contact_id}/collections

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

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

See the resources (attachments) section for an example

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

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

Contracts (Retainers)

Resource URI:
/api/v0/contracts

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

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

The Contract Object

Example contract:

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

The contract object contains the following fields and linked objects:

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

The Contract Period

Example contract period object:

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

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

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

The Contract Type

Example contract type object:

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

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

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

This object does not support the _ALL argument under _fields.

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

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

The Contract Budget

Example contract budget object:

{
  "id": "1",
  "value": "25.00",
  "product_charged": "30.00",
  "time_charged": "24.00",
  "time": "1000",
  "against_type": "contract_period",
  "against_id": "10"
}

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

Get Contract

Sample Request:

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

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

GET /contracts/{contract_id}

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

Configuring the Response

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

Handling the Response

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

List Contracts

Sample Request:

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

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

GET /contracts

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

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

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

Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
date_started
date_expired
date_period_expires

Order Filters

This request supports order filters over the following fields:

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

Range Filters

this request supports range filters over the following fields:

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

Object Filters

This request supports the following object filters:

Filter Name	Description
against	Filter by contracts against these objects.

Searching

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

Field
title

Handling the Response

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

Count Contracts

Sample Request:

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

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

GET /contracts/count

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

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

Get Contract Period

Sample Request:

GET /api/v0/contracts/{contract_id}/periods/{period_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contracts/periods/{period_id}

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

Configuring the Response

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

Handling the Response

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

List Contract Periods

Sample Request:

GET /api/v0/contracts/{contract_id}/periods HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contracts/{contract_id}/periods

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

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

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

Date Filters

This request supports date filters over the following fields:

Filter Name
date_created
date_commenced
date_expires
date_closed

Range Filters

This request supports range filters over the following fields:

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

Order Filters

This request supports order filtering over the following fields:

Filter Name
id
date_created
date_commenced
date_expires
date_closed

Handling the Response

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

List Contract Types

Sample Request:

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

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

GET /contracts/types

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

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

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

Basic filters

This request supports basic filters over the following fields:

Field
id
standing
auto_renew
parent
send_invoice
period_template_id
invoice_template_id
service_tax_id
service_ledger_id

Order Filters

This request supports order filters over the following fields:

Field
id
title
standing
ordering

Range Filters

This request supports range filters over the following fields:

Field
id
renew_days

Empty Filters

This request supports empty filters over the following fields:

Field
title

Searching

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

Field
title

Handling the Response

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

Count Contract Types

Sample Request:

GET /api/v0/contracts/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contracts/types/count

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

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

Get Contract Type

Sample Request:

GET /api/v0/contracts/types/{type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contracts/types/{type_id}

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

Configuring the Request

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

Handling the Response

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

Get Contract Status

Sample Request:

GET /api/v0/contracts/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contracts/statuses/{status_id}

This request returns the contract status specified by its status_id.

Configuring the Response

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

Handling the Response

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

List Contract Statuses

Sample Request:

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

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

GET /contracts/statuses

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

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color

Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering

Searching

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

Field
title

Count Contract Statuses

Sample Request:

GET /api/v0/contracts/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contracts/statuses/count

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

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

Close a Contract Period

Sample Request:

PUT /api/v0/contracts/periods/{period_id}/close HTTP/1.1
HOST: {deployment.api.accelo.com}
Authorization: Bearer {access_token}

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

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

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

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

Reopen a Contract Period

Sample Request:

PUT /api/v0/contracts/periods/{period_id}/open HTTP/1.1
HOST: {deployment.api.accelo.com}
Authorization: Bearer {access_token}

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

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

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

List Available Progressions on a Contract

See the progressions section for a sample request

GET /contracts/{contract_id}/progressions

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

Auto Run a Progression on a Contract

See the progressions section for a sample request

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

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

List a Contract's Resource Collections

See the resources (attachments) section for an example

GET /contracts/{contract_id}/collections

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

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

See the resources (attachments) section for an example

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

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

List a Contract's Profile Field Values

See the profiles section for a sample request

GET /contracts/{contract_id}/profiles/values

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

List all Profile Field Values on Contracts

See the profiles section for a sample request

GET /contracts/profiles/values

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

List Contract Profile Fields

See the profiles section for a sample request

GET /contracts/profiles/fields

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

List Contract Extension Fields

See the extension section for an example

GET /contracts/extensions/fields

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

List all Extensions Field Values on Contracts

See the extension section for an example

GET /contracts/extensions/values

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

List a Contract's Extension Field Values

See the extension section for an example

GET /contracts/{contract_id}/extensions/values

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

Update an Extension Field Value on a Contract

See the extension section for an example

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

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

Set an Extension Value on a Contract

See the extension section for an example

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

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

Contributors

Resource URI: /api/v0/contributors

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

The Contributor Object

Example contributor object:

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

The contributor object contains the following:

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

The Contributor Type Object

Example contributor type object:

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

The contributor type object contains the following:

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

Get Contributor

Sample Request:

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

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

GET /contributors/{id}

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

Configuring the Response

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

Handling the Response

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

List Contributors

Sample Request:

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

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

GET /contributors

This request returns a list of contributors on the deployment.

Configuring the Request

Pagination

This request accepts all the standard pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
standing
status_id
contributor_type_id
against_type
against_id
object_id
object_type
auto_cc

Order Filters

This request supports order filters over the following fields:

Filter Name
id
contributor_type_id
standing
status_id
against_id
auto_cc

Range Filters

This request supports range filters over the following fields:

Filter Name
id
against_id
object_id
contributor_type_id

Searching

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

Filter Name
description

Handling the Response

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

Count Contributors

Sample Request:

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

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

GET /contributors/count

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

Field	Type	Description
count	unsigned	A count of contributors listed.

Get Contributor Type

Sample Request:

GET /api/v0/contributors/types/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contributors/types/{id}

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

Configuring the Response

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

Handling the Response

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

List Contributor Types

Sample Request:

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

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

GET /contributors/types

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

Configuring the Request

Pagination

This request accepts all the standard pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
title
default_status_id
default_standing

Order Filters

This request supports order filters over the following fields:

Filter Name
ordering

Handling the Response

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

Count Contributor Types

Sample Request:

GET /api/v0/contributors/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /contributors/types/count

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

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

Divisions

Resource URI:
/api/v0/divisions

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

The Division Object (Beta)

Sample division JSON object:

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

The division object contains the following:

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

Get Division (Beta)

Sample request:

curl -X get \
    https://{deployment}.api.accelo.com/api/v0/divisions/{division_d} \
    -H 'authorization: Bearer {access_token} \
    -d '_fields=standing'

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

_fields=standing

GET /division/{division_id}

This request returns a division specified by its unique identifier.

Configuring the Response

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

Handling the Response

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

List Divisions (Beta)

Sample request:

curl -X get \
    https://deployment.api.accelo.com/api/v0/divisions \
    -H 'authorization: Bearer foobar'
    -d '_fields=_ALL'
    -d '_filters=standing(active)'

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

GET /divisions

This request returns a list of divisions on the deployment.

Configuring the Response

Pagination

This request supports all of the pagination parameters.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing

Order Filters

This request supports order filters over the following fields:

Field
id
ordering

Searching

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

Field
title

Handling the Response

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

Count Divisions (Beta)

Sample request:

curl -X get \
    https://deployment.api.accelo.com/api/v0/divisions/count \
    -H 'authorization: Bearer foobar'
    -d '_fields=_ALL'
    -d '_filters=standing(active)'

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

GET /divisions/count

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

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

Expenses

Resource URI:
/api/v0/expenses

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

The Expenses Object

Sample expense:

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

The expense object contains the following fields and linked objects:

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

The Expense Type

Sample expense type:

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

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

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

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

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

Get Expense

Sample Request:

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

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

GET /expenses/{expense_id}

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

Configuring the Request

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

Handling the Response

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

List Expenses

Sample Request:

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

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

GET /expenses

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

Configuring the Request

Pagination

This request supports all the pagination parameters:

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

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

Date Filters

This request supports date filters over the following fields:

Filter Name
date_incurred

Order Filters

This requesting supports order filters over the following fields:

Filter Name
id
date_incurred
title
standing

Range Filters

This request supports range filters over the following fields:

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

Object Filters

This request supports the following object filters:

Filter	Description
against	Filter by expenses against these objects.

Searching

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

Field
title

handling the Response

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

Count Expenses

Sample Request:

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

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

GET /expenses/count

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

	Type	Description
count	unsigned	A count of the listed expenses.

Get Expense Type

Sample Request:

GET /api/v0/expenses/types/{type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /expenses/types/{type_id}

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

Configuring the Response

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

handling the Response

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

List Expense Types

Sample Request:

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

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

GET /expenses/types

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

Configuring the Response

Pagination

This request supports all the pagination parameters:

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

Filter Name
id
standing
ledger_id
tax_id

Order Filters

This request supports order filters over the following fields:

Filter Name
id
title
standing

Range Filters

This request supports range filters over the following fields:

Filter Name
id

Empty Filters

This request supports empty filters over the following fields:

Field
title

Searching

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

Field
title

handling the Response

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

Count Expense Types

Sample Request:

GET /api/v0/expenses/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

GET /expenses/types/count

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

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

Update an Expense

Sample Request:

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

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

PUT /expenses/{expense_id}

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

Configuring the Expense

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

Field Name
title
quantity
billable
reimbursable
type_id
unit_cost
date_incurred
resource_id

Configuring the Response

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

handling the Response

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

Create an Expense

Sample Request:

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

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

POST /expenses

This request creates and returns an expense object.

Configuring the Expense

The following fields from the expense object may be set with this request:

Field Name	Notes
title
against_id
against_type
unit_cost
quantity
type_id
price	If not included, this will default to unit_cost.
date_incurred
billable
reimbursable
file	Allows you to upload a file with the expense (i.e. a receipt in the form of an image or PDF). If this value is set then it must be POSTed with multipart/form-data.
resource_id	The unique identifier of a resource (attachment) to be sent with the expense. Note: you may only pass one of resource_id or file.

Configuring the Response

This response supports requesting extra fields and linked objects from the expenses object through the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The request will return the single new expense object with its default fields, and any additional fields requested through _fields.

Delete an Expense

Sample Request:

DELETE /api/v0/expenses/{expense_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

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

DELETE /expenses/id

This request removes an expense from the deployment. It takes no parameters and returns no resources.

List Available Progressions on an Expense

See the progressions section for a sample request

GET /companies/{expense_id}/progressions

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

Auto Run a Progression on an Expense

See the progressions section for a sample request

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

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

Extensions (Custom Fields)

Resource URI:
/api/v0/extensions

Extensions, also known as Custom Fields, are similar to profiles. The main difference is in their availability. A given profile may be available to all types of a particular object, for example any type of issues, or even across a range of objects. Conversely, an extension is available to only one type of one object at at time, see also the support documentation. Extensions may be set up through the Accelo deployment, see the support documentation for information on setting them up. Currently the following objects support extensions through the API:

• Assets
• Contracts
  
• Issues
  
• Jobs
  
• Prospects

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:

• Activities
  
• Affiliations
  
• Companies
  
• Contracts
  
• Expenses
  
• Issues
  
• Jobs
• Milestones
  
• Prospects
  
• Quotes
  
• Staff
  
• Tasks

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 its invoice_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "invoices", and whose value is {invoice_id}.

Get Line Item (Beta)

Sample Request:

GET /api/v0/invoices/line_items/{line_item_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/invoices/line_items/{line_item_id} \
  -H 'authorization: Bearer {access_token}'

GET /invoices/line_items/{line_item_id}

This request returns a line item specified by its line_item_id.

Configuring the Response

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

Handling the Response

The request will return the single invoice line item with its default fields and any additional fields requested through _fields.

List Line Items (Beta)

Sample request:

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

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/invoices/line_items \
  -H 'authorization: Bearer {access_token}'

This request returns a list of invoice line item.

Configuring the Response

Pagination

This request supports all of the standard pagination parameters

Additional Fields and Linked objects

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

Basic Filters

This request supports the following basic filters:

Filter
id
invoice_id
ledger_id
tax_id

Order Filters

This request supports the following order filters:

Filter
id
invoice_id
ledger_id
tax_id
quantity
rate
total
ordering

Range Filters

This request supports range filters over the following fields:

Filter
id
invoice_id
ledger_id
tax_id
quantity
rate
total

Searching

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

Field
description

Handling the Response

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

Count Line Items (Beta)

Sample request:

GET /api/v0/invoices/line_items/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/invoices/line_items/count \
  -H 'authorization: Bearer {access_token}'

GET /invoices/line_items/count

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

Field	Type	Description
count	unsigned	A count of line items listed.

Issues (Tickets)

Resource URI: /api/v0/issues

Issues (also known as "Tickets") are used for when you need to track billable time against a client, but don’t need the complexity of a full Project and its workflow and components. For example, issues may be used to track support cases where you’re diagnosing and fixing a problem and don’t know beforehand the specific steps which will be required to resolve the Issue. See the support documentation for more information on these objects.

The Issue Object

Example issue object:

{
  "assignee": "14",
  "title": "Issue with public field",
  "referrer_type": null,
  "affiliation": "98",
  "date_submitted": "1493872605",
  "date_modified": "1553728167",
  "resolution_detail": "I fixed the field, it now displays as expected.",
  "staff_bookmarked": "1",
  "against": "companies/39",
  "contract": "1",
  "billable_seconds": "1400",
  "submitted_by": "14",
  "against_type": "company",
  "date_due": "1493906400",
  "contact": "98",
  "date_closed": "1495683190",
  "standing": "closed",
  "object_budget": "8",
  "date_started": "1493820000",
  "class": "19",
  "resolved_by": "14",
  "date_last_interacted": "1493872783",
  "resolution": "8",
  "closed_by": "14",
  "date_resolved": "1495683190",
  "referrer_id": null,
  "custom_id": "",
  "status": "4",
  "opened_by": "14",
  "type": "1",
  "description": "A public field is showing as public",
  "against_id": "39",
  "id": "7",
  "company": "39",
  "issue_priority": "1",
  "date_opened": "1493872605"
}

The issue object contains the following:

Field	Type	Description
id	unsigned	A unique identifier for the issue.
title	string	A name for the issue
custom_id	string	The custom ID for the issue. Only issues whose type allows custom IDs will have a value for this field.
description	string	A description of the issue.
against	string	The API URI of the object this issue is against.
against_type	string	A string representing the type of object this issue is against.
against_id	unsigned	The unique identifier of the object this issue is against.
type	unsigned or object	The issue type of this issue. Deprecated, please use issue_type.
issue_type	unsigned or object	The issue type of this issue.
affiliation	unsigned or object	The affiliation associated with this issue.
class	unsigned or object	The issue class of this issue.
priority	unsigned or object	Deprecated please use issue_priority
issue_priority	unsigned or object	The priority of the issue.
resolution	unsigned or object	The resolution type used by the issue, if it has been resolved.
resolution_detail	string	A description of the resolution, if resolved.
status	unsigned or object	The status of the issue.
standing	string	The standing of the issue, taken from the issue status.
date_submitted	unix ts	The date the issue was submitted
submitted by	unsigned or object	The staff member who submitted the issue.
date_opened	unix ts	The date the issue was opened.
opened_by	unsigned or object	The staff member who opened the issue.
date_resolved	unix ts	If resolved, the date the issue was resolved.
resolved_by	unsigned or object	The staff member who resolved the issue.
date_closed	unix ts	If closed, the date the issue was closed.
closed_by	unsigned or object	The staff member who closed the issue.
date_due	unix ts	The due date for the issue.
date_last_interacted	unix ts	The date the issue was last interacted with.
date_modified	unix ts	The date the issue was last modified.
referrer_type	string	If the issue was created from the deployment as a "related issue" to an object, this will be the object's type.
referrer_id	unsigned	The unique identifier of this related object.
staff_bookmarked	boolean	Whether the current viewer has bookmarked the issue.
billable_seconds	unsigned	The amount of billable time, in seconds, on the issue.
company	unsigned or object	If against_type is company, the company the issue is against.
assignee	unsigned or object	The staff assigned to the issue.
contract	unsigned or object	If the issue is assigned a contract (retainer), this will return the contract object.
issue_object_budget	unsigned or object	The object budget associated with the issue.
object_budget	unsigned or object	Deprecated please use issue_object_budget.

The Issue Priority

Example priority object:

{
  "title": "Extreme",
  "id": "1",
  "color": "Red",
  "factor": "5"
}

Issue priorities help you keep track of what needs to be done. They may be set up from the deployment, see the support documentation for information. They contain the following:

Field	Type	Description
id	unsigned	A unique identifier for the priority.
title	string	A name for the priority.
color	select	The color of the priority when displayed on the deployment. The colors, in order of increasing urgency a "grey", "blue", "green", "orange", "red".
factor	unsigned	A number representing the urgency of the priority. 5 is "Extreme", 1 is "None".

The Issue Status

Example issue status object:

{
  "standing": "open",
  "start": "yes",
  "color": "yellow",
  "ordering": "2",
  "title": "Open",
  "id": "2"
}

Statuses may be used to track the progress of an issue. These statuses may be configured from the deployment, see the support documentation for more information. The status objects contain the following

Field	Type	Description
id	unsigned	A unique identifier for the status.
title	string	A name for the status.
standing	string	A string describing the standing of the issue.
color	string	The color of the status shown on the deployment.
start	select	Either "yes" or "no", whether an issue may be created with this status.
ordering	unsigned	A number describing the order of the status on the deployment.

The Issue Type

Example issue type object:

{
  "notes": "Issue type for support issues.",
  "standing": "active",
  "title": "Support",
  "id": "2",
  "parent": "0"
}

Issue types let you sort your issues according to the type of work the entail. Issue types may be set up and edited from the deployment, see the support documentation for more information.

Field	Type	Description
id	unsigned	A unique identifier for the issue type.
title	string	A name for the issue type.
notes	string	Notes about the issue type.
parent	unsigned	The unique identifier of the parent issue type. If there is no parent has the value "0"
standing	select	Either "active" or "inactive", the standing of the issue type.
budget	select	Either "yes" or "no", whether issues under this type are billable.
ordering	unsigned	A number describing the type's ordering on the deployment.

Note: the type field is deprecated, please request the issue type object through the issue_type field, which contains the following additional fields:

Field	Type	Description
default_class_id	unsigned	The unique identifier of the default issue class for this type of issue. Default is null.
has_custom_id	boolean	Either "1" or "0", whether the issue type uses custom ids.

The Issue Resolution

Example issue resolution:

{
  "standing": "active",
  "title": "Support Resolution",
  "id": "8",
  "parent": "7",
  "report": "Use this resolution when resolving support issues.",
  "description": "I fixed the field, it now displays as expected."
}

Issue resolutions track how certain issues are resolved and may be set up on the deployment, see the support documentation for more information. The issue resolution contains the following:

Field	Type	Descriptions
id	unsigned	A unique identifier for the issue resolution.
title	string	A name for the issue resolution.
parent	unsigned	The unique identifier of the parent resolution, it there is no parent this has value "0".
description	string	A generic description of the resolution, may be changed for a given issue.
report	string	A fixed description of the resolution.
standing	select	Either "active" or "inactive", the standing of the resolution.

The Issue Class

Example issue class:

{
  "standing": "active",
  "description": "For issues pertaining to our website",
  "parent": "0",
  "title": "Website",
  "id": "2"
}

Issue classes help to classify symptoms or characteristics of an issue. They can be set up from the deployment, see the support documentation for information. Ticket classes contain the following:

Field	Type	Description
id	unsigned	A unique description for the class.
title	string	A name for the class.
description	string	A description of the class.
parent	unsigned	The unique identifier of the parent class, if there is no parent this has value "0".
standing	select	Either "active" or "inactive", the standing of the class.

Get Issue

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
  -H 'authorization: Bearer {access_token}'

GET /issues/{issue_id}

This request returns a single issue, identified by its issue_id.

Configuring the Response

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

Handling the Response

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

List Issues

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues \
  -H 'authorization: Bearer {access_token}'

GET /issues

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

Pagination

This request supports the standard pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports basic filters over the following fields:

Filter Name	Notes
id
standing
custom_id
referrer_type
referrer_id
against_id
against_type
status	Filter by the status_id of the issue.
type	Filter by the type_id of the issue. Deprecated, please use issue_type.
issue_type	Filter by the issue_type_id.
affiliation	Filter by the affiliation_id of the issue.
class	Filter by the class_id of the issue.
priority	Deprecated, please use issue_priority
issue_priority	Filter by the priority_id of the issue.
resolution	Filter by the resolution_id of the issue.
submitted_by	Filter by the staff_id of the submitter.
opened_by	Filter by the staff_id of the user who opened the issue.
closed_by	Filter by the staff_id of the user who closed the issue.
resolved_by	Filter by the staff_id of the user who resolved the issue.
assignee	Filter by the staff_id of the assignee.
contract	Filter by the contract_id of any linked contracts.

Date Filters

This request supports date filters over the following fields:

Filter Name
date_opened
date_submitted
date_started
date_due
date_closed
date_modified

Order Filters

This request supports order filters over the following fields:

Filter Name	Notes
id
date_opened
date_submitted
date_started
date_due
date_closed
date_resolved
date_last_interacted
date_modified
title
standing
status	Order by the status_id

Range Filters

This request supports range filters over the following fields:

Filter Name	Notes
id
reopened_count	Range over the number of times the issue has been reopened.
rate_charged
against_id
billable_seconds
assignee	Range over the staff_id of assignees.
type	Range over the type_id. Deprecated, please use issue_type.
issue_type	Range over issue_type_id.
affiliation	Range over the affiliation_id.
class	Range over the class_id.
resolution	Range over the range_id.
priority	Deprecated, please use issue_priority
issue_priority	Range over the priority_id.
submitted_by	Range over the staff_id of submitters.
opened_by	Range over the staff_id of staff members who opened issues.
resolved_by	Range over the staff_id of staff members who resolved issues.
closed_by.	Range over the staff_id of staff members who closed issues.
status	Range over the status_id.
rate	Range over the rate_id of the rate charged.
contract	Range over the contract_id of contracts linked to issues.

Object Filters

This request supports the following object filters:

Filter Name	Description
against	Filter by issues against these objects.
referrer	Filter by issues referred by these objects.

Searching

This request supports using the _search function to search over the following fields:

Field
subject

Handling the Response

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

Count Issues

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/count \
  -H 'authorization: Bearer {access_token}'

GET /issues/count

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

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

List Recent Issues

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/recent \
  -H 'authorization: Bearer {access_token}'

GET /issues/recent

This request returns a list of issues on the deployment sorted by most recently submitted, that is, in descending order of date_submitted.

Configuring the Request

This request accepts the same parameters and filters over the same fields as the GET /issues request, although it will always be ordered in descending order of date_submitted.

Handling the Response

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

List Issue Statuses

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/statuses \
  -H 'authorization: Bearer {access_token}'

GET /issues/statuses

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

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color

Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering

Searching

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

Field
title

Handling the Response

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

Get Issue Type

Sample request:

GET /api/v0/issues/types/{issue_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/issues/types/{issue_type_id} \
  -H 'authorization: Bearer {access_token}'

GET /issues/types/{issue_type_id}

This request returns an issue type specified by its unique id.

Configuring the Response

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

Handling the Response

The response will contain a single issue type with its default fields and any additional fields requested through _fields.

List Issue Types

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/types \
  -H 'authorization: Bearer {access_token}'

GET /issues/types

This request returns a list of issue types on the deployment. The _filters parameter is set to standing_not(inactive) by default.

Configuring the Response

Pagination

This request supports the standard pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the issue type object using the _fields parameter. Note this request does not support the _ALL argument for this parameter.

Handling the Response

The response will be a list of issue types with their default fields and any additional fields requested through _fields.

Basic Filters

This request supports the following basic filters:

Filter
id
standing
budget
default_class_id
parent

Order Filters

This request supports order filters over the following fields:

Field
id
title
standing
ordering

Range Filters

This request supports range filters over the following fields:

Field
id

Searching

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

Field
title

List Issue Classes

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/classes \
  -H 'authorization: Bearer {access_token}'

GET /issues/classes

This request returns a list of issue classes on the deployment.

Configuring the Response

This request supports requesting additional fields and linked objects from the issue class object using the _fields parameter. Note this request does not support the _ALL argument for this parameter.

Handling the Response

The response will be a list of issue types with their default fields and any additional fields requested through _fields.

Get Issue Resolution

Sample request:

GET /api/v0/issues/resolutions/{resolution_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/issues/resolutions/{resolution_id} \
  -H 'authorization: Bearer {access_token}' \

GET/issues/resolutions/{resolution_id}

This request returns a single issue resolution, specified by its resolution_id.

Configuring the Response

Additional Fields and Linked Objects

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

Handling the Response

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

List Issue Resolutions

Sample request:

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

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/issues/resolutions \
  -H 'authorization: Bearer {access_token}' \

GET/issues/resolutions

Returns a list of issue resolutions.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter	Description
id
standing
parent_id

Order Filters

This request supports the following order filters:

Filter	Description
id
standing
title

Range Filters

This request supports range filters over the following fields:

Field
id

Empty Filters

This request supports empty filters over the following fields:

Field
title

Searching

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

Field
title

Handling the Response

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

Count Issue Resolutions

Sample request:

GET /api/v0/issues/resolutions/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/issues/resolutions/count \
  -H 'authorization: Bearer {access_token}' \

GET/issues/resolutions/count

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

Field	Type	Description
count	Unsigned	A count of issue resolutions listed

List Tasks Against an Issue

Sample Request: GET /issues/{issue_id}/tasks

GET /api/v0/issues/{issue_id}/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/tasks \
  -H 'authorization: Bearer {access_token}'

This request returns a list of tasks against an issue specified by its issue_id.

Configuring the Response

This response may be configuring in the same way as GET /tasks

Handling the Response

This response may be handled in the same way as GET /tasks

Update an Issue

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /issues/{issue_id}

This request updates and returns an issue object, identified by its issue_id.

Configuring the Issue

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

	Notes
title
description
against_id	Note: If supplied, you must also supply an against_type.
against_type	Note: If supplied, you must also supply an against_id.
class_id	Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes.
affiliation_id
date_started
date_due
assignee	A staff_id, must point to a valid staff member. The staff will be assigned and informed of this assigned issue.
priority_id	The priority object's id. For available priorities see GET /issues/priorities
status_id	Must point to a valid issue status. Should not be sent in conjunction with standing, otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses. If you have a status_id, please use this instead of standing. standing will be used to guess the status, thus, status_id is more precise. Warning this will bypass any progressions and should only be used deliberately when automating tasks.
standing	The standing you want to change the issue to (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). Warning this will bypass any progressions and should only be used deliberately when automating tasks.
resolution_id	The identifier of the issue resolution. The resolution will only show if the issue's standing is resolved. This must point to a valid resolution, you may retrieve a list of resolutions through GET /issues/resolutions.
resolution_detail	The details of any resolution. To clear the resolution_detail you may send this field with no value.
contract_id	The id of the contract the issue is under, if this field is empty, the contract_id will be unset. This must point to a related contract, you can use the is_related_to_issue filter on GET /contracts to find related contracts.

Configuring the Response

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

Handling the Response

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

Create an Issue

Sample Request:

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

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

POST /issues

This request creates and returns an issue.

Configuring the Issue

Values for the following fields from the issue object may be set through this request:

	Notes
title
type_id	Must point to a valid issue type. You may retrieve a list of types through GET /issues/types.
against_type	Must be a valid type of object.
against_id	Must point to a valid object of type against_type.
standing	Must be a valid standing. (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). If you have a status_id, please use this instead of standing. standing will be used to guess the status, thus, status_id is more precise.
status_id	Must point to a valid issue status. Should not be sent in conjunction with standing, otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses.
affiliation_id
date_started
date_due
description
class_id	Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes
assignee	A staff_id, must point to a valid staff member.
priority_id	The priority object's id. For available priorities see GET /issues/priorities

Configuring the Response

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

Handling the Response

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

Delete an Issue

Sample Request:

DELETE /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
  -H 'authorization: Bearer {access_token}' \

DELETE /issues/{issue_id}

This request removes an issue from the deployment, specified by its issue_id. This request takes no parameters and returns no resources.

List Issue Priorities

GET /issues/priorities

This request returns a list of priorities available for issues.

Get Issue Priority

GET /issues/priorities/{priority_id}

Returns a single priority for the given priority id.

Count Issue Priorities

GET /issues/priorities/count

Returns the number of issue priorities.

List an Issue's Profile Field Values

See the profiles section for a sample request

GET /issues/{issue_id}/profiles/values

This request returns a list of profile values of an issue, specified by its issue_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "issues", and whose id is {issue_id}.

List all Profile Field Values on Issues

See the profiles section for a sample request

GET /issues/profiles/values

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

List Issue Profile Fields

See the profiles section for a sample request

GET /issues/profiles/fields

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

Update a Profile Value on an Issue

See the profiles section for a sample request

PUT /issues/{issue_id}/profiles/values/{profile_value_id}

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

Set a Profile Value on an Issue

See the profiles section for a sample request

POST /issues/{issue_id}/profiles/fields/{profile_field_id}

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

List Issue Extension Fields

See the extension section for an example

GET /issues/extensions/fields

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

List an Issue's Extension Field Values

See the extension section for an example

GET /issues/{issue_id}/extensions/values

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

List all Extension Field Values on Issues

See the extension section for an example

GET /issues/extensions/values

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

Update an Extension Field Value on an Issue

See the extension section for an example

PUT /issues/{issue_id}/extensions/values/{extension_value_id}

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

Set an Extension Field Value on an Issue

Sample Request:

POST /issues/{issue_id}/extensions/fields/{extension_field_id}

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

List Available Progressions on an Issue

See the progressions section for a sample request

GET /issues/{issue_id}/progressions

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

Auto Run a Progression on an Issue

See the progressions section for a sample request

[POST|PUT] /issues/{issue_id}/progressions/{progression_id}/auto

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

List an Issue's Resource Collections

See the resources (attachments) section for an example

GET /issues/{issue_id}/collections

This request returns a list of resource collections against an issue, specified by its issue_id. This is the request GET /{object}/{object_id}/collections where the object is "issues" and hose id is {issue_id}.

Upload a Resource (Attachment) to a Collection on an Issue

See the resources (attachments) section for an example

POST /issues/{issue_id}/collections/{collection_id}/resources

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

Jobs (Projects)

Resource URI:
api/v0/jobs

Jobs (or Projects) help you to plan, delegate and track client and internal projects. Projects can be as simple or complex as you like, see the support documentation for more information.

The Job Object

Example job object:

{
  "date_modified": "1495681796",
  "modified_by": "14",
  "status": "5",
  "staff_bookmarked": "1",
  "type": "3",
  "job_type": "3",
  "against": "companies/65",
  "date_completed": null,
  "against_id": "39",
  "against_type": "company",
  "company": "39",
  "id": "2",
  "date_due": "1495245600",
  "rate": "3",
  "date_created": "1495238402",
  "standing": "active",
  "date_started": "1495245600",
  "title": "New Logo Design",
  "paused": "0",
  "date_last_interacted": "1495686301",
  "manager": "7",
  "rate_charged": "125.00",
  "date_commenced": "1494209132",
  "affiliation": "77",
  "custom_id": "TIM#42"
}

The jobs object contains the following:

Field	Type	Description
id	unsigned	A unique identifier for the job.
title	string	A name for the job.
against_type	string	The type of object the job is against.
against_id	unsigned	The unique identifier of the object the job is against.
against	string	The API URI of the object the job is against, that is,against_type and against_id concatenated with a "/".
custom_id	string	The custom id for this job.
paused	integer	The number of days the jobs has been paused.
staff_bookmarked	boolean	Whether the current user has bookmarked the job on the deployment.
date_created	unix ts	The date the project was created.
date_modified	unix ts	The date the project was last modified.
date_commenced	unix ts	The date the job started, that is, when its status moved from "setup" to "active"
date_started	unix ts	The date the job is scheduled to start.
date_due	unix ts	The date the job is scheduled to be completed.
date_completed	unix ts	The date the job was completed.
date_last_interacted	unix ts	The date the job was last interacted with.
type	unsigned or object	The job type object of the job. Deprecated, please use job_type.
job_type	unsigned or object	The job type associated with the job.
rate	unsigned or object	The rate object associated with the job.
rate_charged	decimal	The rate charged for billable work, this is part of the rate object.
status	unsigned or object	The status associated with the job
standing	string	The standing of the project. This is part of the status.
manager	unsigned or object	The staff manager managing the job.
modified_by	unsigned or object	The staff member who last modified the job.
company	unsigned or object	The company against the job, if any.
affiliation	unsigned or object	The affiliation against the job.
job_object_budget	unsigned or object	The object budget associated with the job.
job_contract	unsigned or object	The contract associated with the job, if any.

The Job Type

Example job type:

{
  "id": "3",
  "title": "Internal",
  "standing": "active",
  "ordering": "0"
}

You may set up and configure different job types to suit your business processes, general information on types can be found in the support documentation. For jobs, the type object contains the following:

Field	Type	Description
id	unsigned	A unique identifier for the job type.
title	string	A name for the job type.
standing	select	Either "active" or "inactive", the standing of the job type.
ordering	integer	An integer representing the type's order as displayed on the deployment.

Note: Requesting the job type object via type() is deprecated, please instead request it via job_type(), this object will have an additional field:

Field	Type	Description
has_custom_id	boolean	Either "1" or "0", whether the job type has a custom id.

Get Job

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
  -H 'authorization: Bearer {access_token}'

GET /jobs/{job_id}

This request returns a single job, specified by its job_id.

Configuring the Response

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

Handling the Response

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

List Jobs

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs \
  -H 'authorization: Bearer {access_token}'

GET /jobs

This request returns a list of jobs on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Object

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

Basic Filters

This request supports basic filters over the following fields:

Filter Name	Notes
id
standing
against_id
against_type
paused
type	Filter by the type_id of the job. Deprecated, please use job_type.
job_type	Filter by the job_type_id.
manager	Filter by the staff_id of the job manager.
modified_by	Filter by the staff_id of the last staff member to modify the job.
status	Filter by the status_id.
rate	Filter by the rate_id.
affiliation	Filter by the affiliation_id.
custom_id

Date Filters

This request supports date filters over the following fields:

Filter Name
dated_created
date_modified
date_started
date_commenced
date_due
date_completed

Order Filters

This request supports order filters over the following fields:

Filter Name	Notes
date_started
date_created
date_commenced
date_due
date_completed
date_modified
date_last_interacted
id
title
standing
status	Order by the status_id.
custom_id

Range Filters

This request supports range filters over the following fields:

Filter Name	Notes
id
against_id
type	Range by the type_id. Deprecated, please use job_type.
job_type	Range by the job_type_id.
manager	Range by the staff_id of the manager of the job.
affiliation	Range by the affiliation_id.
modified_by	Range by the staff_id of the last staff member to modify the job.
status	Range by the status_id.
rate	Range by the rate_id.
rate_charged
contract	Range by the contract_id of any contract associated with the job.
plan_modified_by	Range by the staff_id of the last staff member to modify the job plan.
custom_id

Object Filters

This request supports the following object filters:

Filter	Description
against	Filter by jobs against these objects.

Searching

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

Field
title

Handling the Response

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

Count Jobs

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/count \
  -H 'authorization: Bearer {access_token}'

GET /jobs/count

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

Field	Type	Value
count	unsigned	A count of jobs listed.

List Recent Jobs

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/recent \
  -H 'authorization: Bearer {access_token}'

GET /jobs/recent

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

Configuring the Response

The response to this response may be configured as per GET /jobs, although any order filters used will have no impact on the response.

Handling the Response

This request will return a list of job objects on the deployment with their default fields and any additional fields requested through _fields, displayed in descending order of date_created and according to any pagination parameters, filters, or searches used.

List Latest Modified Jobs

Sample Request:

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

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/newest \
  -H 'authorization: Bearer {access_token}'

GET /jobs/newest

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

Configuring the Response

The response to this response may be configured as per GET /jobs, although any order filters used will have no impact on the response.

Handling the Response

This request will return a list of job objects on the deployment with their default fields and any additional fields requested through _fields, displayed in descending order of date_modified and according to any pagination parameters, filters, or searches used.

Get Job Type

Sample request:

GET /api/v0/jobs/types/{job_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

_fields=standing,has_custom_id

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/jobs/types/{job_type_id} \
  -H 'authorization: Bearer {access_token}' \
  -d '_fields=standing,has_custom_id'

GET /jobs/types/{job_type_id}

This request returns a job type specified by its unique id.

Configuring the Response

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

Handling the Response

The response will contain a single job type with its default fields and any additional fields requested through _fields.

List Job Types

Sample request:

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

_fields=standing,has_custom_id
_filters=standing(active)

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/jobs/types \
  -H 'authorization: Bearer {access_token}' \
  -d '_fields=standing,has_custom_id' \
  -d '_filters=standing(active)'

GET /jobs/types

This request returns a list of job types.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter
id
standing

Order Filters

This request supports order filters over the following fields:

Field
id
title
standing

Range Filters

This request supports range filters over the following fields:

Field
id

Searching

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

Field
title

Handling the Response

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

Get Job Status

Sample Request:

GET /api/v0/jobs/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}'

GET /jobs/statuses/{status_id}

This request returns the job status specified by its status_id.

Configuring the Response

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

Handling the Response

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

List Job Statuses

Sample request:

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

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/jobs/statuses \
  -H 'authorization: Bearer {access_token}' \

GET/jobs/statuses

This request returns a list of job statuses.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

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

Basic Filters

This request supports the following basic filters:

Filter	Notes
id
title
standing
color

Order Filters

This request supports order filters over the following fields:

Filter	Notes
id
title
standing
color
ordering

Searching

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

Field
title

Handling the Response

The response will be a list of statuses with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Job Statuses

Sample Request:

GET /api/v0/jobs/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/jobs/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /jobs/statuses/count

This request will return a count of job statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all job statuses on the deployment. This request returns a single field:

Field	Type	Description
count	unsigned	A count of the listed job statuses.

List Job Milestones

Sample Request:

GET /api/v0/jobs/{job_id}/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id}/milestones \
  -H 'authorization: Bearer {access_token}'

GET /jobs/{job_id}/milestones

This request returns a list of milestones of a job, specified by its job_id. This request is handled and configured in the same way as GET /milestones.

Update a Job

Sample Request:

PUT /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

PUT /jobs/{job_id}

This request updates and returns a job, specified by its job_id.

Configuring the Job

The following fields from the job object may be updated with this request:

Filter Name	Notes
title
engagement_table	The against_type for the job
engagement_id	The against_id for the job.
manager_id	The staff_id of the staff member to be assigned manager.
status_id	MUST point to a valid job status.
contract_id	The contract_id of a contract to be linked to the job
affiliation_id	The affiliation_id of an affiliation to be linked to the job.
rate_id
rate_charged
date_due
date_created

Configuring the Response

This request supports requesting additional fields and linked resources from the jobs object through the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, updated job with its default fields and any additional fields requested through _fields.

Create a Job

Sample Request:

POST /api/v0/jobs/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/\
  -H 'authorization: Bearer {access_token}' \
  -H 'Content-Type: application/x-www-form-urlencoded'

POST /jobs

This request creates and returns a new job.

Configuring the Job

The following fields may be set through this request:

Filter Name	Notes
against_type	The against_type for the job.
against_id	The against_id for the job.
manager_id	The staff_id of the staff member to be assigned manager. This MUST point to a valid staff.
type_id*	MUST point to a valid job type.
title
rate_id
status_id	MUST point to a valid job status.
contract_id	The contract_id of a contract to be linked to the job.
affiliation_id	The affiliation_id of an affiliation to be linked to the job.
rate_charged
date_due
date_started
date_created	If this is not sent it will default to the current time.
is_billable	If the job is billable or nonbillable

Configuring the Response

This request supports requesting additional fields and linked resources from the jobs object through the _fields parameter. This request also supports breadcrumbs.

Handling the Response

The response will be the single, created job with its default fields and any additional fields requested through _fields.

Delete a Job

Sample Request:

DELETE /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
  -H 'authorization: Bearer {access_token}'

DELETE /jobs/{job_id}

This request deletes a job from the deployment, specified by its job_id. This request takes no arguments and returns no resources.

List a Job's Profile Field Values

See the profiles section for a sample request

GET /jobs/{job_id}/profiles/values

This request returns a list of profile values of a job, specified by its job_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "jobs", and whose id is {job_id}.

List all Profile Field Values on a Job

See the profiles section for a sample request

GET /jobs/profiles/values

This request returns a list of all profile field values on jobs. This is the request GET /{object}/profiles/values, where the object is "jobs".

List Jobs Profile Fields

See the profiles section for a sample request

GET /jobs/profiles/fields

This request returns a list of profile fields available for jobs. This is the request GET/{object}/profiles/fields where the object is "jobs".

Update a Profile Value on a Job

See the profiles section for a sample request

PUT /jobs/{job_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular job, specified by its job_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "jobs", and whose value is {job_id}.

Set a Profile Value on a Job

See the profiles section for a sample request

POST /jobs/{job_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a "job", specified by its job_id. This is the request POST/{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "jobs", and whose value is {job_id}.

List Job Extension Fields

See the extension section for an example

GET /jobs/extensions/fields

This request returns a list of extension fields available for any job. This is the request GET /{object}/extensions/fields, where the object is "jobs".

List a Job's Extension Field Values

See the extension section for an example

GET /jobs/{job_id}/extensions/values

This request returns a list of extension values for a job, specified by its job_id. This is the request GET /{object}/{object_id}/extensions/values, where the object is "jobs", and whose id is the job_id.

List all Extension Field Values on Jobs

See the extension section for an example

GET /jobs/extensions/values

This request returns a list of extension field values on jobs. This is the request GET /{object}/extensions/values, where the object is "jobs".

Update an Extension Field Value on a Job

See the extension section for an example

PUT /jobs/{job_id}/extensions/values/{extension_value_id}

This request updates the value of an extension field value, specified by its extension_value_id, of a job, specified by its job_id. This is the request PUT{object}/{object_id}/extensions/values/{extension_value_id}, where the object is "jobs", and whose id is job_id

Set an Extension Field Value on a Job

Sample Request:

POST /jobs/{job_id}/extensions/fields/{extension_field_id}

This request sets and returns the value of an extension field, specified by its extension_field_id, of a job, specified by its job_id. This request is the request POST/{object}/{object_id}/extensions/fields/{extension_field_id} where our object is "jobs" whose id is job_id.

List Available Progressions on a Job

See the progressions section for a sample request

GET /jobs/{jobs_id}/progressions

This request returns a list of available progressions for a job, specified by its job_id. This is the request GET /{object}/{object_id}/progressions where the object is "jobs" whose id is job_id.

Auto Run Progression on a Job

See the progressions section for a sample request

[POST|PUT] /jobs/{jobs_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress a job, specified by its jobs_id. This is the request [POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto where the object is "jobs" whose id is job_id.

List a Job's Resource Collections

See the resources (attachments) section for an example

GET /jobs/{job_id}/collections

This request returns a list of resource collections against a job, specified by its job_id. This is the request GET /{object}/{object_id}/collections where the object is "jobs" and hose id is {job_id}.

Upload a Resource (Attachment) to a Collection on a Job

See the resources (attachments) section for an example

POST jobs/{job_id}/collections/{collection_id}/resources

This request uploads a resource to a collection, specified by its collection_id, of a job specified by its job_id. This is the request POST/{object}/{object_id}/collections/{collection_id}/resources where the object is "jobs" whose id is {job_id}.

Ledgers

Accelo supports account ledgers, it also allows account ledger integration with certain online accounting systems (e.g. Xero). These account ledgers are described by the API through the ledger object. For information on viewing, adding and syncing account ledgers from your deployment, please see the support documentation.

The Ledger Object (Beta)

Example ledger

{
    "code": "200",
    "comment": "Ledger to be used for sales",
    "id": "1",
    "title": "Sales",
    "standing": "active",
    "parent_id": "0"
    }

The ledger object contains the following:

Field	Type	Description
id	unsigned	The unique identifier of the ledger.
title	string	The ledger's title.
code	string	The account ledger code
parent_id	unsigned	The unique identifier of the parent ledger, defaults to "0" is there is no parent
standing	select	The standing of the ledger, either "active" or "inactive".
comment	string	Comments on the ledger

Get Ledger (Beta)

GET /api/v0/ledgers/{ledger_id} HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}

curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/ledgers/{ledger_id} \
    -H 'authorization: Bearer {access_token}'

GET /ledgers/{ledger_id}

This request returns a ledger identified by its unique ledger_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the ledger object using the _fields parameter.

Handling the Response

The response wil be the single ledger with its default fields and any additional fields requested through _fields.

List Ledgers (Beta)

GET /api/v0/ledgers HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}

curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/ledgers/ \
    -H 'authorization: Bearer {access_token}'

GET /ledgers

This request returns a list of ledgers.

Configuring the Response

Pagination

This request supports all the standard pagination parameters.

Additional fields and Linked Objects

This request supports requesting additional fields and linked objects from the ledger object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter
id
code
parent_id
standing

Order Filters

This request supports the following order filters:

Filter
id
code
parent_id
standing
title

Range Filters

This request supports the following range filters:

Filter
id
parent_id

Searching

This request supports the _search parameter to search over the following fields:

Field
title
code

Handling the Response

The response will be a list of ledgers with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Ledgers (Beta)

GET /api/v0/ledgers/count HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}

curl -X GET \
    https://{deplyoment}.api.accelo.com/api/v0/ledgers/count \
    -H 'authorization: Bearer {access_token}'

GET /ledgers/count

This request will return a count of ledgers in a list defined by any available searches or filters. With no searches or filters this will be a count of all ledgers on the deployment. This request returns a single field:

Field	Type	Description
count	unsigned	A count of ledgers listed.

Milestones

Resource URI:
/api/vo/milestones

Milestones are the steps on the road to a Job's (Project's) completion. They define the schedule of the job, and contain the budget for their respective portion of the job. For information on accessing milestones through the deployment, see the support documentation, milestones may also be imported through the deployment, see again the support documentation for information.

Deleting, creating, and updating milestones is only available through the deployment on the project planning screen, see the support documentation for more information.

The Milestone Object

Example milestone object:

{
  "date_modified": "1494912868",
  "date_completed": "1494911355",
  "status": "4",
  "date_due": "1495072800",
  "id": "1",
  "description": "Initial planning",
  "standing": "complete",
  "date_created": "1494286008",
  "job": "2",
  "rate": "3",
  "title": "A milestone",
  "date_started": "1494208800",
  "object_budget": "12",
  "milestone_object_budget": "12",
  "rate_charged": "125.00",
  "ordering": "1",
  "parent": "0",
  "manager": "21",
  "date_commenced": "1494286232"
}

The milestone object contains the following:

Field	Type	Description
id	unsigned	A unique identifier for the milestone.
title	string	A name for the milestone.
description	string	A description of the milestone.
ordering	integer	An integer representing the milestone's ordering on the deployment.
parent	unsigned	The unique identifier of the parent milestone. If there is not parent this has the value "0".
date_created	unix ts	The date the milestone was created.
date_modified	unix ts	The date the milestone was last modified.
date_started	unix ts	The date the milestone is scheduled to start.
date_commenced	unix ts	The date the milestone was started, that is, when the standing was changed from "pending".
date_due	unix ts	The date the milestone is scheduled to be completed.
date_complete	unix ts	The date the milestone was completed.
job	unsigned or object	The job (project) the milestone has been created for.
manager	unsigned or object	The staff member assigned to manage the project.
status	unsigned or object	The status of the milestone.
standing	string	The standing of the milestone. This is part of the status object
rate	unsigned or object	The rate associated with the milestone.
rate_charged	decimal	The rate charged for billable work within this milestone. This is part of the rate object.
milestone_object_budget	unsigned or object	The object budget associated with the milestone.
object_budget	unsigned or object	Deprecated please use milestone_object_budget.

Get Milestone

Sample Request:

GET /api/v0/milestones/{milestone_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones/{milestone_id} \
  -H 'authorization: Bearer {access_token}'

GET /milestones/{milestone_id}

This request returns a single milestone, identified by its milestone_id.

Configuring the Response

This request supports requesting additional fields and linked resource from the milestone object using the _fields parameter.

Handling the Response

The response will be the single milestone with its default fields and any additional fields requested through _fields.

List Milestones

Sample Request:

GET /api/v0/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones \
  -H 'authorization: Bearer {access_token}'

GET /milestones

This request returns a list of milestones on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports request additional fields and linked objects from the milestone object using the _fields.

Basic Filters

This request supports basic filters over the following fields:

Filter Name	Notes
id
standing
ordering
job	Filter by the job_id.
parent	Filter by the milestone_id of the parent milestone.
manager	Filter by the staff_id of the manager.
rate	Filter by the rate_id.
object_budget	Filter by the object_budget_id.
status	Filter by the status_id.

Date Filters

This request supports date filters over the following fields:

Filter Name
date_modified
date_created
date_started
date_commenced
date_due
date_completed

Range Filters

This request supports range filters over the following fields:

Filter Name	Notes
id
job	Range by the job_id.
manager	Range by the staff_id of the manager.
status	Range by the status_id.
modified_by	Range by the staff_id of the last staff to modify the milestone.
rate	Range by the rate_id.
rate_charged

Searching

This request supports the _search parameter to search over the following fields:

Filter Name
title

Handling the Response

The response will be a list of milestones containing their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Count Milestones

Sample Request:

GET /api/v0/milestones/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones/count \
  -H 'authorization: Bearer {access_token}'

GET /milestones/count

This request will return a count of milestones in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestones on the deployment. This request does not return a response object, just a single value:

Field	Type	Description
response	unsigned	A count of milestones listed.

Get Milestone Status

Sample Request:

GET /api/v0/milestones/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/milestones/statuses/{status_id} \
  -H 'authorization: Bearer {access_token}' \

GET /milestones/statuses/{status_id}

This request returns the milestone status specified by its status_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the status object using the _fields parameter.

Handling the Response

The response will be a milestone status object for the specified status with its default fields and any additional fields requested through _fields.

List Milestone Statuses

Sample Request:

GET /api/v0/milestones/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/milestones/statuses \
  -H 'authorization: Bearer {access_token}'

GET /milestones/statuses

This request returns a list of milestone statuses on the deployment.

Configuring the Response

Pagination

This request supports the standard pagination requests.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the milestone status object through the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
title
standing
color

Order Filters

This request supports the following order filters:

Filter Name
id
title
standing
color
ordering

Searching

This request supports the _search parameter to search over the following fields:

Field
title

Count Milestone Statuses

Sample Request:

GET /api/v0/milestones/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
  https://{deployment}.api.accelo.com/api/v0/milestones/statuses/count \
  -H 'authorization: Bearer {access_token}' \

GET /milestones/statuses/count

This request will return a count of milestone statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestone statuses on the deployment. This request returns a single field:

Field	Type	Description
count	unsigned	A count of the listed milestone statuses.

List a Milestone's Profile Field Values

See the profiles section for a sample request

GET /milestones/{milestone_id}/profiles/values

This request returns a list of profile values of a milestone, specified by its milestone_id. This is the request GET /{object}/{object_id}/profiles/values, where the object is "milestones", and whose id is milestone_id.

List all Profile Field Values on a Milestone

See the profiles section for a sample request

GET /milestones/profiles/values

This request returns a list of all profile field values on milestones. This is the request GET /{object}/profiles/values, where the object is "milestones".

List Milestone Profile Fields

See the profiles section) for a sample request

GET /milestones/profiles/fields

This request returns a list of profile fields available for milestones. This is the request GET /{object}/profiles/fields where the object is "milestones".

Update a Profile Field Value on a Milestone

See the profiles section for a sample request

PUT /milestones/{milestone_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular milestone, specified by its milestone_id. This is the request PUT/{object}/{object_id}/profiles/values/{profile_value_id} where the object is "milestones", and whose id is the milestone_id.

Set a Profile Field Value on a Milestone

See the profiles section for a sample request

POST /milestones/{milestone_id}/profiles/fields/{profile_field_id}

This request sets and returns a profile value for a profile field, specified by its profile_field_id, for a milestone, specified by its milestone_id. This is the request POST /{object}/{object_id}/profiles/fields/{profile_field_id} where the object is "milestones", and whose value is milestone_id.

List Available Progressions on a Milestone

See the progressions section for a sample request

GET /milestones/{milestone_id}/progressions

This request returns a list of available progressions for a milestone, specified by its milestone_id. This is the request GET /{object}/{object_id}/progressions where the object is "milestones" whose id is milestone_id.

Auto Run a Progression on a Milestone

See the progressions section for a sample request

PUT|POST /milestones/{milestone_id}/progressions/{progression_id}/auto

This request uses the given progression, specified by its progression_id to progress a milestone, specified by its milestone_id. This is the request [POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto where theobject is "milestone" whose id is milestone_id.

Object Budgets

Resource URI:
api/v0/object_budgets

Object budgets are budgets against a specific object, for example a budget against an issue or a milestone. They are able to track the time and money spent by staff and on services, as well as expenses and the cost of materials.

The Object Budget

Example object budget:

{
  "charged": "45.84",
  "service_time": "0",
  "material_price_subtotal": "56.10",
  "service_time_estimate": "0",
  "service_price_subtotal_estimate": "425.00",
  "billable": "1320",
  "expense_price": "0.00",
  "material_cost_subtotal": "35.50",
  "remaining_subtotal": "180",
  "object_table": "job",
  "service_price_subtotal": "0.00",
  "charged_subtotal": "70.84",
  "logged": "1500",
  "object_id": "2",
  "logged_subtotal": "2100",
  "is_billable": "yes",
  "billable_subtotal": "1920",
  "material_cost": "35.50",
  "id": "11",
  "service_price_estimate": "0.00",
  "nonbillable": "180",
  "service_price": "0.00",
  "material_price": "56.10",
  "service_time_subtotal_estimate": "10800",
  "nonbillable_subtotal": "180"
}

The object budget resource contains the following:

Field	Type	Description
id	unsigned	A unique identifier for the object budget.
against_type	string	The type of object the object budget is against.
against_id	unsigned	The unique identifier of the object the object budget is against.
object_table	string	The type of object the object budget is against. Deprecated please use "against_type".
object_id	unsigned	The unique identifier of the object the object budget is against.Deprecated please use "against_type".
object	string	The API URI of the object the object budget is against. This is "{against_type}/{against_id}"
is_billable	select	Either "yes" or "no", whether time logged against the object is billable.
service_time_estimate	integer	The estimated total time for services against the object, in seconds.
service_time	integer	The total time logged for services against the object, in seconds.
service_time_subtotal_estimate	integer	The estimated total time for services against the object and its children, in seconds.
service_price_estimate	decimal	An estimate for the total price of services against the object.
service_price	decimal	The total price of services against the object.
service_price_subtotal_estimate	decimal	An estimate for the total price of services against the object and all of its children.
service_price_subtotal	decimal	The total price of services against the object and all of its children.
expense_price	decimal	The total prices of expenses for the object.
material_cost	decimal	The total cost of materials for the object.
material_cost_subtotal	decimal	the total cost of materials for the object and all its children.
material_price	decimal	The total price of materials for the object.
material_price_subtotal	decimal	The total price of materials for the object and all its children.
billable	integer	The total billable time logged against the object, in seconds.
billable_subtotal	integer	The total billable time logged against the object and all its children, in seconds.
nonbillable	integer	The total nonbillable time logged against the object, in seconds.
nonbillable_subtotal	integer	The total nonbillable time logged against the object and all its children, in seconds.
logged	integer	The total time logged against the object, in seconds. That is, the sum of billable and nonbillable.
logged_subtotal	integer	The total time logged against the object and all its children, in seconds.
charged	decimal	The total cost charged against the object.
charged_subtotal	decimal	The total cost charged against the object, and all its children.
remaining_subtotal	decimal	If object_table is tasks the remaining budget for the task, otherwise the sum of the remaining subtotal of all the object's children's.

The Item Template Object

Example template object:

{
    "code": "260",
    "cost": "0.0000",
    "cost_rate_id": null,
    "description": "Other Revenue GST on Income",
    "expense_type_ledger": "20",
    "id": "8",
    "ledger_id": "20",
    "line_item_ledger": "20",
    "price": "0.0000",
    "price_rate_id": null,
    "quantity": "1.0000",
    "standing": "active",
    "tax_id": "12",
    "title": "Other Revenue GST on Income",
    "type": "service"
}

These are templates for expenses, materials, and services. These templates allow you to easily add items to your budgets. The template object contains:

Field	Type	Description
id	unsigned	A unique identifier for the template.
title	string	The title of the template.
description	string	A description of the template.
price	decimal	The sale price.
type	select	Either 'expense', 'material', or 'service', the type of item described by the template.
code	string	The code given for the template
standing	select	Either 'active' or 'inactive', the standing of the template.
quantity	decimal	The default quantity used with this template.
cost	Decimal	The cost (or purchase price) of the template.
cost_rate_id	unsigned	The id of the cost rate associated with the template (if any).
cost_tax_id	unsigned	The id of the cost tax (or purchase tax) associated with the template.
cost_ledger_id	unsigned	The id of the cost ledger (or purchase ledger) associated with the template.
price	decimal	The sale price of the template.
price_rate_id	unsigned	The id of the price rate associated with the template (if any).
tax_id	unsigned	The id of the sale tax associated with the template.
ledger_id	unsigned	Then id of the sale ledger associated with the template.
line_item_ledger	unsigned or object	The ledger associated with the template.
expense_type_ledger	unsigned or object	Where type is expense, the ledger associated with the template.
cost_tax	unsigned or object	The cost tax (or purchase tax) associated with the template.
cost_ledger	unsigned or object	The cost ledger (or purchase ledger) associated with the template.

The Material Object

Example material object:

{
    "against_id": "201",
    "against_type": "milestone",
    "budget_item_template": "0",
    "budget_item_template_id": "0",
    "cost": "24.0000",
    "date_created": "1457523796",
    "id": "10",
    "material_item_ledger": "0",
    "material_item_ledger_id": null,
    "ordering": "0",
    "price": "0.9900",
    "quantity": "1.0000",
    "tax_id": null,
    "title": "Design Tools",
    "contract_period_id": null,
}

These describe instances of material templates as items on a budget. These contain the following:

Field	Type	Description
id	unsigned	A unique identifier for the material.
title	string	A title for the material.
against_type	string	The type of object the material has be added against.
against_id	unsigned	The id of the object the material has been added against.
quantity	decimal	The quantity of the material added.
cost	decimal	The cost (or purchase price) of the material.
price	decimal	The sale price of the material
date_created	unix ts	The date the material was created.
material_ledger_id	unsigned	The unique identifier of the ledger used by the material.
material_template_id	unsigned	The unique identifier of the item template the material is based off.
tax_id	unsigned	The unique identifier of the tax on the material.
material_ledger	unsigned or object	The ledger used by the material.
material_template	unsigned or object	The item template the material is based off.
ordering	unsigned	A number describing the order the material is displayed.
contract_period_id	unsigned	The unique identifier for the contract period the material is linked to.

The Service Object

Example service object:

{
    "against_id": "22",
    "against_type": "contract",
    "budget_item_template": "8",
    "budget_item_template_id": "8",
    "id": "92",
    "service_item_ledger": "20",
    "service_item_ledger_id": "20",
    "tax_id": "12"
}

These describe instances of service templates as items on a budget. These contain the following:

Field	Type	Description
id	unsigned	A unique identifier for the service.
against_type	string	The type of object the service has been added against.
against_id	unsigned	The id of the object the service has been added against.
service_ledger_id	unsigned	The unique identifier of the ledger used by the service.
service_template_id	unsigned	The unique identifier of the template used by the service.
tax_id	unsigned	The unique identifier of the tax used by the service.
service_ledger	unsigned or object	The ledger used by the service.
service_template	unsigned of object	The template used by the service.

Get Object budget

Sample Request:

GET /api/v0/object_budgets/{object_budget_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/object_budgets/{object_budget_id} \
  -H 'authorization: Bearer {access_token}'

GET /object_budgets/{object_budget_id}

This request returns an object budget identified by its object_budget_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the object budget using the _fields parameter.

Handling the Response

The response will be the single object budget with its default fields and any additional fields requested through _fields.

List Object Budgets

Sample Request:

GET /api/v0/object_budgets HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/object_budgets \
  -H 'authorization: Bearer {access_token}'

GET /object_budgets

This request returns a list of object budgets on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the object budget using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name
id
against_id
against_type

Order Filters

This request supports the following order filters:

Filter Name
id

Object Filters

This request supports the following object filters:

Filter Name
against

Handling the Response

The response will be a list of object budgets with their default fields and any additional fields requested through _fields, and displayed according to any pagination requests used.

Count Object Budgets

Sample Request:

GET /api/v0/object_budgets/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/object_budgets/count \
  -H 'authorization: Bearer {access_token}'

GET /object_budgets/count

This request will return a count of object budgets in a list defined by any available searches or filters. With no searches or filters this will be a count of all object budgets on the deployment. This request returns a single field:

Field	Type	Description
count	unsigned	A count of object budgets listed.

List Item Templates

Sample request:

GET /api/v0/object_budgets/templates HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/templates \
  -H 'authorization: Bearer {access_token}' \

GET /object_budgets/templates

This request returns a list of item templates on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the item template object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name	Notes
id
type
standing
ledger_id
cost_ledger_id
cost_tax_id
tax_id

Range Filters

This request supports range filters over the following fields:

Filter Name	Notes
id
price
cost

Order Filters

This request supports the following order filters:

Filter Name	Notes
id
cost
title
price
standing

Empty Filters

This request supports empty filters over the following fields:

Filter Name	Notes
title

Searching

This request supports the _search parameter to search over the following fields:

Field
title
description
code

Handling the Response

The response will be a list of item templates with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

List Materials

Sample request:

GET /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
  -H 'authorization: Bearer {access_token}' \

GET /object_budgets/materials

This request returns a list of materials on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the material object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name	Notes
id
against_id
against_type
material_ledger_id
material_template_id
quantity
cost
price
tax_id
contract_period_id

Date Filters

This request supports date filters over the following fields:

Filter Name	Notes
date_created

Range Filters

This request supports range filters over the following fields:

Filter Name	Notes
id
cost
price
quantity

Order Filters

This request supports the following order filters:

Filter Name	Notes
id
quantity
price
cost
date_created

Searching

This request supports the _search parameter to search over the following fields:

Field
title

Handling the Response

The response will be a list of materials with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

List Services

Sample request:

GET /api/v0/object_budgets/services HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X GET \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/services \
  -H 'authorization: Bearer {access_token}' \

GET/object_budgets/services

This request returns a list of services on the deployment.

Configuring the Response

Pagination

This request supports all the pagination parameters.

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the service object using the _fields parameter.

Basic Filters

This request supports the following basic filters:

Filter Name	Notes
id
against_id
against_type
service_template_id
service_ledger_id
tax_id

Range Filters

This request supports range filters over the following fields:

Filter Name	Notes
id

Object Filters

This request supports the following object filters:

Filter Name	Notes
against

Order Filters

This request supports the following order filters:

Filter Name	Notes
id

Handling the Response

The response will be a list of services with their default fields and any additional fields requested through _fields, and displayed according to any pagination parameters, filters, or searches used.

Update a Material

Sample request:

PUT /api/v0/object_budgets/materials/{material_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

quantity=10
price=20

curl -X PUT \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/materials/{material_id} \
  -H 'authorization: Bearer {access_token}' \
  -d 'quantity=10'
  -d 'price=20'

PUT /object_budgets/materials/{material_id}

This request updates and returns the material with the given material_id

Configuring the Response

The following fields may be used to update the material:

Field Name	Notes
title
quantity
price
cost
template_id

Configuring the Response

This request supports requesting additional fields and linked objects from the material object using the _fields parameter.

Handling the Response

The response will be the update material with its default fields and any additional fields requested through_fields.

Create a Material

Sample request:

POST /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

authorization: Bearer {access_token}
against_type=contract_period
against_id=123
title=Shovels for digging
quantity=12
cost=10
price=2
template_id=4

curl -X POST \
  https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
  -H 'authorization: Bearer {access_token}' \
  -d 'against_type=contract_period' \
  -d 'against_id=123' \
  -d 'title=Shovels for digging' \
  -d 'quantity=12' \
  -d 'cost=10' \
  -d 'price=2' \
  -d 'template_id=4'

POST /object_budgets/materials

This request creates and returns a material.

Configuring the Response

The following fields may be set when creating the material:

Field Name	Notes
against_type	Supports: 'job', 'issue', 'milestone', 'contract_period'
against_id
title
quantity
price
cost
template_id

Handling the Response

The response will be the newly created material with its default fields and any additional fields requested through_fields.

Object Schedules

An object schedule is a schedule against a specific object. For example, the schedule on a given task.

The Object Schedule

Sample JSON object:

{
  "date_planned_due": "1362618000",
  "against_id": "24",
  "date_planned_start": "1362358800",
  "id": "113",
  "against_type": "task"
}

The object schedule budget contains the following

Field	Type	Description
id	unsigned	A unique identifier for the object schedule.
against_id	unsigned	The unique identifier of the object the schedule is against.
against_type	string	The type of object the schedule is against.
date_planned_start	unix ts	The planned start date.
date_planned_due	unix ts	The planned due date.
date_predicted_start	unix ts	The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations.
date_predicted_end	unix ts	The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations.
date_commenced	unix ts	The actual commenced date.
date_completed	unix ts	The actual completed date.
date_user_estimated_start	unix ts	The date the assignee has scheduled to start the work.
date_user_estimated_due	unix ts	The date the assignee has scheduled to complete the work.
date_targeted_start	unix ts	The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations.
date_targeted_due	unix ts	The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations.
date_fixed_start	unix ts	The fixed start date.
date_fixed_due	unix ts	The fixed deadline for the due date.

There are no endpoints associated with this object.

Payments

Resource URI
/api/v0/payments

Payments made, for example against an invoice, are stored under the payments object through the API. Attached to these payments are methods, receipts, and the currency used.

The Payment Object (Beta)

Sample payment object:

{
    "payment_method": "2",
    "receipt_id": "28945",
    "id": "30507",
    "currency_id": "0",
    "direction": "credit",
    "created_by_staff_id": "1055",
    "method_id": "2",
    "amount": "79.00",
    "against_id": "31347",
    "date_created": "1496887498",
    "payment_currency": "0",
    "against_type": "account_invoice",
    "payment_receipt": "28945"
}

The payment object contains the following:

Field	Type	Description
id	unsigned	The unique identifier of the payment.
receipt_id	unsigned	The unique identifer of the receipt associated with the payment.
amount	decimal	The amount paid through the payment.
currency_id	unsigned	The unique identifier of the currency used.
method_id	unsigned	The unique identifier of the payment method.
against_id	unsigned	The unique identifier of the object the payment is against.
against_type	string	The type of object the payment is against.
date_created	unix ts	The date the payment was created.
created_by_staff_id	unsigned	The unique identifier of the staff member who entered the payment.
direction	select	Either "debit" or "credit", defaults to "credit".
payment_currency	unsigned or object	The currency used for the payment.
payment_method	unsigned or object	The method of the payment.
payment_receipt	unsigned or objects	The receipt for the payment.

The Payment Receipt Object (Beta)

Sample receipt object:

{
    "owner_type": "staff",
    "owner_id": "1055",
    "id": "28945",
    "affiliation_id": "152348",
    "amount": "79.00"
}

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:

• Affiliations
• Companies
• Contacts
• Contracts
• Invoices
• Issues
• Jobs
• Milestones
• Prospects
• Staff

The Profile Field Object

Example profile field:

{  
  "link_type": "company",
  "required": "no",
  "parent_id": "0",
  "description": "These are the companies opening hours in the form \"HH-HH\", use 24h time.",
  "id": "12",
  "lookup_type": null,
  "confidential": "no",
  "field_name": "Opening Hours",
  "restrictions": "all",
  "field_type": "text",
  "exported": "no"
}

These are objects describing the custom fields on the deployment, they contain the following:

Field	Type	Description
id	unsigned	A unique identifier for the profile field.
field_name	string	A name for the profile field.
field_type	select	The type of the profile field. This can be "text", "integer", "decimal", "date", "date_time", "currency", " lookup", "structure", "select", "multi_select", or "hyperlink".
parent_id	unsigned	The unique identifier of the parent profile field. If there is no parent this has a value of "0".
link_type	string	The type of object this profile field is against. For example "contact".
required	select	Either "yes" or "no", whether this profile field is required for the object it is against.
restrictions	select	Who is able to edit the value of this field. May be one of "all", "edit", "process", "admin". For example, if set to "process", only users with "process" permission for custom fields will be able to edit this field. See the support documentation for information on setting permissions.
exported	select	Either "yes" or "no", whether this profile field will be included when you export the against object.
lookup_type	string	When field_type is "lookup", this will contain the lookup type, e.g. "company".
options	array	When field_type is either "select" or "multi_select" this will contain the possible values.
confidential	select	Either "yes" or "no", whether this is a confidential profile field. These are profile fields viewable only within confidential relationships, see the support documentation for more information.
description	string	A description of the profile field.

The Profile Value Object

Example profile value object:

{
  "value_type": null,
  "id": "128",
  "field_type": "multi_select",
  "value": "one, two",
  "values": ["one", "two"],
  "date_modified": "1495669367",
  "field_name": "Implementation Phases",
  "field_id": "12",
  "modified_by": "14",
  "link_type": "issues",
  "link_id": "45"
}

These are objects describing a value of a given profile field, identified by the field_id, they contain the following:

Field	Type	Description
id	unsigned	A unique identifier for the profile field value.
field_type	string	The profile field type for this value, see the profile field object for possible values.
field_name	string	The name for the profile field.
value_type	string	For fields of type lookup this is the type of the lookup object. For example "company", "contact". Otherwise it is null.
value	dynamic	The value of the profile field. The type will change according to the field_type, for example if the field type is "date" this will be a unix ts. If it's a "multi_select" this will be all values joined by a comma. e.g, "one, two" for ["one", "two"]
values*	array	When the field type is "multi_select", this will contain an array of the selected values. e.g, ["one", "two"]
date_modified	unix ts	The date this profile field value was last modified.
modified_by	unsigned or object	The staff member who last modified this profile field value.
field_id	unsigned	The unique identifier of the profile field this value is for.
link_type	string	The object the profile value was created against.
link_id	unsigned	The unique identifier of the object the profile value is against.

^* The values field is only returned when the field_type is "multi_select". When it's "multi_select", it's returned by default.

List Profile Fields

Sample Request:

GET /api/v0/{issues}/profiles/fields HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/issues/profiles/fields \
  -H 'authorization: Bearer {access_token}'

GET /{object}/profiles/fields

This request returns a list of profile fields available for the given object.

Configuring the Response

This request supports requesting additional fields and linked objects from the profile field object using the _fields parameter.

Handling the Response

This response will be a list of profile fields with their default fields, and any additional fields requested through _fields.

List Object Profile Values

Sample Request:

GET /api/v0/issues/{issue_id}/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \ 
 https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/profiles/values \
  -H 'authorization: Bearer {access_token}'

GET /{object}/{object_id}/profiles/values

This request returns a list of profile values for the given object of identified by object_id.

Configuring the Response

This request supports requesting additional fields and linked objects from the profile value object using the _fields parameter.

Handling the Response

This response will be a list of profile values with their default fields, and any additional fields requested through _fields.

List Profile Values

Sample Request:

GET /api/v0/issues/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}

curl -X get \
 https://{deployment}.api.accelo.com/api/v0/issues/profiles/values \
  -H 'authorization: Bearer {access_token}'

GET /{object}/profiles/values

This request returns a list of profile values for the given object.

Configuring the Response

Pagination

This request supports all of the pagination parameters

Additional Fields and Linked Objects

This request supports requesting additional fields and linked objects from the profile value object using the _fields parameter.

Basic Filter

This request supports basic filters over the following fields:

Filter Name
unified
field_id
link_id
link_type

Order Filters

This request supports order filters over the following fields:

Filter Name
field_id
link_id
link_type
value_type
date_modified

Range Filters

This request supports range filters over the following fields:

Filter Name
field_id
link_id

Searching

This request supports the _search parameter to search over the following fields:

Filter Name
title

Update a Profile Value

Example, a business has changed its opening hours:

curl -X put \
  https://{deployment}.api.accelo.com/api/v0/companies/{company_id}/profiles/values/128 \
  -H 'authorization: Bearer {access_token}' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -d 'value=09-18'

PUT /{object}/{object_id}/profiles/values/{profile_value_id}

This request updates and returns a profile value, specified by its profile_value_id, of a particular object, specified by its object_id, of a particular type, specified by object.

Configuring the Profile Value

This request updates the value of a profile value, since this object is dynamic the field we send will depend on the type of value:

Field Name	Type	Description
value_int	int	If field_type is "integer", update the value with this integer.
value_date	string	If field_type is "date", update the value with this string. This field supports values as both unix timestamps and in ISO8601 form, for ease of readability we recommend ISO8601.
value_id	integer	If field_type is "lookup", update the value with this integer, representing an object id.
value_type	string	If field_type is "lookup", update the value_type with this string.
value	string	If field_type is none of the above, update the value with this string.

Configuring the Response

This request supports requesting additional fields and linked objects from the profile value object using the _fields parameter.

Handling the Response

The response will be the single, updated profile value with its default fields, and any additional fields requested through _fields.

Create a Profile Value

Example, a company has give us their business h