Introduction
Welcome to Accelo's Public REST API documentation. Here you will find resources and information to help you use the API.
Developer Forum - Connect with other developers on our developer forum. Use this space to ask any questions and report errors in the documentation.
Registering your Application
Before doing anything, you will need to register your application with Accelo. This is done from your deployment under "Configuration" → "API" → "Register Application". Accelo currently offers three types of applications:
- 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.
Cipher Suites
In order to maintain security for Accelo and our customers, we may need to stop using old cipher suites; this could cause problems for users utilising older SSL/TLS libraries. Before doing so we will ensure that this will not affect the majority of our users, and will work with those that would be impacted.
See the following documentation for technical details, as of 2023 we are using ELBSecurityPolicy-FS-1-2-Res-2020-10
.
Response and Request Structure
Sample request to return a list of staff as XML:
GET https://{deployment}.api.accelo.com/api/v0/staff.xml
By default, all resource requests return JSON (application/json)
. You may also request the response in XML or YAML by
either setting the Accept-Type
header to text/xml
or text/x-yaml
, or by appending the extension type to the end of
the request resource.
Sample response with no suppression:
{
"meta" : {
"more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok",
"status" : "ok",
"message" : "Everything executed as expected."
},
"response" : { "..." }
}
Sample failed response, here we requested a company by an id that doesn't exist:
{
"response": null,
"meta": {
"message": "The request could not be interpreted. This can be caused by missing or invalid data. Please ensure that the resource you are requesting actually exists.",
"more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#invalid_request",
"status": "invalid_request"
}
}
The Meta Object
Each request made will return two objects, a meta object, and a response object. The response object contains the requested response data. The meta object contains the following:
Field Name | Description |
---|---|
status | A string representing the result of the request. |
message | An explanation of the status |
more_info | A URL where more information regarding the current status may be found. |
response code | HTTP status. Only visible when suppressing http status with _suppress_http_status=yes . See here for a list of possible response codes. |
Sample response with _suppress_message=yes and _suppress_http_status=yes
{
"meta" : {
"status" : "ok",
"response_code" : 200
},
"response" : { "..." }
}
The following parameters may be used to suppress parts, or all, of the meta response:
Name | Description |
---|---|
_suppress_message | Suppresses message and more_info . |
_suppress_http_status | Forces HTTP status to 200 and stores the actual status in response_code |
_suppress_meta | Suppresses all meta data. This is useful if you wish to purely utilize HTTP headers. |
They make take values of either "1" or "yes", for example to suppress all meta we could use _suppress_meta=yes
or _suppress_meta=1
.
Default and Required Fields
A resource will only return a small number of fields by default, these fields will be in bold in the resource's table of fields and linked objects. Similarly, POST request will generally require values for some fields, these fields will be in bold within the endpoint's description.
The following parameter may be used to hide the default fields that would be returned in the response:
Name | Description |
---|---|
_hide_defaults | Hides the default fields from the response. This is useful to reduce the size of the payload to just the fields you need. |
Overriding the Request Method
We understand that certain types of requests are not always available to the client. In response to this we allow you to
override the request method using the _method
parameter, this can take one of four values:
Value | Description |
---|---|
get | Override the request type to be GET. |
put | Override the request type to be PUT. |
post | Override the request type to be POST. |
delete | Override the request type to be DELETE. |
For example, each of the following deletes the company with id 10:
DELETE /companies/10
GET /companies/10?_method=delete
POST /companies/10?_method=delete
JSON Content Types
Requests may also be sent as JSON. This can greatly simplify the client side implementation as it offers filters and fields that translate well to programmatic structures. This may also be necessary when you wish to search or filter using non-alphanumeric characters e.g "@", "." or special or accented characters e.g. "à ", "ç", "ö".
Parsing _fields as JSON
Translating "_fields" from query to json, query:
_fields=status(color),username,company(_ALL)
Equivalent JSON "_fields" object:
"_fields": "status(color), username, company(_ALL)"
When sending JSON data with your request, the "_fields"
key should hold a string of the desired fields and linked
objects, separated by a comma. For example, the query _fields=status
would be equivalent to including "_fields":
"status"
in the JSON body. The same method is used to request additional objects and their fields as for queries, the
"_ALL" value also works as for queries..
Parsing _filters as JSON
Example, converting a query list of filters to JSON:
_filters=id(12,13),date_created_after(1498175480), rate_charged_greater_than(10),order_by_desc(status)
Equivalent JSON "_filters" object
"_filters": {
"id": [12, 13],
"date_created_after": [1498175480],
"rate_charged_greater_than": [10],
"order_by_desc": ["status"]
}
Filters are sent through JSON bodies using the _filters
key, which hold a hash of keys (filter names) and values (the
values to be filtered). For example applying the filter _filters=id(12,13),status(3,1)
would be equivalent to
including in the value of "_filters"
the pair "id": [12,13], "status": [3,1]
. This basic key-value pairing works for
all filters outside of object filters.
Example object filter query and json. Here we are using the against and referrer filters of issues.
_filters=against(company(312,466),job(998)),referrer(prospect(42))
{
"_filters": {
"against": [{
"company": [312,466],
"job": [998],
}],
"referrer": [{
"prospect": [42]
}]
}
}
There are two ways to generate object filters though JSON bodies. The first is by simply building them from the
corresponding basic filters, for example the filter against(company(32))
is equivalent to
against_type(company),against_id(32)
, which can be parsed into JSON as shown above. The other is to build a nested
JSON object of the form "<object_filter>": [{ "<object_type>": ["<object id>"] }]
.
Parsing _search as JSON
Parsing a search through _search
in JSON is simply a matter of assigning a string to be searched to the key
"_search". For example searching for a contact with name "Hubert Farnsworth" may be done in a query through
_search=(Hubert+Farnsworth)
, or in a JSON request by adding "_search": "Hubert Farnsworth"
.
Rate Limiting
Meta object for a 429 response:
{
"message": "Rate limit exceeded for planet-express.api.accelo.com",
"status": "too_many_requests",
"more_info": "api.accelo.com/docs/#rate-limiting"
}
Requests to the API will be limited to 5000/hour per deployment, this is to protect the quality of the service offered
by the API. Authentication or authorization requests (those made to /oauth2
endpoints) will not be limited and will
not be counted against this limit. Requests made after exceeding this limit will return a 429
error.
The following headers have also been added to track usage rates:
Header | Type | Description |
---|---|---|
X-RateLimit-Reset | unix ts | The time at which the current rate limit window resets. |
X-RateLimit-Remaining | int | Number of requests remaining in the current rate limit window. |
X-RateLimit-Limit | int | Maximum number of requests allowed in each rate limit window. |
Configuring Responses
There are several tools available to configure the response from the API:
Pagination
Accelo has the capacity to hold tens of thousands of resources. So, without being careful we could have a hard time returning the required resources. Thankfully, the API also supports pagination to help us work through a resource list. The available parameters are:
Argument | Description |
---|---|
_page | The page of result to retrieve. For example to retrieve the first page you would use _page=0 , and for the 5th page, _page=4 . The default is 0 |
_limit | The max number of resources to return. When combined with _page , this is the number of requests returned per page. Default is 10, max is 100 |
_offset | The resource to return from. Default is 0, this will be overridden if _page is set. |
Requesting Additional Fields and Linked Objects
Requesting companies with the "website" and "phone" fields, as well as the linked "postal_address" object and its "city" field:
GET /companies HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_fields=website,phone,postal_address(city)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/companies \
-H 'authorization: Bearer {access_token}' \
-d '_fields=website,phone,postal_address(city)'
By default, each resource returns only the minimal required fields, these are displayed in the table describing the
object. To request additional fields we can use the _fields
parameter. For example, the company object
has additional fields website
and phone
, to display these in a request response we would add
_fields=website,phone
to our request. The keyword _ALL
may be used to return all optional fields.
For linked objects (those marked as "unsigned or object") the _fields
parameter may be used to request the linked
object by adding parenthesis to the field. For example, the company object contains a link to an address
object under the postal_address
field, to return this object with its default fields we add
_fields=postal_address()
. Requesting optional fields from a linked object is done by including the fields within these
parenthesis, for example if we wanted the city
field from within the postal_address
we would use
_fields=postal_address(city)
, here the _ALL
keyword would return all optional fields from the postal_address
object. If a linked object is request without the parenthesis, e.g. _fields=postal_address
then the unique identifier
for the object will be returned. This process also supports nesting, for example if we wish to return the country
object from within the postal_address
object here we would use _fields=postal_address(country())
.
Breadcrumbs
Breadcrumbs give identifying information on the parent object(s) of the object requested. They may be requested through
_fields=breadcrumbs
. Requesting breadcrumbs will return an array of breadcrumb objects, these contain the following
fields:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the parent object. |
table | string | The type of the parent object. |
title | string | The title of the parent object. |
For example if a job is created against a company, then the job will have a single breadcrumb containing information on the company. If a task is then created against that job the task will have two breadcrumbs, one identifying the job and another identifying the company. Breadcrumbs are always displayed in ascending order, so the direct parent will be displayed first, then its parent, an so on.
Searching
Some requests support the use of the _search
parameter to search through certain fields and display only results
satisfying the search. For example, the GET /contacts
request supports this filter over the firstname
,
surname
,mobile
and email
, so _search=kurt+wagner
would display any contacts where "kurt" and "wagner" is found
in the first name, surname, mobile or email. Another available search method is through the
search filter.
Filtering
Most API endpoints support a _filters
parameter that allows you to filter the response. The supported filters will be
listed for each endpoint, in general there are several types of filters:
Filters may take any number of arguments, new arguments may be separated by a comma. Appending _not
to any filter will
return results that DO NOT satisfy the filter, e.g. standing_not(active)
would return only results whose standing is
not 'active'. Any number of filters may be combined in a single request.
For example if we wanted to find all activities that were NOT created against a job we would use
_filters=engagement_table_not(job)
.
Basic Filters
Example request, filter activities by those owned by a staff member:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=owner_type(staff)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=owner_type(staff)'
These simply filter resources with certain fields for certain values, generally they are requested simply by
<field>(<value>)
. For examples, activities support basic filters on the owner_type
and owner_id
fields, so for example if we wanted to search for activities owned by the staff member with id 17 we would use
_filters=owner_type(staff),owner_id(17)
.
Date Filters
Filter activities by those created after 2017-03-22 00:00:00 (UTC)
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=date_created_after(1490140800)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=date_created_after(1490140800)'
Many endpoints contain fields representing dates, such as date_created
under activities. Date fields
are expressed as unix timestamps (for brevity we will just use the shorter "unix ts"). The API supports filtering for many
of these "date_fields" through the following filters:
Filter | Description |
---|---|
<date_field>_before(<date>) | Filter by results whose value of <date_field> is less than the <date> value (expressed as a unix ts). |
<date_fields>_after(<date>) | Filter by results whose value of <date_field> is greater than the <date> value (expressed as a unix ts). |
Range Filters
Filter activities with and id greater than 17:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=id_greater_than(17)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=id_greater_than(17)'
These are similar to Date Filters except they operate on non-date fields. For a given "field" there are four range filters defined:
Filter | Description |
---|---|
<field_name>_greater_than(<value>) | Filter by results that have a value for <field> greater than <value> . |
<field_name>_less_than(<value>) | Filter by results that have a value for <field_name> less than <value> . |
<field_name>_greater_than_or_equal(<value>) | Filter by results that have a value for <field_name> greater than or equal to <value> . |
<field_name>_less_than_or_equal(<value>) | Filter by results that have a value for <field_name> less than or equal to <value> . |
Order Filters
Filter activities by descending order of id:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=order_by_desc(id)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=order_by_desc(id)'
These change of the order in which the response is displayed, they are not strictly filters in that they will not
exclude any objects from the response, but they are called using _filters
so we shall list them here. By default a
response will be sorted in ascending order of the id
of the objects requested. For a given "field" there are two order
filters defined:
Filter | Description |
---|---|
order_by_asc(<field>) | Order the results in ascending value of <field> . |
order_by_desc(<field>) | Order the results in descending value of <field> . |
Empty Filters
Filter contracts with an empty date_expires:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=empty(date_expires)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=empty(date_expires)'
These filter resources which have no value for the given field, the format is empty(<field_name>)
. For example, the
date_expires
field for contract supports this filter, so _filters=empty(date_expires)
would display
all contracts without an expiry date.
Object Filters
Filter activities owned by "staff/17"
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=owner(staff(17))
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=owner(staff(17))'
These are an extension of basic filters that allow for more compact filtering over entire objects, they take both an
object and an id as arguments. For example, activities support object filtering on the "owner" object. As
we saw previously we could specify activities by a certain staff member using _filters=owner_type(staff),owner_id(17)
we may achieve the same using the owner
object filter on activities, _filters=owner(staff(17))
.
As with other filters, additional arguments for both fields may be added and separated by a comma, for example
_filters=owner(staff(17,13),affiliation(22)
would show all activities owned by the staff with id 17 or 13, or owned by
the affiliation with id 22.
Search Filters
Filter contacts by "kurt wagner"
GET /contacts HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=search(kurt wagner)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/contacts \
-H 'authorization: Bearer {access_token}' \
-d '_filters=search(kurt wagner)'
This filter is similar to the searching parameter and supports the same requests available to that
parameter. Automatically this filter will append an AND
between multiple search requirements. Search terms are
separated by ,
or any space. Some characters e.g. (,)
and ,
will be ignored using this filter whereas these are
accepted by _search
. It will search through the available fields and only return results that satisfy the search. This
filter expands on the searching parameter by allowing the use of _OR
. For example, the GET /contacts
request
supports search over firstname
, surname
, mobile
, and email
so if we wanted to find contacts with "kurt" or
"wagner" in any of the listed fields we could use _filters=_OR(search(kurt),search(wagner))
.
Combining Filters
Filter by activities owned by "staff/17" and created after 2017-03-22 00:00:00 (UTC) and not against a job
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=owner(staff(17)),date_created_after(1490140800),against_type_not(job)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=owner(staff(17)),date_created_after(1490140800),against_type_not(job)'
Any combination of filters may be used to filter response, this is achieved by separating them with a comma. More
flexible filter combinations may be achieved through the _AND
and _OR
keywords. For example, if we wanted to
search for activities owned by the specific staff OR created after a given date we could use
_filters=_OR(staff(17),date_created_after(1490140800))
. One _AND
can be nested inside an _OR
for greater filtering
flexibility. For example, if we wanted all activities created by the given staff member, or after a given date and
before another date we could use
_filters=_OR(staff(17),_AND(date_created_after(1490140800),date_created_before(1500140800)))
. Nested _OR
keywords are
not supported.
If the same filter is used more than once in a combination only the final instance of the filter will be used. For
example _filters=_OR(staff(10),staff(11))
will just filter by staff with id 11, here the simple filter
_filters=staff(10,11)
should be used.
Only a single _AND
can be defined inside the filters param.
Authentication
Accelo's API uses the OAuth 2.0 protocol and provides routines that cover web, service and installed application's authorization and authentication. It supports authorization code grants and client credential grants as necessary between the available API applications.
Please read OAuth 2.0's final version specification for more information on the protocol.
Generally, accessing an Accelo resource protected by OAuth2.0 takes three steps:
1. Authorize
2. Acquire token
3. Access resource
Before access to a token is granted authorization is achieved for a limited range of requests using the client_id
and
client_secret
which can be found through your Accelo toolbox and are given upon registering your API. To gain an
access token your application must first be authorized by the end user, once authorized we are able to send a token
request to the OAuth endpoint. We will go through this process for each of the application types support by Accelo.
OAuth2.0 URI
Example OAuth2.0 base URI for planet express:
https://planet-express.api.accelo.com/oauth2/v0
The OAuth2.0 base URI is different to the base URI for Accelo resources, in general this base URI will be found at:
https://{deployment}.api.accelo.com/oauth2/v0
This URI is used to authorize and access tokens.
Scope
For example, to request permission to read all information and write only to companies and contacts:
scope=read(all),write(companies,contacts)
For example, to request permission to read and write to contacts and staff:
scope=write(contacts,staff)
The range of access permissions for a given token is provided by the scope
parameter. Currently, the following scopes
are available:
read({resource})
- Read only access to data related to the {resource}
object, which may be any resource. read(all)
gives read only access to all data the user owns or has access to. To provide read access to any collection of
resources, {resource_1},{resource_2},...
you can simply concatenate, read({resource_1},{resource_2},...)
write({resource})
- Read and write access related to the resource specified. write(all)
gives read and write access
to all data the user owns or has access to. As for read access, write access for a collection of resources is given via
concatenation.
The scope
field is optional in all requests that use it, and defaults to read(all)
.
OAUTH2.0 Endpoints
There are three endpoints off the OAUTH2.0 URI, they are /authorize
, /token
, and revoke
. These endpoints support
the following requests:
Request | Description |
---|---|
GET | POST /authorize | Request authorization from a user. |
POST /token | Request an access token using a grant code or refresh token. |
POST /revoke | Revoke and access token. |
We will cover handling the responses on a case-by-case basis for each application type, as the responses vary between them. Note that authorization and token requests should always be encoded, for the purposes of demonstration, our examples are not.
Redirect URIs
Redirect URIs are used in the authorization of web and installed applications, these are the URIs to which the end- user's response to authentication requests are sent. Redirect URIs for an application may be registered through the api control panel. You may register many callback URIs for a web application, but only one for an installed application.
Authentication Without a Token
Authenticating an application before you have been granted an access token is done
using HTTP Basic authorization. The format is {client_id}:{client_secret}
encoded in base64.
For example if your client id is 5ba17c78ao@planet-express.accelo.com
and your client
secret is zTfFgiyQCVDFk-1EtUerVLRk1is6LgL6
then you would authorize with the header:
Authorization: Basic NWJhMTdjNzhhb0BwbGFuZXQtZXhwcmVzcy5hY2NlbG8uY29tOnpUZkZnaXlRQ1ZERmstMUV0VWVyVkxSazFpczZMZ0w2
.
For convenience we will just write {client_credentials}
Service Applications
These are not run from the end user's deployment, and hence do not need to be authorized by the user, so authorization and accessing a token is are combined into one step for these application.
Token Acquisition for Service Applications
Example token request for the Planet Express deployment, here
{client_credentials}
isclient_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 |
---|---|---|
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. |
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:
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. |
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:
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. |
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 | |
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 | |
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 | |
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 | |
position | |
status_id | Must point to a valid status. |
standing | |
communication | Must be "yes" or "no", whether or not communications, such as updates, newsletters etc. are sent to this affiliation, default "no". |
invoice_method | e.g. "email", "fax" or "postal", the method by which invoices should be sent. |
Configuring the Response
This request supports requesting additional fields and linked objects from the affiliation object
using the _fields
parameter.
Handling the Response
The response will be the single, new, affiliation object, with its default fields and any
additional fields requested through _fields
Delete an Affiliation
DELETE /api/v0/affiliations/{affiliation_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X delete \
https://{deployment}.api.accelo.com/api/v0/affiliations/{affiliation_id} \
-H 'authorization: Bearer {access_token}'
DELETE /affiliations/{affiliation_id}
This request will delete the affiliation identified by its affiliation_id
. This request takes no parameters and return
no resources.
List an Affiliation's Profile Field Values
See the profiles section for a sample request
GET /affiliations/{affiliation_id}/profiles/values
This request returns a list of profile field values of an affiliation,
specified by its affiliation_id
. This is the request
GET/{object}/{object_id}/profiles/values
, where the object is "affiliations" whose id
is {affiliation_id}
.
List Affiliation Profile Field Values
See the profiles section for a sample request
GET /affiliations/profiles/values
This request returns a list of all profile field values on affiliations.
This is the request GET /{object}/profiles/values
, where the object is "affiliations".
List Affiliation Profile Fields
See the profiles section for a sample request
GET /affiliations/profiles/fields
This request returns a list of profile fields available for affiliations.
This is the request GET /{object}/profiles/fields
where the object is "affiliations".
Update a Profile Field Value on an Affiliation
See the profiles section for a sample request
PUT /affiliations/{affiliation_id}/profiles/values/{profile_value_id}
This request updates and returns a profile field value, specified by its profile_value_id
of a particular affiliation, identified by its affiliation_id
. This is the request
PUT/{object}/{object_id}/profiles/values/{profile_value_id}
where the object is
"affiliations", and whose id is {affiliation_id}
.
Set a Profile Field Value on an Affiliation
See the profiles section for a sample request
POST /affiliations/{affiliation_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field,
specified by its profile_field_id
, for an affiliation, specified by its affiliation_id
.
This is the request POST /{object}/{object_id}/profiles/fields/{profile_field_id}
where is object is "affiliations" and whose id is {affiliation_id}
List Available Progressions on an Affiliation
See the progressions section for a sample request
GET /affiliations/{affiliation_id}/progressions
This request returns a list of available progressions for an affiliation
identified by its affiliation_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "affiliations" whose id is {affiliation_id}
Auto Run a Progression on an Affiliation
See the progressions section for a sample request
[PUT | POST] /affiliations/{affiliation_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress the status of an
affiliation, specified by its affiliation_id
. This is the request
[PUT|POST]/{object}/{object_id}/progressions/{progression_id/auto}
where the
object is "affiliations" whose id is {affiliation_id}
.
Assets
Endpoint URI:
/api/v0/assets
Assets are flexible objects within Accelo, they can represent almost any asset or object you want. For example, you may wish to store information on the computers owned by your company, or the prices of advertising media offered by external companies. For more information see the support documentation.
The Asset Object
The asset object contains the following:
Sample JSON asset:
{
"address": "14",
"against_id": "39",
"asset_type_id": "2",
"manager_id": "14",
"id": "2",
"affiliation": "98",
"asset_type": "2",
"title": "Latest Laptop",
"date_created": "1492651877",
"manager": "14",
"affiliation_id": "98",
"standing": "inactive",
"against_type": "company",
"address_id": "14"
}
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier for the asset. |
title | string | The name given to the asset. |
latest_asset_link | object | The most recent asset link made on the asset. |
standing | string | The standing of the asset, see the status object for more information. |
date_created | unix ts | The date the asset was created. |
against_type | string | A string representing the object the endpoint is against. |
against_id | unsigned | The unique identifier of the object the asset is created against. |
asset_type | unsigned or object | The type of the asset. Asset types can be created and edited from your Accelo deployment, see the assets module page for more information. |
asset_type_id | unsigned | The unique identifier given to this asset type. |
affiliation | unsigned or object | The affiliation associated with the asset (if any). |
affiliation_id | unsigned | The unique identifier of the affiliation associated with the asset. |
manager | unsigned or object | The staff assigned to manage the asset (if any). |
manager_id | unsigned | The unique identifier of the staff assigned to manage the asset. |
address | unsigned or object | The physical address associated with this asset (if any). |
address_id | unsigned | The unique identifier of the physical address assigned to the asset. |
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. |
string | The contact's email address. Deprecated as for "mobile". | |
username | string | The contact's Accelo username. |
middlename | string | The contact's middle name. |
title | string | The contact's preferred title. For example "Ms", "Mr", "Dr". |
timezone | string | The contact's timezone. |
date_created | unix ts | The date the contact was added on the Accelo deployment. |
date_modified | unix ts | The date the contact was last modified. |
date_last_interacted | unix ts | The most recent date of interaction with the contact. |
comments | string | Any comments or notes made against the contact. |
default_affiliation | unsigned | The unique identifier of the default affiliation associated with the contact. |
contact_status | unsigned or object | The status of the contact. |
standing | string | The contact's standing, this is part of the status object. For example "active", "potential". |
Get Contact
Sample Request:
GET /api/v0/contacts/{contact_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contacts/{contact_id} \
-H 'authorization: Bearer {access_token}'
GET /contacts
This request returns a single contact, identified by their contact_id
.
Configuring the Request
This request supports requesting additional fields and linked objects from the contact object
using the _fields
parameter.
Handling the Response
The response will contain a single contact object with its default fields, and any additional fields requested through
_fields
.
List Contacts
Sample Request:
GET /api/v0/contacts/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contacts/ \
-H 'authorization: Bearer {access_token}'
GET /contacts
This request returns a list of contacts on the Accelo deployment.
Configuring the Response
Pagination
This request supports all of the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting any extra fields or linked objects from the contacts object
object via the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Field | Notes |
---|---|
id | |
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 | |
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. |
string | As for phone but an email address. Must be a valid email address. |
|
position | string | The contact's position in the associated company. |
communication | string | As in the affiliation object |
invoice_method | string | As in the affiliation object |
Configuring the Response
This request supports requesting additional fields and linked resources from the contact object
using the _fields
parameter.
Handling the Response
This request will return the single new contact, with its default fields and any additional fields requested through
_fields
Deactivate a Contact
Sample Request:
DELETE /api/v0/contacts/{contact_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contacts/{contact_id} \
-H 'authorization: Bearer {access_token}'
-H 'Content-Type: application/x-www-form-urlencoded'
DELETE /contacts/{contact_id}
Equivalent request:
PUT /contact/{contact_id}?standing=inactive
This request sets a contact on the Accelo deployment, identified by its contact_id
, to inactive
. This request does
NOT delete the contact, a user can only be removed from the web deployment, see the support
documentation for information. This request accepts no parameters and only returns the meta
object.
List Addresses Against a Contact
Sample Request:
PUT /api/v0/contacts/{contact_id}/addresses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contacts/{contact_id}/addresses \
-H 'authorization: Bearer {access_token}'
-H 'Content-Type: application/x-www-form-urlencoded'
GET /contacts/{contact_id}/addresses
This is simply the GET /{object}/{object_id}/addresses
request, where {object}
is company and {object_id}
is the {company_id}
.
Create an Address Against a Contact
Sample Request (TODO):
POST /contacts/{contacts_id}/addresses
This request creates and returns an address against a contact specified by its
contact_id
. This is the request POST /{object}/{object_id}/addresses
where
the object is "addresses" whose id is {contact_id}
.
Get a Contact's Status
Sample Request:
GET /contacts/{contact_id}/status
This request returns the status of a contact on the Accelo deployment, identified by their contact_id
.
Configuring the Request
This request supports requesting additional fields and linked objects from the status using the _fields
parameter.
Handling the Response
This request returns a single status with its default fields and any additional fields requested through _fields
.
Get Contact Status
Sample Request:
GET /api/v0/contacts/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contacts/statuses/{status_id} \
-H 'authorization: Bearer {access_token}' \
GET /contacts/statuses/{status_id}
This request returns the contact status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a contact status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Contact Statuses
Sample Request:
GET /api/v0/contacts/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contacts/statuses \
-H 'authorization: Bearer {access_token}'
GET /contacts/statuses
This request returns a list of contact statuses on the deployment.
Configuring the Response
Pagination
This request supports the standard pagination requests.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the contact status object through
the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Count Contact Statuses
Sample Request:
GET /api/v0/contacts/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contacts/statuses/count \
-H 'authorization: Bearer {access_token}' \
GET /contacts/statuses/count
This request will return a count of contact statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all contact statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed contact statuses. |
List Contact Segmentations
Sample Request:
GET /contacts/{contact_id}/segmentations
This request returns a list of segmentations for a contact specified
by its contact_id
. This request supports no parameters and returns a list of segmentations.
List a Contact's Profile Field Values
See the profiles section for a sample request
GET /contacts/{contact_id}/profiles/values
This request returns a list of profile values of a contact,
specified by its contact_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "contacts", and whose id is contact_id
.
List all Profile Field Values on a Contact
See the profiles section for a sample request
GET /contacts/profiles/values
This request returns a list of all profile field values on contacts.
This is the request GET /{object}/profiles/values
, where the object is "contacts".
List Contact Profile Fields
See the profiles section for general usage.
GET /contacts/profiles/fields
This request returns a list of profile fields available for contacts.
Update a Profile Field Value on a Contact
See the profiles section for general usage.
PUT /contacts/{contact_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular contact, specified by its contact_id
.
Set a Contact's Profile Field Value
See the profiles section for a sample request
POST /contacts/{contact_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for a contact, specified by its contact_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "contacts",
and whose value is contact_id
.
List Available Progressions on a Contact
See the progressions section for a sample request
GET /contacts/{contact_id}/progressions
This request returns a list of available progressions for a contact,
specified by its contact_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "contacts" whose id is contact_id
.
Auto Run a Progression on a Contact
See the progressions section for a sample request
PUT|POST /contacts/{contact_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress a contact,
specified by its contact_id
. This is the request
[POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto
where the
object is "contact" whose id is contact_id
.
List a Contact's Resource Collections
See the resources (attachments) section for an example
GET /contacts/{contact_id}/collections
This request returns a list of collections against a contact, specified
by its contact_id
. This is the request GET /{object}/{object_id}/collections
where the object is "contacts" and whose id is {contact_id}
.
Upload a Resource (Attachment) to a Collection on a Contact
See the resources (attachments) section for an example
POST /contacts/{contact_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of a
contact specified by its contact_id
. This is the request
POST/{object}/{object_id}/collections/{collection_id}/resources
where the
object is "contacts" and whose id is {contact_id}
.
Contracts (Retainers)
Resource URI:
/api/v0/contracts
Contracts (also known as retainers) are objects for managing recurring client work, maintenance quotas, or periodic invoicing - such as license fee. A contract is created against a company/client record (that is, an affiliation), and work is tracked against the contract through periods. You can configure your contract to automatically create periods at certain intervals, and invoice up-front for a fixed amount or at the end of the period for the work done. See the support documentation for more information on contracts/retainers.
The contracts model integrates flawlessly with the the issues and jobs modules so that you can even allocate work from those into a contract period. Contracts can also be linked to service items, allowing for easy handling of things like tax codes and ledger codes.
The Contract Object
Example contract:
{
"id": "1",
"date_last_interacted": "1493265142",
"send_invoice": "none",
"job": null,
"against_id": "39",
"against_type": "company",
"type": "1",
"period_template_id": "2",
"date_expires": "1495591200",
"deployment": "1495325400",
"auto_renew": "no",
"title": "A new contract",
"standing": "active",
"manager": "14",
"renew_days": "0",
"date_created": "1493265142",
"date_started": "1493258400",
"company": "39",
"status": "2",
"billable": "98",
"date_period_expires": "1493776800",
"value": "0.00",
"against": "companies/39",
"notes": "This contract was created against a company",
"affiliation": "98",
"staff_bookmarked": "1",
}
The contract object contains the following fields and linked objects:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the contract. |
title | string | A title for the contract. |
period_template_id | unsigned | The unique identifier of the period_template . See the support documentation for information on period templates. |
date_created | unix ts | The date the contract was created on the Accelo deployment. |
date_started | unix ts | The date the contract was started. |
date_expires | unix ts | The date the contract expires. |
date_period_expires | unix ts | The date the current period ends. |
against | string | The API URI for the object the contract is against. For example "contact/94". |
against_id | unsigned | The unique identifier of the object the contract is against. |
against_type | string | The type of object the contract is against. For example "contact". |
value | decimal | The total value of this contract. |
auto_renew | string | Either "yes" or "no", whether the contract auto renews. |
renew_days | string | Number of days before the current period expires to renew. |
send_invoice | string | Type of invoice to be sent on renewal, if any. Can be "none", "email", "fax" or "postal". |
notes | string | Any notes made against the contract. |
staff_bookmarked | bool | Whether the current user has favourited the contract. |
owner_affiliation | unsigned or object | The affiliation the contract is owned by. This replaces the deprecated "affiliation" object, please avoid requesting both objects at once. |
billable_affiliation | unsigned | The unique id for the billable affiliation. |
type | unsigned or object | The type of the contract, contract types may be configured on the deployment. Deprecated, please use contract_type . |
contract_type | unsigned or object | The contract type of the contract. |
manager | unsigned or object | The staff member managing this contract. |
status | unsigned or object | The status of the contract. |
standing | string | The standing of the contract, this is part of the status object. For example "active", "cancelled". |
job | unsigned or object | The job the contract is against, if any. |
company | unsigned or object | The company the contract is against, if any. |
The Contract Period
Example contract period object:
{
"allowance_type": "unlimited_hours",
"budget_type": "pre-paid",
"duration_type": "fixed",
"date_created": "1493265142",
"rate_id": "11",
"date_commenced": "1493258400",
"rollover": "no",
"contract": "contracts/1",
"standing": "opened",
"service_item_id": "1",
"contract_budget": "1",
"id": "1",
"rate_type": "object",
"date_expires": "1493776800",
"contract_id": "1",
"date_closed": null
}
The contract period is a duration of time to track and invoice a contract. The contract_period
object contains the
following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the period. |
date_created | unix ts | The date the period was created. |
date_commenced | unix ts | The date the period commenced. |
date_expires | unix ts | The date the period expires. |
date_closed | unix ts | The date the period was closed. |
budget_type | select | The budget or billing type. May be either "pre-paid" or "post-paid". |
allowance_type | select | The prepaid allowance for the period. May be either "unlimited hours", "fixed hours", or "fixed value". |
rate_type | select | Whether activities linked to the period should use the rate defined by the object they are against, or the rate defined by the contract. May be either "contract" or "object". |
rate_id | unsigned | The unique identifier of the rate object of the period. |
service_item_id | unsigned | The unique identifier of the service item linked to the contract. See the support documentation for information on service items. |
duration_type | select | The type of the period duration. May be either "fixed" or "unlimited". |
rollover | select | Whether an expiring period should roll unused allowance into the next period. Either "yes" or "no". |
standing | string | The standing of the period. For example "opened", "closed". |
contract | string | The API URI of the contract the period belongs to. |
contract_id | unsigned | The unique identifier of the contract the period belongs to. |
contract_budget | unsigned or object | The id or object of the budget assigned to the period. |
The Contract Type
Example contract type object:
{
"period_template_id": "1",
"title": "Default",
"auto_renew": "no",
"parent": "0",
"renew_days": "0",
"id": "1"
}
For ease of use and automation, different contract templates can be set up on the Accelo deployment. These templates are covered by the contract type which contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the contract type. |
title | string | A title for the contract type. |
parent | unsigned | The unique identifier for the parent contract. Value is "0" if there is no parent. |
standing | string | The standing of the contract upon creation. For example "pending", "active". |
ordering | unsigned | The ordering of the contract type on the Accelo deployment. |
auto_renew | string | As in the contracts object. |
renew_days | string | As in the contracts object. |
send_invoice | string | As in the contracts object. |
period_template_id | unsigned | As in the contracts object. |
This object does not support the _ALL
argument under _fields
.
Note: The type
field is deprecated, please request the contract type through the contract_type
field,
which contains the following additional fields:
Field | Type | Description |
---|---|---|
invoice_template_id | unsigned | The unique identifier of the invoice template used for this contract type. |
service_tax_id | unsigned | The unique identifier of the service tax used for this contract type. |
service_tax_ledger_id | unsigned | The unique identifier of the service tax ledger used for this contract type. |
auto_complete_task | boolean | Either "1" or "0" whether this contract type is set to autocomplete tasks. |
The Contract Budget
Example contract budget object:
{
"id": "1",
"value": "25.00",
"product_charged": "30.00",
"time_charged": "24.00",
"time": "1000",
"against_type": "contract_period",
"against_id": "10"
}
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the contract budget. |
value | string | The financial value of the budget (sum of all values within budget). This requires full financial access. |
product_charged | string | The financial value charged for the budget's product(s) (sum of all product charges within budget). This requires full financial access. |
time_charged | string | The financial value charged for the budget's time (sum of all time charges within budget). This requires full financial access. |
time | unsigned | The time spent in seconds on the budget (sum of all time within budget). |
against_type | string | The type of object this budget is against. e.g, "contract_period". |
against_id | unsigned | The id of the object this budget is against. |
Get Contract
Sample Request:
GET /api/v0/contracts/{contract_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}
-H 'authorization: Bearer {access_token}'
GET /contracts/{contract_id}
This request returns a single contract from the Accelo deployment, specified by its contract_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the contract object
using the _fields
parameter. This request also supports breadcrumbs
.
Handling the Response
The response will be a single contract object, with its default fields and any additional fields
requested by _fields
.
List Contracts
Sample Request:
GET /api/v0/contracts HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts
-H 'authorization: Bearer {access_token}'
GET /contracts
This request returns a list of contracts from the Accelo deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting any extra fields or linked objects from the contracts object
via the _fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
type | Filter against the type_id . Deprecated, please use contract_type . |
contract_type | Filter against the contract_type_id . |
manager | Filter against the staff_id of the manager. |
billable_affiliation | Filter against the affiliation_id of the billable affiliation. |
owner_affiliation | Filter against the affiliation_id of the owner affiliation. |
status | Filter against the status_id . |
against_id | |
against_type | |
is_related_to_issue | Filter contracts related to an issue (or list of issues), identified by its issue_id . |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_created |
date_started |
date_expired |
date_period_expires |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
id | |
date_created | |
date_started | |
date_expires | |
date_period_expires | |
standing | Order by the string field standing . |
status | Order by the status_id |
title | |
date_last_interacted |
Range Filters
this request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
type | Range by type_id . Deprecated, please use contract_type . |
contract_type | Range by the contract_type_id . |
billable | Range by the company_id of the billable company. |
affiliation | Range by affiliation_id . |
manager | Range by the staff_id of the manager of the contract. |
against_id | |
status | Range by status_id . |
value | |
renew_days | |
period_template | Range by period_template_id . |
service_tax | Range by service_tax_id from the service item linked to the contract, if any. |
service_ledger | Rage by service_ledger_id .from the service item linked to the contract, if any. |
Object Filters
This request supports the following object filters:
Filter Name | Description |
---|---|
against | Filter by contracts against these objects. |
Searching
This request supports the use of the _search
parameter over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of contract objects containing the default fields and any additional
field requested by _fields
, and displayed according to any pagination parameters or filters used.
Count Contracts
Sample Request:
GET /api/v0/contracts/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/count
-H 'authorization: Bearer {access_token}'
GET /contracts/count
This request will return a count of contracts in a list defined by any available searches or filters. With no searches or filters this will be a count of all contracts on the deployment. This request does not return a response object, just a single value:
Field | Type | Description |
---|---|---|
response | unsigned | A count of the listed contracts. |
Get Contract Period
Sample Request:
GET /api/v0/contracts/{contract_id}/periods/{period_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}/periods/{period_id}
-H 'authorization: Bearer {access_token}'
GET /contracts/periods/{period_id}
This request returns a single contract period object from the Accelo deployment.
Configuring the Response
This request supports requesting additional fields and linked objects from the contract period object using the _fields
parameter. This request also supports
breadcrumbs.
Handling the Response
This response will be a single contract period object, with its default fields and any additional fields requested via
_fields
.
List Contract Periods
Sample Request:
GET /api/v0/contracts/{contract_id}/periods HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}/periods
-H 'authorization: Bearer {access_token}'
GET /contracts/{contract_id}/periods
This request returns a list of contract periods for a contract, specified by its contract_id
.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting extra fields or linked objects from the contract_period object
using the _fields
parameter. This request also supports
breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
budget_type | |
allowance_type | |
rate_type | |
rate | Filter over the rate_id . |
service_item | Filter over the service_item_id . |
duration_type | |
rollover | |
standing | |
contract | Filter over the contract_id . |
contract_budget | Filter by the id of the budget assigned to the period. |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_created |
date_commenced |
date_expires |
date_closed |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
contract | Range over the contract_id . |
rate | Range over the rate_id . |
rate_charged | Range over the rate at which billable time is charged for activities against this contract. |
budget | Range over the budget_id . |
service_item | Range over the service_item_id . |
Order Filters
This request supports order filtering over the following fields:
Filter Name |
---|
id |
date_created |
date_commenced |
date_expires |
date_closed |
Handling the Response
The response will be a list of contract objects containing the default fields and any additional
fields requested by _fields
, and displayed according to any pagination parameters or filters used.
List Contract Types
Sample Request:
GET /api/v0/contracts/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/types
-H 'authorization: Bearer {access_token}'
GET /contracts/types
This request returns a list of contract types on the Accelo deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the contract type object
using the _fields
parameter.
Basic filters
This request supports basic filters over the following fields:
Field |
---|
id |
standing |
auto_renew |
parent |
send_invoice |
period_template_id |
invoice_template_id |
service_tax_id |
service_ledger_id |
Order Filters
This request supports order filters over the following fields:
Field |
---|
id |
title |
standing |
ordering |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
renew_days |
Empty Filters
This request supports empty filters over the following fields:
Field |
---|
title |
Searching
This request the use of the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
This request will return a list of contract types containing the default fields and any additional fields request by
_fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Contract Types
Sample Request:
GET /api/v0/contracts/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/types/count
-H 'authorization: Bearer {access_token}'
GET /contracts/types/count
This request returns a count of contract types in a list defined by any available searches or filters. With no searches or filters this will be a count of all contract types on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed contract types. |
Get Contract Type
Sample Request:
GET /api/v0/contracts/types/{type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/types/{type_id}
-H 'authorization: Bearer {access_token}'
GET /contracts/types/{type_id}
This request returns a single contract type object identified by its contract_type_id
.
Configuring the Request
This request supports requesting extra fields or objects from the contract type object through the
_fields
parameter.
Handling the Response
The response will contain the single contract type with its default fields, and any additional fields requested through
_fields
.
Get Contract Status
Sample Request:
GET /api/v0/contracts/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/statuses/{status_id} \
-H 'authorization: Bearer {access_token}' \
GET /contracts/statuses/{status_id}
This request returns the contract status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a contract status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Contract Statuses
Sample Request:
GET /api/v0/contracts/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/statuses \
-H 'authorization: Bearer {access_token}'
GET /contracts/statuses
This request reutrns a list of contract statuses on the deployment.
Configuring the Response
Pagination
This request supports the standard pagination requests.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the contract status object through
the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Count Contract Statuses
Sample Request:
GET /api/v0/contracts/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/statuses/count \
-H 'authorization: Bearer {access_token}' \
GET /contracts/statuses/count
This request will return a count of contract statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all contract statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed contract statuses. |
Close a Contract Period
Sample Request:
PUT /api/v0/contracts/periods/{period_id}/close HTTP/1.1
HOST: {deployment.api.accelo.com}
Authorization: Bearer {access_token}
curl -X PUT \
https://{deployment}.api.accelo.com/api/v0/contracts/periods/{period_id}/close \
-H 'authorization: Bearer {access_token}
[PUT | POST] /contracts/periods/{period_id}/close
This request closes and returns a contract period, see the support documentation for information on closing contract periods. The response may be configured as per get contract period.
Take Care: This request doesn't just set the standing to 'closed', but will replicate the actions taken when you close a contract period via the Web App, including closing tickets/issues if the contract is set to auto complete.
Reopen a Contract Period
Sample Request:
PUT /api/v0/contracts/periods/{period_id}/open HTTP/1.1
HOST: {deployment.api.accelo.com}
Authorization: Bearer {access_token}
curl -X PUT \
https://{deployment}.api.accelo.com/api/v0/contracts/periods/{period_id}/open \
-H 'authorization: Bearer {access_token}
[PUT | POST] /contracts/periods/{period_id}/open
This request reopens and returns a previously close contract period. The response may be configured as pre get contract period.
List Available Progressions on a Contract
See the progressions section for a sample request
GET /contracts/{contract_id}/progressions
This request returns a list of available progressions for an contract, specified by its
contract_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "contracts" whose id is {contract_id}
.
Auto Run a Progression on a Contract
See the progressions section for a sample request
[POST|PUT] /contracts/{contract_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress an contract, specified by its
contract_id
. This is the request
[POST|PUT] /{object}/{object_id}/progressions/{progression_id}/auto
where the object is "contracts" whose id is {contract_id}
.
List a Contract's Resource Collections
See the resources (attachments) section for an example
GET /contracts/{contract_id}/collections
This request returns a list of collections against a contracts,
specified by its contract_id
. This is the request GET /{object}/{object_id}/collections
where the object is "contracts" whose id is {contract_id}
.
Upload a Resource (Attachment) to a Collection on a Contract
See the resources (attachments) section for an example
POST /contracts/{contract_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of a contracts,
specified by its contract_id
. This is the request
POST/{object}/{object_id}/collections/{collection_id}/resources
where the object is "contracts" whose id is {contract_id}
.
List a Contract's Profile Field Values
See the profiles section for a sample request
GET /contracts/{contract_id}/profiles/values
This request returns a list of profile field values of a contracts,
specified by its contract_id
. This is the request
GET/{object}/{object_id}/profiles/values
, where the object is "contracts" whose id is {contract_id}
.
List all Profile Field Values on Contracts
See the profiles section for a sample request
GET /contracts/profiles/values
This request returns a list of all profile field values on contracts.
This is the request GET /{object}/profiles/values
, where the object is "contracts".
List Contract Profile Fields
See the profiles section for a sample request
GET /contracts/profiles/fields
This request returns a list of profile fields available for any contract.
This is the request GET /{object}/profiles/fields
, where the object is "contracts".
List Contract Extension Fields
See the extension section for an example
GET /contracts/extensions/fields
This request returns a list of extension fields available for an contract, specified by
its contract_id
. This is the request GET /{object}/extensions/fields
, where
the object is "contracts".
List all Extensions Field Values on Contracts
See the extension section for an example
GET /contracts/extensions/values
This request returns a list of extension field values on contracts. This is the request
GET /{object}/extensions/values
, where the object is "contracts".
List a Contract's Extension Field Values
See the extension section for an example
GET /contracts/{contract_id}/extensions/values
This request returns a list of extension values for an contract, specified by its
contract_id
. This is the request GET /{object}/{object_id}/extensions/values
,
where the object is "contracts", and whose id is the contract_id
.
Update an Extension Field Value on a Contract
See the extension section for an example
PUT /contracts/{contract_id}/extensions/values/{extension_value_id}
This request updates the value of an extension field value, specified by its
extension_value_id
, of a contract, specified by its contract_id
. This is the request
PUT{object}/{object_id}/extensions/values/{extension_value_id}
, where the object is
"contracts", and whose id is contract_id
Set an Extension Value on a Contract
See the extension section for an example
POST /contracts/{contract_id}/extensions/fields/{extension_field_id}
This request sets and returns the value of an extension field, specified by its extension_field_id
, of an contract,
specified by its contract_id
. This request is the request
POST/{object}/{object_id}/extensions/fields/{extension_field_id}
where our object is
"contracts" whose id is contract_id
.
Contributors
Resource URI:
/api/v0/contributors
Contributors are third party contacts who are involved in your client's work. You can easily keep them in the loop on any project or issue by making them a contributor. See the support documentation for more information on contributors. Contributors link Staff or Affiliations to work like Jobs or issues.
The Contributor Object
Example contributor object:
{
"id": "2",
"against_id": "7",
"type_id": "1",
"against_type": "prospect",
"description": "Description of work the contributor will do",
"auto_cc": "0",
"status_id": null,
"standing": "active",
"object_type": "affiliation",
"object_id": "159"
}
The contributor object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the contributor. |
description | string | The description of the contributor. |
standing | select | The status of the contributor. |
status_id | unsigned | The id of the status associated with the contributor. |
against_type | string | The object the contributor was created against. |
against_id | unsigned | The unique identifier for the object the contributor was created against. |
object_type | string | The type of object linked by the contributor. |
object_id | unsigned | The unique id of the object linked by the contributor. |
contributor_type_id | unsigned | The id of the contributor. |
contributor_type | unsigned or object | The id of or whole contributor type object for the contributor. |
auto_cc | boolean | Whether the contributor will be Auto-CC'd on correspondence. |
The Contributor Type Object
Example contributor type object:
"response": {
"id": "1",
"title": "Advisor",
"default_status_id": "2",
"has_status": "1",
"auto_cc": "1",
"default_standing": "active",
"standing": "active",
"ordering": "0"
}
The contributor type object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the contributor. |
title | string | The title of the type |
default_status_id | unsigned | The identifier for the default status of this contributor type. |
has_status | boolean | Whether the contributor type has a status. |
auto_cc | boolean | Whether the contributors of this type will be Auto-CC'd on correspondence. |
default_standing | string | The default standing for this contributor type. Related to the default_status_id. |
standing | string | The current standing for this contributor type. Related to has_status. |
ordering | unsigned | The contributor types order as displayed in the web application. |
Get Contributor
Sample Request:
GET /api/v0/contributors/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contributors/{id} \
-H 'authorization: Bearer {access_token}'
GET /contributors/{id}
This request returns a single contributor, specified by its id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the contributor
using the _fields
parameter.
Handling the Response
The response will be the single requested contributor with its default fields and any
additional fields requested through _fields
.
List Contributors
Sample Request:
GET /api/v0/contributors HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contributors \
-H 'authorization: Bearer {access_token}'
GET /contributors
This request returns a list of contributors on the deployment.
Configuring the Request
Pagination
This request accepts all the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
standing |
status_id |
contributor_type_id |
against_type |
against_id |
object_id |
object_type |
auto_cc |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
contributor_type_id |
standing |
status_id |
against_id |
auto_cc |
Range Filters
This request supports range filters over the following fields:
Filter Name |
---|
id |
against_id |
object_id |
contributor_type_id |
Searching
This request supports the _search
parameter to search over the following fields:
Filter Name |
---|
description |
Handling the Response
The response will be a list of contributors on the deployment, with their default fields and
any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Count Contributors
Sample Request:
GET /api/v0/contributors/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contributors/count \
-H 'authorization: Bearer {access_token}'
GET /contributors/count
This request will return a count of contributors in a list defined by any available searches of filters. With no searches or filters this will be a count of all contributors on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of contributors listed. |
Get Contributor Type
Sample Request:
GET /api/v0/contributors/types/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contributors/types/{id} \
-H 'authorization: Bearer {access_token}'
GET /contributors/types/{id}
This request returns a single contributor type, specified by its id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the contributor type
using the _fields
parameter.
Handling the Response
The response will be the single requested contributor type with its default fields and any
additional fields requested through _fields
.
List Contributor Types
Sample Request:
GET /api/v0/contributors/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contributors/types \
-H 'authorization: Bearer {access_token}'
GET /contributors/types
This request returns a list of contributor types on the deployment.
Configuring the Request
Pagination
This request accepts all the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
title |
default_status_id |
default_standing |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
ordering |
Handling the Response
The response will be a list of contributor types on the deployment, with their default
fields and any additional fields requested through _fields
, and displayed according to any pagination parameters,
filters, or searches used.
Count Contributor Types
Sample Request:
GET /api/v0/contributors/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contributors/types/count \
-H 'authorization: Bearer {access_token}'
GET /contributors/types/count
This request will return a count of contributor types in a list defined by any available searches of filters. With no searches or filters this will be a count of all contributors types on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of contributor types listed. |
Divisions
Resource URI:
/api/v0/divisions
Divisions allow you manage contacts, companies, and staff under different details, rates, or identities. See the support documentation for more information.
The Division Object (Beta)
Sample division JSON object:
{
"title": "Support",
"standing": "active",
"ordering": "0",
"id": "1"
}
The division object contains the following:
Name | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the division |
title | string | The title of the division. |
standing | select | Either "active" or "inactive", the standing of the division. |
ordering | unsigned | The division's ordering as displayed on the deployment. |
Get Division (Beta)
Sample request:
curl -X get \
https://{deployment}.api.accelo.com/api/v0/divisions/{division_d} \
-H 'authorization: Bearer {access_token} \
-d '_fields=standing'
GET /api/v0/divisions/{division_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
_fields=standing
GET /division/{division_id}
This request returns a division specified by its unique identifier.
Configuring the Response
This request supports requesting additional fields and linked objects from the division object using the _fields
parameter.
Handling the Response
The response will be a single division with its default fields and any additional fields requested through _fields
.
List Divisions (Beta)
Sample request:
curl -X get \
https://deployment.api.accelo.com/api/v0/divisions \
-H 'authorization: Bearer foobar'
-d '_fields=_ALL'
-d '_filters=standing(active)'
GET /api/v0/divisions HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
GET /divisions
This request returns a list of divisions on the deployment.
Configuring the Response
Pagination
This request supports all of the pagination parameters.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
Order Filters
This request supports order filters over the following fields:
Field |
---|
id |
ordering |
Searching
This request supports the use of the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of divisions with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Divisions (Beta)
Sample request:
curl -X get \
https://deployment.api.accelo.com/api/v0/divisions/count \
-H 'authorization: Bearer foobar'
-d '_fields=_ALL'
-d '_filters=standing(active)'
GET /api/v0/divisions/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
GET /divisions/count
This request will return a count of divisions in a list defined by any available searches or filters. With no searches or filters this will be a count of all divisions on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the divisions listed. |
Expenses
Resource URI:
/api/v0/expenses
In the Accelo API, expenses are against objects, such as jobs, or issues. For example, an expense may be the cost of some training materials, or the cost of travel expenses for a staff member.
The Expenses Object
Sample expense:
{
"reimbursable": "no",
"resource": "3",
"type": "2",
"quantity": "1.0000",
"activity_id": "1052",
"against_type": "job",
"submitter_id": "14",
"against_id": "2",
"id": "2",
"standing": "submitted",
"approver_id": "22",
"title": "Lunch meeting",
"submitter": "14",
"billable": "no",
"price": "78.0000",
"unit_cost": "78.0000",
"date_incurred": "1495634400",
"approver": "22",
"activity": "1052",
"type_id": "2"
}
The expense object contains the following fields and linked objects:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the expense. |
title | string | A title for the expense. |
unit_cost | decimal | The cost for one of the expense. |
quantity | decimal | The quantity of the expense. |
standing | string | The standing of the expense. For example "submitted", "invoiced". |
price | decimal | The cost charged to a customer for one of the expense. |
date_incurred | unix ts | The date the expense was incurred. |
activity_id | unsigned | The unique identifier for the activity against the expense; the id for the note sent to the approver. |
type_id | unsigned | The unique identifier for the type of expense. |
approver_id | unsigned | The unique identifier of the staff member assigned to approve the expense. |
submitter_id | unsigned | The unique identifier of the staff member who submitted the expense. |
against_id | unsigned | The unique identifier of the object the expense is against. |
against_type | string | The type of object the expense is against. |
billable | string | Whether the expense is billable. May be either "yes" or "no". |
reimbursable | string | Whether the expense is reimbursable. May be either "yes" or "no". |
approver | unsigned or object | The staff object of the approver of the expense. |
submitter | unsigned or object | The staff object of the submitter of the expense. |
type | unsigned or object | The expense type object of the expense. Deprecated, please use expense_type . |
expense_type | unsigned or object | The expense type object of the expense. |
activity | unsigned or object | The activity object of the activity against the expense. |
resource | unsigned or object | The resource object (attachment) associated with the expense. |
The Expense Type
Sample expense type:
{
"ledger_id": "3",
"standing": "active",
"title": "Food",
"id": "2"
}
Similarly to contracts, expenses have types associated with them. Expense types may be set up on the Accelo deployment (see the support documentation for information). This expense type object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the type. |
title | string | A name for the type. |
standing | string | The standing of the expense when created. |
ledger_id | unsigned | The unique identifier of the billing ledger associated with this expense type. See the support documentation for information on ledgers. |
Note: The type
field is deprecated, please request the expense type through the expense_type
field,
which contains the following additional fields:
Field | Type | Description |
---|---|---|
tax_id | unsigned | The unique identifier of the tax object associated with the expense type. |
expense_type_ledger | unsigned or object | The unique identifier of the ledger associated with the expense type. |
Get Expense
Sample Request:
GET /api/v0/expenses/{expense_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses/{expense_id} \
-H 'authorization: Bearer {access_token}'
GET /expenses/{expense_id}
This request returns a single expense object specified by its expense_id
.
Configuring the Request
This request supports requesting additional objects and fields from the expenses object using the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be a single expense object with its default fields and any additional fields requesting through _fields
.
List Expenses
Sample Request:
GET /api/v0/expenses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses \
-H 'authorization: Bearer {access_token}'
GET /expenses
This request returns a list of expenses on the Accelo deployment.
Configuring the Request
Pagination
This request supports all the pagination parameters:
Additional Fields and Linked Objects
This request also supports requesting extra fields or linked objects of the expenses object using the _fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
type | Filter over the type_id . Deprecated, please use expense_type . |
expense_type | Filter over the expense_type_id . |
submitter | Filter over the submitter_id . |
approver | Filter over the approver_id . |
against_type | |
against_id |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_incurred |
Order Filters
This requesting supports order filters over the following fields:
Filter Name |
---|
id |
date_incurred |
title |
standing |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
type | Range over type_id . Deprecated, please use expense_type . |
expense_type | Range over the expense_type_id . |
submitter | Range over submitter_id . |
approver | Range over approver_id . |
quantity | |
unit_cost | |
cost | Range over the total cost, that is unit_cost times quantity . |
Object Filters
This request supports the following object filters:
Filter | Description |
---|---|
against | Filter by expenses against these objects. |
Searching
This request supports the use of the _search
parameter to search over the following fields:
Field |
---|
title |
handling the Response
This request will return a list of expenses containing the default fields and any additional fields request by _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Expenses
Sample Request:
GET /api/v0/expenses/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses/count \
-H 'authorization: Bearer {access_token}'
GET /expenses/count
This request will return a count of expenses in a list defined by any available searches or filters. With no searches or filters this will be a count of all expenses on the deployment. This request returns a single field:
Type | Description | |
---|---|---|
count | unsigned | A count of the listed expenses. |
Get Expense Type
Sample Request:
GET /api/v0/expenses/types/{type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses/types/{type_id} \
-H 'authorization: Bearer {access_token}'
GET /expenses/types/{type_id}
This request returns a single expenses type object, specified by its type_id
.
Configuring the Response
This request supports requesting extra fields and linked objects from the expenses type object using the _fields
parameter.
handling the Response
The response will be a single expense type object with its default fields, and any additional fields requested through _fields
.
List Expense Types
Sample Request:
GET /api/v0/expenses/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses/types \
-H 'authorization: Bearer {access_token}'
GET /expenses/types
This request returns a list of types of expenses on the Accelo deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters:
Additional Fields and Linked Objects
This request supports requesting extra fields and linked objects from the expense type object using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
standing |
ledger_id |
tax_id |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
title |
standing |
Range Filters
This request supports range filters over the following fields:
Filter Name |
---|
id |
Empty Filters
This request supports empty filters over the following fields:
Field |
---|
title |
Searching
This request the use of the _search
parameter to search over the following fields:
Field |
---|
title |
handling the Response
The response will contain a list of expense types with their default fields, and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Expense Types
Sample Request:
GET /api/v0/expenses/types/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses/types/count \
-H 'authorization: Bearer {access_token}'
GET /expenses/types/count
This request returns a count of expense types in a list defined by any available searches or filters. With no searches or filters this will be a count of all expense types on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of expense types listed. |
Update an Expense
Sample Request:
PUT /api/v0/expenses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /expenses/{expense_id}
This request updates and returns an expense, identified by its expense_id
.
Configuring the Expense
The following fields from the expense object may be updated through this request:
Field Name |
---|
title |
quantity |
billable |
reimbursable |
type_id |
unit_cost |
date_incurred |
resource_id |
Configuring the Response
This request supports requesting additional fields and linked objects from the expense object using the _fields
parameter. This request also supports breadcrumbs.
handling the Response
The response will be the single updated expense object with its default fields, and any additional fields requested through _fields
.
Create an Expense
Sample Request:
POST /api/v0/expenses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /expenses
This request creates and returns an expense object.
Configuring the Expense
The following fields from the expense object may be set with this request:
Field Name | Notes |
---|---|
title | |
against_id | |
against_type | |
unit_cost | |
quantity | |
type_id | |
price | If not included, this will default to unit_cost . |
date_incurred | |
billable | |
reimbursable | |
file | Allows you to upload a file with the expense (i.e. a receipt in the form of an image or PDF). If this value is set then it must be POSTed with multipart/form-data. |
resource_id | The unique identifier of a resource (attachment) to be sent with the expense. Note: you may only pass one of resource_id or file . |
Configuring the Response
This response supports requesting extra fields and linked objects from the expenses object through the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The request will return the single new expense object with its default fields, and any additional fields requested through _fields
.
Delete an Expense
Sample Request:
DELETE /api/v0/expenses/{expense_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/expenses/{expense_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
DELETE /expenses/id
This request removes an expense from the deployment. It takes no parameters and returns no resources.
List Available Progressions on an Expense
See the progressions section for a sample request
GET /companies/{expense_id}/progressions
This request returns a list of available progressions for an expense identified by its expense_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "companies" whose id is {expense_id}
Auto Run a Progression on an Expense
See the progressions section for a sample request
[PUT|POST] /companies/{expense_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress the status of an expense, specified by its expense_id
. This is the request [PUT|POST] /{object}/{object_id}/progressions/{progression_id/auto}
where the object is "companies" whose id is {expense_id}
.
Extensions (Custom Fields)
Resource URI:
/api/v0/extensions
Extensions, also known as Custom Fields, are similar to profiles. The main difference is in their availability. A given profile may be available to all types of a particular object, for example any type of issues, or even across a range of objects. Conversely, an extension is available to only one type of one object at at time, see also the support documentation. Extensions may be set up through the Accelo deployment, see the support documentation for information on setting them up. Currently the following objects support extensions through the API:
Similarly to profiles, extensions are described by extension fields and extension values, which store the information of values of an extension field.
The Extension Field Object
Sample extension field:
{
"link_type": "job",
"default_value": "national",
"lookup_type": null,
"field_type": "fixed_select",
"field_name": "Project Work Location",
"link_type_id": "1",
"information": "Will the work be carried out internationally?",
"options": [
"national",
"international"
],
"exported": "no",
"ordering": "0",
"id": "9",
"required": "no",
"important": "no",
"archived": "no"
}
These are objects describing the custom field on the deployment, they contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the extension. |
field_name | string | A name for the extension. |
field_type | select | The type of extension, may be either "text", "textbox", "int", "date", "date_time", "float", "certify", "fixed_select", "flexible_select", "multi_select", "lookup", "currency", "hyperlink", or "contributor". |
link_type_id | unsigned | The unique identifier of the type of object this extension is linked to. For example, if "link_type" is job, this will be the id of the job type that this extension can appear under. |
link_type | string | The type of object the extension is linked to. |
ordering | int | The extension's order on the Accelo deployment. |
required | select | Either "yes" or "no", whether this extension is required for the object it is linked to. |
archived | select | Either "yes" or "no", whether this extension is no longer in use and has been archived. |
exported | select | Either "yes" or "no", whether this extension is exported when the linked object is exported. |
important | select | Either "yes" or "no", whether this extension has been marked as "important" on the Accelo deployment. |
default_value | dynamic | The default value for the field, the type will depend on the field_type . |
lookup_type | string | When field_type is lookup, this will contain the type of object for the lookup. |
information | string | Any extra information about the extension. |
The Extension Value Object
Example extension field value:
{
"value": "one, two",
"id": "1684",
"is_sensitive": "0",
"field_description": null,
"link_type": "job",
"date_modified": "1528787815",
"link_type_id": "5",
"field_type": "multi_select",
"is_important": "1",
"field_id": "111",
"field_name": "Configuration Values",
"values": [
"one",
"two"
],
"is_exported": "0",
"link_id": "1197",
"modified_by": "44",
"default_value": ""
}
These describe the value of a given extension field, identified by the field_id
. This
object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the extension value. |
field_type | string | The field_type of the related extension field. |
file_name | string | The name of the related extension field. |
value | dynamic | The value for the extension, the type will depend on the field_type of the related extension field. If field_type is "lookup" then this will be the title of the linked object. If field_type is "contributor" it will be the name of the affiliation or staff who is the contributor. If it's a "multi_select" this will be all the selected values joined by a comma e.g. "one, two" for ["one", "two"] |
values* | array | When the field type is "multi_select", this will contain an array of the selected values. e.g, ["one", "two"] |
field_id | unsigned | The unique identifier of the related extension field. |
link_id | unsigned | The unique identifier of the object the profile value is against. |
link_type | string | The type of object the related extension field is linked to. |
link_type_id | unsigned | The unique identifier of the type of object the related extension is linked to. |
date_modified | unix ts | The date this extension value was last modified. |
modified_by | unsigned or object | The staff member who last modified this extension value. |
default_value | dynamic | The default value of the related extension field. |
is_sensitive | bool | Whether this value can only be viewed by people with "sensitive" permissions for the link_type object. See the support documentation for information on setting permissions. |
is_important | bool | Whether the related extension field is marked as "important". |
is_exported | bool | Whether the related extension field is "exported". |
value_id | unsigned | If field_type is "lookup" or "contributor" this will be the ID of the lookup object (e.g, the company id) or the contributor id |
value_type | string | If field_type is "lookup" or "contributor" this will be the type of lookup object (e.g, "company") or "contributor" |
field_description | string | Any extra information about the extension field used by the value. |
default_value | dynamic | The default value for the extension field use by the value, the type will depend on the field_type . |
field_name | string | The name of the extension field used by the value. |
* The values
field is only returned when the field_type
is "multi_select". When it's "multi_select",
it's returned by default.
List Extension Fields
Sample Request:
GET /api/v0/contracts/extensions/fields HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/extensions/fields
-H 'authorization: Bearer {access_token}'
GET /{object}/extensions/fields
This request request returns a list of extension fields available for the given object
Configuring the Response
Pagination
This request supports all of the pagination parameters
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the extension field object
using the _fields
parameter.
Handling the Response
The response will be a list of extension field object with their default fields, and any
additional fields requested using _fields.
List Objects Extension Values
Sample Request:
GET /api/v0/contracts/{contract_id}/extensions/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/{contract_id}/extensions/values
-H 'authorization: Bearer {access_token}'
GET /{object}/{object_id}/extensions/values
This request returns a list of extension field values for the given object
identified
by its object_id
.
Configuring the Response
Pagination
This request supports all of the pagination parameters
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the extension value object
using the _fields
parameter.
Handling the Response
The response will be a list of extension field values with their default fields, and any
additional fields requested through _fields
.
List Extension Values
Sample Request:
GET /api/v0/contracts/extensions/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/contracts/extensions/values
-H 'authorization: Bearer {access_token}'
GET /{object}/extensions/values
This request returns a list of extension field values for the given object
.
Configuring the Response
Pagination
This request supports all of the pagination parameters
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the extension value object
using the _fields
parameter.
Update an Extension Field Value
Sample Request, here we are updating the value of an extension field value of "jobs/56" to be "international":
PUT /api/v0/jobs/56/extensions/values/4 HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
value=international
curl -X put \
https://{deployment}.api.accelo.com/api/v0/jobs/56/extensions/values/4 \
-H 'authorization: Bearer {access_token}' \
-H 'content-type: application/x-www-form-urlencoded'
-d 'value=international'
PUT /{object}/{object_id}/extensions/values/{extension_value_id}
This request updates and returns a extension values, specified by its
extension_value_id
, of a particular object, specified by its object_id
, of a particular type, specified by object
.
Configuring the Extension Value
This request updates the value
of an extension value, since this object is dynamic the field we send will depend on the type of value
:
Field | Type | Description |
---|---|---|
value_int | int | If field_type is "integer", update the value with this integer. |
value_date | unix ts | If field_type is "date", "date_time", or "certify", update the value with this string. |
value_id | int | If field_type is "lookup" or "contributor", update the value with this integer, representing an object id. |
value_type | string | If 'field_type' is "lookup", update the value_type with this string. |
value | string | If field_type is none of the above, update the value with this string. |
Configuring the Response
This request supports requesting additional fields and linked objects from the extension value object
using the _fields
parameter.
Handling the Response
This request will return the single, updated extension value object with its default
fields, and any additional fields requesting through _fields
.
Set an Extension Field Value
Sample Request, here we are setting a value for an extension field value for "jobs/12":
PUT /api/v0/jobs/59/extensions/fields/12 HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
value=international
curl -X put \
https://{deployment}.api.accelo.com/api/v0/jobs/59/extensions/fields/12 \
-H 'authorization: Bearer {access_token}' \
-H 'content-type: application/x-www-form-urlencoded'
-d 'value=international'
POST /{object}/{object_id}/extensions/fields/{extension_field_id}
This request sets and returns an extension value. for an extension field, specified by
its extension_field_id
. The object whose profile field is to be updated is identified by object
and object_id
Configuring the Extension Value
This request accepts the same fields as the previous request, that is, it takes only the relevant value field(s). These fields are required for this request.
Configuring the Response
This request supports requesting additional fields and linked objects from the extension value object
using the _fields
parameter.
Handling the Response
This request will return the newly created extension value object with its default fields
and any additional fields requested using _fields
.
Filters
Resource URI:
/api/v0/filters
Filters are available on the Accelo deployment that allow you to search through the resources on the deployment. These filters may be customized and saved on the deployment, see the support documentation for more information. Currently these filters are supported through the API on the following objects:
- 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
parameter to search over the following fields:
Filter Name |
---|
subject |
invoice_number |
Handling the Response
The response will be a list of invoices on the Deployment, with their default fields and any
additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Count Invoices
Sample Request:
GET /api/v0/invoices/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/invoices/count \
-H 'authorization: Bearer {access_token}'
GET /invoices/count
This request will return a count of invoices in a list defined by any available searches or filters. With no searches or filters this will be a count of all invoices on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of invoices listed. |
List an Invoice's Profile Field Values
See the profiles section for a sample request
GET /invoices/{invoice_id}/profiles/values
This request returns a list of profile values of an invoice,
specified by its invoice_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "invoices", and whose id is {invoice_id}
.
List all Profile Field Values on an Invoice
See the profiles section for a sample request
GET /invoices/profiles/values
This request returns a list of all profile field values on invoices.
This is the request GET /{object}/profiles/values
, where the object is "invoices".
List Invoices Profile Fields
See the profiles section for a sample request
GET /invoices/profiles/fields
This request returns a list of profile fields available for invoices. This is the request
GET /{object}/profiles/fields
where the object is "invoices".
Update a Profile Value on an Invoice
See the profiles section for a sample request
PUT /invoices/{invoice_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular invoice, specified by its invoice_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "invoices",
and whose value is {invoice_id}
.
Set a Profile Value on an Invoice
See the profiles section for a sample request
POST /invoices/{invoice_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for an "invoice", specified by its invoice_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "invoices",
and whose value is {invoice_id}
.
Get Line Item (Beta)
Sample Request:
GET /api/v0/invoices/line_items/{line_item_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/invoices/line_items/{line_item_id} \
-H 'authorization: Bearer {access_token}'
GET /invoices/line_items/{line_item_id}
This request returns a line item specified by its line_item_id.
Configuring the Response
This request supports requesting additional fields and linked objects from the line item object
using the _fields
parameter.
Handling the Response
The request will return the single invoice line item with its default fields and any additional fields requested through
_fields
.
List Line Items (Beta)
Sample request:
GET /api/v0/invoices/line_items/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/invoices/line_items \
-H 'authorization: Bearer {access_token}'
This request returns a list of invoice line item.
Configuring the Response
Pagination
This request supports all of the standard pagination parameters
Additional Fields and Linked objects
This request supports requesting additional fields and linked objects from the line item object
using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
invoice_id |
ledger_id |
tax_id |
Order Filters
This request supports the following order filters:
Filter |
---|
id |
invoice_id |
ledger_id |
tax_id |
quantity |
rate |
total |
ordering |
Range Filters
This request supports range filters over the following fields:
Filter |
---|
id |
invoice_id |
ledger_id |
tax_id |
quantity |
rate |
total |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
description |
Handling the Response
The response will contain a list of invoice line items with their default fields and any additional fields requested
through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Line Items (Beta)
Sample request:
GET /api/v0/invoices/line_items/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/invoices/line_items/count \
-H 'authorization: Bearer {access_token}'
GET /invoices/line_items/count
This request will return a count of line items in a list defined by any available searches or filters. With no searches or filters this will be a count of all line items on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of line items listed. |
Issues (Tickets)
Resource URI:
/api/v0/issues
Issues (also known as "Tickets") are used for when you need to track billable time against a client, but don’t need the complexity of a full Project and its workflow and components. For example, issues may be used to track support cases where you’re diagnosing and fixing a problem and don’t know beforehand the specific steps which will be required to resolve the Issue. See the support documentation for more information on these objects.
The Issue Object
Example issue object:
{
"assignee": "14",
"title": "Issue with public field",
"referrer_type": null,
"affiliation": "98",
"date_submitted": "1493872605",
"date_modified": "1553728167",
"resolution_detail": "I fixed the field, it now displays as expected.",
"staff_bookmarked": "1",
"against": "companies/39",
"contract": "1",
"billable_seconds": "1400",
"submitted_by": "14",
"against_type": "company",
"date_due": "1493906400",
"contact": "98",
"date_closed": "1495683190",
"standing": "closed",
"object_budget": "8",
"date_started": "1493820000",
"class": "19",
"resolved_by": "14",
"date_last_interacted": "1493872783",
"resolution": "8",
"closed_by": "14",
"date_resolved": "1495683190",
"referrer_id": null,
"custom_id": "",
"status": "4",
"opened_by": "14",
"type": "1",
"description": "A public field is showing as public",
"against_id": "39",
"id": "7",
"company": "39",
"issue_priority": "1",
"date_opened": "1493872605"
}
The issue object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the issue. |
title | string | A name for the issue |
custom_id | string | The custom ID for the issue. Only issues whose type allows custom IDs will have a value for this field. |
description | string | A description of the issue. |
against | string | The API URI of the object this issue is against. |
against_type | string | A string representing the type of object this issue is against. |
against_id | unsigned | The unique identifier of the object this issue is against. |
type | unsigned or object | The issue type of this issue. Deprecated, please use issue_type . |
issue_type | unsigned or object | The issue type of this issue. |
affiliation | unsigned or object | The affiliation associated with this issue. |
class | unsigned or object | The issue class of this issue. |
priority | unsigned or object | Deprecated please use issue_priority |
issue_priority | unsigned or object | The priority of the issue. |
resolution | unsigned or object | The resolution type used by the issue, if it has been resolved. |
resolution_detail | string | A description of the resolution, if resolved. |
status | unsigned or object | The status of the issue. |
standing | string | The standing of the issue, taken from the issue status. |
date_submitted | unix ts | The date the issue was submitted |
submitted by | unsigned or object | The staff member who submitted the issue. |
date_opened | unix ts | The date the issue was opened. |
opened_by | unsigned or object | The staff member who opened the issue. |
date_resolved | unix ts | If resolved, the date the issue was resolved. |
resolved_by | unsigned or object | The staff member who resolved the issue. |
date_closed | unix ts | If closed, the date the issue was closed. |
closed_by | unsigned or object | The staff member who closed the issue. |
date_due | unix ts | The due date for the issue. |
date_last_interacted | unix ts | The date the issue was last interacted with. |
date_modified | unix ts | The date the issue was last modified. |
referrer_type | string | If the issue was created from the deployment as a "related issue" to an object, this will be the object's type. |
referrer_id | unsigned | The unique identifier of this related object. |
staff_bookmarked | boolean | Whether the current viewer has bookmarked the issue. |
billable_seconds | unsigned | The amount of billable time, in seconds, on the issue. |
company | unsigned or object | If against_type is company, the company the issue is against. |
assignee | unsigned or object | The staff assigned to the issue. |
contract | unsigned or object | If the issue is assigned a contract (retainer), this will return the contract object. |
issue_object_budget | unsigned or object | The object budget associated with the issue. |
object_budget | unsigned or object | Deprecated please use issue_object_budget . |
The Issue Priority
Example priority object:
{
"title": "Extreme",
"id": "1",
"color": "Red",
"factor": "5"
}
Issue priorities help you keep track of what needs to be done. They may be set up from the deployment, see the support documentation for information. They contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the priority. |
title | string | A name for the priority. |
color | select | The color of the priority when displayed on the deployment. The colors, in order of increasing urgency a "grey", "blue", "green", "orange", "red". |
factor | unsigned | A number representing the urgency of the priority. 5 is "Extreme", 1 is "None". |
The Issue Status
Example issue status object:
{
"standing": "open",
"start": "yes",
"color": "yellow",
"ordering": "2",
"title": "Open",
"id": "2"
}
Statuses may be used to track the progress of an issue. These statuses may be configured from the deployment, see the support documentation for more information. The status objects contain the following
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the status. |
title | string | A name for the status. |
standing | string | A string describing the standing of the issue. |
color | string | The color of the status shown on the deployment. |
start | select | Either "yes" or "no", whether an issue may be created with this status. |
ordering | unsigned | A number describing the order of the status on the deployment. |
The Issue Type
Example issue type object:
{
"notes": "Issue type for support issues.",
"standing": "active",
"title": "Support",
"id": "2",
"parent": "0"
}
Issue types let you sort your issues according to the type of work the entail. Issue types may be set up and edited from the deployment, see the support documentation for more information.
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the issue type. |
title | string | A name for the issue type. |
notes | string | Notes about the issue type. |
parent | unsigned | The unique identifier of the parent issue type. If there is no parent has the value "0" |
standing | select | Either "active" or "inactive", the standing of the issue type. |
budget | select | Either "yes" or "no", whether issues under this type are billable. |
ordering | unsigned | A number describing the type's ordering on the deployment. |
default_issue_class | unsigned or Object | The default issue class for issues created with this type. |
default_issue_priority | unsigned or Object | The default issue_priority for issues created with this type. |
Note: the type
field is deprecated, please request the issue type object through the
issue_type
field, which contains the following additional fields:
Field | Type | Description |
---|---|---|
default_class_id | unsigned | The unique identifier of the default issue class for this type of issue. Default is null . |
has_custom_id | boolean | Either "1" or "0", whether the issue type uses custom ids. |
The Issue Resolution
Example issue resolution:
{
"standing": "active",
"title": "Support Resolution",
"id": "8",
"parent": "7",
"report": "Use this resolution when resolving support issues.",
"description": "I fixed the field, it now displays as expected."
}
Issue resolutions track how certain issues are resolved and may be set up on the deployment, see the support documentation for more information. The issue resolution contains the following:
Field | Type | Descriptions |
---|---|---|
id | unsigned | A unique identifier for the issue resolution. |
title | string | A name for the issue resolution. |
parent | unsigned | The unique identifier of the parent resolution, it there is no parent this has value "0". |
description | string | A generic description of the resolution, may be changed for a given issue. |
report | string | A fixed description of the resolution. |
standing | select | Either "active" or "inactive", the standing of the resolution. |
The Issue Class
Example issue class:
{
"standing": "active",
"description": "For issues pertaining to our website",
"parent": "0",
"title": "Website",
"id": "2"
}
Issue classes help to classify symptoms or characteristics of an issue. They can be set up from the deployment, see the support documentation for information. Ticket classes contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique description for the class. |
title | string | A name for the class. |
description | string | A description of the class. |
parent | unsigned | The unique identifier of the parent class, if there is no parent this has value "0". |
standing | select | Either "active" or "inactive", the standing of the class. |
Get Issue
Sample Request:
GET /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
-H 'authorization: Bearer {access_token}'
GET /issues/{issue_id}
This request returns a single issue, identified by its issue_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the issue object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single requested issue with its default fields, and any additional fields
requested through _fields
.
List Issues
Sample Request:
GET /api/v0/issues HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues \
-H 'authorization: Bearer {access_token}'
GET /issues
This request returns a list of issue objects on the deployment.
Pagination
This request supports the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issues object using
the _fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
custom_id | |
referrer_type | |
referrer_id | |
against_id | |
against_type | |
status | Filter by the status_id of the issue. |
type | Filter by the type_id of the issue. Deprecated, please use issue_type . |
issue_type | Filter by the issue_type_id . |
affiliation | Filter by the affiliation_id of the issue. |
class | Filter by the class_id of the issue. |
priority | Deprecated, please use issue_priority |
issue_priority | Filter by the priority_id of the issue. |
resolution | Filter by the resolution_id of the issue. |
submitted_by | Filter by the staff_id of the submitter. |
opened_by | Filter by the staff_id of the user who opened the issue. |
closed_by | Filter by the staff_id of the user who closed the issue. |
resolved_by | Filter by the staff_id of the user who resolved the issue. |
assignee | Filter by the staff_id of the assignee. |
contract | Filter by the contract_id of any linked contracts. |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_opened |
date_submitted |
date_started |
date_due |
date_closed |
date_modified |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
id | |
date_opened | |
date_submitted | |
date_started | |
date_due | |
date_closed | |
date_resolved | |
date_last_interacted | |
date_modified | |
title | |
standing | |
status | Order by the status_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
reopened_count | Range over the number of times the issue has been reopened. |
rate_charged | |
against_id | |
billable_seconds | |
assignee | Range over the staff_id of assignees. |
type | Range over the type_id . Deprecated, please use issue_type . |
issue_type | Range over issue_type_id . |
affiliation | Range over the affiliation_id . |
class | Range over the class_id . |
resolution | Range over the range_id . |
priority | Deprecated, please use issue_priority |
issue_priority | Range over the priority_id . |
submitted_by | Range over the staff_id of submitters. |
opened_by | Range over the staff_id of staff members who opened issues. |
resolved_by | Range over the staff_id of staff members who resolved issues. |
closed_by. | Range over the staff_id of staff members who closed issues. |
status | Range over the status_id . |
rate | Range over the rate_id of the rate charged. |
contract | Range over the contract_id of contracts linked to issues. |
Object Filters
This request supports the following object filters:
Filter Name | Description |
---|---|
against | Filter by issues against these objects. |
referrer | Filter by issues referred by these objects. |
Searching
This request supports using the _search
function to search over the following fields:
Field |
---|
subject |
Handling the Response
This request will return a list of issues containing the default fields and any additional fields
request by _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Issues
Sample Request:
GET /api/v0/issues/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/count \
-H 'authorization: Bearer {access_token}'
GET /issues/count
This request will return a count of issues in a list defined by any available searches or filters. With no searches or filters this will be a count of all issues on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the issues listed. |
List Recent Issues
Sample Request:
GET /api/v0/issues/recent HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/recent \
-H 'authorization: Bearer {access_token}'
GET /issues/recent
This request returns a list of issues on the deployment sorted by most recently submitted, that is, in descending order
of date_submitted
.
Configuring the Request
This request accepts the same parameters and filters over the same fields as the GET /issues
request,
although it will always be ordered in descending order of date_submitted
.
Handling the Response
This request will return a list of contacts displayed according to any parameters used, and with their default fields
plus any additional fields requested by _fields
, and ordered in descending order of date_submitted
.
List Issue Statuses
Sample Request:
GET /api/v0/issues/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/statuses \
-H 'authorization: Bearer {access_token}'
GET /issues/statuses
This request returns a list of issue statuses on the deployment.
Configuring the Response
Pagination
This request supports the standard pagination requests.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue status object through
the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
This request will return a list of issue statuses with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters or searches used.
Get Issue Type
Sample request:
GET /api/v0/issues/types/{issue_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/types/{issue_type_id} \
-H 'authorization: Bearer {access_token}'
GET /issues/types/{issue_type_id}
This request returns an issue type specified by its unique id.
Configuring the Response
This request supports request additional fields and linked objects from the issue type using the
_fields
parameter.
Handling the Response
The response will contain a single issue type with its default fields and any additional fields requested through
_fields
.
List Issue Types
Sample Request:
GET /api/v0/issues/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/types \
-H 'authorization: Bearer {access_token}'
GET /issues/types
This request returns a list of issue types on the deployment. The _filters
parameter is set to
standing_not(inactive)
by default.
Configuring the Response
Pagination
This request supports the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue type object
using the _fields
parameter. Note this request does not support the _ALL
argument for this parameter.
Handling the Response
The response will be a list of issue types with their default fields and any additional fields
requested through _fields
.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
standing |
budget |
default_class_id |
parent |
Order Filters
This request supports order filters over the following fields:
Field |
---|
id |
title |
standing |
ordering |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
List Issue Classes
Sample Request:
GET /api/v0/issues/classes HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/classes \
-H 'authorization: Bearer {access_token}'
GET /issues/classes
This request returns a list of issue classes on the deployment.
Configuring the Response
This request supports requesting additional fields and linked objects from the issue class object
using the _fields
parameter. Note this request does not support the _ALL
argument for this parameter.
Handling the Response
The response will be a list of issue types with their default fields and any additional fields
requested through _fields
.
Get Issue Resolution
Sample request:
GET /api/v0/issues/resolutions/{resolution_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/issues/resolutions/{resolution_id} \
-H 'authorization: Bearer {access_token}' \
GET/issues/resolutions/{resolution_id}
This request returns a single issue resolution, specified by its resolution_id
.
Configuring the Response
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue resolution
using the _fields
parameter.
Handling the Response
The response will be the single issue resolution with its default fields, and any additional
fields requested through _fields
.
List Issue Resolutions
Sample request:
GET /api/v0/issues/resolutions HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/issues/resolutions \
-H 'authorization: Bearer {access_token}' \
GET/issues/resolutions
Returns a list of issue resolutions.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue resolution
using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter | Description |
---|---|
id | |
standing | |
parent_id |
Order Filters
This request supports the following order filters:
Filter | Description |
---|---|
id | |
standing | |
title |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
Empty Filters
This request supports empty filters over the following fields:
Field |
---|
title |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
Handling the Response
The response will be a list of issue resolutions with their default fields and any additional
fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Issue Resolutions
Sample request:
GET /api/v0/issues/resolutions/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/issues/resolutions/count \
-H 'authorization: Bearer {access_token}' \
GET/issues/resolutions/count
This request returns a count of issue resolutions in a list defined by any available filters or searches. With no searches or filters this will be a count of all issue resolutions on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | Unsigned | A count of issue resolutions listed |
List Tasks Against an Issue
Sample Request:
GET /issues/{issue_id}/tasks
GET /api/v0/issues/{issue_id}/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/tasks \
-H 'authorization: Bearer {access_token}'
This request returns a list of tasks against an issue specified by its issue_id
.
Configuring the Response
This response may be configuring in the same way as GET /tasks
Handling the Response
This response may be handled in the same way as GET /tasks
Update an Issue
Sample Request:
PUT /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /issues/{issue_id}
This request updates and returns an issue object, identified by its issue_id
.
Configuring the Issue
The following fields from the issue object may be updated through this request:
Notes | |
---|---|
title | |
description | |
against_id | Note: If supplied, you must also supply an against_type . |
against_type | Note: If supplied, you must also supply an against_id . |
class_id | Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes . |
affiliation_id | |
date_started | |
date_due | |
assignee | A staff_id , must point to a valid staff member. The staff will be assigned and informed of this assigned issue. |
priority_id | The priority object's id. For available priorities see GET /issues/priorities |
status_id | Must point to a valid issue status. Should not be sent in conjunction with standing , otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses . If you have a status_id , please use this instead of standing . standing will be used to guess the status, thus, status_id is more precise. Warning this will bypass any progressions and should only be used deliberately when automating tasks. |
standing | The standing you want to change the issue to (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). Warning this will bypass any progressions and should only be used deliberately when automating tasks. |
resolution_id | The identifier of the issue resolution. The resolution will only show if the issue's standing is resolved . This must point to a valid resolution, you may retrieve a list of resolutions through GET /issues/resolutions . |
resolution_detail | The details of any resolution. To clear the resolution_detail you may send this field with no value. |
contract_id | The id of the contract the issue is under, if this field is empty, the contract_id will be unset. This must point to a related contract, you can use the is_related_to_issue filter on GET /contracts to find related contracts. |
Configuring the Response
This request supports requesting additional fields and linked objects from the issue object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single updated issue with its default fields and any additional fields
requested through _fields
.
Create an Issue
Sample Request:
POST /api/v0/issues/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/ \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /issues
This request creates and returns an issue.
Configuring the Issue
Values for the following fields from the issue object may be set through this request:
Notes | |
---|---|
title | |
type_id | Must point to a valid issue type. You may retrieve a list of types through GET /issues/types . |
against_type | Must be a valid type of object. |
against_id | Must point to a valid object of type against_type . |
standing | Must be a valid standing. (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). If you have a status_id , please use this instead of standing . standing will be used to guess the status, thus, status_id is more precise. |
status_id | Must point to a valid issue status. Should not be sent in conjunction with standing , otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses . |
affiliation_id | |
date_started | |
date_due | |
description | |
class_id | Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes |
assignee | A staff_id , must point to a valid staff member. |
priority_id | The priority object's id. For available priorities see GET /issues/priorities |
Configuring the Response
This request supports requesting additional fields and linked resources from the issue object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the created issue with its default fields and any additional fields requested
through _fields
.
Delete an Issue
Sample Request:
DELETE /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
-H 'authorization: Bearer {access_token}' \
DELETE /issues/{issue_id}
This request removes an issue from the deployment, specified by its issue_id
. This request takes no parameters and
returns no resources.
List Issue Priorities
GET /issues/priorities
This request returns a list of priorities available for issues.
Get Issue Priority
GET /issues/priorities/{priority_id}
Returns a single priority for the given priority id.
Count Issue Priorities
GET /issues/priorities/count
Returns the number of issue priorities.
List an Issue's Profile Field Values
See the profiles section for a sample request
GET /issues/{issue_id}/profiles/values
This request returns a list of profile values of an issue, specified by
its issue_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "issues", and whose id is {issue_id}
.
List all Profile Field Values on Issues
See the profiles section for a sample request
GET /issues/profiles/values
This request returns a list of all profile field values on issues.
This is the request GET /{object}/profiles/values
, where the object is "issues".
List Issue Profile Fields
See the profiles section for a sample request
GET /issues/profiles/fields
This request returns a list of profile fields available for issues. This is the request
GET /{object}/profiles/fields
where the object is "issues".
Update a Profile Value on an Issue
See the profiles section for a sample request
PUT /issues/{issue_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular issue,specified by its issue_id
. This is the request
PUT/{object}/{object_id}/profiles/values/{profile_value_id}
where the object is "issues",
and whose id is the {issue_id}
.
Set a Profile Value on an Issue
See the profiles section for a sample request
POST /issues/{issue_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for an issue, specified by its issue_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "issues",
and whose value is {issue_id}
.
List Issue Extension Fields
See the extension section for an example
GET /issues/extensions/fields
This request returns a list of extension fields available for an issue, specified by its
issue_id
. This is the request GET /{object}/extensions/fields
, where the
object is "issues".
List an Issue's Extension Field Values
See the extension section for an example
GET /issues/{issue_id}/extensions/values
This request returns a list of extension values for an issue, specified by its
issue_id
. This is the request GET /{object}/{object_id}/extensions/values
, where the object is "issues", and whose id is the {issue_id}
.
List all Extension Field Values on Issues
See the extension section for an example
GET /issues/extensions/values
This request returns a list of extension field values on issues.
This is the request GET /{object}/extensions/values
, where the object is "issues".
Update an Extension Field Value on an Issue
See the extension section for an example
PUT /issues/{issue_id}/extensions/values/{extension_value_id}
This request updates the value of an extension field value, specified by its
extension_value_id
, of an issue, specified by its issue_id
. This is the request
PUT{object}/{object_id}/extensions/values/{extension_value_id}
, where the object is "issues",
and whose id is {issue_id}
Set an Extension Field Value on an Issue
Sample Request:
POST /issues/{issue_id}/extensions/fields/{extension_field_id}
This request sets and returns the value of an extension field, specified by its extension_field_id
, of an issue,
specified by its issue_id
. This request is the request
POST/{object}/{object_id}/extensions/fields/{extension_field_id}
where our object is "issues"
whose id is issue_id
.
List Available Progressions on an Issue
See the progressions section for a sample request
GET /issues/{issue_id}/progressions
This request returns a list of available progressions for an issue, specified by its
issue_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "issues" whose id is {issue_id}
.
List All Progressions For Issues
GET /issues/progressions
This request returns all progressions available for issues.
This returns a list of progressions with the following fields added to the response.
Field | Type | Description |
---|---|---|
issue_status | unsigned or object | The issue status of the issue. |
issue_type | unsigned or object | The issue type that the progression is for. |
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
issue_type_id |
Boolean Filters
this request also supports a special kind of filter, the boolean filter. These filters take boolean arguments, the supported filters are:
Filter Name | Notes |
---|---|
on_create | Filter whether the progression can be run on create |
Auto Run a Progression on an Issue
See the progressions section for a sample request
[POST|PUT] /issues/{issue_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress an issue, specified by its
issue_id
. This is the request [POST|PUT] /{object}/{object_id}/progressions/{progression_id}/auto
where the object is "issues" whose id is {issue_id}
.
List an Issue's Resource Collections
See the resources (attachments) section for an example
GET /issues/{issue_id}/collections
This request returns a list of resource collections against an issue,
specified by its issue_id
. This is the request GET /{object}/{object_id}/collections
where the object is "issues" and hose id is {issue_id}
.
Upload a Resource (Attachment) to a Collection on an Issue
See the resources (attachments) section for an example
POST /issues/{issue_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of an
issue specified by its issue_id
. This is the request
POST/{object}/{object_id}/collections/{collection_id}/resources
where the
object is "issues" whose id is {issue_id}.
Jobs (Projects)
Resource URI:
api/v0/jobs
Jobs (or Projects) help you to plan, delegate and track client and internal projects. Projects can be as simple or complex as you like, see the support documentation for more information.
The Job Object
Example job object:
{
"date_modified": "1495681796",
"modified_by": "14",
"status": "5",
"staff_bookmarked": "1",
"type": "3",
"job_type": "3",
"against": "companies/65",
"date_completed": null,
"against_id": "39",
"against_type": "company",
"company": "39",
"id": "2",
"date_due": "1495245600",
"rate": "3",
"date_created": "1495238402",
"standing": "active",
"date_started": "1495245600",
"title": "New Logo Design",
"paused": "0",
"date_last_interacted": "1495686301",
"manager": "7",
"rate_charged": "125.00",
"date_commenced": "1494209132",
"affiliation": "77",
"custom_id": "TIM#42"
}
The jobs object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the job. |
title | string | A name for the job. |
against_type | string | The type of object the job is against. |
against_id | unsigned | The unique identifier of the object the job is against. |
against | string | The API URI of the object the job is against, that is,against_type and against_id concatenated with a "/". |
custom_id | string | The custom id for this job. |
paused | integer | The number of days the jobs has been paused. |
staff_bookmarked | boolean | Whether the current user has bookmarked the job on the deployment. |
date_created | unix ts | The date the project was created. |
date_modified | unix ts | The date the project was last modified. |
date_commenced | unix ts | The date the job started, that is, when its status moved from "setup" to "active" |
date_started | unix ts | The date the job is scheduled to start. |
date_due | unix ts | The date the job is scheduled to be completed. |
date_completed | unix ts | The date the job was completed. |
date_last_interacted | unix ts | The date the job was last interacted with. |
type | unsigned or object | The job type object of the job. Deprecated, please use job_type . |
job_type | unsigned or object | The job type associated with the job. |
rate | unsigned or object | The rate object associated with the job. |
rate_charged | decimal | The rate charged for billable work, this is part of the rate object. |
status | unsigned or object | The status associated with the job |
standing | string | The standing of the project. This is part of the status. |
manager | unsigned or object | The staff manager managing the job. |
modified_by | unsigned or object | The staff member who last modified the job. |
company | unsigned or object | The company against the job, if any. |
affiliation | unsigned or object | The affiliation against the job. |
job_object_budget | unsigned or object | The object budget associated with the job. |
job_contract | unsigned or object | The contract associated with the job, if any. |
job_object_schedule | unsigned or object | The object schedule linked to the job. |
The Job Type
Example job type:
{
"id": "3",
"title": "Internal",
"standing": "active",
"ordering": "0"
}
You may set up and configure different job types to suit your business processes, general information on types can be found in the support documentation. For jobs, the type object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the job type. |
title | string | A name for the job type. |
standing | select | Either "active" or "inactive", the standing of the job type. |
ordering | integer | An integer representing the type's order as displayed on the deployment. |
Note: Requesting the job type object via type()
is deprecated, please instead
request it via job_type()
, this object will have an additional field:
Field | Type | Description |
---|---|---|
has_custom_id | boolean | Either "1" or "0", whether the job type has a custom id. |
Get Job
Sample Request:
GET /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
-H 'authorization: Bearer {access_token}'
GET /jobs/{job_id}
This request returns a single job, specified by its job_id
.
Configuring the Response
This request supports requesting additional fields and linked resources from the job object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single job with its default fields and any additional fields requested through _fields
.
List Jobs
Sample Request:
GET /api/v0/jobs HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs \
-H 'authorization: Bearer {access_token}'
GET /jobs
This request returns a list of jobs on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Object
This request supports requesting additional fields and linked objects from the jobs object using the
_fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
against_id | |
against_type | |
paused | |
type | Filter by the type_id of the job. Deprecated, please use job_type . |
job_type | Filter by the job_type_id . |
manager | Filter by the staff_id of the job manager. |
modified_by | Filter by the staff_id of the last staff member to modify the job. |
status | Filter by the status_id . |
rate | Filter by the rate_id . |
affiliation | Filter by the affiliation_id . |
custom_id |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
dated_created |
date_modified |
date_started |
date_commenced |
date_due |
date_completed |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
date_started | |
date_created | |
date_commenced | |
date_due | |
date_completed | |
date_modified | |
date_last_interacted | |
id | |
title | |
standing | |
status | Order by the status_id . |
custom_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
against_id | |
type | Range by the type_id . Deprecated, please use job_type . |
job_type | Range by the job_type_id . |
manager | Range by the staff_id of the manager of the job. |
affiliation | Range by the affiliation_id . |
modified_by | Range by the staff_id of the last staff member to modify the job. |
status | Range by the status_id . |
rate | Range by the rate_id . |
rate_charged | |
contract | Range by the contract_id of any contract associated with the job. |
plan_modified_by | Range by the staff_id of the last staff member to modify the job plan. |
custom_id |
Object Filters
This request supports the following object filters:
Filter | Description |
---|---|
against | Filter by jobs against these objects. |
Searching
This request supports the _search
filter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of job objects containing the default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters or searches used.
Count Jobs
Sample Request:
GET /api/v0/jobs/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/count \
-H 'authorization: Bearer {access_token}'
GET /jobs/count
This request will return a count of jobs in a list defined by any available searches or filters. With no searches or filters this will be a count of all jobs on the deployment. This request returns a single field:
Field | Type | Value |
---|---|---|
count | unsigned | A count of jobs listed. |
List Recent Jobs
Sample Request:
GET /api/v0/jobs/recent HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/recent \
-H 'authorization: Bearer {access_token}'
GET /jobs/recent
This request returns a list of job on the deployment, sorted by the most recently created, that is
in descending order of date_created
.
Configuring the Response
The response to this response may be configured as per GET /jobs
, although any order filters
used will have no impact on the response.
Handling the Response
This request will return a list of job objects on the deployment with their default fields and any
additional fields requested through _fields
, displayed in descending order of date_created
and according to any
pagination parameters, filters, or searches used.
List Latest Modified Jobs
Sample Request:
GET /api/v0/jobs/newest HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/newest \
-H 'authorization: Bearer {access_token}'
GET /jobs/newest
This request returns a list of jobs on the deployment, sorted by the most recently modified, that
is, in descending order of date_modified
.
Configuring the Response
The response to this response may be configured as per GET /jobs
, although any order filters
used will have no impact on the response.
Handling the Response
This request will return a list of job objects on the deployment with their default fields and any
additional fields requested through _fields
, displayed in descending order of date_modified
and according to any
pagination parameters, filters, or searches used.
Get Job Type
Sample request:
GET /api/v0/jobs/types/{job_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_fields=standing,has_custom_id
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/types/{job_type_id} \
-H 'authorization: Bearer {access_token}' \
-d '_fields=standing,has_custom_id'
GET /jobs/types/{job_type_id}
This request returns a job type specified by its unique id.
Configuring the Response
This request supports requesting additional fields and linked objects from the job type object using the
_fields
parameter.
Handling the Response
The response will contain a single job type with its default fields and any additional fields requested through
_fields
.
List Job Types
Sample request:
GET /api/v0/jobs/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_fields=standing,has_custom_id
_filters=standing(active)
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/types \
-H 'authorization: Bearer {access_token}' \
-d '_fields=standing,has_custom_id' \
-d '_filters=standing(active)'
GET /jobs/types
This request returns a list of job types.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the job type using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
standing |
Order Filters
This request supports order filters over the following fields:
Field |
---|
id |
title |
standing |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
Handling the Response
The response will be a list of job types with their default fields and any additional fields requested
through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Get Job Status
Sample Request:
GET /api/v0/jobs/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/statuses/{status_id} \
-H 'authorization: Bearer {access_token}'
GET /jobs/statuses/{status_id}
This request returns the job status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a job status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Job Statuses
Sample request:
GET /api/v0/jobs/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/jobs/statuses \
-H 'authorization: Bearer {access_token}' \
GET/jobs/statuses
This request returns a list of job statuses.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter | Notes |
---|---|
id | |
title | |
standing | |
color |
Order Filters
This request supports order filters over the following fields:
Filter | Notes |
---|---|
id | |
title | |
standing | |
color | |
ordering |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
Handling the Response
The response will be a list of statuses with their default fields and any additional fields requested
through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Job Statuses
Sample Request:
GET /api/v0/jobs/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/statuses/count \
-H 'authorization: Bearer {access_token}' \
GET /jobs/statuses/count
This request will return a count of job statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all job statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed job statuses. |
List Job Milestones
Sample Request:
GET /api/v0/jobs/{job_id}/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id}/milestones \
-H 'authorization: Bearer {access_token}'
GET /jobs/{job_id}/milestones
This request returns a list of milestones of a job, specified by its job_id
. This request is handled
and configured in the same way as GET /milestones
.
Update a Job
Sample Request:
PUT /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /jobs/{job_id}
This request updates and returns a job, specified by its job_id
.
Configuring the Job
The following fields from the job object may be updated with this request:
Filter Name | Notes |
---|---|
title | |
engagement_table | The against_type for the job |
engagement_id | The against_id for the job. |
manager_id | The staff_id of the staff member to be assigned manager. |
status_id | MUST point to a valid job status. |
contract_id | The contract_id of a contract to be linked to the job |
affiliation_id | The affiliation_id of an affiliation to be linked to the job. |
rate_id | |
rate_charged | |
date_due | |
date_created |
Configuring the Response
This request supports requesting additional fields and linked resources from the jobs object through
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single, updated job with its default fields and any additional fields
requested through _fields
.
Create a Job
Sample Request:
POST /api/v0/jobs/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/\
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /jobs
This request creates and returns a new job.
Configuring the Job
The following fields may be set through this request:
Filter Name | Notes |
---|---|
against_type | The against_type for the job. |
against_id | The against_id for the job. |
manager_id | The staff_id of the staff member to be assigned manager. This MUST point to a valid staff. |
type_id* | MUST point to a valid job type. |
title | |
rate_id | |
status_id | MUST point to a valid job status. |
contract_id | The contract_id of a contract to be linked to the job. |
affiliation_id | The affiliation_id of an affiliation to be linked to the job. |
rate_charged | |
date_due | |
date_started | |
date_created | If this is not sent it will default to the current time. |
is_billable | If the job is billable or nonbillable |
Configuring the Response
This request supports requesting additional fields and linked resources from the jobs object through
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single, created job with its default fields and any additional fields
requested through _fields
.
Delete a Job
Sample Request:
DELETE /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
-H 'authorization: Bearer {access_token}'
DELETE /jobs/{job_id}
This request deletes a job from the deployment, specified by its job_id
. This request takes no arguments and returns
no resources.
List a Job's Profile Field Values
See the profiles section for a sample request
GET /jobs/{job_id}/profiles/values
This request returns a list of profile values of a job, specified by its
job_id
. This is the request GET /{object}/{object_id}/profiles/values
, where
the object is "jobs", and whose id is {job_id}
.
List all Profile Field Values on a Job
See the profiles section for a sample request
GET /jobs/profiles/values
This request returns a list of all profile field values on jobs. This
is the request GET /{object}/profiles/values
, where the object is "jobs".
List Jobs Profile Fields
See the profiles section for a sample request
GET /jobs/profiles/fields
This request returns a list of profile fields available for jobs. This is the request
GET/{object}/profiles/fields
where the object is "jobs".
Update a Profile Value on a Job
See the profiles section for a sample request
PUT /jobs/{job_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular job, specified by its job_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "jobs", and
whose value is {job_id}
.
Set a Profile Value on a Job
See the profiles section for a sample request
POST /jobs/{job_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for a "job", specified by its job_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "jobs", and
whose value is {job_id}
.
List Job Extension Fields
See the extension section for an example
GET /jobs/extensions/fields
This request returns a list of extension fields available for any job.
This is the request GET /{object}/extensions/fields
, where the object is
"jobs".
List a Job's Extension Field Values
See the extension section for an example
GET /jobs/{job_id}/extensions/values
This request returns a list of extension values for a job, specified
by its job_id
. This is the request GET /{object}/{object_id}/extensions/values
,
where the object is "jobs", and whose id is the job_id
.
List all Extension Field Values on Jobs
See the extension section for an example
GET /jobs/extensions/values
This request returns a list of extension field values on jobs.
This is the request GET /{object}/extensions/values
, where the object is "jobs".
Update an Extension Field Value on a Job
See the extension section for an example
PUT /jobs/{job_id}/extensions/values/{extension_value_id}
This request updates the value of an extension field value, specified by its
extension_value_id
, of a job, specified by its job_id
. This is the request
PUT{object}/{object_id}/extensions/values/{extension_value_id}
, where the object is "jobs",
and whose id is job_id
Set an Extension Field Value on a Job
Sample Request:
POST /jobs/{job_id}/extensions/fields/{extension_field_id}
This request sets and returns the value of an extension field, specified by its extension_field_id
, of a job,
specified by its job_id
. This request is the request
POST/{object}/{object_id}/extensions/fields/{extension_field_id}
where our object is "jobs"
whose id is job_id
.
List Available Progressions on a Job
See the progressions section for a sample request
GET /jobs/{jobs_id}/progressions
This request returns a list of available progressions for a job, specified
by its job_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "jobs" whose id is job_id
.
Auto Run Progression on a Job
See the progressions section for a sample request
[POST|PUT] /jobs/{jobs_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress a job,
specified by its jobs_id
. This is the request
[POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto
where the object is "jobs" whose id is job_id
.
List a Job's Resource Collections
See the resources (attachments) section for an example
GET /jobs/{job_id}/collections
This request returns a list of resource collections against a job,
specified by its job_id
. This is the request GET /{object}/{object_id}/collections
where the object is "jobs" and hose id is {job_id}
.
Upload a Resource (Attachment) to a Collection on a Job
See the resources (attachments) section for an example
POST jobs/{job_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of a job
specified by its job_id
. This is the request
POST/{object}/{object_id}/collections/{collection_id}/resources
where the
object is "jobs" whose id is {job_id}.
Ledgers
Accelo supports account ledgers, it also allows account ledger integration with certain online accounting systems (e.g. Xero). These account ledgers are described by the API through the ledger
object. For information on viewing, adding and syncing account ledgers from your deployment, please see the support documentation.
The Ledger Object (Beta)
Example ledger
{
"code": "200",
"comment": "Ledger to be used for sales",
"id": "1",
"title": "Sales",
"standing": "active",
"parent_id": "0"
}
The ledger object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the ledger. |
title | string | The ledger's title. |
code | string | The account ledger code |
parent_id | unsigned | The unique identifier of the parent ledger, defaults to "0" is there is no parent |
standing | select | The standing of the ledger, either "active" or "inactive". |
comment | string | Comments on the ledger |
Get Ledger (Beta)
GET /api/v0/ledgers/{ledger_id} HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/ledgers/{ledger_id} \
-H 'authorization: Bearer {access_token}'
GET /ledgers/{ledger_id}
This request returns a ledger identified by its unique ledger_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the ledger object using the _fields
parameter.
Handling the Response
The response wil be the single ledger with its default fields and any additional fields requested through _fields
.
List Ledgers (Beta)
GET /api/v0/ledgers HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/ledgers/ \
-H 'authorization: Bearer {access_token}'
GET /ledgers
This request returns a list of ledgers.
Configuring the Response
Pagination
This request supports all the standard pagination parameters.
Additional fields and Linked Objects
This request supports requesting additional fields and linked objects from the ledger object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
code |
parent_id |
standing |
Order Filters
This request supports the following order filters:
Filter |
---|
id |
code |
parent_id |
standing |
title |
Range Filters
This request supports the following range filters:
Filter |
---|
id |
parent_id |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
code |
Handling the Response
The response will be a list of ledgers with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Ledgers (Beta)
GET /api/v0/ledgers/count HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/ledgers/count \
-H 'authorization: Bearer {access_token}'
GET /ledgers/count
This request will return a count of ledgers in a list defined by any available searches or filters. With no searches or filters this will be a count of all ledgers on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of ledgers listed. |
Milestones
Resource URI:
/api/vo/milestones
Milestones are the steps on the road to a Job's (Project's) completion. They define the schedule of the job, and contain the budget for their respective portion of the job. For information on accessing milestones through the deployment, see the support documentation, milestones may also be imported through the deployment, see again the support documentation for information.
Deleting, creating, and updating milestones is only available through the deployment on the project planning screen, see the support documentation for more information.
The Milestone Object
Example milestone object:
{
"date_modified": "1494912868",
"date_completed": "1494911355",
"status": "4",
"date_due": "1495072800",
"id": "1",
"description": "Initial planning",
"standing": "complete",
"date_created": "1494286008",
"job": "2",
"rate": "3",
"title": "A milestone",
"date_started": "1494208800",
"object_budget": "12",
"milestone_object_budget": "12",
"rate_charged": "125.00",
"ordering": "1",
"parent": "0",
"manager": "21",
"date_commenced": "1494286232"
}
The milestone object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the milestone. |
title | string | A name for the milestone. |
description | string | A description of the milestone. |
ordering | integer | An integer representing the milestone's ordering on the deployment. |
parent | unsigned | The unique identifier of the parent milestone. If there is not parent this has the value "0". |
date_created | unix ts | The date the milestone was created. |
date_modified | unix ts | The date the milestone was last modified. |
date_started | unix ts | The date the milestone is scheduled to start. |
date_commenced | unix ts | The date the milestone was started, that is, when the standing was changed from "pending". |
date_due | unix ts | The date the milestone is scheduled to be completed. |
date_complete | unix ts | The date the milestone was completed. |
job | unsigned or object | The job (project) the milestone has been created for. |
manager | unsigned or object | The staff member assigned to manage the project. |
status | unsigned or object | The status of the milestone. |
standing | string | The standing of the milestone. This is part of the status object |
rate | unsigned or object | The rate associated with the milestone. |
rate_charged | decimal | The rate charged for billable work within this milestone. This is part of the rate object. |
milestone_object_budget | unsigned or object | The object budget associated with the milestone. |
object_budget | unsigned or object | Deprecated please use milestone_object_budget . |
milestone_object_schedule | unsigned or object | The object schedule linked to the milestone. |
Get Milestone
Sample Request:
GET /api/v0/milestones/{milestone_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/{milestone_id} \
-H 'authorization: Bearer {access_token}'
GET /milestones/{milestone_id}
This request returns a single milestone, identified by its milestone_id
.
Configuring the Response
This request supports requesting additional fields and linked resource from the milestone object
using the _fields
parameter.
Handling the Response
The response will be the single milestone with its default fields and any additional fields
requested through _fields
.
List Milestones
Sample Request:
GET /api/v0/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones \
-H 'authorization: Bearer {access_token}'
GET /milestones
This request returns a list of milestones on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports request additional fields and linked objects from the milestone object
using the _fields
.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
ordering | |
job | Filter by the job_id . |
parent | Filter by the milestone_id of the parent milestone. |
manager | Filter by the staff_id of the manager. |
rate | Filter by the rate_id . |
object_budget | Filter by the object_budget_id . |
status | Filter by the status_id . |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_modified |
date_created |
date_started |
date_commenced |
date_due |
date_completed |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
job | Range by the job_id . |
manager | Range by the staff_id of the manager. |
status | Range by the status_id . |
modified_by | Range by the staff_id of the last staff to modify the milestone. |
rate | Range by the rate_id . |
rate_charged |
Searching
This request supports the _search
parameter to search over the following fields:
Filter Name |
---|
title |
Handling the Response
The response will be a list of milestones containing their default
fields and any additional fields requested through _fields
, and displayed according to any pagination parameters,
filters, or searches used.
Count Milestones
Sample Request:
GET /api/v0/milestones/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/count \
-H 'authorization: Bearer {access_token}'
GET /milestones/count
This request will return a count of milestones in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestones on the deployment. This request does not return a response object, just a single value:
Field | Type | Description |
---|---|---|
response | unsigned | A count of milestones listed. |
Get Milestone Status
Sample Request:
GET /api/v0/milestones/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/statuses/{status_id} \
-H 'authorization: Bearer {access_token}' \
GET /milestones/statuses/{status_id}
This request returns the milestone status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a milestone status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Milestone Statuses
Sample Request:
GET /api/v0/milestones/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/statuses \
-H 'authorization: Bearer {access_token}'
GET /milestones/statuses
This request returns a list of milestone statuses on the deployment.
Configuring the Response
Pagination
This request supports the standard pagination requests.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the milestone status object through
the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Count Milestone Statuses
Sample Request:
GET /api/v0/milestones/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/statuses/count \
-H 'authorization: Bearer {access_token}' \
GET /milestones/statuses/count
This request will return a count of milestone statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestone statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed milestone statuses. |
List a Milestone's Profile Field Values
See the profiles section for a sample request
GET /milestones/{milestone_id}/profiles/values
This request returns a list of profile values of a milestone,
specified by its milestone_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "milestones", and whose id is milestone_id
.
List all Profile Field Values on a Milestone
See the profiles section for a sample request
GET /milestones/profiles/values
This request returns a list of all profile field values on milestones.
This is the request GET /{object}/profiles/values
, where the object is "milestones".
List Milestone Profile Fields
See the profiles section) for a sample request
GET /milestones/profiles/fields
This request returns a list of profile fields available for milestones.
This is the request GET /{object}/profiles/fields
where the object is "milestones".
Update a Profile Field Value on a Milestone
See the profiles section for a sample request
PUT /milestones/{milestone_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular milestone, specified by its milestone_id
. This is the request
PUT/{object}/{object_id}/profiles/values/{profile_value_id}
where the object is
"milestones", and whose id is the milestone_id
.
Set a Profile Field Value on a Milestone
See the profiles section for a sample request
POST /milestones/{milestone_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for a milestone, specified by its milestone_id
. This is the request
POST /{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is
"milestones", and whose value is milestone_id
.
List Available Progressions on a Milestone
See the progressions section for a sample request
GET /milestones/{milestone_id}/progressions
This request returns a list of available progressions for a milestone,
specified by its milestone_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "milestones" whose id is milestone_id
.
Auto Run a Progression on a Milestone
See the progressions section for a sample request
PUT|POST /milestones/{milestone_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress a milestone,
specified by its milestone_id
. This is the request
[POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto
where theobject is "milestone" whose id is milestone_id
.
Object Budgets
Resource URI:
api/v0/object_budgets
Object budgets are budgets against a specific object, for example a budget against an issue or a milestone. They are able to track the time and money spent by staff and on services, as well as expenses and the cost of materials.
The Object Budget
Example object budget:
{
"charged": "45.84",
"service_time": "0",
"material_price_subtotal": "56.10",
"service_time_estimate": "0",
"service_price_subtotal_estimate": "425.00",
"billable": "1320",
"expense_price": "0.00",
"material_cost_subtotal": "35.50",
"remaining_subtotal": "180",
"object_table": "job",
"service_price_subtotal": "0.00",
"charged_subtotal": "70.84",
"logged": "1500",
"object_id": "2",
"logged_subtotal": "2100",
"is_billable": "yes",
"billable_subtotal": "1920",
"material_cost": "35.50",
"id": "11",
"service_price_estimate": "0.00",
"nonbillable": "180",
"service_price": "0.00",
"material_price": "56.10",
"service_time_subtotal_estimate": "10800",
"nonbillable_subtotal": "180"
}
The object budget resource contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the object budget. |
against_type | string | The type of object the object budget is against. |
against_id | unsigned | The unique identifier of the object the object budget is against. |
object_table | string | The type of object the object budget is against. Deprecated please use "against_type". |
object_id | unsigned | The unique identifier of the object the object budget is against.Deprecated please use "against_type". |
object | string | The API URI of the object the object budget is against. This is "{against_type} /{against_id} " |
is_billable | select | Either "yes" or "no", whether time logged against the object is billable. |
service_time_estimate | integer | The estimated total time for services against the object, in seconds. |
service_time | integer | The total time logged for services against the object, in seconds. |
service_time_subtotal_estimate | integer | The estimated total time for services against the object and its children, in seconds. |
service_price_estimate | decimal | An estimate for the total price of services against the object. |
service_price | decimal | The total price of services against the object. |
service_price_subtotal_estimate | decimal | An estimate for the total price of services against the object and all of its children. |
service_price_subtotal | decimal | The total price of services against the object and all of its children. |
expense_price | decimal | The total prices of expenses for the object. |
material_cost | decimal | The total cost of materials for the object. |
material_cost_subtotal | decimal | the total cost of materials for the object and all its children. |
material_price | decimal | The total price of materials for the object. |
material_price_subtotal | decimal | The total price of materials for the object and all its children. |
billable | integer | The total billable time logged against the object, in seconds. |
billable_subtotal | integer | The total billable time logged against the object and all its children, in seconds. |
nonbillable | integer | The total nonbillable time logged against the object, in seconds. |
nonbillable_subtotal | integer | The total nonbillable time logged against the object and all its children, in seconds. |
logged | integer | The total time logged against the object, in seconds. That is, the sum of billable and nonbillable . |
logged_subtotal | integer | The total time logged against the object and all its children, in seconds. |
charged | decimal | The total cost charged against the object. |
charged_subtotal | decimal | The total cost charged against the object, and all its children. |
remaining_subtotal | decimal | If object_table is tasks the remaining budget for the task, otherwise the sum of the remaining subtotal of all the object's children's. |
The Item Template Object
Example template object:
{
"code": "260",
"cost": "0.0000",
"cost_rate_id": null,
"description": "Other Revenue GST on Income",
"expense_type_ledger": "20",
"id": "8",
"ledger_id": "20",
"line_item_ledger": "20",
"price": "0.0000",
"price_rate_id": null,
"quantity": "1.0000",
"standing": "active",
"tax_id": "12",
"title": "Other Revenue GST on Income",
"type": "service"
}
These are templates for expenses, materials, and services. These templates allow you to easily add items to your budgets. The template object contains:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the template. |
title | string | The title of the template. |
description | string | A description of the template. |
price | decimal | The sale price. |
type | select | Either 'expense', 'material', or 'service', the type of item described by the template. |
code | string | The code given for the template |
standing | select | Either 'active' or 'inactive', the standing of the template. |
quantity | decimal | The default quantity used with this template. |
cost | Decimal | The cost (or purchase price) of the template. |
cost_rate_id | unsigned | The id of the cost rate associated with the template (if any). |
cost_tax_id | unsigned | The id of the cost tax (or purchase tax) associated with the template. |
cost_ledger_id | unsigned | The id of the cost ledger (or purchase ledger) associated with the template. |
price | decimal | The sale price of the template. |
price_rate_id | unsigned | The id of the price rate associated with the template (if any). |
tax_id | unsigned | The id of the sale tax associated with the template. |
ledger_id | unsigned | Then id of the sale ledger associated with the template. |
line_item_ledger | unsigned or object | The ledger associated with the template. |
expense_type_ledger | unsigned or object | Where type is expense , the ledger associated with the template. |
cost_tax | unsigned or object | The cost tax (or purchase tax) associated with the template. |
cost_ledger | unsigned or object | The cost ledger (or purchase ledger) associated with the template. |
The Material Object
Example material object:
{
"against_id": "201",
"against_type": "milestone",
"budget_item_template": "0",
"budget_item_template_id": "0",
"cost": "24.0000",
"date_created": "1457523796",
"id": "10",
"material_item_ledger": "0",
"material_item_ledger_id": null,
"ordering": "0",
"price": "0.9900",
"quantity": "1.0000",
"tax_id": null,
"title": "Design Tools",
"contract_period_id": null,
}
These describe instances of material templates as items on a budget. These contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the material. |
title | string | A title for the material. |
against_type | string | The type of object the material has be added against. |
against_id | unsigned | The id of the object the material has been added against. |
quantity | decimal | The quantity of the material added. |
cost | decimal | The cost (or purchase price) of the material. |
price | decimal | The sale price of the material |
date_created | unix ts | The date the material was created. |
material_ledger_id | unsigned | The unique identifier of the ledger used by the material. |
material_template_id | unsigned | The unique identifier of the item template the material is based off. |
tax_id | unsigned | The unique identifier of the tax on the material. |
material_ledger | unsigned or object | The ledger used by the material. |
material_template | unsigned or object | The item template the material is based off. |
ordering | unsigned | A number describing the order the material is displayed. |
contract_period_id | unsigned | The unique identifier for the contract period the material is linked to. |
The Service Object
Example service object:
{
"against_id": "22",
"against_type": "contract",
"budget_item_template": "8",
"budget_item_template_id": "8",
"id": "92",
"service_item_ledger": "20",
"service_item_ledger_id": "20",
"tax_id": "12"
}
These describe instances of service templates as items on a budget. These contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the service. |
against_type | string | The type of object the service has been added against. |
against_id | unsigned | The id of the object the service has been added against. |
service_ledger_id | unsigned | The unique identifier of the ledger used by the service. |
service_template_id | unsigned | The unique identifier of the template used by the service. |
tax_id | unsigned | The unique identifier of the tax used by the service. |
service_ledger | unsigned or object | The ledger used by the service. |
service_template | unsigned of object | The template used by the service. |
Get Object budget
Sample Request:
GET /api/v0/object_budgets/{object_budget_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/object_budgets/{object_budget_id} \
-H 'authorization: Bearer {access_token}'
GET /object_budgets/{object_budget_id}
This request returns an object budget identified by its object_budget_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the object budget using the _fields
parameter.
Handling the Response
The response will be the single object budget with its default fields and any additional fields requested through _fields
.
List Object Budgets
Sample Request:
GET /api/v0/object_budgets HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/object_budgets \
-H 'authorization: Bearer {access_token}'
GET /object_budgets
This request returns a list of object budgets on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the object budget using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
against_id |
against_type |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
Object Filters
This request supports the following object filters:
Filter Name |
---|
against |
Handling the Response
The response will be a list of object budgets with their default fields and any additional fields requested through _fields
, and displayed according to any pagination requests used.
Count Object Budgets
Sample Request:
GET /api/v0/object_budgets/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/object_budgets/count \
-H 'authorization: Bearer {access_token}'
GET /object_budgets/count
This request will return a count of object budgets in a list defined by any available searches or filters. With no searches or filters this will be a count of all object budgets on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of object budgets listed. |
List Item Templates
Sample request:
GET /api/v0/object_budgets/templates HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/object_budgets/templates \
-H 'authorization: Bearer {access_token}' \
GET /object_budgets/templates
This request returns a list of item templates on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the
item template object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name | Notes |
---|---|
id | |
type | |
standing | |
ledger_id | |
cost_ledger_id | |
cost_tax_id | |
tax_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
price | |
cost |
Order Filters
This request supports the following order filters:
Filter Name | Notes |
---|---|
id | |
cost | |
title | |
price | |
standing |
Empty Filters
This request supports empty filters over the following fields:
Filter Name | Notes |
---|---|
title |
Searching
This request supports the _search
parameter
to search over the following fields:
Field |
---|
title |
description |
code |
Handling the Response
The response will be a list of item templates with their default fields and any additional
fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
List Materials
Sample request:
GET /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
-H 'authorization: Bearer {access_token}' \
GET /object_budgets/materials
This request returns a list of materials on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the material object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name | Notes |
---|---|
id | |
against_id | |
against_type | |
material_ledger_id | |
material_template_id | |
quantity | |
cost | |
price | |
tax_id | |
contract_period_id |
Date Filters
This request supports date filters over the following fields:
Filter Name | Notes |
---|---|
date_created |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
cost | |
price | |
quantity |
Order Filters
This request supports the following order filters:
Filter Name | Notes |
---|---|
id | |
quantity | |
price | |
cost | |
date_created |
Searching
This request supports the _search
parameter
to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of materials with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
List Services
Sample request:
GET /api/v0/object_budgets/services HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/object_budgets/services \
-H 'authorization: Bearer {access_token}' \
GET/object_budgets/services
This request returns a list of services on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the service object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name | Notes |
---|---|
id | |
against_id | |
against_type | |
service_template_id | |
service_ledger_id | |
tax_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id |
Object Filters
This request supports the following object filters:
Filter Name | Notes |
---|---|
against |
Order Filters
This request supports the following order filters:
Filter Name | Notes |
---|---|
id |
Handling the Response
The response will be a list of services with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Update a Material
Sample request:
PUT /api/v0/object_budgets/materials/{material_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
quantity=10
price=20
curl -X PUT \
https://{deployment}.api.accelo.com/api/v0/object_budgets/materials/{material_id} \
-H 'authorization: Bearer {access_token}' \
-d 'quantity=10'
-d 'price=20'
PUT /object_budgets/materials/{material_id}
This request updates and returns the material with the given material_id
Configuring the Response
The following fields may be used to update the material:
Field Name | Notes |
---|---|
title | |
quantity | |
price | |
cost | |
template_id |
Configuring the Response
This request supports requesting additional fields and linked objects from the material object
using the _fields
parameter.
Handling the Response
The response will be the update material with its default fields and any additional fields requested through_fields
.
Create a Material
Sample request:
POST /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
authorization: Bearer {access_token}
against_type=contract_period
against_id=123
title=Shovels for digging
quantity=12
cost=10
price=2
template_id=4
curl -X POST \
https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
-H 'authorization: Bearer {access_token}' \
-d 'against_type=contract_period' \
-d 'against_id=123' \
-d 'title=Shovels for digging' \
-d 'quantity=12' \
-d 'cost=10' \
-d 'price=2' \
-d 'template_id=4'
POST /object_budgets/materials
This request creates and returns a material.
Configuring the Response
The following fields may be set when creating the material:
Field Name | Notes |
---|---|
against_type | Supports: 'job', 'issue', 'milestone', 'contract_period' |
against_id | |
title | |
quantity | |
price | |
cost | |
template_id |
Handling the Response
The response will be the newly created material with its default fields and any additional fields requested through_fields
.
Object Schedules
An object schedule is a schedule against a specific object. For example, the schedule on a given task.
The Object Schedule
Sample JSON object:
{
"date_planned_due": "1362618000",
"against_id": "24",
"date_planned_start": "1362358800",
"id": "113",
"against_type": "task"
}
The object schedule budget contains the following
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the object schedule. |
against_id | unsigned | The unique identifier of the object the schedule is against. |
against_type | string | The type of object the schedule is against. |
date_planned_start | unix ts | The planned start date. |
date_planned_due | unix ts | The planned due date. |
date_predicted_start | unix ts | The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations. |
date_predicted_end | unix ts | The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations. |
date_commenced | unix ts | The actual commenced date. |
date_completed | unix ts | The actual completed date. |
date_user_estimated_start | unix ts | The date the assignee has scheduled to start the work. |
date_user_estimated_due | unix ts | The date the assignee has scheduled to complete the work. |
date_targeted_start | unix ts | The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations. |
date_targeted_due | unix ts | The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations. |
date_fixed_start | unix ts | The fixed start date. |
date_fixed_due | unix ts | The fixed deadline for the due date. |
There are no endpoints associated with this object.
Payments
Resource URI
/api/v0/payments
Payments made, for example against an invoice, are stored under the payments
object through the API. Attached to these payments are methods, receipts, and the currency used.
The Payment Object (Beta)
Sample payment object:
{
"payment_method": "2",
"receipt_id": "28945",
"id": "30507",
"currency_id": "0",
"direction": "credit",
"created_by_staff_id": "1055",
"method_id": "2",
"amount": "79.00",
"against_id": "31347",
"date_created": "1496887498",
"payment_currency": "0",
"against_type": "account_invoice",
"payment_receipt": "28945"
}
The payment object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the payment. |
receipt_id | unsigned | The unique identifer of the receipt associated with the payment. |
amount | decimal | The amount paid through the payment. |
currency_id | unsigned | The unique identifier of the currency used. |
method_id | unsigned | The unique identifier of the payment method. |
against_id | unsigned | The unique identifier of the object the payment is against. |
against_type | string | The type of object the payment is against. |
date_created | unix ts | The date the payment was created. |
created_by_staff_id | unsigned | The unique identifier of the staff member who entered the payment. |
direction | select | Either "debit" or "credit", defaults to "credit". |
payment_currency | unsigned or object | The currency used for the payment. |
payment_method | unsigned or object | The method of the payment. |
payment_receipt | unsigned or objects | The receipt for the payment. |
The Payment Receipt Object (Beta)
Sample receipt object:
{
"owner_type": "staff",
"owner_id": "1055",
"id": "28945",
"affiliation_id": "152348",
"amount": "79.00",
"date_received": "1496887498"
}
Where a payment object stores the information on a payment made against a single object, a receipt may be issued for a single payment, or a collection of payments. For information on accessing receipts from the deployment and receiving receipts from an integrated accounting system see the support documentation. The receipt object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the receipt. |
amount | decimal | The amount the receipt is for. |
affiliation_id | unsigned | The unique id of the affiliation associated with the receipt. |
owner_id | unsigned | The unique identifier of the owner. |
owner_type | select | Either "staff" or "contact", the type of owner of the receipt. |
date_received | unix ts | The date the receipt was received. |
The Payment Method Object (Beta)
Sample payment method object:
{
"id": "2",
"title": "Visa",
"standing": "active"
}
The payment method describes the different methods payment may be given, for example via cash or via mastercard. Payments from online billing systems should automatically update the method, see the support documentation for more information. The payment method object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the method. |
title | string | A name for the method. |
standing | select | Either "active" or "inactive", the standing of the method. |
The Currency Object (Beta)
Sample currency object:
{
"rate": "1",
"id": "1",
"symbol": "$",
"title": "Australian Dollars",
"code": "AUD"
}
The different currencies that may be handled by your deployment are stored in the currency object, this contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the currency. |
title | string | A name for the currency. |
code | string | A short code for the currency. |
symbol | character | The symbol used for the currency. |
rate | decimal | The rate, generally pulled from an external accounting system. |
Get Payment (Beta)
Sample request, list payments against a specific invoice:
GET /payments/{payment_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
filters=against(account_invoice(133))
curl -X GET \
https://{deplyoment}.api.accelo.com/payments/{payment_id} \
-H 'authorization: Bearer {access_token}' \
-d 'filters=against(account_invoice(133))
GET /payments/{payment_id}
This request returns a payment identified by its unique payment_id
.
Configuring the Response
This request supports requesting additional fields and linked object from the payment object using the _fields
parameter.
Handling the Response
The response will be the single payment object with its default fields and any additional fields requested through _fields
.
List Payments (Beta)
Sample request:
GET /payments/ HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/payments/ \
-H 'authorization: Bearer {access_token}'
GET /payments
This request returns a list of payments on the deployment.
Configuring the Response
Pagination
This request supports all the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked object from the payment object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
currency_id |
method_id |
receipt_id |
created_by_staff_id |
against_id |
against_type |
Date Filters
This request supports date filters over the following fields:
Field |
---|
date_created |
Order Filters
This request supports the following order filters:
Filter |
---|
id |
currency_id |
method_id |
receipt_id |
created_by_staff_id |
amount |
date_created |
direction |
against_id |
Range Filters
This request supports the following range filters:
Filter |
---|
id |
currency_id |
method_id |
receipt_id |
created_by_staff_id |
amount |
against_id |
Object Filters
This request supports the following object filters:
Filter | Description |
---|---|
against | Filter by the object the payment is against. |
Handling the Response
The response will be a list of payments with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters or filters used.
Count Payments (Beta)
Sample request:
GET /payments/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/payments/count \
-H 'authorization: Bearer {access_token}'
GET /payments/count
This request will return a count of payments in a list defined by any available searches or filters. With no searches or filters this will be a count of all payments on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of payments listed. |
Profiles
Profile fields are objects used for tracking extra information from your Accelo deployment. See the support documentation for further information about profile fields. Currently, custom profile fields are supported on the following objects:
The Profile Field Object
Example profile field:
{
"link_type": "company",
"required": "no",
"parent_id": "0",
"description": "These are the companies opening hours in the form \"HH-HH\", use 24h time.",
"id": "12",
"lookup_type": null,
"confidential": "no",
"field_name": "Opening Hours",
"restrictions": "all",
"field_type": "text",
"exported": "no"
}
These are objects describing the custom fields on the deployment, they contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the profile field. |
field_name | string | A name for the profile field. |
field_type | select | The type of the profile field. This can be "text", "integer", "decimal", "date", "date_time", "currency", " lookup", "structure", "select", "multi_select", or "hyperlink". |
parent_id | unsigned | The unique identifier of the parent profile field. If there is no parent this has a value of "0". |
link_type | string | The type of object this profile field is against. For example "contact". |
required | select | Either "yes" or "no", whether this profile field is required for the object it is against. |
restrictions | select | Who is able to edit the value of this field. May be one of "all", "edit", "process", "admin". For example, if set to "process", only users with "process" permission for custom fields will be able to edit this field. See the support documentation for information on setting permissions. |
exported | select | Either "yes" or "no", whether this profile field will be included when you export the against object. |
lookup_type | string | When field_type is "lookup", this will contain the lookup type, e.g. "company". |
options | array | When field_type is either "select" or "multi_select" this will contain the possible values. |
confidential | select | Either "yes" or "no", whether this is a confidential profile field. These are profile fields viewable only within confidential relationships, see the support documentation for more information. |
description | string | A description of the profile field. |
The Profile Value Object
Example profile value object:
{
"value_type": null,
"id": "128",
"field_type": "multi_select",
"value": "one, two",
"values": ["one", "two"],
"date_modified": "1495669367",
"field_name": "Implementation Phases",
"field_id": "12",
"modified_by": "14",
"link_type": "issues",
"link_id": "45"
}
These are objects describing a value of a given profile field, identified by the
field_id
, they contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the profile field value. |
field_type | string | The profile field type for this value, see the profile field object for possible values. |
field_name | string | The name for the profile field. |
value_type | string | For fields of type lookup this is the type of the lookup object. For example "company", "contact". Otherwise it is null . |
value | dynamic | The value of the profile field. The type will change according to the field_type , for example if the field type is "date" this will be a unix ts. If it's a "multi_select" this will be all values joined by a comma. e.g, "one, two" for ["one", "two"] |
values* | array | When the field type is "multi_select", this will contain an array of the selected values. e.g, ["one", "two"] |
date_modified | unix ts | The date this profile field value was last modified. |
modified_by | unsigned or object | The staff member who last modified this profile field value. |
field_id | unsigned | The unique identifier of the profile field this value is for. |
link_type | string | The object the profile value was created against. |
link_id | unsigned | The unique identifier of the object the profile value is against. |
* The values
field is only returned when the field_type
is "multi_select".
When it's "multi_select", it's returned by default.
List Profile Fields
Sample Request:
GET /api/v0/{issues}/profiles/fields HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/profiles/fields \
-H 'authorization: Bearer {access_token}'
GET /{object}/profiles/fields
This request returns a list of profile fields available for the given object.
Configuring the Response
This request supports requesting additional fields and linked objects from the profile field object
using the _fields
parameter.
Handling the Response
This response will be a list of profile fields with their default fields, and any
additional fields requested through _fields
.
List Object Profile Values
Sample Request:
GET /api/v0/issues/{issue_id}/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/profiles/values \
-H 'authorization: Bearer {access_token}'
GET /{object}/{object_id}/profiles/values
This request returns a list of profile values for the given object
of identified by object_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the profile value object
using the _fields
parameter.
Handling the Response
This response will be a list of profile values with their default fields, and any
additional fields requested through _fields
.
List Profile Values
Sample Request:
GET /api/v0/issues/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/profiles/values \
-H 'authorization: Bearer {access_token}'
GET /{object}/profiles/values
This request returns a list of profile values for the given object
.
Configuring the Response
Pagination
This request supports all of the pagination parameters
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the profile value object
using the _fields
parameter.
Basic Filter
This request supports basic filters over the following fields:
Filter Name |
---|
unified |
field_id |
link_id |
link_type |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
field_id |
link_id |
link_type |
value_type |
date_modified |
Range Filters
This request supports range filters over the following fields:
Filter Name |
---|
field_id |
link_id |
Searching
This request supports the _search
parameter to search over the following fields:
Filter Name |
---|
title |
Update a Profile Value
Example, a business has changed its opening hours:
curl -X put \
https://{deployment}.api.accelo.com/api/v0/companies/{company_id}/profiles/values/128 \
-H 'authorization: Bearer {access_token}' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'value=09-18'
PUT /{object}/{object_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular object, specified by its object_id
, of a particular type, specified by object
.
Configuring the Profile Value
This request updates the value
of a profile value, since this object is dynamic the field we send will depend on the
type of value
:
Field Name | Type | Description |
---|---|---|
value_int | int | If field_type is "integer", update the value with this integer. |
value_date | string | If field_type is "date", update the value with this string. This field supports values as both unix timestamps and in ISO8601 form, for ease of readability we recommend ISO8601. |
value_id | integer | If field_type is "lookup", update the value with this integer, representing an object id. |
value_type | string | If field_type is "lookup", update the value_type with this string. |
value | string | If field_type is none of the above, update the value with this string. |
Configuring the Response
This request supports requesting additional fields and linked objects from the profile value object
using the _fields
parameter.
Handling the Response
The response will be the single, updated profile value with its default fields, and any
additional fields requested through _fields
.
Create a Profile Value
Example, a company has give us their business hours:
curl -X post \
https://{deployment}.api.accelo.com/api/v0/companies/{company_id}/profiles/fields/{profiles_field_id}
-H 'authorization: Bearer {access_token}' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'value=16-20'
POST /{object}/{object_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
. The object whose profile field is to be update is identified by object_id
and object
.
Configuring the Profile Value
This request accepts the same fields as the previous request, that is, it takes only the relevant value field(s). The relevant value field is required for this request.
Configuring the Response
This request supports requesting additional fields and linked objects from the profile value object
using the _fields
parameter.
Handling the Response
The response will be the newly created profile value with its default fields, and any
additional fields requested through _fields
.
Progressions
Progressions allow you and your team to intelligently move records between statuses. The Public API currently supports automatic progressions, which skip over details requiring user interaction. These automatic progressions are currently supported over the following resources:
1. tasks
2. companies
3. jobs
4. prospects
5. issues
6. milestones
7. affiliations
8. contracts
9. contacts
10. expenses
NOTE: For a user to perform an interaction on a progression they MUST have the process permission or be a manager (or assignee for tasks) of the object. The list progression actions endpoint will NOT return progressions on objects that do not meet these requirements.
See the support documentation for information on progressions, including how to define new progressions on your deployment.
The Progression Object
Example progression object:
{
"standing": "paused",
"color": "pink",
"title": "Paused",
"id": "8"
}
The progressions object contains the following fields and linked objects:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the progression. |
title | string | A name for the progression. |
status | object | The status the progression will move to. Note, the status object here does not contain the start field. |
The Progression History
The history of progressions taken by an object (equivalently, the history of statuses that it has taken) is tracked via the progression history. Each of these objects tracks the status the object was moved to, by whom, and when. These objects contain:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the history object |
to_id | unsigned | The id of the status the object was progressed to. |
to_title | string | The title of the status the object was progressed to. |
against_type | string | The type of object the progression was made against. |
against_id | unsigned | The unique identifier of the object the progression was made against. |
modified_by | unsigned | The unique identifier of the staff who progressed the object. |
date_modified | unix ts | The date the object was progressed. |
Using Progressions
Progressions may be used to perform an automatic status update, this is a three step process:
1. Determine which status progressions are available for the given object, this is achieved by a GET
request which retrieves a list of available progressions.
2. From this list identify the appropriate progressions for your action, keep track of the progression_id
.
3. Use this progression id
in a POST
request to run a status update.
List Available Progressions
Example request:
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id}/progressions \
-H 'authorization: Bearer {access_token}'
GET /{resource}/{resource_id}/progressions
This request returns a list of progressions available for a given resource, which may be one of the types above, specified by its unique resource id.
Handling the Response
This request will return a list of progressions available for the object given, displayed in ascending order of their progression_id
.
List Progression History
Sample request:
GET /api/v0/progressions/history HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/progressions/history \
-H 'authorization: Bearer {access_token}' \
GET/progressions/history
This request returns a list of progression history objects.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the progression history
object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter | Description |
---|---|
id | |
against_type | |
against_id | |
modified_by |
Order Filters
This request supports the following order filters:
Filter | Description |
---|---|
id | |
date_modified |
Range Filters
This request supports range filters over the following fields:
Field | Description |
---|---|
id |
Object Filters
This request supports the following object filters:
Filter Name | Description |
---|---|
against | Filter by histories against these objects. |
Date Filters
This request supports date filters over the following fields:
Filter Name | Description |
---|---|
date_modified |
Handling the Response
The response will be a list of progression history objects with their default fields and any
additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Get Progression History
Sample request:
GET /api/v0/progressions/history/{progression_history_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/progressions/history/{progression_history_id} \
-H 'authorization: Bearer {access_token}' \
GET/progressions/history/{progression_history_id}
This request returns a single progression history object specified by its unique id.
Count Progression Histories
Sample request:
GET /api/v0/progressions/history/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/progressions/history/count \
-H 'authorization: Bearer {access_token}' \
GET/progressions/history/count
This request will return a count of progression histories in a list defined by any available
searches or filters. See GET /progressions/history
for a list of available filters. With
no searches or filters this will be a count of all progression histories. The response contains a single fie
Field | Type | Description |
---|---|---|
count | Unsigned | A count of progression histories listed |
Auto Run a Progression
Example request, we wish to move our job to "complete" from the above request we found that the progression with id "8" will do this:
curl -X post \
https://{deployment}.api.accelo.com/api/v0/progressions/8/auto \
-H 'authorization: Bearer {access_token}' \
-H 'content-type: application/x-www-form-urlencoded'
[POST|PUT] /{resource}/{resource_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress the status of the object, specified by its unique id. The object may be any one of those listed above.
Handling the Response
The response will contain the single updated object. Please see the appropriate resource endpoint for handling and configuring the response.
Prospects (Sales)
Resource URI:
api/v0/prospects
Prospects (also known as Sales) are a way to keep track of your sales and deals. See the support documentation for more information on the full potential of these, and also information on setting up and configuring them via the deployment.
The Prospect Object
Example prospects object
{
"affiliation": "75",
"progress": "0.2500",
"staff_bookmarked": "0",
"status": "2",
"comments": "Lets get these shoes out the door",
"manager": "2",
"date_created": "1494293760",
"contact": "75",
"date_actioned": "1494252000",
"success": "no",
"id": "9",
"value": "1000.00",
"type": "1",
"value_weighted": "20",
"standing": "active",
"date_due": "1494424800",
"date_last_interacted": "1494263000",
"title": "Super Sonic Shoes (SSS)",
"prospect_probability": "5",
"weighting": "3"
}
The prospect object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the prospect. |
title | string | A name for the prospect. |
date_created | unix ts | The date the prospect was created. |
date_actioned | unix ts | The date the prospect was actioned. |
date_due | unix ts | The due date for the prospect. |
date_last_interacted | unix ts | The date the prospect was last interacted with. |
date_modified | unix ts | The date the prospect was last modified. |
weighting | integer | A rating of the prospect, this is on a scale of 1-5, with 5 being the highest rating. |
value | decimal | The currency value of the prospect. |
success | select | Either "yes" or "no", whether the sale has been successfully completed, or won. |
comments | string | Comments, description etc. of the Prospect. |
progress | decimal | A decimal representation of the "progress %" associated with the current standing of the prospect. See the support documentation on setting up progressions for information on this field. |
value_weighted | integer | A value incorporating the progress and weighting values to describe the prospect. |
staff_bookmarked | boolean | Whether the current user has bookmarked the prospect on the deployment. |
won_by_id | unsigned | The id of the staff who won the prospect. 'null' if the prospect has not been won. |
cancelled_by_id | unsigned | The id of the staff who cancelled the prospect. 'null' if the prospect has not been cancelled. |
abandoned_by_id | unsigned | The id of the staff who abandoned the prospect. 'null' if the prospect has not been abandoned. |
contact | unsigned or object | The contact associated with the prospect |
manager | unsigned or object | The staff assigned to manage the prospect. |
type | unsigned or object | The prospect type. Deprecated, please use prospect_type . |
prospect_type | unsigned or object | The prospect type of the prospect. |
status | unsigned or object | The status of the prospect. |
standing | string | The standing of the prospect, this is part of the status object |
prospect_probability | unsigned or object | The prospect probability of the prospect. |
affiliation | unsigned or object | The affiliation associated with the prospect. |
The Prospect Type
Example prospect type object:
{
"title": "Partner",
"id": "1",
"parent": "0",
"ordering": "3",
"standing": "active"
}
You may group prospect using prospect types to reflect the different actions taken on different types of prospect. See the support documentation for information on prospect types. The prospect type contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the prospect type. |
title | string | A name for the prospect type. |
parent | unsigned | The unique identifier of the parent prospect type. If there is no parent this has the value "0". |
standing | select | The standing of the prospect type, may be either "active" or "inactive". |
ordering | integer | An integer representing the prospect type's ordering as displayed on the deployment. |
The Prospect Probability
Prospect probabilities are customizable fields you may use to reflect how likely you are to win a sale. See the support documentation for more information. The prospect probability contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the prospect probability. |
title | string | A name for the prospect probability. |
value | integer | The value assigned to the prospect probability. |
ordering | integer | An integer representing the prospect probability's ordering as displayed on the deployment. |
The Prospect Status
Example Prospect Status object:
{
"standing": "active",
"start": "yes",
"ordering": "1",
"id": "2",
"title": "Qualified",
"color": "yellow"
}
Prospect Statuses may be used to track the progress of a Prospect. These may be configured on the deployment, see the support documentation for more information. The status object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the status. |
title | string | A name for the status. |
standing | string | A string describing the standing of the prospect. |
color | string | The color of the status shown on the deployment. |
start | select | Either "yes" or "no", whether an prospect may be created with this status. |
ordering | unsigned | A number describing the order of the status on the deployment. |
Get Prospect
Sample Request:
GET /api/v0/prospects/{prospect_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id} \
-H 'authorization: Bearer {access_token}'
GET /prospects/{prospect_id}
This request returns a single prospect, identified by its prospect_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the prospect object
using the _fields
parameter.
Handling the Response
The response will be the single prospect with its default fields and any additional fields
requested via _fields
.
List Prospects
Sample Request:
GET /api/v0/prospects HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects \
-H 'authorization: Bearer {access_token}'
GET /prospects
This request returns a list of prospects on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the prospects object
using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
weighting | |
success | |
affiliation | Filter by the affiliation_id . |
manager | Filter by the staff_id of the manager. |
type | Filter by the type_id . Deprecated, please use prospect_type . |
prospect_type | Filter by the prospect_type_id . |
status | Filter by the status_id . |
prospect_probability | Filter by the prospect_probability . |
company | Filter by the company_id . |
won_by_id | Filter by the id of the staff who won the prospect. |
cancelled_by_id | Filter by the id of the staff who cancelled the prospect. |
abandoned_by_id | Filter by the id of the staff who abandoned the prospect. |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_created |
dated_actioned |
date_due |
date_modified |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
date_actioned | |
date_created | |
date_due | |
date_last_interacted | |
date_modified | |
title | |
id | |
status | Order by the status_id . |
standing |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
weighting | |
value | |
progress | |
value_weighted | |
affiliation | Range over the affiliation_id . |
manager | Range over the staff_id of the manager. |
type | Range over the type_id . Deprecated, please use prospect_type . |
prospect_type | Range over the prospect_type_id . |
status | Range over the status_id . |
Searching
This request supports the _search
parameter to search over the following fields:
Filter Name |
---|
title |
Handling the Response
This request will return a list of prospects with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Prospects
Sample Request:
GET /api/v0/prospects/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/count \
-H 'authorization: Bearer {access_token}'
GET /prospects/count
This request will return a count of prospects in a list defined by any available searches or filters. With no searches or filters this will be a count of all prospects on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the prospects listed. |
Get Prospect Status
Sample Request:
GET /api/v0/prospects/{prospect_id}/status HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id}/status \
-H 'authorization: Bearer {access_token}'
GET /prospects/{prospect_id}/status
This request returns the prospect status of a prospect, identified by its prospect_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the prospect status object
using the _fields
parameter.
Handling the Response
The response will be the single prospect status with its default fields and any additional
fields requested through _fields
.
List Prospect Statuses
Sample Request:
GET /api/v0/prospects/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/statuses \
-H 'authorization: Bearer {access_token}'
GET /prospects/statuses
This request returns a list of statuses for prospects on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of prospect statuses with their default fields and
any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
List Prospect Types
Sample Request:
GET /api/v0/prospects/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/types \
-H 'authorization: Bearer {access_token}'
GET /prospects/types
This request returns a list of prospect types on the deployment.
The _filters
parameter is set to standing_not(inactive)
by default.
Configuring the Request
Pagination
This request supports all of the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the prospect type
object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
standing |
Order Filters
This request supports order filters over the following fields:
Field |
---|
id |
title |
standing |
ordering |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
Handling the Response
The response will be a list of prospect types with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters used.
Get Prospect Probability
Sample Request
GET /api/v0/prospects/probabilities/{probability_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/probabilities/{probability_id} \
-H 'authorization: Bearer {access_token}'
GET /prospects/probabilities/{probability_id}
This request returns the given probability specified by its probability_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the prospect probability
using the _fields
parameter.
Handling the Response
The response will be the single prospect probability with its default fields and any
additional fields requested through _fields
.
List Prospect Probabilities
Sample Request
GET /api/v0/prospects/probabilities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/probabilities \
-H 'authorization: Bearer {access_token}'
GET /prospect/probabilities
This request returns a list of all probabilities on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the probability object
using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
value |
Order Filters
This request supports the following order filters:
Filter Name |
---|
title |
ordering |
value |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of prospect probabilities with their default fields and any
additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Count Prospect Probabilities
Sample Request
GET /api/v0/prospects/probabilities/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/probabilities/count \
-H 'authorization: Bearer {access_token}'
GET /prospects/probabilities/count
This request will return a count of prospect probabilities in a list defined by any available searches of filters. With no searches of filters this will be a count of all prospects on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the probabilities listed. |
Update a Prospect
Sample Request:
PUT /api/v0/prospects/{prospect_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id} \
-H 'authorization: Bearer {access_token}'
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /prospects/{prospects_id}
This request updates and returns a prospect, specified by its prospect_id
.
Configuring the Prospect
The following fields may be updated through this request:
Field | Type | Notes |
---|---|---|
title | string | |
comments | string | |
value | decimal | |
success | select | If provided, must be one of 'yes' or 'no'. |
affiliation_id | int | MUST point to a valid affiliation. Updating this may relocate the prospect to a new company. |
staff_id | int | Update the staff_id of the manager. MUST point to a valid staff. |
date_due | unix ts or ISO8601 String | |
weighting | int | Must be between 0 and 5. |
progress | int | Must be between 0 and 100. |
probability_id | int | |
status_id | int | Must point to a valid prospect status. Warning This will bypass any progressions and should only be used deliberately when automating tasks. Please use progressions otherwise. |
See the prospect object for more information on these fields.
Configuring the Response
This request supports requesting additional fields and linked objects from the prospect object
using the _fields
parameter.
Handling the Response
The response will be the single, updated prospect object with its default fields and any
additional fields requested through _fields
.
Create a Prospect
Sample Request:
POST /api/v0/jobs HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
title='New Prospect'
affiliation_id=1421
type_id=3
curl -X POST \
https://{deployment}.api.accelo.com/api/v0/jobs/ \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'title=New Prospect' \
-d 'affiliation_id=1421' \
-d 'type_id=1'
POST /prospects
This request creates and returns a new prospect
Configuring the Prospect
All fields available when updating a prospect may also be set here, with the following additions:
Field | Type | Notes |
---|---|---|
title | string | |
affiliation_id | int | Must point to a valid affiliation. |
type_id | int | Must point to a valid prospect type. |
status_id | int | The starting status for the progression. Defaults to the status with the lowest ordering . Note this will skip any progressions. |
Handling the Response
The response will be the newly created prospect with its default fields and any additional fields requested through
_fields
Delete a Prospect
Sample Request:
DELETE /api/v0/prospects/{prospect_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Content-Type: application/x-www-form-urlencoded
curl -X delete \
https://{deployment}.api.accelo.com/api/v0/prospects/{prospect_id} \
-H 'authorization: Bearer {access_token}'
DELETE /prospects/{prospect_id}
This request will delete the prospect identified by its prospect_id
. This request takes no parameters and returns no
resources.
List a Prospect's Profile Field Values
See the profiles section for a sample request
GET /prospects/{prospect_id}/profiles/values
This request returns a list of profile values of a prospect,
specified by its prospect_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "prospects", and whose id is prospect_id
.
List all Profile Field Values on a Prospect
See the profiles section for a sample request
GET /prospects/profiles/values
This request returns a list of all profile field values on prospects.
This is the request GET /{object}/profiles/values
, where the object is "prospects".
List Prospect Profile Fields
See the profiles section for a sample request)
GET /prospects/profiles/fields
This request returns a list of profile fields available for prospects.
This is the request GET /{object}/profiles/fields
where the object is "prospects".
Update a Profile Field Value on a Prospect
See the profiles section for a sample request
PUT /prospects/{prospect_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular prospect, specified by its prospect_id
. This is the request
PUT/{object}/{object_id}/profiles/values/{profile_value_id}
where the object is
"prospects", and whose id is the prospect_id
.
Set a Profile Field Value on a Prospect
See the profiles section for a sample request
PUT|POST /prospects/{prospect_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for a prospect, specified by its prospect_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is
"prospects", and whose value is prospects_id
.
List Prospect Extension Fields
See the extension section for an example
GET /prospects/extensions/fields
This request returns a list of extension fields available for any prospect.
This is the request GET/{object}/extensions/fields
, where the object is "prospects".
List a Prospect's Extension Field Values
See the extension section for an example
GET /prospects/{prospect_id}/extensions/values
This request returns a list of extension values for a prospect,
specified by its prospect_id
. This is the request GET /{object}/{object_id}/extensions/values
,
where the object is "prospects", and whose id is prospect_id
.
List all Extension Field Values on Prospects
See the extension section for an example
GET /prospects/extensions/values
This request returns a list of extension field values on prospects.
This is the request GET /{object}/extensions/values
, where the object is "prospects".
Update an Extension Field Value on a Prospect
See the extension section for an example
PUT /prospects/{prospect_id}/extensions/values/{extension_value_id}
This request updates the value of an extension field value, specified by its
extension_value_id
, of a prospect, specified by its prospect_id
. This is the request
PUT{object}/{object_id}/extensions/values/{extension_value_id}
, where the object is
"prospect", and whose id is prospect_id
Set an Extension Field Value on a Prospect
Sample Request:
POST /prospects/{prospect_id}/extensions/fields/{extension_field_id}
This request sets and returns the value of an extension field, specified by its extension_field_id
, of a prospect
, specified by its prospect_id
. This request is the request
POST/{object}/{object_id}/extensions/fields/{extension_field_id}
where our object is
"prospects" whose id is prospect_id
.
List Available Progressions on a Prospect
See the progressions section for a sample request
GET /prospects/{prospect_id}/progressions
This request returns a list of available progressions for a prospect,
specified by its prospect_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "prospects" whose id is prospect_id
.
Auto Run a Progression on a Prospect
See the progressions section for a sample request
PUT|POST /prospects/{prospect_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress a prospect,
specified by its prospect_id
. This is the request
[POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto
where the object is "prospect" whose id is prospect_id
.
List a Prospect's Resource Collections
Sample Request:
GET /prospects/{prospect_id}/collections
This request returns a list of resource collections against an prospect,
specified by its prospect_id
. This is the request GET /{object}/{object_id}/collections
where the object is "prospects" and hose id is {prospect_id}
.
Upload a Resource (Attachment) to a Collection on a Prospect
Sample Request:
POST /prospects/{prospect_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of an
prospect specified by its prospect_id
. This is the request
POST/{object}/{object_id}/collections/{collection_id}/resources
where the
object is "prospects" whose id is {prospect_id}
.
Purchases
Object URI:
/api/v0/purchases
Track the purchases made when completing a job, issue or contract. More information can be found on the support documentation
The Purchase Object
The purchase object contains the following fields:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier for the purchase. |
title | string | The title of the purchase. |
owner_id | unsigned | The identifier of the staff who owns the purchase. Defaults to "0". |
creator_id | unsigned | The identifier of the staff who created the invoice. Defaults to "0". |
affiliation_id | unsigned | The identifier of the affiliation associated with the purchase. Defaults to "0". |
amount | decimal | The monetary amount of the purchase. Defaults to "0.00". |
tax | decimal | The tax on the purchase. Defaults to "0.00". |
total | decimal | The total value of the purchase: amount + tax . Defaults to "0.00". |
date_purchased | unix ts | The date of the purchase. Defaults to "0". |
Get Purchase
GET /purchases/{purchase_id}
Sample request:
GET /api/v0/purchases/{purchase_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
CURL -X get \
https://{deployment}.api.accelo.com/api/v0/purchases/{purchase_id} \
-H 'authorization: Bearer {access_token}'
This request returns a purchase identified by its purchase_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the purchase object
using the _fields
parameter. This request also supports
breadcrumbs.
Handling the Response
The response will be the purchase with its default fields and any additional fields
requested through _fields
.
List Purchases
GET /purchases
GET /api/v0/purchases/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
CURL -X get \
https://{deployment}.api.accelo.com/api/v0/purchases/ \
-H 'authorization: Bearer {access_token}'
This request returns a list of purchases on the deployment.
Configuring the Response
Pagination
This request supports all of the pagination parameters.
Additional Fields and Linked Objects
This request also supports requesting additional fields and linked objects from the purchase object
using the _fields
parameter, as well as breadcrumbs.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
owner_id |
creator_id |
affiliation_id |
Date Filters
This request supports the following date filters:
Filter |
---|
date_purchased |
Order Filters
This request supports order filters over the following fields:
Field |
---|
amount |
tax |
total |
id |
owner_id |
creator_id |
affiliation_id |
Range Filters
This request supports range filters over the following fields:
Field |
---|
amount |
tax |
total |
id |
owner_id |
creator_id |
affiliation_id |
Searching
This request supports the _search
parameter to search over teh following fields:
Field |
---|
title |
Handling the Response
The response will be a list of purchases with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Purchases
GET /purchases/count
GET /api/v0/purchases/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
CURL -X get \
https://{deployment}.api.accelo.com/api/v0/purchases/count \
-H 'authorization: Bearer {access_token}'
This request will return a count of purchases in a list defined by any available searches or filters. With no searches or filters this will return a count of all purchases on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the purchases listed. |
List a Purchase's Profile Field Values
See the profiles section for a sample request
GET /purchases/{purchase_id}/profiles/values
This request returns a list of profile field values on a purchase
specified by its purchase_id
. This is the request GET/{object}/{object_id}/profiles/values
,
where the object is "purchases" whose id is {purchase_id}
List all Profile Field Values on Purchases
See the profiles section for a sample request
GET /purchases/profiles/values
This request returns a list of all profile field values on purchases
This is the request GET /{object}/profiles/values
, where the object is "purchases".
List Purchase Profile Fields
See the profiles section for a sample request
GET /purchases/profiles/fields
This request returns a list of profile fields available for any purchase
This is the request GET /{object}/profiles/fields
, where the object is "purchases".
Quotes
Resource URI:
/api/v0/quotes
Quotes in Accelo allow you to generate and edit your quotes and proposals. See the support documentation for information on quotes.
The Quote Object
Example quote object:
{
"created_by": "14",
"conclusion": "<p><b>Looking forward to starting.</b></p>",
"service_time_total": "3600",
"created_by_staff_id": "14",
"status_id": "1",
"notes": "Here are some notes",
"date_expiry": null,
"title": "Website Redesign",
"portal_access": "0",
"affiliation": "98",
"service_price_total": "300.50",
"manager": "14",
"status": "1",
"terms": "<p><i>These are some terms and conditions</i></p>",
"against": "prospects/9",
"introduction": "<h1>We're quite happy to perform the work.</h1>",
"contact": "98",
"material_price_total": "41.10",
"affiliation_id": "98",
"total_price": "341.60",
"manager_id": "14",
"date_created": "1494311070",
"standing": "draft",
"against_id": "9",
"against_type": "prospect",
"id": "3"
}
The quote object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the quote. |
title | string | A name for the quote. |
against_type | string | The type of object the quote is against. |
against_id | unsigned | The unique identifier of the object the quote is against. |
against | string | The API URI of the object the quote is against. |
notes | string | Additional notes on the quote. |
portal_access | boolean | Whether the quote has been published with a client portal link. |
affiliation_id | unsigned | The unique identifier of the affiliation associated with the quote. |
affiliation | unsigned or object | The affiliation associated with the quote |
date_created | unix ts | The date the quote was created. |
date_expiry | unix ts | The date the quote is set to expire. |
manager_id | unsigned | The unique identifier of the staff member who is set to manage the quote. |
manager | unsigned or object | The staff member who is assigned to manage the quote. |
status_id | unsigned | the unique identifier of the quote status of the quote. |
status | unsigned or object | The quote status |
standing | string | The standing of the quote. This is part of the status object. |
created_by_staff_id | unsigned | The unique identifier of the staff member who created the quote. |
created_by | unsigned or object | The staff member who created the quote. |
introduction | string | HTML for a the introduction of the published quote. |
conclusion | string | HTML for the conclusion of the published quote. |
terms | string | HTML for the terms and conditions of the published quote. |
service_price_total | decimal | The total price for all services associated with the quote. |
service_time_total | integer | The total time, in seconds, of services for the quote. |
material_price_total | decimal | The total price for all materials associated with the quote. |
total_price | decimal | The total price of the quote; service_price_total + material_price_total |
Get Quote
Sample Request:
GET /api/v0/quotes/{quote_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes/{quote_id} \
-H 'authorization: Bearer {access_token}'
GET /quotes/{quote_id}
This request returns a single quote, identified by its quote_id
.
Configuring the Response
This request supports requesting additional fields and linked resources from the quote object using the _fields
parameter.
Handling the Response
The response will be the single quote object with its default fields and any additional fields requested through _fields
.
List Quotes
Sample Request:
GET /api/v0/quotes HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes \
-H 'authorization: Bearer {access_token}'
GET /quotes
This request returns a list of quotes on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Resources
This request supports requesting additional fields and linked resources from the quote object using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
affiliation | Filter by affiliation_id . |
manager | Filter by the manager_id . |
status | Filter by the status_id . |
against_type | |
against_id | |
created_by | Filter by the created_by_staff_id . |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_created |
date_expiry |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
date_created |
date_expiry |
service_price_total |
service_time_total |
material_price_total |
total_price |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
against_id | |
manager | Range by the manager_id . |
affiliation | Range by the affiliation_id . |
status | Range by the status_id . |
created_by | Range by the created_by_staff_id . |
service_price_total | |
service_time_total | |
material_price_total | |
total_price |
Object Filters
This request supports the following object filters:
Filter | Description |
---|---|
against | Filter by quotes against these objects. |
Searching
This request supports the _search
request over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of quotes with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Quotes
Sample Request:
GET /api/v0/quotes/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes/count \
-H 'authorization: Bearer {access_token}'
GET /quotes/count
This request will return a count of quotes in a list defined by any available searches or filters. With no searches or filters this will be a count of all quotes on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the quotes listed |
Update a Quote
Sample Request:
PUT /api/v0/quotes/{quote_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes/{quote_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /quotes/{quote_id}
This request updates and returns a quote, identified by its quote_id
.
Configuring the Quote
The following fields from the quote object may be updated with this request:
Filter Name | Notes |
---|---|
title | |
affiliation_id | |
manager_id | |
date_expiry | |
notes | |
introduction | |
conclusion | |
terms_and_conditions | Update the HTML of the terms of the published quote. |
client_portal_access | Update the portal_access field. |
Configuring the Response
This request supports requesting additional fields and linked objects from the quote object using the _fields
parameter.
Handling the Response
The response will be the single, updated quote with its default fields and any additional fields requested through _fields
Create a Quote
Sample Request:
POST /api/v0/quotes HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /quotes
This request creates and returns a quote.
Configuring the Quote
This request accepts the same fields as PUT /quotes/{quote_id}
, with the addition of the following required fields:
Filter Name |
---|
title |
against_id |
against_type |
Configuring the Response
This request supports requesting additional fields and linked objects from the quote object using the _fields
parameter.
Handling the Response
The response will be the single, created quote object with its default fields and any additional fields requested through _fields
.
Get Quote Status
Sample Request:
GET /api/v0/quotes/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes/statuses/{status_id} \
-H 'authorization: Bearer {access_token}' \
GET /quotes/statuses/{status_id}
This request returns the quote status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a quote status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Quote Statuses
Sample Request:
GET /api/v0/quotes/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes/statuses \
-H 'authorization: Bearer {access_token}'
GET /quotes/statuses
This request returns a list of statuses for quotes on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The request will return a list of quote statuses with their default fields and
any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Count Quote Statuses
Sample Request:
GET /api/v0/quotes/statuses/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/quotes/statuses/count \
-H 'authorization: Bearer {access_token}'
GET /quotes/statuses/count
This request will return a count of quote statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all quote statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed quote statuses. |
List Resource Collections
See the resources (attachments) section for an example
GET /quotes/{quote_id}/collections
This request returns a list of resource collections against an quote, specified by its quote_id
. This is the request GET /{object}/{object_id}/collections
where the object is "quotes" and hose id is {quote_id}
.
Upload a Resource (Attachment)
See the resources (attachments) section for an example
POST /quotes/{quote_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of an quote specified by its quote_id
. This is the request POST /{object}/{object_id}/collections/{collection_id}/resources
where the object is "quotes" whose id is {quote_id}
.
Rates
Resource URI:
/api/v0/rates
Rates define the hourly rate paid for work done. They may be set up and modified from the deployment, see the support documentation for information.
The Rate Object
Example rate object:
{
"object": "staff,issue,job,milestone,contract_period",
"standing": "active",
"charged": "175.00",
"title": "Consulting",
"id": "6"
}
The rate object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the rate. |
title | string | A name for the rate. |
charged | decimal | The hourly rate for this rate. |
standing | select | Either "active" or "inactive", the standing of the rate. |
object | string | A list of objects this rate is applicable to. |
Get Rate
Sample Request:
GET /api/v0/rates/{rate_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/rates/{rate_id} \
-H 'authorization: Bearer {access_token}'
GET /rates/{rate_id}
This request returns a rate specified by its rate_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the rate object using the _fields
parameter.
Handling the Response
The response will be the single rate with its default fields and any additional fields requested through _fields
.
List Rates
Sample Request:
GET /api/v0/rates HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/rates \
-H 'authorization: Bearer {access_token}'
GET /rates
This request returns a list of rates on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the rate object using the _fields
parameter.
Handling the Response
The response will be a list of rates with the default fields and any additional fields requested through _fields
, displayed according to any pagination parameters used.
Count Rates
Sample Request:
GET /api/v0/rates/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/rates/count \
-H 'authorization: Bearer {access_token}'
GET /rates/count
This request will return a count of rates in a list defined by any available searches or filters. With no searches or filters this will be a count of all rates on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of rates listed. |
Referrals
Resource URI:
/api/v0/referrals
Referrals provide a link between an object and the object it was created from. An example of this would be a job that has been created from a prospect.
The Referral Object
Example referral object:
{
"id": "29",
"referrer_id": "88",
"referrer_type": "job",
"against_id": "84",
"against_type": "issue",
"updated_by": "1",
"date_updated": "1448519478",
"created_by": "2",
"date_created": "1448519478",
}
The referrals object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the referral. |
referrer_id | unsigned | The id of the object which made the referral. |
referrer_type | string | The type of the object which made the referral. eg. 'prospect'. |
against_id | unsigned | The id of the object which was created via referral. |
against_type | string | The type of the object which was created via referral. eg. A 'job' which was created via a 'prospect'. |
updated_by | unsigned | The id of the staff member who last updated this referral. |
date_updated | unix ts | The date that this referral was last updated. |
created_by | unsigned | The identifier of the user who created the referral. |
date_created | unix ts | The date that the referral was created. |
Get Referral
Sample Request:
GET /api/v0/referrals/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/referrals/{id} \
-H 'authorization: Bearer {access_token}'
GET /referrals/{id}
This request returns a single referral, specified by its id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the referral
using the _fields
parameter.
Handling the Response
The response will be the single requested referral with its default fields and any
additional fields requested through _fields
.
List Referrals
Sample Request:
GET /api/v0/referrals HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/referrals \
-H 'authorization: Bearer {access_token}'
GET /referrals
This request returns a list of referrals on the deployment.
Configuring the Request
Pagination
This request accepts all the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
against_type |
against_id |
referrer_type |
referrer_id |
created_by |
updated_by |
probability |
standing |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
created |
updated |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
date_created |
date_updated |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id |
Handling the Response
The response will be a list of referrals on the Deployment, with their default fields and
any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Count Referrals
Sample Request:
GET /api/v0/referrals/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/referrals/count \
-H 'authorization: Bearer {access_token}'
GET /referrals/count
This request will return a count of referrals defined by any available searches of filters. With no searches or filters this will be a count of all referrals on the deployment. This request returns a single field.
Field | Type | Description |
---|---|---|
count | unsigned | A count of referrals listed. |
Requests
Resource URI:
/api/v0/requests
These allow you to track request from clients sent to your shared company addresses, such as "@support" or "@sales" addresses. See the support documentation for more information on requests.
The Request Object
Sample request object:
{
"thread_id": "1039",
"id": "31",
"source": null,
"standing": "pending",
"request_priority": "1",
"date_created": "1494823725",
"date_modified" : "123456789",
"type_id": "2",
"claimer": "23",
"body": "This is a support request, it is urgent!",
"title": "Urgent support request",
"priority_id": "1",
"type": "2",
"affiliation_id": "77",
"lead_id": "0",
"affiliation": "77",
"claimer_id": "23"
}
The request object contains the following:
Field | Types | Description |
---|---|---|
id | unsigned | A unique identifier for the request. |
title | string | A name for the request. |
body | string | The body of the request. |
standing | select | The standing of the request ,may be either "pending", "open", "converted", or "closed". |
source | string | Either "email" or null , whether the source of the request was an external email. |
lead_id | unsigned | A unique identifier for the sender, if they are a lead. If a request comes from an unknown sender they will be marked as a "lead". |
thread_id | unsigned | The unique identifier of the activity thread the request is associated with. |
date_created | unix ts | The date the request was created. |
date_modified | unix ts | The date the request was last updated. |
type_id | unsigned | The unique identifier of the request type. |
type | unsigned or object | The request type. |
priority_id | unsigned | The unique identifier of the request priority. |
priority | unsigned or object | Deprecated, please use request_priority |
request_priority | unsigned or object | The request priority. |
claimer_id | unsigned | The unique identifier of the staff who has claimed the request. |
claimer | unsigned or object | The staff member who has claimed the request. |
affiliation_id | unsigned | The unique identifier of the affiliation associated with the request. |
affiliation | unsigned or object | The affiliation associated with the request. |
The Request Type
Example request type object:
{
"unresolved_count": "21",
"id": "2",
"subscribed": 0,
"status": "active",
"title": "Support"
}
The request type object allows you to assign a type to each request, making them easier to track and categorize. By default there are two types "support" and "sales", you may set up as many different types as you like from your deployment, see the support documentation for more information. This object contains the following:
Fields | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the request type. |
title | string | A name for the request type. |
standing | select | The standing of the request type, either "active" or "inactive". |
The Request Priority
Issue priorities help you keep track of what needs to be done. They may be set up from the deployment, they contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the priority. |
title | string | A name for the priority. |
color | select | The color of the priority when displayed on the deployment. The colors, in order of increasing urgency a "grey", "blue", "green", "orange", "red". |
factor | unsigned | A number representing the urgency of the priority. 5 is "Extreme", 1 is "None". |
Request Threads
Sample request thread:
{
"title": "Urgent support request",
"date_last_responded": 1494823725,
"id": 31,
"date_created": "1494823725",
"number_of_activities": 1,
"senders": [
{
"id": 77,
"type": "affiliation"
}
],
"thread_id": 1039,
"standing": "pending",
"date_latest_external_interaction": 1494823725,
"claimer": {
"type": "staff",
"id": 23
},
"type": {
"id": 2,
"type": "request_type"
},
"body": "This is a support request, it is urgent!",
"affiliation": {
"type": "affiliation",
"contact": {
"type": "contact",
"id": 77
},
"id": 77,
"company": {
"id": 54,
"type": "company"
}
}
}
Since request are communications made from the deployment, they each have an associated activity. We can then track the communication made on a request as a thread of activities, although we want a bit more information than is given in activity threads; the request thread contains the following:
Field | Type | Description |
---|---|---|
thread_id | unsigned | The unique activity_id of the original request. |
id | unsigned | The id of the request. |
title | string | As in the request object. |
body | string | As in the request object. |
standing | select | As in the request object. |
number_of_activities | integer | The number of activities in the thread. |
date_created | unix ts | as in the request object. |
date_last_responded | unix ts | The date of the latest response to the request (from either the client or a staff member). |
date_last_external_interaction | unix ts | the date of the last interaction on the request by a client. |
claimer | object | An object describing the claimer of the request, this object contains a "type" field, describing the type of object, and an "id" field giving its identifier. |
type | object | The request type of the request. |
senders | array | An array of senders of the original request, each defined by a "type" an an "id". |
affiliation | object | As in the request object. |
Request Thread Unresponded Counts
Example object:
{
"subscribed": 1,
"unresolved_count": "22",
"id": "2",
"title": "Support",
"status": "active"
}
These objects track the number of unresponded requests against each request type, they may be requested with request threads, see the list threads request. The unresponded counts object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier for the request type. |
title | string | The name of the request type. |
status | string | The standing of the request as in the type object. |
unresolved_count | unsigned | A count of unresolved requests of the given type. |
subscribed | boolean | Either "1" or "0", whether the user has subscribed to the given request type through their preferences. |
Get Request
Sample Request:
GET /api/v0/requests/{request_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/requests/{request_id} \
-H 'authorization: Bearer {access_token}'
GET /requests/{request_id}
This request returns a request specified by its request_id
.
Configuring the Response
This request supports requesting additional fields and linked from the request object using the _fields
parameter.
Handling the Response
The response will be the single request with its default fields and any additional fields requested through _fields
.
List Requests
Sample Request:
GET /api/v0/requests HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/requests \
-H 'authorization: Bearer {access_token}'
GET /requests
This request returns a list of requests on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the request object using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
affiliation | Filter by affiliation_id . |
type | Filter by the type_id . |
priority | Deprecated, please use request_priority |
request_priority | Filter by the priority_id . |
lead | Filter by the lead_id . |
claimer_id |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_created |
date_modified |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
date_created |
date_modified |
Range Filters
This request supports range filters over the following fields:
Notes | |
---|---|
id | |
type | Range over the type_id . |
progressed_by | Range over the staff_id of the last staff member to progress the standing of the request. |
lead | Range over the lead_id . |
affiliation | Range over the affiliation_id . |
priority | Deprecated, please use request_priority |
request_priority | Range over the affiliation_id . |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of requests with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used. s
Count Requests
Sample Request:
GET /api/v0/requests/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/requests/count \
-H 'authorization: Bearer {access_token}'
GET /requests/count
This request will return a count of requests in a list defined by any available searches or filters. With no searches or filters this will be a count of all requests on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of requests listed. |
List Request Threads
Sample Request:
GET /api/v0/requests/threads HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/requests/threads \
-H 'authorization: Bearer {access_token}'
GET /requests/threads
This request returns a list of request threads on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
standing | |
request_type_id | Filter by the type_id . |
interact_from_staff | Filter by the staff_id of staff who have interacted with the request. |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_created |
Boolean Filters
this request also supports a special kind of filter, the boolean filter. These filters take boolean arguments, the supported filters are:
Filter Name | Notes |
---|---|
request_is_claimed | Filter by whether or not a request is claimed. |
show_inactive_type | Whether or not to show requests from inactive types. By default these are not shown. |
order_by_date_created | Whether to order in ascending order of date_created . |
order_by_desc_latest_external_interaction | Whether to order in ascending order of date_last_external_interaction . |
List Unresponded Counts
Sample request:
GET /api/v0/requests/threads HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_include_unresponded_counts = 1
curl -X get \
https://{deployment}.api.accelo.com/api/v0/requests/threads \
-H 'authorization: Bearer {access_token}' \
-d '_include_unresponded_counts = 1'
This request also supports a flag, include_unresponded_counts
which may be either '0' or '1'. If set to '1' this returns an additional array, unresponded_counts
Handling the Response
The response will be an array of request threads labeled "requests", and an array of linked objects labeled "linked_objects". The "linked_objects" array is an array of objects linked to the requests in the "requests" array. Any filters used will be applied to the elements of the "request" array.
List Request Types (Beta)
Sample Request:
curl -X get \
https://{deployment}.api.accelo.com/api/v0/requests/types \
-H 'authorization: Bearer {access_token}' \
GET /api/v0/requests/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
GET /requests/types
This request returns a list of request_type
objects, which contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the object. |
title | string | A title for the object. |
status | select | Either "active" or "inactive" the status of the type. |
unresolved_count | integer | A count of unresolved requests of this type on the deployment. |
subscribed | boolean 1/0 | Whether the current user is subscribed to this request type. |
Note this is different to the request type object.
Handling the Response
This request does not accept pagination, filtering, or searching. The response will be a list of request_type
objects on the deployment.
Update a Request
Sample Request:
PUT /api/v0/requests HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/requests \
-H 'authorization: Bearer {access_token}'
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /requests/{request_id}
This request updates and returns a request identified by its request_id
.
Configuring the Request
Values for the following fields may be updated through this request:
Field Name |
---|
title |
body |
type_id |
lead_id |
affiliation_id |
priority_id |
source |
standing |
claimer_id |
Configuring the Response
This request supports requesting additional fields and linked objects from the request object using the _fields
parameter
Handling the Response
The response will be the single, updated request with its default fields and any additional fields requested through _fields
.
Create a Request
Example request:
curl -post \
https://al-interns.api.accelo.com/api/v0/requests \
-H 'authorization: Bearer {access_token}' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'title=I%20request%20support%20your%20website' \
-d 'body=how%20do%20I%20use%20it%3F' \
-d 'type_id=2' \
-d 'affiliation_company_name=Jack%20and%20Co.' \
-d 'affiliation_company_phone=%2B13%203234%202324' \
-d 'affiliation_contact_firstname=Jack' \
-d 'affiliation_contact_surname=Black' \
-d 'affiliation_email=jack.black%40jack-and-co.com' \
-d 'affiliation_phone=64%20444%20444%20444'
Request using JSON:
curl -X post \
https://al-interns.api.accelo.com/api/v0/requests \
-H 'authorization: Bearer H3idpjeiXO9FaS4C5IA3phXnYQYCT5bVmJRXruVCcpb7PdApC5K8Rrss-mO17wPi' \
-H 'content-type: application/json' \
-d '{
"type_id": 2,
"title": "The website has become unresponsive",
"body": "Your home page is timing out?",
"affiliation": {
"contact" : {
"firstname": "Jack",
"surname": "Black"
},
"company": {
"name": "Jack and Co.",
"phone": "+13 3234 2324"
},
"email": "jack.black@jack-and-co.com",
"phone": "64 444 444 444"
}
}'
POST /requests
This request creates and returns a request. Since a request requires an affiliation, and request may not necessarily come from known contacts, using this request you may also create a contact/affiliation, see.
Configuring the Request
The following fields may be set through this request:
Field Name | Notes |
---|---|
title | |
body | |
type_id | |
affiliation_id | If an affiliation_id is not available please follow the proceeding steps. |
priority_id | |
source | May either be "email" or "null". |
lead_id |
Handling a Lack of Affiliation
If no affiliation data is available we will attempt to link the given data to a known affiliation, otherwise we will create one. There are three minimum sets of information we can use to create an affiliation:
Given a Firstname and a Surname
If an affiliation exists which exactly matches these two names, we will link it. Otherwise, we will create a company and contact with the name "firstname
surname
", and then create an affiliation to link the two.
Given a Firstname and a Company Name
If there is no match the company name, a new company with this name will be used, then a contact under this company will be created using the firstname supplied, finally an affiliation will be created to link the two.
Given an Email Address
If there is no match, we will attempt to extract a name from the email provided. Next, a company will be made with the provided email as the name, then a contact will be made under this company, whose name would be the name extracted from the email. Finally an affiliation would link the two.
The following fields may be used to send this information:
Create a new request without an affiliation: The JSON method
{
"type_id": 2,
"subject": "The website has become unresponsive",
"title": "Your home page is timing out?",
"affiliation": {
"contact" : {
"firstname": "Jack",
"surname": "Black"
},
"company": {
"name": "Jack and Co.",
"phone": "+13 3234 2324"
},
"email": "jack.black@jack-and-co.com",
"phone": "64 444 444 444"
}
}
Field Name |
---|
affiliation_email |
affiliation_phone |
affiliation_contact_id |
affiliation_contact_firstname |
affiliation_contact_surname |
affiliation_company_id |
affiliation_company_name |
affiliation_company_phone |
You may also send contact and company information as a JSON payload. Ensure that the content type is set to application/json
in this case. For example here we have created a contact, company and affiliation in handling a request.
Configuring the Response
The request supports requesting additional fields and linked objects from the request object using the _fields
parameter.
Handling the Response
The response will be the new, single, request with its default fields and any fields requested through _fields
.
Resources (Attachments)
Resource URI:
api/v0/resources
Resources (or attachments) are files uploaded to the deployment. Collections are used to group resources on the deployment, they are similar to a folder system for resources.
The Resource Object
Example resource object:
{
"id": "4",
"title": "Quote 14 May 2015.pdf",
"date_created": "1431565085",
"mimetype": "application/pdf",
"filesize": "13678"
}
The resource object contains the details on an uploaded file:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the resource. |
title | string | A name for the resource. |
date_created | unix ts | The date the resource was uploaded. |
mimetype | string | The MIME type of the resource. For example "application/pdf", "image/png". |
filesize | integer | The size of the file in bytes. |
collection_id | unsigned | The unique identifier of the collection the resources belongs to. |
owner_type | string | The type of object that uploaded the resource. |
owner_id | unsigned | The unique identifier of the object that uploaded the resource. |
The Collection Object
Example collection object:
{
"id": "48",
"title": "1. Sign up quote"
}
The collection object describes a collection against a specific object, it contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the collection. |
title | string | A name for the collection. |
against_type | string | The type of object the collection is against. |
against_id | unsigned | The unique identifier of the object the collection is against. |
Get Resource
Sample Request:
GET /api/v0/resources/{resource_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/resources/{resource_id} \
-H 'authorization: Bearer {access_token}'
GET /resources/{resource_id}
This request returns a resource identified by its resource_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the resource objects using the _fields
parameter.
Handling the Response
The response will be the resource with its default fields and any additional fields requested through _fields
.
List Resources
Sample Request:
GET /api/v0/resources HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/resources \
-H 'authorization: Bearer {access_token}'
GET /resources
This request returns a list of resources on the deployment.
Configuring the Response
Pagination
This request supports all the pagination requests.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the resource object using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
mimetype | |
activity_id | Filter by the activity_id of the activity through which the resources was uploaded. |
collection_id | Filter by resources belonging to the collections with these IDs. |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_created |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
title |
filesize |
mimetype |
Object Filters
This request supports the following object filters:
Filter Name | Notes |
---|---|
owner | Filter by resources owned by these objects. |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of resources with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Resources
Sample Request:
GET /api/v0/resources/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/resources/count \
-H 'authorization: Bearer {access_token}'
GET /resources/count
This request will return a count of resources in a list defined by any available searches or filters. With no searches or filters this will be a count of all resources on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of resources listed. |
List Collections for an Object
Sample Request:
GET /api/v0/{object}/{object_id}/collections HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0{object}/{object_id}/collections \
-H 'authorization: Bearer {access_token}'
GET /{object}/{object_id}/collections
This request returns a list of collections against an object
, identified by its object_id
.
Configuring the Response
Pagination
This request supports all of the pagination parameters.
Handling the Response
The response will be a list of collections with their default fields, and displayed according to any pagination filters used.
Upload a Resource to a Collection
Sample Sample Request:
POST /api/v0/companies/39/collections/83/resources
HOST: {deployment}.api.accelo.com
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Authorization: Bearer {access_token}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="resource"; filename="example.pdf"
Content-Type: application/pdf
------WebKitFormBoundary7MA4YWxkTrZu0gW--
curl -X post \
https://{deployment}.api.accelo.com/api/v0/companies/39/collections/83/resources \
-H 'authorization: Bearer tM.G-I_F8jEn8oKzm.IvqWtq7gii4rHj.FBSKZr-RaABnRsYaF734afGRzXosjrY' \
-H 'content-type: multipart/form-data' \
-F 'resource=@/home/user/example.pdf'
POST /{object}/{object_id}/collections/{collection_id}/resources
This request uploads a file to a given collection, identified by its collection_id
, of a particular object identified through object
and object_id
.
Configuring the Resource
The file may be uploaded using the following parameter:
Field | Type | Description |
---|---|---|
resource | file | The file to be uploaded. |
Handling the Response
The response will contain the following fields:
Field | Type | Description |
---|---|---|
title | string | The name of the resource. |
size | integer | The size of the attachment in bytes. |
mimetype | string | The mime type of the attachment. |
Download a Resource
Sample Request:
GET /api/v0/resources/{resource_id}/download HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/resources/{resource_id} \
-H 'authorization: Bearer {access_token}'
GET /resources/{resource_id}/download
This request downloads a resource, identified by its resource_id
. This request takes no parameters and returns only the file to be downloaded.
Segmentations
Resource URI:
/api/v0/segmentations
Segmentations or (Categories) organize and segment your Company list into different categories for better management and reporting, letting you shape Accelo to match just what your business needs. See the support documentation for more information.
The Segmentation Object
Example segmentation object:
{
"link_type": "company",
"id": "2",
"leaf": "1",
"title": "Size",
"exclusive": "1",
"required": "0",
"standing": "active"
}
The segmentation object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the segmentation. |
title | string | A name for the segmentation. |
link_type | string | The object type that the segmentation is related to, may be 'company', 'affiliation' or 'contact'. |
standing | string | The standing of the segmentation, may be "active" or "inactive". |
required | boolean | Either Yes or No, whether this segmentation is required for the object it is against. |
exclusive | boolean | Either Yes or No, whether this segmentation is limited to one value. |
leaf | boolean | Either Yes or No, whether this segmentation is limited to only child options. |
Get a Segmentation
Sample Request:
GET /api/v0/segmentation/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/segmentation{id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
GET /segmentations/{id}
This request gets and returns a single segmentation specified by its id
.
Configuring the Response
This request supports requesting additional fields and linked items from the segmentation
object using the _fields
parameter.
Handling the Response
The response will be a single segmentation with its default fields and any additional fields
requested through _fields
.
List Segmentations
Sample Request:
GET /api/v0/segmentations HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/segmentations \
-H 'authorization: Bearer {access_token}'
GET /segmentations
This request returns a list of segmentations for the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Resource
This request supports requesting additional fields and linked resources from the
segmentation using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
link_type |
standing |
required |
exclusive |
leaf |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id |
Handling the Response
The response will be a list of segmentations with their default fields and any additional
fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Segmentations
Sample Request:
GET /api/v0/segmentations/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/segmentations/count \
-H 'authorization: Bearer {access_token}'
GET /segmentations/count
This request will return a count of segmentations in a list defined by any available searches or filters. With no searches or filters this will be a count of all segmentations on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the segmentations listed. |
Signoffs
Resource URI:
/api/v0/signoffs
Signoffs in Accelo allow your clients to approve your work and make comments against attachments and work descriptions. See the support documentation for more information on signoffs.
The Signoff Object
Example Signoff Object:
{
"against": "jobs/39",
"requires": "any",
"standing": "draft",
"date_created": "1398651556",
"date_updated": "1529619011",
"html_body": "Finish creating those things",
"standing_color": "yellow",
"against_id": "39",
"body": "Finish creating those things",
"created_by_id": "40",
"subject": "Creating things",
"permissions": {
"can_redraft": 0,
"can_send": 1,
"can_edit": 1
},
"date_expires": "1519822799",
"preview_body": "Finish creating those things",
"against_type": "job",
"id": "1",
"created_by": "40"
}
The signoff object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the signoff. |
subject | string | A name for the signoff. |
standing | string | The signoffs standing/status. Either "Draft", "Sent", "Approved" or "Declined". |
requires | string | Whether the signoff requires "any" approvers or "all" approvers to approve the quote. |
against | string | The API URL for the object the signoff is against e.g. "jobs/39". |
date_created | unix ts | The date the signoff was created. |
date_updated | unix ts | The date the signoff was last updated. |
standing_colour | string | The colour associated with the signoffs current standing/status. |
against_id | unsigned | The unique identifier of the object this signoff is against. |
against_type | string | The type of object this signoff is against. |
body | string | The main content for the signoff. |
preview_body | string | A shortened form of the main content of the signoff |
html_body | string | The main content of the signoff returned as HTML. |
created_by | unsigned or object | The staff member who created this signoff. |
created_by_id | unsigned | The unique identifier for the staff member who created this signoff. |
permissions | object | An object containing the permissions for the current user on this signoff |
date_expires | unix ts | The date the signoff becomes invalid. |
The Recipient Object
A recipient is the contact or contributor that a signoff is sent to.
Example Recipient Object
{
"recipient": {
"type": "affiliation",
"name": "Fred",
"id": "300",
"email": "fred@email.com"
},
"response": "pending",
"date_responded": "1516689196",
"recipient_type": "affiliation",
"recipient_id": "300",
"signoff_id": "2",
"approver": "1",
"id": "6"
}
The recipient object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the recipient. |
signoff_id | unsigned | The identifier of the signoff this recipient is related to. |
recipient_id | unsigned | The identifier of the recipient |
recipient_type | string | The object type of the recipient e.g. 'affiliation' or 'staff'. |
response | string | The response of the recipient to the signoff. |
date_responded | unix ts | The date in which the recipient responded to the sign off. |
recipient | object | An object describing more information about the recipient. |
approver | boolean | Whether the user can approve the quote related to this signoff. |
The Attachment Object
The attachment object represents one resource that is attached to a signoff.
Example Attachment Object
{
"signoff_id": "2",
"activity_id": "0",
"id": "1",
"resource": "316",
"resource_id": "316",
"standing": "active"
}
The attachment object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the attachment. |
signoff_id | unsigned | The identifier for the signoff the attachment is related to. |
resource_id | unsigned | The identifier for the resource that is attached. |
standing | string | The standing/status for the attachment either 'active' or 'inactive'. |
activity_id | unsigned | The identifier of the activity (if any) that the attachment is related to. |
Get Signoff
Sample Request
GET /api/v0/signoffs/{signoff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/{signoff_id}} \
-H 'authorization: Bearer {access_token}'
GET /signoffs/{signoff_id}
This request returns a single signoff using the _fields
parameter.
Configuring the response
This request supports requesting additional fields and linked resources from the signoff object
using the _fields
parameter.
Handling the Response
The response will be the single signoff object with its default fields and any additional fields
requested through _fields
.
List Signoffs
Sample Request:
GET /api/v0/signoffs HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs \
-H 'authorization: Bearer {access_token}'
GET /signoffs
This request returns a list of signoffs for the deployment.
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Resources
This request supports requesting additional fields and linked resources from the signoff object
using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
created_by | |
standing | |
requires | |
against_type | |
against_id |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
created |
expires |
updated |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
date_created |
date_expires |
date_updated |
standing |
subject |
Empty Filters
This request supports empty filters over the following fields:
Field |
---|
subject |
body |
created_by |
date_expires |
date_updated |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id |
Object Filters
This request supports the following object filters:
Filter | Description |
---|---|
against | Filter by quotes against these objects. |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
subject |
Count Signoffs
Sample Request:
GET /api/v0/signoffs/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/count \
-H 'authorization: Bearer {access_token}'
GET /signoffs/count
This request will return a count of the signoffs in a list defined by any available searches or filters. With no searches or filters, this will be a count of all signoffs on the deployment. This request returns a single field.
Field | Type | Description |
---|---|---|
count | unsigned | A count of the signoffs listed. |
Update Signoff
Sample Request:
PUT /api/v0/signoffs/signoff/{signoff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X put \
https://{deployment}.api.accelo.com/api/v0/signoffs/signoffs/{signoff_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /signoffs/signoff/{signoff_id}
This request updates and returns a signoff, identified by its signoff_id
.
Configuring the Signoff
The following fields from the signoff object may be updated with this request:
Field |
---|
body |
Redraft a signoff
Sample Request:
POST /api/v0/signoffs/{signoff_id}/redraft HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X post \
https://{deployment}.api.accelo.com/api/v0/signoffs/{signoff_id}/redraft \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /signoffs/{signoff_id}/redraft
This request allows a signoff to be re-drafted and returns the signoff, identified by its signoff_id
.
Send a signoff
Sample Request:
POST /api/v0/signoffs/{signoff_id}/send HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X post \
https://{deployment}.api.accelo.com/api/v0/signoffs/{signoff_id}/send \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /signoffs/{signoff_id}/send
This request allows a signoff to be sent and returns the sent signoff, identified by its signoff_id
.
List Signoff Recipients
Sample Request:
GET /api/v0/signoffs/recipients HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/recipients \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
GET /signoffs/recipients
This request returns a list of all recipients for the deployment.
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Resources
This request supports requesting additional fields and linked resources from the recipient object
using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
signoff_id | |
recipient_type | |
recipient_id | |
response | |
approver |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
responded |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
date_responded |
Range Filters
This request supports range filters over the following fields:
Filter Name |
---|
id |
signoff_id |
Empty Filters
This request supports empty filters over the following fields:
Field |
---|
date_responded |
Count Signoff Recipients
Sample Request:
GET /api/v0/signoffs/signoffs/recipients/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/count \
-H 'authorization: Bearer {access_token}'
GET /signoffs/recipients/count
This request will return a count of recipients in a list defined by any available searches or filters. With no searches or filters this will be a count of all recipients on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of recipients listed. |
Get Signoff Recipient
Sample Request:
GET /api/v0/signoffs/recipients/{recipient_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/{recipient_id} \
-H 'authorization: Bearer {access_token}'
GET /signoffs/recipients/{recipient_id}
This request returns a recipient identified by its recipient_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the recipient objects
using the _fields
parameter.
Handling the Response
The response will be the recipient with its default fields and any additional fields requested
through _fields
.
Create Signoff Recipient
Sample Request:
POST /api/v0/signoffs/recipients HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X post \
https://{deployment}.api.accelo.com/api/v0/signoffs/recipients \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /signoffs/recipient
This request allows a recipient to be added to a signoff and returns a recipient. The following fields are set via this request.
Field | Type | Description |
---|---|---|
signoff_id | unsigned | The identifier of the signoff this recipient is related to. |
recipient_id | unsigned | The identifier of the recipient |
recipient_type | string | The object type of the recipient e.g. 'affiliation' or 'staff'. |
approver | string | Whether the user can approve the quote related to this signoff. Must be one of 'yes' or 'no'. |
Update Signoff Recipient
Sample Request:
PUT /api/v0/signoffs/recipients/{recipient_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X put \
https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/{recipient_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /signoffs/recipients/{recipient_id}
This request allows the recipient of a quote to be updated and returns the recipient object,
identified by their recipient_id
. A recipient can only be edited if a user is the recipient and if the quote is in draft.
The following fields can be updated by this request:
Field | Notes |
---|---|
approver | |
response | You may only update your own response, and only if you are an approver. |
Delete Signoff Recipient
Sample Request:
DELETE /api/v0/signoffs/recipients/{recipient_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X delete \
https://{deployment}.api.accelo.com/api/v0/signoffs/recipients/{recipient_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
DELETE /signoffs/recipients/{recipient_id}
This request allows the recipient of a quote to be deleted, identified by their recipient_id
.
List Signoff Attachments
Sample Request:
GET /api/v0/signoffs/signoffs/attachments HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/attachments \
-H 'authorization: Bearer {access_token}'
GET /signoffs/attachments
This request an list of attachment objects for the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting extra fields or linked objects from the attachment object
using the _fields
parameter. This request also supports
breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
signoff_id | |
standing | |
resource_id | |
activity_id |
Handling the Response
The response will be a list of containing the default fields and any additional fields
requested by _fields
, and displayed according to any pagination parameters or filters used.
Get Signoff Attachment
Sample Request:
GET /api/v0/signoffs/signoffs/attachments/{attachment_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/attachments/{attachment_id} \
-H 'authorization: Bearer {access_token}'
GET /signoffs/attachments/{attachment_id}
This request returns an attachment specified by its attachment_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the attachment objects
using the _fields
parameter.
Handling the Response
The response will be the attachment with its default fields and any additional fields
requested through _fields
.
Count Signoff Attachments
Sample Request:
GET /api/v0/signoffs/signoffs/attachments/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/attachments/count \
-H 'authorization: Bearer {access_token}'
GET /signoffs/attachments/count
This request will return a count of attachments in a list defined by any available searches or filters. With no searches or filters this will be a count of all attachments on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of attachments listed. |
Upload Signoff Attachment
Sample Request:
POST /api/v0/signoffs/{signoff_id}/attachments HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="resource"; filename="example.pdf"
Content-Type: application/pdf
------WebKitFormBoundary7MA4YWxkTrZu0gW--
curl -X POST \
https://{deployment}.api.local.accelo.com/api/v0/signoffs/1/attachments\
-H 'authorization: Bearer {access_token}
-H 'content-type: multipart/form-data'
-F 'file=@example.pdf'
POST /signoffs/{signoff_id}/attachments
This request uploads a file as an attachment to the given signoff.
Configuring the Resource
The file may be uploaded using the following parameter:
Field | Type | Description |
---|---|---|
file | file | The file to be uploaded. |
Handling the Response
The response will be the uploaded attachment with its default fields and any additional fields requests
through _fields
.
Update Signoff Attachment
Sample Request:
PUT /api/v0/signoffs/signoffs/attachments/{attachment_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/signoffs/attachments/{attachment_id} \
-H 'authorization: Bearer {access_token}'
PUT /signoffs/attachments/{attachment_id}
This request updates an attachment identified by its attachment_id
and returns the updated
attachment object.
The fields able to be updated by this request are:
Field | Notes |
---|---|
Status | Updates the standing field |
Skills
Resource URI:
/api/v0/skills
Skills are tags assigned to tasks or users which can then be used to appropriately assign work. See the support documentation for more information skills and how to use them on the deployment.
The Skill Object
Example skill object:
{
"id": "4",
"title": "Android"
}
The skills object contains the following:
Field | Type | Description |
---|---|---|
id | A unique identifier for the skill. | |
title | A name for the skill. |
List Skills
Sample Request:
GET /api/v0/skills HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/skills \
-H 'authorization: Bearer {access_token}'
GET /skills
This request returns a list of skills on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Resource
This request supports requesting additional fields and linked resources from the skill object using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
title |
Object Filters
This request supports the following object filters:
Filter Name | Description |
---|---|
against | Filter by skills applied to this object. |
Searching
This request supports using the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of skills with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Skills
Sample Request:
GET /api/v0/skills/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/skills/count \
-H 'authorization: Bearer {access_token}'
GET /skills/count
This request will return a count of skills in a list defined by any available searches or filters. With no searches or filters this will be a count of all skills on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the skills listed. |
Create a Skill
Sample Request:
POST /api/v0/skills HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/skills \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /skills
This request creates and returns a skill.
Configuring the Skill
This request supports setting the following fields from the skill object:
Field Name |
---|
title |
Configuring the Response
This request supports requesting additional fields and linked items from the skill object using the _fields
parameter.
Handling the Response
The response will be the single, created skill with its default fields and any additional fields requested through _fields
.
Staff
Resource URI:
/api/v0/staff
Staff (or users) are the users registered on the Accelo deployment. They are the company's Accelo users, admins, professionals, and collaborators
The Staff Object
The staff object contains the following
Field | Type | Description |
---|---|---|
id | string | A unique identifier for the staff member. |
firstname | string | The staff member's first name. |
surname | string | The staff member's surname. |
standing | select | Either "active", "inactive", or "lockout", the standing of the staff member. |
financial_level | select | Either "none", "time", or "all", the staff member's financial permission level. |
title | string | A title for the member, for example "Mr", "Ms". |
string | The staff member's email address. | |
mobile | string | The staff member's mobile number. |
phone | string | The staff member's phone number. |
fax | string | The staff member's fax number. |
position | string | The staff member's position in the company. |
username | string | The staff member's username on the deployment. |
timezone | string | The staff member's timezone. |
staff_rate | decimal | The staff member's billable rate. Not returned when requesting _ALL fields. |
staff_cost_rate | decimal | The staff member's cost rate. Not returned when requesting _ALL fields. |
The Staff Membership Object
This object tracks group membership for staff, each entry describes a link between a staff and a group.
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the membership. |
group_id | unsigned | The id of the group the staff member is part of. |
staff_id | unsigned | The id of the staff linked to the group. |
staff | unsigned or object | The staff linked to the group. |
Get Staff
Sample Request:
GET /api/v0/staff/{staff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff/{staff_id} \
-H 'authorization: Bearer {access_token}'
GET /staff/{staff_id}
This requests returns a staff member, specified by their staff_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the staff object using
the _fields
parameter.
Handling the Response
The response is the single staff object with its default fields and any additional fields requested
through _fields
.
Get Current Staff
Sample Request:
GET /api/v0/staff/whoami HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff/whoami \
-H 'authorization: Bearer {access_token}'
GET /staff/whoami
This request returns the staff object for the current staff member. It can be configured and
handled in the same way as GET /staff/{staff_id}
.
List Staff
Sample Request:
GET /api/v0/staff HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff \
-H 'authorization: Bearer {access_token}'
GET /staff
This request returns a list of staff members on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the staff object using
the _fields
.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
standing |
username |
Range Filters
This request supports range filters over the following fields:
Filter Name |
---|
id |
rate |
Handling the Response
The response will be a list of staff objects with their default fields and any additional fields
requested through _fields
, displayed according to any pagination parameters or filters used.
Count Staff
Sample Request:
GET /api/v0/staff/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff/count \
-H 'authorization: Bearer {access_token}'
GET /staff/count
This request will return a count of staff in a list defined by any available searches or filters. With no searches or filters this will be a count of all staff on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of staff members listed. |
List Staff Memberships
Sample Request:
GET /api/v0/staff/memberships HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff/memberships \
-H 'authorization: Bearer {access_token}'
GET /staff/memberships
This request returns a list of staff memberships on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the staff
membership using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name | Notes |
---|---|
id | |
staff_id | |
group_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id |
Order Filters
This request supports the following order filters:
Filter Name | Notes |
---|---|
id |
Handling the Response
The response will be a list of staff memberships with their default fields and any additional
fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Update a Staff Member
Sample Request:
PUT /api/v0/staff/{staff_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff/{staff_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /staff/{staff_id}
This request updates and returns a staff member, identified by their staff_id
.
Configuring the Staff
The following fields from the staff object may be updated with this Sample Request:
Field Name |
---|
firstname |
surname |
title |
fax |
phone |
mobile |
position |
Configuring the Response
This request supports requesting additional fields and linked objects from the staff object using
the _fields
parameter.
Handling the Response
The response will be the update staff object with its default fields and any additional fields
requested through _fields
.
Create a Staff Member
Sample Request:
POST /api/v0/staff HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /staff
This request creates and returns a new staff member.
Configuring the Staff
The following fields from the staff object may be set through this Sample Request:
Field Name | Notes |
---|---|
username | |
password | A password for the new staff member on the deployment. |
firstname | |
surname | |
title | |
fax | |
phone | |
mobile | |
position |
Configuring the Response
This request supports requesting additional fields and linked objects from the staff object using
the _fields
parameter.
Handling the Response
The response will be the single, updated staff object with its default fields and any additional
fields requested through _fields
.
Delete a Staff Member
Sample Request:
DELETE /api/v0/staff HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/staff \
-H 'authorization: Bearer {access_token}'
DELETE /staff/{staff_id}
This request removes a staff member from the deployment, identified by their staff_id
. This
request takes no parameters and returns no resources.
List a Staff's Profile Field Values
See the profiles section for a sample request
GET /staff/{staff_id}/profiles/values
This request returns a list of profile values of a staff object,
specified by its staff_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "staff", and whose id is staff_id
.
List all Profile Field Values on a Staff
See the profiles section for a sample request
GET /staff/profiles/values
This request returns a list of all profile field values on staff.
This is the request GET /{object}/profiles/values
, where the object is "staff".
List Staff Profile Fields
See the profiles section for a sample request
GET /staff/profiles/fields
This request returns a list of profile fields available for any staff object.
This is the request GET /{object}/profiles/fields
where the object is "staff".
Update a Profile Field Value on a Staff
See the profiles section for a sample request
PUT /staff/{staff_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular staff object, specified by its staff_id
. This is the request
PUT/{object}/{object_id}/profiles/values/{profile_value_id}
where the object is "staff",
and whose id is the staff_id
.
Set a Profile Field Value on a Staff
See the profiles section for a sample request
PUT|POST /staff/{staff_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for a staff object, specified by its staff_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "staff",
and whose value is staff_id
.
Statuses
Statuses are used to track the progress of work. See the support documentation for more information. Since many resources on Accelo track various types and aspects of work, statuses are present in many different resources. Currently, statuses are supported on the following objects:
Status Objects
The status object contain the following:
Fields | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the status. |
title | string | A title for the status. |
color | string | The color the status will appear in the Accelo deployment. |
standing | string | The standing of the status. For example "active", "paused". |
start | string | Either "yes" or "no", whether this status is available upon creation of the object. |
ordering | unsigned | A number representing the status' order on the Accelo deployment. |
Note that each resources keeps track of statuses separately, so a given status may not contain all the fields listed above, if this is the case we will state it in that resource's section.
Tags
Resource URI:
/api/v0/tags
Tags are keywords you my apply to a range of objects within Accelo, for example activities or jobs. They may both help describe the object, and make searching easier. See the support documentation for more information on tags and how to apply them.
The Tag Object
The tag object contains the following:
Fields | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the tag. |
name | string | A name for the tag. |
List Tags
Sample Request:
GET /api/v0/tags HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tags \
-H 'authorization: Bearer {access_token}'
GET /tags
This request returns a list of tags on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Resources
This request supports requesting additional fields and linked resources from the tag object using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
name |
Object Filters
This request supports the following object filters:
Filter Name | Description |
---|---|
against | Filter by tags applied to this object. |
Searching
This request supports the _search
parameter to search over the following fields:
Field Name |
---|
name |
Handling the Response
The response will be a list of tags with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Tags
Sample Request:
GET /api/v0/tags/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tags/count \
-H 'authorization: Bearer {access_token}'
GET /tags/count
This request will return a count of tags in a list defined by any available searches or filters. With no searches or filters this will be a count of all tags on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of tags listed. |
Create a Tag
Sample Request:
POST /api/v0/tags HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tags \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /tags
This request creates and returns a tag.
Configuring the Tag
The following fields from the tag object may be set with this request:
Field Name |
---|
name |
Configuring the Response
This request supports requesting additional fields and linked objects from the tag object using the _fields
parameter.
Handling the Response
The response will be the single, created tag with its default fields and any additional fields request through _fields
.
Tasks
Resource URI:
/api/v0/tasks
Tasks are small units of work, they may be thought of as the type of work you would put on a "to-do" list. See the support documentation for more information on tasks and how to interact with them on the deployment.
The Task Object
Example task:
{
"affiliation": "292",
"against": "milestones/15",
"against_id": "15",
"against_type": "milestone",
"assignee": "7",
"billable": "3600",
"budgeted": "0",
"company": null,
"contact": "292",
"creator": "staff/7",
"creator_id": "7",
"creator_type": "staff",
"custom_id": null,
"date_accepted": "1362533400",
"date_commenced": "1362533400",
"date_completed": "1374208724",
"date_created": "1362533400",
"date_due": "1374199200",
"date_modified": "1532347231",
"date_started": "1362531600",
"description": null,
"id": "24",
"issue": null,
"job": null,
"logged": "3600",
"manager": "7",
"milestone": "15",
"nonbillable": "0",
"object_budget": "113",
"rate_charged": "175.00",
"rate_id": "6",
"remaining": "0",
"staff_bookmarked": "0",
"standing": "complete",
"status": "5",
"task_job": null,
"task_object_budget": "113",
"task_object_schedule": "113",
"task_object_schedule_id": "113",
"task_priority": "1",
"task_status": "5",
"task_type": "1",
"title": "SEO Audit",
"type": "1"
}
The task object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the task. |
title | string | A name for the task. |
description | string | A description of the task. |
billable | integer | The total billable time logged against the task, in seconds. |
nonbillable | integer | The total nonbillable time logged against the task, in seconds |
logged | integer | The total time logged against the task, in seconds. |
budgeted | integer | The total time budgeted, or estimated, for the task, in seconds |
remaining | integer | The amount of budgeted time left, in seconds. |
staff_bookmarked | boolean | Whether the current user has bookmarked the task in the deployment. |
date_created | unix ts | The date the task was created. |
date_started | unix ts | The date the task is is scheduled to start. |
date_commenced | unix ts | The date the task was started; when its standing was progressed to "started". |
date_accepted | unix ts | The date the task was accepted. |
date_due | unix ts | The date the task is due to be completed. |
date_completed | unix ts | The date the task was completed. |
date_modified | unix ts | The date the task was last modified. |
against_type | string | The type of object the task is against. |
against_id | unsigned | The unique identifier of the object the task is against. |
against | string | The API URI of the object the task is against. That is "against_type /against_id ". |
creator_type | string | The type of object that created the task. |
creator_id | unsigned | The unique identifier of the object that made the task. |
creator | string | The API URI of the object that made the task. That is "creator_type "/"creator_id ". |
assignee | unsigned or object | The staff member assigned to the task. |
type | unsigned or object | The task type of the task. Deprecated, please use task_type . |
task_type | unsigned or object | The task type of the task. |
status | unsigned or object | The status of the task. Deprecated, please use task_status . |
task_status | unsigned or object | The status of the task. |
standing | string | The standing of the task, this is contained in the status object. |
manager | unsigned or object | The staff member assigned to manager the task. |
contact | unsigned or object | The contact associated with the against object, if any. |
affiliation | unsigned or object | The affiliation associated with the against object, if any. |
company | unsigned or object | The company object the task is against, if any. |
issue | unsigned or object | The issue object the task is against, if any. |
job | unsigned or object | The job object the task is against, if any. Deprecated, please use task_job |
task_job | unsigned or object | The job object the task is against, if any. |
milestone | unsigned or object | The milestone object the task is against, if any. |
task_object_budget | unsigned or object | The object budget linked to the task, if any. |
task_object_schedule | unsigned or object | The object schedule linked to the task. |
task_object_schedule_id | unsigned | The id of the object schedule linked to the task. |
task_priority | unsigned or object | The priority of the task. |
rate_id | unsigned | The unique identifier of the rate object of the task. |
rate_charged | decimal | The rate charged for billable work within this task. This is part of the rate object. |
ordering | unsigned | An integer representing the task's order on the against object, only if the task is against a job or milestone |
skills | array[object] | The skills assigned to the task. |
The Task Priority
Task priorities help you prioritize your task. They may be set up from the deployment, see the support documentation for information. They contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the task priority. |
title | string | A title for the task priority. |
icon | select | The icon of the priority when displayed on the deployment. The icons, in order of decreasing urgency a critical_priority , high_priority , normal_priority , low_priority , none_priority . |
level | unsigned | A number representing the urgency of the priority. 1 is "Critical", 5 is "None" |
The Task Type
Task types allow you to assign type labels to tasks. The task type contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the task type. |
title | string | A title for the task type. |
standing | Select | Either "active" or "inactive", the standing of the task type. |
ordering | unsigned | An integer representing the task type's order on the deployment. |
Note: This object does not support the _ALL
argument when request with _fields
.
The Task Metadata
The metadata object associated with tasks is a list of the following:
Task Metadata Managers
This is a list of staff members managing tasks on the deployment, the object has the following fields:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the staff member. |
name | string | The staff member's full name (first name and surname). |
string | The staff member's email address. |
Task Metadata Assignees
This is a list of staff members assigned to tasks on the deployment. The object contains the same fields as the managers metadata object
Task Metadata Against
This is a list of object types that have tasks listed against them on the deployment, this object contains the following:
Field | Type | Description |
---|---|---|
id | string | An identifier to identify the object within the API. For example "prospect". |
name | string | A name for the object. For example "Sale". |
Task Metadata Status
This is a list of status objects available to tasks on the deployment. Note that this is a status object without the start
field.
Get Task
Sample Request:
GET /api/v0/tasks/{task_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks/{task_id} \
-H 'authorization: Bearer {access_token}'
GET /tasks/{task_id}
This request returns a single task, identified by its task_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the task object using the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single task object with its default fields and any additional fields requested through _fields
.
List Tasks
Sample Request:
GET /api/v0/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks \
-H 'authorization: Bearer {access_token}'
GET /tasks
This request returns a list of tasks on the deployment.
Configuring the Response
Pagination
This request supports the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the task object using the _fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
assignee | Filter by the staff_id of the assignee. |
manager | Filter by the staff_id of the manager. |
status | Filter by status_id . |
standing | |
against_type | |
against_id | |
custom_id | |
child_of_job | Filter by the job_id of the job the task, or its against object, is against. This allows you to find tasks under a certain job, even when they are not created directly against that job, for example if they are created against a milestone under the job. |
rate_id | |
rate_charged |
Date Filters
This request supports date_filters over the following fields:
Filter Name |
---|
date_created |
date_started |
date_commenced |
date_accepted |
date_completed |
date_modified |
date_due |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
billable | |
nonbillable | |
budgeted | |
remaining | |
against_id | |
creator_id | |
assignee | Range over the staff_id of the assignee. |
type | Range over type_id . Deprecated, please use task_type . |
task_type | Range over the task_type_id . |
status | Range over status_id . |
manager | Range over the staff_id of the manager. |
contact | Range over the contact_id of the associated contact. |
rate_charged |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
id | |
date_created | |
date_started | |
date_commenced | |
date_accepted | |
date_completed | |
date_modified | |
date_due | |
task_priority | |
title | |
standing | |
status | Order by the status_id . |
rate_charged | |
ordering | The order of the tasks on their against object, if the against object is a job or milestone |
Object Filters
This request supports the following object filters:
Filter Name | Description |
---|---|
against | Filter by tasks against these objects. |
creator | Filter by tasks created by these objects. |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
description |
title |
Handling the Response
The response will be a list of tasks with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Tasks
Sample Request:
GET /api/v0/tasks/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks/count \
-H 'authorization: Bearer {access_token}'
GET /tasks/count
This request will return a count of tasks in a list defined by any available searches or filters. With no searches or filters this will be a count of all tasks on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of tasks listed. |
List Task Priorities
Sample Request:
GET /api/v0/tasks/priorities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks/priorities \
-H 'authorization: Bearer {access_token}'
GET /tasks/priorities
This request returns a list of priorities available for tasks.
Get Task Status
Sample Request:
GET /api/v0/tasks/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks/statuses/{status_id} \
-H 'authorization: Bearer {access_token}'
GET /tasks/statuses/{status_id}
This request returns the task status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a task status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Task Statuses
Sample Request:
GET /api/v0/tasks/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks/statuses \
-H 'authorization: Bearer {access_token}'
GET /tasks/statuses
This request returns a list of statuses available for tasks on the deployment.
Configuring the Response
Pagination
This request supports the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the statuses object using the _fields
parameter. Note, this request does not support the _ALL
argument. Note, the status object for tasks does not contain the start
field.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of statuses with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters or searches used.
Count Task Statuses
Sample Request:
GET /api/v0/tasks/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks/statuses/count \
-H 'authorization: Bearer {access_token}' \
GET /tasks/statuses/count
This request will return a count of task statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all task statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed task statuses. |
List Meta Data
Sample Request:
GET /api/v0/tasks/meta HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks/meta \
-H 'authorization: Bearer {access_token}'
GET /tasks/meta
This request returns a list of metadata objects for tasks on the deployment. That is, a list of lists.
Handling the Response
The response will be a list of task managers, task assignees, against objects, and statuses.
Update a Task
Sample Request:
PUT /api/v0/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /tasks/{task_id}
This request updates and return a task on the deployment.
Configuring the Task
The following fields from the task object may be updated through this Sample Request:
Field Name |
---|
title |
description |
assignee_id |
affiliation_id |
manager_id |
priority_id |
type_id |
rate_id |
rate_charged |
date_due |
remaining |
Configuring the Response
This request supports requesting additional fields and linked resources from the task object using the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single, updated task with its default fields and any additional fields requested through _fields
.
Create a Task
Sample Request:
POST /api/v0/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/tasks \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /tasks
This request creates and returns a task.
Configuring the Task
The following fields from the task object may be set with this Sample Request:
Field Name | Notes |
---|---|
title | |
against_id | Must point to a valid object. |
against_type | Must point to a valid object type. |
date_started | |
description | |
status_id | The status_id for the initial status. You may retrieve a list of statuses for tasks if required. |
manager_id | The staff_id for the staff to be assigned manager. |
assignee_id | The staff_id for the staff to be assigned to the task. |
affiliation_id | The affiliation_id for the affiliation to be associated with the task. |
date_due | |
priority_id | The priority object's id. For available priorities see GET /tasks/priorities |
remaining | The field budgeted will be automatically updated with this value upon creation. |
rate_id | Only available if the task is against a "job" or "milestone". The rate_id of the rate for this task. |
rate_charged | Only available if the task is against a "job" or "milestone". The rate charged for work on this task, as a decimal. |
is_billable | Only available if the task is against a "job" or "milestone". Whether this task is billable, may either by "yes" or "no". |
Configuring the Response
This request supports requesting additional fields and linked objects from the task object using the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single, created task with its default fields and any additional fields requested through _fields
.
List Available Progressions on a Task
See the progressions section for a sample request
GET /tasks/{task_id}/progressions
This request returns a list of available progressions for a task, specified by its task_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "tasks" whose id is task_id
.
Auto Run a Progression on a Task
See the progressions section for a sample request
PUT|POST /tasks/{task_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress a task, specified by its task_id
. This is the request [POST|PUT] /{object}/{object_id}/progressions/{progression_id}/auto
where the object is "task" whose id is task_id
.
Auto Progress a Task to Start or End
Requests:
PUT|POST /tasks/{task_id}/progressions/start
PUT|POST /tasks/{task_id}/progressions/done
These requests will auto progress the status of a task, identified by its task_id
to "start" or "done", respectively.
Taxes
The different account tax codes are stored by Accelo in the tax object. For information on these, and instructions on interacting with them through the deployment please see the support doucmentation
The Tax Object (Beta)
Example tax:
{
"rate": "0.10000",
"id": "6",
"standing": "active",
"title": "GST on Capital"
}
The tax object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the tax. |
title | string | A name for the tax. |
standing | select | The standing of the tax, either "active" or "inactive". |
rate | decimal | The rate the tax is charged. |
Get Tax (Beta)
GET /api/v0/taxes/{tax_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/taxes/{tax_id} \
-H 'authorization: Bearer {access_token}
GET /taxes/{tax_id}
This request returns a tax object specified by its tax_id
Configuring the Response
This request supports requesting additional fields and linked objects from the tax object using the _fields
parameter.
Handling the Response
The response will be the single tax object with its default fields and any additional fields requested through _fields
.
List Taxes (Beta)
GET /api/v0/taxes HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/taxes \
-H 'authorization: Bearer {access_token}
GET /taxes
This request returns a list of taxes.
Configuring the Response
Pagination
This request supports all the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the tax object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
standing |
Order Filters
This request supports the following order filters:
Filter |
---|
id |
standing |
title |
Range Filters
This request supports the following range filters:
Filter |
---|
id |
Handling the Response
The response will be a list of taxes with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters or filters used.
Count Taxes (Beta)
GET /api/v0/taxes/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/taxes/count \
-H 'authorization: Bearer {access_token}
GET /taxes/count
This request will return a count of taxes in a list defined by any available searches or filters. With no searches or filters this will be a count of all taxes on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of taxes listed. |
Time Externals
Resource URI:
/api/v0/time_externals
Time Externals are imported appointments from calendars such as Google, Exchange, or Outlook. Once they are imported and turned into activities you can use them on your schedule and entries on your timesheet. See the support documentation for more information on time externals.
The Time External Object
Example time external object:
{
"id": "2",
"staff_id": "7",
"title": "Budget Meeting",
"description": "Discuss next quarter's budget",
"date_created": "1362707577",
"date_modified": "1362707577",
"date_started": "1362772800",
"date_ended": "1362776400",
}
The contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the time external. |
staff_id | unsigned | The unique identifier for the staff member |
title | string | The title of the appointment. |
description | string | A description of the appointment. |
date_created | unix ts | The date the appointment was created. |
date_modified | unix ts | The last date the appointed was modified. |
date_started | unix ts | The start date and time of the appointment. |
date_ended | unix ts | The end date and time of the appointment. |
Get Time External
Sample Request:
GET /api/v0/time/externals/{id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/time/externals/{id} \
-H 'authorization: Bearer {access_token}'
GET /time/externals/{id}
This request returns a single time external, specified by its id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the time external
using the _fields
parameter.
Handling the Response
The response will be the single requested time external with its default fields and any
additional fields requested through _fields
.
List Time Externals
Sample Request:
GET /api/v0/time/externals HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/time/externals \
-H 'authorization: Bearer {access_token}'
GET /time/externals
This request returns a list of time externals on the deployment.
Configuring the Request
Pagination
This request accepts all the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects using the _fields
parameter.
Basic Filters
This request supports basic filters over the following fields:
Filter Name |
---|
id |
staff_id |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
id |
staff_id |
date_created |
date_modified |
date_started |
date_ended |
Range Filters
This request supports range filters over the following fields:
Filter Name |
---|
id |
staff_id |
Searching
This request supports the _search
parameter to search over the following fields:
Filter Name |
---|
title |
description |
Handling the Response
The response will be a list of time externals on the Deployment, with their default fields and
any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Count Time Externals
Sample Request:
GET /api/v0/time/externals/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/time/externals/count \
-H 'authorization: Bearer {access_token}'
GET /time/externals/count
This request will return a count of time externals in a list defined by any available searches of filters. With no searches or filters this will be a count of all time externals on the deployment. This request returns a single field.
Field | Type | Description |
---|---|---|
count | unsigned | A count of time externals listed. |
Delete a Time External
Sample Request:
DELETE /api/v0/time/externals/{time_external_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/time/externals/{time_external_id} \
-H 'authorization: Bearer {access_token}' \
DELETE /time/externals/{time_externals_id}
This request removes an external appointment from the deployment and deletes it from any given timesheet or schedule it
is linked to, specified by its time_external_id
.
Convert a Time External to an Activity
Sample Request:
POST /time/externals/{time_external_id}/convert_to_meeting HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/time/externals/{time_external_id}/convert_to_meeting \
-H 'authorization: Bearer {access_token}' \
POST /time/externals/:time_external_id/convert_to_meeting
This request will convert the external into an activity as a meeting. This
request requires a valid engagement_table
and engagement_id
for the activity to be created against. It will also
create a second activity as a report on the meeting. This is the process
to converting the external appointment as a workable entry to use in Accelo.
Timers
Resource URI:
/api/v0/timers
Timers are used to log time through Accelo. See the support documentation for more information on these objects, and how to access them on the deployment.
NOTE: Timer endpoints all operate from the current user and because of this are not available to service applications. If this restriction impacts your business model, please contact support and we will consider opening certain timer access up to service applications by requiring a staff id. It also means that a user will only be able to view or edit timers that they own.
The Timer Object
The timer object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the timer. |
subject | string | A name for the timer. |
seconds | integer | How long the timer has been running for, in seconds. |
status | select | Either "stopped" or "running", whether the timer is running. |
against_type | string | The type of object the timer is against. |
against_id | unsigned | The unique identifier of the object the timer is against. |
against_title | string | The title of the object the timer is against. |
staff_id | unsigned | The unique identifier of the staff member running the timer. |
staff | unsigned or object | The staff member running the timer. |
Get Timer
Sample Request:
GET /api/v0/timers/{timer_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers/{timer_id} \
-H 'authorization: Bearer {access_token}'
GET /timers/{timer_id}
This request returns a timer identified by its timer_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the timer object using the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the timer with its default fields and any additional fields requested through _fields
.
List Timers
Sample Request:
GET /api/v0/timers HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers \
-H 'authorization: Bearer {access_token}'
GET /timers
This request returns a list of timers on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the timer objects using the _fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
staff | Filter by the staff_id . |
status |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
against_id | |
staff | Range by the staff_id . |
Handling the Response
The response will be a list of timers with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters or filters used.
Update a Timer
Sample Request:
POST /api/v0/timers/{timer_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers/{timer_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /timers/{timer_id}
This request updates and returns a timer identified by its timer_id
.
Configuring the Timer
The following fields from the timer objects may be updated through this Sample Request:
Field Name | Notes |
---|---|
subject | |
against_type | |
against_id | |
seconds | Can only be updated for stopped timers. |
Configuring the Response
This request supports requesting additional fields and linked objects from the timer object using the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response is the single, updated timer with its default fields and any additional fields requested through _fields
Create a Timer
Sample Request:
POST /api/v0/timers HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /timers
This request creates and returns a timer.
Configuring the Timer
The following fields may be set through this Sample Request:
Field Name | Notes |
---|---|
subject | |
against_id | |
against_type | |
seconds | |
auto_start | May be either "1" or "0", whether the timer starts upon creation. If it starts, it will stop any current timers. The default is "0". |
Configuring the Response
This request supports requesting additional fields and linked objects from the timer object through the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single, created, timer with its default fields and any additional fields requested through _fields
Delete a Timer
Sample Request:
DELETE /api/v0/timers/{timer_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers/{timer_id} \
-H 'authorization: Bearer {access_token}'
DELETE /timers/{timer_id}
This request deletes a timer, specified by its timer_id
. It takes no parameters and returns no resources.
Pause a Timer
Sample Request:
PUT /api/v0/timers/{timer_id}/pause HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers/{timer_id}/pause \
-H 'authorization: Bearer {access_token}'
PUT|POST /timers/{timer_id}/pause
This request pauses and returns a timer identified by its timer_id
. This request may be handled, and configured, in the same way as GET /timers/{timer_id}
Start a Timer
Sample Request:
PUT /api/v0/timers/{timer_id}/start HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers/{timer_id}/start \
-H 'authorization: Bearer {access_token}'
PUT|POST /timers/{timer_id}/start
This request starts and returns a timer identified by its timer_id
. This request may be handled, and configured, in the same way as GET /timers/{timer_id}
Cancel a Timer
Sample Request:
PUT /api/v0/timers/{timer_id}/cancel HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/timers/{timer_id}/cancel \
-H 'authorization: Bearer {access_token}'
PUT|POST /timers/{timer_id}/cancel
This is request behaves the same as DELETE /timers/{timer_id}
.
User
This resource contains information about the current user, their deployment, and access token.
The User Object
The user object contains the same fields as the staff object, as well as the following:
Field | Type | Description |
---|---|---|
user_titles | hash | A key-value object containing the user defined plural and singular for each object type. |
user_access | hash | A key-value object containing manages, add, view, and admin permissions for the different types of objects. |
locale | hash | A key-value object containing the user's timezone and currency symbol preferences. |
GET /user
This request returns a user object, it takes no parameters.
Webhooks
Resource URI:
api/v0/webhooks
Webhooks allow you to build integrations that subscribe to specific Accelo events. Once an event is triggered, we will HTTP POST a payload to your registered callback URL containing event meta data and a resource URL. The resource URL can be used by your application to query the individual resource that fired the event. This is commonly referred to as Notification Webhooks.
There's currently no limit on webhooks and they can be installed per deployment from an individual users account using the webhooks control panel. See our blog for more information, and how to access webhooks on the deployment. We do enforce a 10 second timeout rule. If your trigger URL takes more than 10 seconds to respond to webhook delivery, we will cancel the request. If this occurs too many times, we will delete your webhook subscription automatically.
Webhook Subscriptions
Webhook Events
When subscribing to webhooks you choose an event that you would like to receive payloads for. Each event corresponds to a certain set of actions on a per object basis. The available events are:
event_id | Description |
---|---|
assign_task | Any time a task assignee changes. |
unassign_task | Any time a task is unassigned. |
create_task | Any time a task is created. |
create_invoice_pdf | Anytime an invoice PDF is created. |
create_purchase_pdf | Any time a purchase PDF is created. |
create_quote | Anytime a new quote is created |
create_request | Any time a new request is created. |
update_request_status | Any time a request status changes. |
create_issue | Any time an issue is created. |
update_issue | Any time an issue is updated. |
create_contact | Any time a contact is created. |
update_contact | Any time a contact is updated. |
delete_activity | (Beta) Any time an activity is deleted. |
Progression Webhooks
Progression webhooks allow you to subscribe to changing statuses for companies, contacts, prospects, jobs, issues and contracts. Currently you can only do this from the web application's administration page but there are plans to expose this functionality to the API.
[Create Progression Action Button]
[Create Progression Webhook Form]
Payloads
The payload sent to the callback URL will contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the object changed. |
resource_url | string | The full URL of the object changed. |
Delivery Headers
As well as the information in the payload body, the headers of HTTP request sent to the payload URL will contain special headers:
Header | Description |
---|---|
X-Accelo-Event | The event_id of the event that triggered the delivery. For example "assign_task". |
X-Hub-Signature | HMAC hex digest of the payload using your configured subscriptions secret. |
The Webhook Subscription
The webhook subscription object contains the following:
Field | Type | Description |
---|---|---|
content_type | select | Either "application/x-www-form-urlencoded" or "application/json", the content type POSTed to the trigger url. |
event_id | string | One of the events listed above. |
trigger_table | string | The type of object that triggers the subscription. |
trigger_type | string | A string representing the type of trigger, either "create" or "update". |
trigger_url | string | The callback, or payload URL to which the payload is sent. |
user_deployment | string | The user's deployment in the form {deployment} . |
user_id | unsigned | The current user's unique identifier, that is, their staff_id . |
Webhook Subscription Types
Each webhook subscription is of a certain type, defined by the following fields from the webhook subscription object:
Field |
---|
event_id |
event_title |
trigger_table |
trigger_type |
Unsubscribing
Your integration can tell Accelo to automatically unsubscribe by responding with a HTTP Status Gone 410. The dispatcher will respect this and instantly remove the subscription that caused the webhook trigger. Alternatively you can use the delete subscription endpoint mentioned below.
List Webhook Subscriptions
Sample Request:
GET /api/v0/webhooks/subscriptions HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions \
-H 'authorization: Bearer {access_token}'
GET /webhooks/subscriptions
This request returns a list of webhook subscriptions for the current user. This request takes no parameters.
List Webhook Subscription Types
Sample Request:
GET /api/v0/webhooks/subscriptions/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/types \
-H 'authorization: Bearer {access_token}'
GET /webhooks/subscriptions/types
This request returns a list of available webhook subscription types. This request takes no parameters.
Create Webhook Subscription
Sample Request:
POST /api/v0/webhooks/subscriptions HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /webhooks/subscriptions
This request creates and returns a webhook subscription for the current user. This request takes no parameters to configure the response.
Configuring the Subscription
The following fields may be set through this Sample Request:
Notes | |
---|---|
trigger_url | |
event_id | |
content_type | |
secret | Optional secret that we will use to generate a HMAC hex digest of the payload. The digest will be included in the triggered requests "X-Hub-Signature" header. |
Delete Webhook Subscription
Sample Request:
DELETE /api/v0/webhooks/subscriptions/{subscription_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/{subscription_id} \
-H 'authorization: Bearer {access_token}'
DELETE /webhooks/subscriptions/{subscription_id}
This request deletes a webhook subscription, identified by its subscription_id
. It takes no parameters and returns no
resources.
Trigger a Webhook Subscription
Sample Request:
POST /api/v0/webhooks/subscriptions/{subscription_id}/trigger HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/{subscription_id}/trigger \
-H 'authorization: Bearer {access_token}' \
POST /webhooks/subscription/{subscription_id}/trigger
This request manually triggers a given subscription, identified by its subscription_id
. This will queue the event to
all other subscriptions and execute asynchronously. Use this if you want to trigger a subscription for an event for
others, otherwise see dispatch a webhook subscription. This request takes the
following parameter:
Field | Type | Description |
---|---|---|
object_id | unsigned | The unique identifier of the object, of type trigger_table , to trigger the subscriptions. |
Handling the Response
This request returns nothing to the user.
Dispatch a Webhook Subscription
Sample Request:
POST /api/v0/webhooks/subscriptions/{subscription_id}/dispatch HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/webhooks/subscriptions/{subscription_id}/dispatch \
-H 'authorization: Bearer {access_token}' \
POST /webhooks/subscriptions/{subscription_id}/dispatch
This request manually dispatches a given subscription, identified by its subscription_id
. This will dispatch
synchronously, and unlike triggering, this will only execute the current subscription so other subscriptions of the
event will not be affected. As this is performed synchronously you will get the HTTP status of the webhook result. This
request takes the following parameter:
Field | Type | Description |
---|---|---|
object_id | unsigned | The unique identifier of the object, of type trigger_table to run the dispatch on. |
Handling the Response
The response will contain a single field:
Field | Type | Description |
---|---|---|
status | integer | The http status of the webhook result. |
Status Codes
The following statuses and codes may be returned.
ok
Code
200
Description
Everything executed as expected.
invalid_client
Code: 401
Description
Invalid client authentication, e.g. unknown client, no client authentication included, or unsupported authentication method.
Common Causes
- No client credentials were provided
- The client was not found in the system
- An incorrect client secret was provided
- The IP is restricted in the application's configuration of the deployment
- The user is locked out due to the number of failed attempts exceeding the max limit
- No token provided when accessing a resources
- Token provided is invalid
- The token's user is invalid
invalid_grant
Code: 400
Description
The provided authorization grant is invalid.
Common Causes
- Provided grant or refresh token is invalid, expired, or revoked
- Provided grant or refresh token does not match the URI used in the authorization request or was issued to another client
duplicate
Code: 400
Description
Your write actions would cause a duplicate unique identifier. The response message should identify the offending field. If it odes not, please report it to us.
Common Causes
- An attempt to create an object with the same name, title, or username as an already existing object of the same type
invalid_request
Code: 400
Description
We could not interpret your request. This is commonly seen when you forgot to include required parameters or attempt to request a resource that doesn't exist. For example /api/v0/monkeys
or /api/v20000/companies
would result in an 'invalid request'.
Common Causes
- The request is for an unknown resource or version
- The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed
- The request includes multiple credentials
- The request did not result in any data to return. For example, requesting a job that doesn't exist
too_many_requests
Code: 429
Description
Your deployment has exceeded the maximum number of allowed requests for this hour. See rate limiting for more information.
server_error
Code: 500
Description
The request failed due to a server error and we were notified. Unfortunately these errors are 99% of the time out of your control. If you continue to see such an error, please notify us.
Common Causes
- Database connection error
- Deployment can't be found
- A routine threw an exception
- Bad or corrupt data
invalid_scope
Code: 400
Description
The request scope is invalid, unknown, malformed or exceeds the scope granted by the resource owner.
Common Causes
- The requested scope doe not conform to our API scope syntax
unsupported_grant_type
Code: 400
Description
The authorization grant type is not supported by the authorization server.
Common Causes
- You are sending an grant type that is not "authorization_code", "refresh_token", or "client_credentials"
unauthorized client
Code: 401
Description
The authenticated client is not authorized to use this authorization grant type
Common Causes
- Provided grant was issue to another client
invalid_permission
Code: 403
Description
The user is authenticated but does not have permission to perform the action
Change log
With the release of the new and easier to maintain documentation, we're going to do a much better job of tracking changes.
Note - Beta Changes: New objects or endpoints may be introduced with a (Beta) tag, which may last up to a month after introduction. While in beta these are subject to change without notice.
Tuesday 5th January 2020
The change log is back!
Features
Added an delete activity webhook. - This will initially be in beta.
Wednesday 11th April 2018
Misc
Added some extra documentation around _not
filters.
Features
Updated the PUT /activities/{activity_id}
endpoint:
- You may now update the
billable
ornonbillable
field when updating an activity.
New fields added to the Activity Object:
- Added the
is_billable
field. - Added the
permissions
object.
Additional changes:
- Added the Contract Budget object on Contract Periods.
- Added
won_by_id
,cancelled_by_id
, andabandoned_by_id
on the Prospect Object.
Tuesday 6th February 2018
Misc
- Rename some sections for clarity and to avoid title duplication.
Features
The following endpoints have been added to activities:
The following endpoints have been added to issues:
GET /issues/resolutions/{resolution_id}
- Get issue resolutionGET /issues/resolutions
- List issue resolutionsGET /issues/resolutions/count
- Count issue resolutions
The following issue endpoints have been updated:
- PUT /issues/{issue_id} - you may now update the following:
- The issue's resolution, via:
resolution
orresolution_details
- The issue's contract via:
contract_id
- The issue's resolution, via:
The following webhook events have been added:
create_issue
update_issue
Deprecations
- The
class
attribute and object on activities is deprecated. Please useactivity_class
instead.
Bug Fixes
In addition to the username
and password
, the following fields are now required when creating a new staff member via
POST /staff:
firstname
surname
email
Friday 2nd February 2018
Features
- Add the
block_send
flag to allow blocking activities created through the API from being sent.
Monday 22nd January 2018
Deprecations
- The
priority
attribute and object on Activities and Requests is deprecated. Please useactivity_priority
andrequest_priority
instead.
Monday 15th January 2018
Deprecations
- The
priority
attribute and object on Issues is deprecated. Please useissue_priority
instead.
Features
- The following endpoints have been added
- The following endpoints have been updated:
PUT /issues/{issue_id}
supports updatingpriority_id
and (status_id
orstanding
)POST /issues
supports settingpriority_id
and (status_id
orstanding
)
Friday 22nd December 2017
Misc Updates
The following endpoints have been added:
Friday 13th October
Object Types
The following objects are to have their type
object deprecated and replaced by
a corresponding _type
object:
Included in this change, the following endpoints have been added:
Friday 6th October
Rate Limiting
Rate limiting will be introduced into the API. We have added documentation describing what the limits will be once it is introduced.
Configuring the Response
This has been moved to its own section, configuring responses.
AND/OR Filtering
The API now supports combining filters using logical AND/OR operations.
Friday 22nd September
Progression Webhooks
Webhooks are now supported on progressions via progression webhooks. These are currently only supported via the Web App but there are plans to implement it via the API.
Purchases
Purchases are now accessible through the API. They are available through the purchase object and accessed via the new endpoints:
Groups
Groups may now be accessed through the API. They are available through the group object and accessed via the new endpoints:
Divisions
Divisions may now be accessed through the API. They are available through the division object and accessed via the new endpoints:
Request Types
A new endpoint for request types has also been added:
Wednesday 16th August
Close/Reopen Contract Periods
Contract periods may now be closed or reopened using the API, this is done through the two new endpoints:
[PUT | POST] /api/v0/contracts/periods/{period_id}/close
[PUT | POST] /api/v0/contracts/periods/{period_id}/open
New Fields for Activities
The following fields have been added to the activity object:
- standing
- invoice_id
- contract_period_id
Friday 21st July
Holidays
User holidays may now be accessed through the API. As well as adding the holiday object, the following endpoints are now available:
Asset Links
We are rolling out asset links, which join an asset to another object, to the API. Currently the following new objects have been added:
As well as the following endpoints:
Invoices
We are also rolling out improvements to assets on the API. As part of these improvements we have added the following objects:
With the following new endpoints:
Future updates will include update, create and delete invoices.
Payments Ledgers and Taxes
Related to our asset improvements is the introduction of payments, ledgers, and taxes with the following endpoints:
- Get payment, Get ledger, Get tax
- List payment, List ledgers, List taxes
- Count payments, count ledgers, count taxes
Future updates will include update, create and delete payments.
Friday 16th June
New documentation
- Complete endpoints
- Up to date
- More examples
New filters
- Filter resources by collection and owners. e.g,
_filters=collection_id(10),owner(staff(10,32))