Introduction
Welcome to Accelo's Public REST API documentation. Here you will find resources and information to help you use the API.
Developer Forum - Connect with other developers on our developer forum / mailing list. Use this space to ask any questions and report errors in the documentation.
Registering your Application
Before doing anything, you will need to register your application with Accelo. This is done from your deployment under "Configuration" → "API" → "Register Application". Accelo currently offers three types of applications:
- Installed Application
- Web Application
- Service Application
Note: An application can only be registered with one type. If your application requires multiple types you will need to register multiple applications
Once registered, your application will be given a client_id
and client_secret
, which are required to authenticate.
Accessing Resources
For example, base URI for a company called "Planet Express":
https://planet-express.api.accelo.com/api/v0
Your Accelo deployment will be given a unique deployment (or hostname), from this we can form the URI for each resource, which will have a form like:
https://{deployment}.api.accelo.com/api/v0
All resources may be called from this base URI:
https://{deployment}.api.accelo.com/api/v0/{resource}
For example, accessing the "Staff" resource of "Planet Express":
https://planet-express.api.accelo.com/api/v0/staff
Keep in mind, for an installed or web application we will want to use the end-user's deployment, not the API's deployment. Note, all authorization endpoints are accessed through the OAuth2.0 base URI, which is different from the resource base URI, see the authentication section for more information.
Response and Request Structure
Sample request to return a list of staff as XML:
GET https://{deployment}.api.accelo.com/api/v0/staff.xml
By default, all resource requests return JSON (application/json)
. You may also request the response in XML or YAML by
either setting the Accept-Type
header to text/xml
or text/x-yaml
, or by appending the extension type to the end of
the request resource.
Sample response with no suppression:
{
"meta" : {
"more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#ok",
"status" : "ok",
"message" : "Everything executed as expected."
},
"response" : { "..." }
}
Sample failed response, here we requested a company by an id that doesn't exist:
{
"response": null,
"meta": {
"message": "The request could not be interpreted. This can be caused by missing or invalid data. Please ensure that the resource you are requesting actually exists.",
"more_info": "https://affinitylive.jira.com/wiki/display/APIS/Status+Codes#invalid_request",
"status": "invalid_request"
}
}
The Meta Object
Each request made will return two objects, a meta object, and a response object. The response object contains the requested response data. The meta object contains the following:
Field Name | Description |
---|---|
status | A string representing the result of the request. |
message | An explanation of the status |
more_info | A URL where more information regarding the current status may be found. |
response code | HTTP status. Only visible when suppressing http status with _suppress_http_status=yes . See here for a list of possible response codes. |
Sample response with _suppress_message=yes and _suppress_http_status=yes
{
"meta" : {
"status" : "ok",
"response_code" : 200
},
"response" : { "..." }
}
The following parameters may be used to suppress parts, or all, of the meta response:
Name | Description |
---|---|
_suppress_message | Suppresses message and more_info . |
_suppress_http_status | Forces HTTP status to 200 and stores the actual status in response_code |
_suppress_meta | Suppresses all meta data. This is useful if you wish to purely utilize HTTP headers. |
They make take values of either "1" or "yes", for example to suppress all meta we could use _suppress_meta=yes
or _suppress_meta=1
.
Default and Required Fields
A resource will only return a small number of fields by default, these fields will be in bold in the resource's table of fields and linked objects. Similarly, POST request will generally require values for some fields, these fields will be in bold within the endpoint's description.
The following parameter may be used to hide the default fields that would be returned in the response:
Name | Description |
---|---|
_hide_defaults | Hides the default fields from the response. This is useful to reduce the size of the payload to just the fields you need. |
Overriding the Request Method
We understand that certain types of requests are not always available to the client. In response to this we allow you to
override the request method using the _method
parameter, this can take one of four values:
Value | Description |
---|---|
get | Override the request type to be GET. |
put | Override the request type to be PUT. |
post | Override the request type to be POST. |
delete | Override the request type to be DELETE. |
For example, each of the following deletes the company with id 10:
DELETE /companies/10
GET /companies/10?_method=delete
POST /companies/10?_method=delete
JSON Content Types
Requests may also be sent as JSON. This can greatly simplify the client side implementation as it offers filters and fields that translate well to programmatic structures. This may also be necessary when you wish to search or filter using non-alphanumeric characters e.g "@", "." or special or accented characters e.g. "à ", "ç", "ö".
Parsing _fields as JSON
Translating "_fields" from query to json, query:
_fields=status(color),username,company(_ALL)
Equivalent JSON "_fields" object:
"_fields": "status(color), username, company(_ALL)"
When sending JSON data with your request, the "_fields"
key should hold a string of the desired fields and linked
objects, separated by a comma. For example, the query _fields=status
would be equivalent to including "_fields":
"status"
in the JSON body. The same method is used to request additional objects and their fields as for queries, the
"_ALL" value also works as for queries..
Parsing _filters as JSON
Example, converting a query list of filters to JSON:
_filters=id(12,13),date_created_after(1498175480), rate_charged_greater_than(10),order_by_desc(status)
Equivalent JSON "_filters" object
"_filters": {
"id": [12, 13],
"date_created_after": [1498175480],
"rate_charged_greater_than": [10],
"order_by_desc": ["status"]
}
Filters are sent through JSON bodies using the _filters
key, which hold a hash of keys (filter names) and values (the
values to be filtered). For example applying the filter _filters=id(12,13),status(3,1)
would be equivalent to
including in the value of "_filters"
the pair "id": [12,13], "status": [3,1]
. This basic key-value pairing works for
all filters outside of object filters.
Example object filter query and json. Here we are using the against and referrer filters of issues.
_filters=against(company(312,466),job(998)),referrer(prospect(42))
{
"_filters": {
"against": [{
"company": [312,466],
"job": [998],
}],
"referrer": [{
"prospect": [42]
}]
}
}
There are two ways to generate object filters though JSON bodies. The first is by simply building them from the
corresponding basic filters, for example the filter against(company(32))
is equivalent to
against_type(company),against_id(32)
, which can be parsed into JSON as shown above. The other is to build a nested
JSON object of the form "<object_filter>": [{ "<object_type>": ["<object id>"] }]
.
Parsing _search as JSON
Parsing a search through _search
in JSON is simply a matter of assigning a string to be searched to the key
"_search". For example searching for a contact with name "Hubert Farnsworth" may be done in a query through
_search=(Hubert+Farnsworth)
, or in a JSON request by adding "_search": "Hubert Farnsworth"
.
Rate Limiting
Meta object for a 429 response:
{
"message": "Rate limit exceeded for planet-express.api.accelo.com",
"status": "too_many_requests",
"more_info": "api.accelo.com/docs/#rate-limiting"
}
Requests to the API will be limited to 5000/hour per deployment, this is to protect the quality of the service offered
by the API. Authentication or authorization requests (those made to /ouath2
endpoints) will not be limited and will
not be counted against this limit. Requests made after exceeding this limit will return a 429
error.
The following headers have also been added to track usage rates:
Header | Type | Description |
---|---|---|
X-RateLimit-Reset | unix ts | The time at which the current rate limit window resets. |
X-RateLimit-Remaining | int | Number of requests remaining in the current rate limit window. |
X-RateLimit-Limit | int | Maximum number of requests allowed in each rate limit window. |
Configuring Responses
There are several tools available to configure the response from the API:
Pagination
Accelo has the capacity to hold tens of thousands of resources. So, without being careful we could have a hard time returning the required resources. Thankfully, the API also supports pagination to help us work through a resource list. The available parameters are:
Argument | Description |
---|---|
_page | The page of result to retrieve. For example to retrieve the first page you would use _page=0 , and for the 5th page, _page=4 . The default is 0 |
_limit | The max number of resources to return. When combined with _page , this is the number of requests returned per page. Default is 10, max is 100 |
_offset | The resource to return from. Default is 0, this will be overridden if _page is set. |
Requesting Additional Fields and Linked Objects
Requesting companies with the "website" and "phone" fields, as well as the linked "postal_address" object and its "city" field:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_fields=website,phone,postal_address(city)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_fields=website,phone,postal_address(city)'
By default, each resource returns only the minimal required fields, these are displayed in the table describing the
object. To request additional fields we can use the _fields
parameter. For example, the company object
has additional fields website
and phone
, to display these in a request response we would add
_fields=website,phones
to our request. The keyword _ALL
may be used to return all optional fields.
For linked objects (those marked as "unsigned or object") the _fields
parameter may be used to request the linked
object by adding parenthesis to the field. For example, the company object contains a link to an address
object under the postal_address
field, to return this object with its default fields we add
_fields=postal_address()
. Requesting optional fields from a linked object is done by including the fields within these
parenthesis, for example if we wanted the city
field from within the postal_address
we would use
_fields=postal_address(city)
, here the _ALL
keyword would return all optional fields from the postal_address
object. If a linked object is request without the parenthesis, e.g. _fields=postal_address
then the unique identifier
for the object will be returned. This process also supports nesting, for example if we wish to return the country
object from within the postal_address
object here we would use _fields=postal_address(country())
.
Breadcrumbs
Breadcrumbs give identifying information on the parent object(s) of the object requested. They may be requested through
_fields=breadcrumbs
. Requesting breadcrumbs will return an array of breadcrumb objects, these contain the following
fields:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the parent object. |
table | string | The type of the parent object. |
title | string | The title of the parent object. |
For example if a job is created against a company, then the job will have a single breadcrumb containing information on the company. If a task is then created against that job the task will have two breadcrumbs, one identifying the job and another identifying the company. Breadcrumbs are always displayed in ascending order, so the direct parent will be displayed first, then its parent, an so on.
Searching
Some requests support the use of the _search
parameter to search through certain fields and display only results
satisfying the search. For example, the GET /contacts
request supports this filter over the firstname
,
surname
,mobile
and email
, so _search=kurt+wagner
would display any contacts where "kurt" and "wagner" is found
in the first name, surname, mobile or email. Another available search method is through the
search filter.
Filtering
Most API endpoints support a _filters
parameter that allows you to filter the response. The supported filters will be
listed for each endpoint, in general there are several types of filters:
Filters may take any number of arguments, new arguments may be separated by a comma. Appending _not
to any filter will
return results that DO NOT satisfy the filter, e.g. standing_not(active)
would return only results whose standing is
not 'active'. Any number of filters may be combined in a single request.
For example if we wanted to find all activities that were NOT created against a job we would use
_filters=engagement_table_not(job)
.
Basic Filters
Example request, filter activities by those owned by a staff member:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=owner_type(staff)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=owner_type(staff)'
These simply filter resources with certain fields for certain values, generally they are requested simply by
<field>(<value>)
. For examples, activities support basic filters on the owner_type
and owner_id
fields, so for example if we wanted to search for activities owned by the staff member with id 17 we would use
_filters=owner_type(staff),owner_id(17)
.
Date Filters
Filter activities by those created after 2017-03-22 00:00:00 (UTC)
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=date_created_after(1490140800)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=date_created_after(1490140800)'
Many endpoints contain fields representing dates, such as date_created
under activities. Date fields
are express as unix timestamps (for brevity we will just use the shorter "unix ts"). The API supports filtering for may
of these "date_fields" through the following filters:
Filter | Description |
---|---|
<date_field>_before(<date>) | Filter by results whose value of <date_field> is less than the <date> value (expressed as a unix ts). |
<date_fields>_after(<date>) | Filter by results whose value of <date_field> is greater than the <date> value (expressed as a unix ts). |
Range Filters
Filter activities with and id greater than 17:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=id_greater_than(17)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=id_greater_than(17)'
These are similar to Date Filters except they operate on non-date fields. For a given "field" there are four range filters defined:
Filter | Description |
---|---|
<field_name>_greater_than(<value>) | Filter by results that have a value for <field> greater than <value> . |
<field_name>_less_than(<value>) | Filter by results that have a value for <field_name> less than <value> . |
<field_name>_greater_than_or_equal(<value>) | Filter by results that have a value for <field_name> greater than or equal to <value> . |
<field_name>_less_than_or_equal(<value>) | Filter by results that have a value for <field_name> less than or equal to <value> . |
Order Filters
Filter activities by descending order of id:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=order_by_desc(id)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=order_by_desc(id)'
These change of the order in which the response is displayed, they are not strictly filters in that they will not
exclude any objects from the response, but they are called using _filters
so we shall list them here. By default a
response will be sorted in ascending order of the id
of the objects requested. For a given "field" there are two order
filters defined:
Filter | Description |
---|---|
order_by_asc(<field>) | Order the results in ascending value of <field> . |
order_by_desc(<field>) | Order the results in descending value of <field> . |
Empty Filters
Filter contracts with an empty date_expires:
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=empty(date_expires)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=empty(date_expires)'
These filter resources which have no value for the given field, the format is empty(<field_name>)
. For example, the
date_expires
field for contract supports this filter, so _filters=empty(date_expires)
would display
all contracts without an expiry date.
Object Filters
Filter activities owned by "staff/17"
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=owner(staff(17))
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=owner(staff(17))'
These are an extension of basic filters that allow for more compact filtering over entire objects, they take both an
object and an id as arguments. For example, activities support object filtering on the "owner" object. As
we saw previously we could specify activities by a certain staff member using _filters=owner_type(staff),owner_id(17)
we may achieve the same using the owner
object filter on activities, _filters=owner(staff(17))
.
As with other filters, additional arguments for both fields may be added and separated by a comma, for example
_filters=owner(staff(17,13),affiliation(22)
would show all activities owned by the staff with id 17 or 13, or owned by
the affiliation with id 22.
Search Filters
Filter contacts by "kurt wagner"
GET /contacts HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=search(kurt wagner)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/contacts \
-H 'authorization: Bearer {access_token}' \
-d '_filters=search(kurt wagner)'
This filter is similar to the searching parameter and supports the same requests available to that
parameter. Automatically this filter will append an AND
between multiple search requirements. Search terms are
separated by ,
or any space. Some characters e.g. (,)
and ,
will be ignored using this filter whereas these are
accepted by _search
. It will search through the available fields and only return results that satisfy the search. This
filter expands on the searching parameter by allowing the use of _OR
. For example, the GET /contacts
request
supports search over firstname
, surname
, mobile
, and email
so if we wanted to find contacts with "kurt" or
"wagner" in any of the listed fields we could use _filters=_OR(search(kurt),search(wagner))
.
Combining Filters
Filter by activities owned by "staff/17" and created after 2017-03-22 00:00:00 (UTC) and not against a job
GET /activities HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_filters=owner(staff(17)),date_created_after(1490140800),against_type_not(job)
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/activities \
-H 'authorization: Bearer {access_token}' \
-d '_filters=owner(staff(17)),date_created_after(1490140800),against_type_not(job)'
Any combination of filters may be used to filter response, this is achieved by separating them with a comma. More
flexible filter combinations may be achieved through the _AND
and _OR
keywords. For example, if we wanted to
search for activities owned by the specific staff OR created after a given date we could use
_filters=_OR(staff(17),date_created_after(1490140800))
. One _AND
can be nested inside an _OR
for greater filtering
flexibility. For example, if we wanted all activities created by the given staff member, or after a given date and
before another date we could use
_filters=_OR(staff(17),_AND(date_created_after(1490140800),date_created_before(1500140800)))
. Nested _OR
keywords are
not supported.
If the same filter is used more than once in a combination only the final instance of the filter will be used. For
example _filters=_OR(staff(10),staff(11))
will just filter by staff with id 11, here the simple filter
_filters=staff(10,11)
should be used.
Only a single _AND
can be defined inside the filters param.
Authentication
Accelo's API uses the OAuth 2.0 protocol and provides routines that cover web, service and installed application's authorization and authentication. It supports authorization code grants and client credential grants as necessary between the available API applications.
Please read OAuth 2.0's final version specification for more information on the protocol.
Generally, accessing an Accelo resource protected by OAuth2.0 takes three steps:
1. Authorize
2. Acquire token
3. Access resource
Before access to a token is granted authorization is achieved for a limited range of requests using the client_id
and
client_secret
which can be found through your Accelo toolbox and are given upon registering your API. To gain an
access token your application must first be authorized by the end user, once authorized we are able to send a token
request to the OAuth endpoint. We will go through this process for each of the application types support by Accelo.
OAuth2.0 URI
Example OAuth2.0 base URI for planet express:
https://planet-express.api.accelo.com/oauth2/v0
The OAuth2.0 base URI is different to the base URI for Accelo resources, in general this base URI will be found at:
https://{deployment}.api.accelo.com/oauth2/v0
This URI is used to authorize and access tokens.
Scope
For example, to request permission to read all information and write only to companies and contacts:
scope=read(all),write(companies,contacts)
For example, to request permission to read and write to contacts and staff:
scope=write(contacts,staff)
The range of access permissions for a given token is provided by the scope
parameter. Currently, the following scopes
are available:
read({resource})
- Read only access to data related to the {resource}
object, which may be any resource. read(all)
gives read only access to all data the user owns or has access to. To provide read access to any collection of
resources, {resource_1},{resource_2},...
you can simply concatenate, read({resource_1},{resource_2},...)
write({resource})
- Read and write access related to the resource specified. write(all)
gives read and write access
to all data the user owns or has access to. As for read access, write access for a collection of resources is given via
concatenation.
The scope
field is optional in all requests that use it, and defaults to read(all)
.
OAUTH2.0 Endpoints
There are three endpoints off the OAUTH2.0 URI, they are /authorize
, /token
, and revoke
. These endpoints support
the following requests:
Request | Description |
---|---|
GET | POST /authorize | Request authorization from a user. |
POST /token | Request an access token using a grant code or refresh token. |
POST /revoke | Revoke and access token. |
We will cover handling the responses on a case-by-case basis for each application type, as the responses vary between them. Note that authorization and token requests should always be encoded, for the purposes of demonstration, our examples are not.
Redirect URIs
Redirect URIs are used in the authorization of web and installed applications, these are the URIs to which the end- user's response to authentication requests are sent. Redirect URIs for an application may be registered through the api control panel. You may register many callback URIs for a web application, but only one for an installed application.
Authentication Without a Token
Authenticating an application before you have been granted an access token is done
using HTTP Basic authorization. The format is {client_id}:{client_secret}
encoded in base64.
For example if your client id is 5ba17c78ao@planet-express.accelo.com
and your client
secret is zTfFgiyQCVDFk-1EtUerVLRk1is6LgL6
then you would authorize with the header:
Authorization: Basic NWJhMTdjNzhhb0BwbGFuZXQtZXhwcmVzcy5hY2NlbG8uY29tOnpUZkZnaXlRQ1ZERmstMUV0VWVyVkxSazFpczZMZ0w2
.
For convenience we will just write {client_credentials}
Service Applications
These are not run from the end user's deployment, and hence do not need to be authorized by the user, so authorization and accessing a token is are combined into one step for these application.
Token Acquisition for Service Applications
Example token request for the Planet Express deployment, here
{client_credentials}
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 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. |
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
paramter to search over the following fields:
Filter Name |
---|
subject |
invoice_number |
Handling the Response
The response will be a list of invoices on the Deployment, with their default fields and any
additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or
searches used.
Count Invoices
Sample Request:
GET /api/v0/invoices/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/invoices/count \
-H 'authorization: Bearer {access_token}'
GET /invoices/count
This request will return a count of invoices in a list defined by any available searches or filters. With no searches or filters this will be a count of all invoices on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of invoices listed. |
List an Invoice's Profile Field Values
See the profiles section for a sample request
GET /invoices/{invoice_id}/profiles/values
This request returns a list of profile values of an invoice,
specified by its invoice_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "invoices", and whose id is {invoice_id}
.
List all Profile Field Values on an Invoice
See the profiles section for a sample request
GET /invoices/profiles/values
This request returns a list of all profile field values on invoices.
This is the request GET /{object}/profiles/values
, where the object is "invoices".
List Invoices Profile Fields
See the profiles section for a sample request
GET /invoices/profiles/fields
This request returns a list of profile fields available for invoices. This is the request
GET /{object}/profiles/fields
where the object is "invoices".
Update a Profile Value on an Invoice
See the profiles section for a sample request
PUT /invoices/{invoice_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular invoice, specified by its invoice_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "invoices",
and whose value is {invoice_id}
.
Set a Profile Value on an Invoice
See the profiles section for a sample request
POST /invoices/{invoice_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for an "invoice", specified by its invoice_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "invoices",
and whose value is {invoice_id}
.
Get Line Item (Beta)
Sample Request:
GET /api/v0/invoices/line_items/{line_item_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/invoices/line_items/{line_item_id} \
-H 'authorization: Bearer {access_token}'
GET /invoices/line_items/{line_item_id}
This request returns a line item specified by its line_item_id.
Configuring the Response
This request supports requesting additional fields and linked objects from the line item object
using the _fields
parameter.
Handling the Response
The request will return the single invoice line item with its default fields and any additional fields requested through
_fields
.
List Line Items (Beta)
Sample request:
GET /api/v0/invoices/line_items/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/invoices/line_items \
-H 'authorization: Bearer {access_token}'
This request returns a list of invoice line item.
Configuring the Response
Pagination
This request supports all of the standard pagination parameters
Additional Fields and Linked objects
This request supports requesting additional fields and linked objects from the line item object
using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
invoice_id |
ledger_id |
tax_id |
Order Filters
This request supports the following order filters:
Filter |
---|
id |
invoice_id |
ledger_id |
tax_id |
quantity |
rate |
total |
ordering |
Range Filters
This request supports range filters over the following fields:
Filter |
---|
id |
invoice_id |
ledger_id |
tax_id |
quantity |
rate |
total |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
description |
Handling the Response
The response will contain a list of invoice line items with their default fields and any additional fields requested
through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Line Items (Beta)
Sample request:
GET /api/v0/invoices/line_items/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/invoices/line_items/count \
-H 'authorization: Bearer {access_token}'
GET /invoices/line_items/count
This request will return a count of line items in a list defined by any available searches or filters. With no searches or filters this will be a count of all line items on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of line items listed. |
Issues (Tickets)
Resource URI:
/api/v0/issues
Issues (also known as "Tickets") are used for when you need to track billable time against a client, but don’t need the complexity of a full Project and its workflow and components. For example, issues may be used to track support cases where you’re diagnosing and fixing a problem and don’t know beforehand the specific steps which will be required to resolve the Issue. See the support documentation for more information on these objects.
The Issue Object
Example issue object:
{
"assignee": "14",
"title": "Issue with public field",
"referrer_type": null,
"affiliation": "98",
"date_submitted": "1493872605",
"date_modified": "1553728167",
"resolution_detail": "I fixed the field, it now displays as expected.",
"staff_bookmarked": "1",
"against": "companies/39",
"contract": "1",
"billable_seconds": "1400",
"submitted_by": "14",
"against_type": "company",
"date_due": "1493906400",
"contact": "98",
"date_closed": "1495683190",
"standing": "closed",
"object_budget": "8",
"date_started": "1493820000",
"class": "19",
"resolved_by": "14",
"date_last_interacted": "1493872783",
"resolution": "8",
"closed_by": "14",
"date_resolved": "1495683190",
"referrer_id": null,
"custom_id": "",
"status": "4",
"opened_by": "14",
"type": "1",
"description": "A public field is showing as public",
"against_id": "39",
"id": "7",
"company": "39",
"issue_priority": "1",
"date_opened": "1493872605"
}
The issue object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the issue. |
title | string | A name for the issue |
custom_id | string | The custom ID for the issue. Only issues whose type allows custom IDs will have a value for this field. |
description | string | A description of the issue. |
against | string | The API URI of the object this issue is against. |
against_type | string | A string representing the type of object this issue is against. |
against_id | unsigned | The unique identifier of the object this issue is against. |
type | unsigned or object | The issue type of this issue. Deprecated, please use issue_type . |
issue_type | unsigned or object | The issue type of this issue. |
affiliation | unsigned or object | The affiliation associated with this issue. |
class | unsigned or object | The issue class of this issue. |
priority | unsigned or object | Deprecated please use issue_priority |
issue_priority | unsigned or object | The priority of the issue. |
resolution | unsigned or object | The resolution type used by the issue, if it has been resolved. |
resolution_detail | string | A description of the resolution, if resolved. |
status | unsigned or object | The status of the issue. |
standing | string | The standing of the issue, taken from the issue status. |
date_submitted | unix ts | The date the issue was submitted |
submitted by | unsigned or object | The staff member who submitted the issue. |
date_opened | unix ts | The date the issue was opened. |
opened_by | unsigned or object | The staff member who opened the issue. |
date_resolved | unix ts | If resolved, the date the issue was resolved. |
resolved_by | unsigned or object | The staff member who resolved the issue. |
date_closed | unix ts | If closed, the date the issue was closed. |
closed_by | unsigned or object | The staff member who closed the issue. |
date_due | unix ts | The due date for the issue. |
date_last_interacted | unix ts | The date the issue was last interacted with. |
date_modified | unix ts | The date the issue was last modified. |
referrer_type | string | If the issue was created from the deployment as a "related issue" to an object, this will be the object's type. |
referrer_id | unsigned | The unique identifier of this related object. |
staff_bookmarked | boolean | Whether the current viewer has bookmarked the issue. |
billable_seconds | unsigned | The amount of billable time, in seconds, on the issue. |
company | unsigned or object | If against_type is company, the company the issue is against. |
assignee | unsigned or object | The staff assigned to the issue. |
contract | unsigned or object | If the issue is assigned a contract (retainer), this will return the contract object. |
issue_object_budget | unsigned or object | The object budget associated with the issue. |
object_budget | unsigned or object | Deprecated please use issue_object_budget . |
The Issue Priority
Example priority object:
{
"title": "Extreme",
"id": "1",
"color": "Red",
"factor": "5"
}
Issue priorities help you keep track of what needs to be done. They may be set up from the deployment, see the support documentation for information. They contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the priority. |
title | string | A name for the priority. |
color | select | The color of the priority when displayed on the deployment. The colors, in order of increasing urgency a "grey", "blue", "green", "orange", "red". |
factor | unsigned | A number representing the urgency of the priority. 5 is "Extreme", 1 is "None". |
The Issue Status
Example issue status object:
{
"standing": "open",
"start": "yes",
"color": "yellow",
"ordering": "2",
"title": "Open",
"id": "2"
}
Statuses may be used to track the progress of an issue. These statuses may be configured from the deployment, see the support documentation for more information. The status objects contain the following
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the status. |
title | string | A name for the status. |
standing | string | A string describing the standing of the issue. |
color | string | The color of the status shown on the deployment. |
start | select | Either "yes" or "no", whether an issue may be created with this status. |
ordering | unsigned | A number describing the order of the status on the deployment. |
The Issue Type
Example issue type object:
{
"notes": "Issue type for support issues.",
"standing": "active",
"title": "Support",
"id": "2",
"parent": "0"
}
Issue types let you sort your issues according to the type of work the entail. Issue types may be set up and edited from the deployment, see the support documentation for more information.
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the issue type. |
title | string | A name for the issue type. |
notes | string | Notes about the issue type. |
parent | unsigned | The unique identifier of the parent issue type. If there is no parent has the value "0" |
standing | select | Either "active" or "inactive", the standing of the issue type. |
budget | select | Either "yes" or "no", whether issues under this type are billable. |
ordering | unsigned | A number describing the type's ordering on the deployment. |
Note: the type
field is deprecated, please request the issue type object through the
issue_type
field, which contains the following additional fields:
Field | Type | Description |
---|---|---|
default_class_id | unsigned | The unique identifier of the default issue class for this type of issue. Default is null . |
has_custom_id | boolean | Either "1" or "0", whether the issue type uses custom ids. |
The Issue Resolution
Example issue resolution:
{
"standing": "active",
"title": "Support Resolution",
"id": "8",
"parent": "7",
"report": "Use this resolution when resolving support issues.",
"description": "I fixed the field, it now displays as expected."
}
Issue resolutions track how certain issues are resolved and may be set up on the deployment, see the support documentation for more information. The issue resolution contains the following:
Field | Type | Descriptions |
---|---|---|
id | unsigned | A unique identifier for the issue resolution. |
title | string | A name for the issue resolution. |
parent | unsigned | The unique identifier of the parent resolution, it there is no parent this has value "0". |
description | string | A generic description of the resolution, may be changed for a given issue. |
report | string | A fixed description of the resolution. |
standing | select | Either "active" or "inactive", the standing of the resolution. |
The Issue Class
Example issue class:
{
"standing": "active",
"description": "For issues pertaining to our website",
"parent": "0",
"title": "Website",
"id": "2"
}
Issue classes help to classify symptoms or characteristics of an issue. They can be set up from the deployment, see the support documentation for information. Ticket classes contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique description for the class. |
title | string | A name for the class. |
description | string | A description of the class. |
parent | unsigned | The unique identifier of the parent class, if there is no parent this has value "0". |
standing | select | Either "active" or "inactive", the standing of the class. |
Get Issue
Sample Request:
GET /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
-H 'authorization: Bearer {access_token}'
GET /issues/{issue_id}
This request returns a single issue, identified by its issue_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the issue object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single requested issue with its default fields, and any additional fields
requested through _fields
.
List Issues
Sample Request:
GET /api/v0/issues HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues \
-H 'authorization: Bearer {access_token}'
GET /issues
This request returns a list of issue objects on the deployment.
Pagination
This request supports the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issues object using
the _fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
custom_id | |
referrer_type | |
referrer_id | |
against_id | |
against_type | |
status | Filter by the status_id of the issue. |
type | Filter by the type_id of the issue. Deprecated, please use issue_type . |
issue_type | Filter by the issue_type_id . |
affiliation | Filter by the affiliation_id of the issue. |
class | Filter by the class_id of the issue. |
priority | Deprecated, please use issue_priority |
issue_priority | Filter by the priority_id of the issue. |
resolution | Filter by the resolution_id of the issue. |
submitted_by | Filter by the staff_id of the submitter. |
opened_by | Filter by the staff_id of the user who opened the issue. |
closed_by | Filter by the staff_id of the user who closed the issue. |
resolved_by | Filter by the staff_id of the user who resolved the issue. |
assignee | Filter by the staff_id of the assignee. |
contract | Filter by the contract_id of any linked contracts. |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_opened |
date_submitted |
date_started |
date_due |
date_closed |
date_modified |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
id | |
date_opened | |
date_submitted | |
date_started | |
date_due | |
date_closed | |
date_resolved | |
date_last_interacted | |
date_modified | |
title | |
standing | |
status | Order by the status_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
reopened_count | Range over the number of times the issue has been reopened. |
rate_charged | |
against_id | |
billable_seconds | |
assignee | Range over the staff_id of assignees. |
type | Range over the type_id . Deprecated, please use issue_type . |
issue_type | Range over issue_type_id . |
affiliation | Range over the affiliation_id . |
class | Range over the class_id . |
resolution | Range over the range_id . |
priority | Deprecated, please use issue_priority |
issue_priority | Range over the priority_id . |
submitted_by | Range over the staff_id of submitters. |
opened_by | Range over the staff_id of staff members who opened issues. |
resolved_by | Range over the staff_id of staff members who resolved issues. |
closed_by. | Range over the staff_id of staff members who closed issues. |
status | Range over the status_id . |
rate | Range over the rate_id of the rate charged. |
contract | Range over the contract_id of contracts linked to issues. |
Object Filters
This request supports the following object filters:
Filter Name | Description |
---|---|
against | Filter by issues against these objects. |
referrer | Filter by issues referred by these objects. |
Searching
This request supports using the _search
function to search over the following fields:
Field |
---|
subject |
Handling the Response
This request will return a list of issues containing the default fields and any additional fields
request by _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Issues
Sample Request:
GET /api/v0/issues/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/count \
-H 'authorization: Bearer {access_token}'
GET /issues/count
This request will return a count of issues in a list defined by any available searches or filters. With no searches or filters this will be a count of all issues on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the issues listed. |
List Recent Issues
Sample Request:
GET /api/v0/issues/recent HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/recent \
-H 'authorization: Bearer {access_token}'
GET /issues/recent
This request returns a list of issues on the deployment sorted by most recently submitted, that is, in descending order
of date_submitted
.
Configuring the Request
This request accepts the same parameters and filters over the same fields as the GET /issues
request,
although it will always be ordered in descending order of date_submitted
.
Handling the Response
This request will return a list of contacts displayed according to any parameters used, and with their default fields
plus any additional fields requested by _fields
, and ordered in descending order of date_submitted
.
List Issue Statuses
Sample Request:
GET /api/v0/issues/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/statuses \
-H 'authorization: Bearer {access_token}'
GET /issues/statuses
This request returns a list of issue statuses on the deployment.
Configuring the Response
Pagination
This request supports the standard pagination requests.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue status object through
the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Handling the Response
This request will return a list of issue statuses with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters or searches used.
Get Issue Type
Sample request:
GET /api/v0/issues/types/{issue_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/types/{issue_type_id} \
-H 'authorization: Bearer {access_token}'
GET /issues/types/{issue_type_id}
This request returns an issue type specified by its unique id.
Configuring the Response
This request supports request additional fields and linked objects from the issue type using the
_fields
parameter.
Handling the Response
The response will contain a single issue type with its default fields and any additional fields requested through
_fields
.
List Issue Types
Sample Request:
GET /api/v0/issues/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/types \
-H 'authorization: Bearer {access_token}'
GET /issues/types
This request returns a list of issue types on the deployment. The _filters
parameter is set to
standing_not(inactive)
by default.
Configuring the Response
Pagination
This request supports the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue type object
using the _fields
parameter. Note this request does not support the _ALL
argument for this parameter.
Handling the Response
The response will be a list of issue types with their default fields and any additional fields
requested through _fields
.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
standing |
budget |
default_class_id |
parent |
Order Filters
This request supports order filters over the following fields:
Field |
---|
id |
title |
standing |
ordering |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
List Issue Classes
Sample Request:
GET /api/v0/issues/classes HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/classes \
-H 'authorization: Bearer {access_token}'
GET /issues/classes
This request returns a list of issue classes on the deployment.
Configuring the Response
This request supports requesting additional fields and linked objects from the issue class object
using the _fields
parameter. Note this request does not support the _ALL
argument for this parameter.
Handling the Response
The response will be a list of issue types with their default fields and any additional fields
requested through _fields
.
Get Issue Resolution
Sample request:
GET /api/v0/issues/resolutions/{resolution_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/issues/resolutions/{resolution_id} \
-H 'authorization: Bearer {access_token}' \
GET/issues/resolutions/{resolution_id}
This request returns a single issue resolution, specified by its resolution_id
.
Configuring the Response
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue resolution
using the _fields
parameter.
Handling the Response
The response will be the single issue resolution with its default fields, and any additional
fields requested through _fields
.
List Issue Resolutions
Sample request:
GET /api/v0/issues/resolutions HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/issues/resolutions \
-H 'authorization: Bearer {access_token}' \
GET/issues/resolutions
Returns a list of issue resolutions.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the issue resolution
using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter | Description |
---|---|
id | |
standing | |
parent_id |
Order Filters
This request supports the following order filters:
Filter | Description |
---|---|
id | |
standing | |
title |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
Empty Filters
This request supports empty filters over the following fields:
Field |
---|
title |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
Handling the Response
The response will be a list of issue resolutions with their default fields and any additional
fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Issue Resolutions
Sample request:
GET /api/v0/issues/resolutions/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/issues/resolutions/count \
-H 'authorization: Bearer {access_token}' \
GET/issues/resolutions/count
This request returns a count of issue resolutions in a list defined by any available filters or searches. With no searches or filters this will be a count of all issue resolutions on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | Unsigned | A count of issue resolutions listed |
List Tasks Against an Issue
Sample Request:
GET /issues/{issue_id}/tasks
GET /api/v0/issues/{issue_id}/tasks HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/tasks \
-H 'authorization: Bearer {access_token}'
This request returns a list of tasks against an issue specified by its issue_id
.
Configuring the Response
This response may be configuring in the same way as GET /tasks
Handling the Response
This response may be handled in the same way as GET /tasks
Update an Issue
Sample Request:
PUT /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /issues/{issue_id}
This request updates and returns an issue object, identified by its issue_id
.
Configuring the Issue
The following fields from the issue object may be updated through this request:
Notes | |
---|---|
title | |
description | |
against_id | Note: If supplied, you must also supply an against_type . |
against_type | Note: If supplied, you must also supply an against_id . |
class_id | Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes . |
affiliation_id | |
date_started | |
date_due | |
assignee | A staff_id , must point to a valid staff member. The staff will be assigned and informed of this assigned issue. |
priority_id | The priority object's id. For available priorities see GET /issues/priorities |
status_id | Must point to a valid issue status. Should not be sent in conjunction with standing , otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses . If you have a status_id , please use this instead of standing . standing will be used to guess the status, thus, status_id is more precise. Warning this will bypass any progressions and should only be used deliberately when automating tasks. |
standing | The standing you want to change the issue to (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). Warning this will bypass any progressions and should only be used deliberately when automating tasks. |
resolution_id | The identifier of the issue resolution. The resolution will only show if the issue's standing is resolved . This must point to a valid resolution, you may retrieve a list of resolutions through GET /issues/resolutions . |
resolution_detail | The details of any resolution. To clear the resolution_detail you may send this field with no value. |
contract_id | The id of the contract the issue is under, if this field is empty, the contract_id will be unset. This must point to a related contract, you can use the is_related_to_issue filter on GET /contracts to find related contracts. |
Configuring the Response
This request supports requesting additional fields and linked objects from the issue object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single updated issue with its default fields and any additional fields
requested through _fields
.
Create an Issue
Sample Request:
POST /api/v0/issues/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/ \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /issues
This request creates and returns an issue.
Configuring the Issue
Values for the following fields from the issue object may be set through this request:
Notes | |
---|---|
title | |
type_id | Must point to a valid issue type. You may retrieve a list of types through GET /issues/types . |
against_type | Must be a valid type of object. |
against_id | Must point to a valid object of type against_type . |
standing | Must be a valid standing. (e.g, 'submitted', 'open', 'resolved', 'closed', or 'inactive'). If you have a status_id , please use this instead of standing . standing will be used to guess the status, thus, status_id is more precise. |
status_id | Must point to a valid issue status. Should not be sent in conjunction with standing , otherwise standing will take priority. You may retrieve a list of statuses through GET /issues/statuses . |
affiliation_id | |
date_started | |
date_due | |
description | |
class_id | Must point to a valid issue class. You may retrieve a list of classes through GET /issues/classes |
assignee | A staff_id , must point to a valid staff member. |
priority_id | The priority object's id. For available priorities see GET /issues/priorities |
Configuring the Response
This request supports requesting additional fields and linked resources from the issue object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the created issue with its default fields and any additional fields requested
through _fields
.
Delete an Issue
Sample Request:
DELETE /api/v0/issues/{issue_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id} \
-H 'authorization: Bearer {access_token}' \
DELETE /issues/{issue_id}
This request removes an issue from the deployment, specified by its issue_id
. This request takes no parameters and
returns no resources.
List Issue Priorities
GET /issues/priorities
This request returns a list of priorities available for issues.
Get Issue Priority
GET /issues/priorities/{priority_id}
Returns a single priority for the given priority id.
Count Issue Priorities
GET /issues/priorities/count
Returns the number of issue priorities.
List an Issue's Profile Field Values
See the profiles section for a sample request
GET /issues/{issue_id}/profiles/values
This request returns a list of profile values of an issue, specified by
its issue_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "issues", and whose id is {issue_id}
.
List all Profile Field Values on Issues
See the profiles section for a sample request
GET /issues/profiles/values
This request returns a list of all profile field values on issues.
This is the request GET /{object}/profiles/values
, where the object is "issues".
List Issue Profile Fields
See the profiles section for a sample request
GET /issues/profiles/fields
This request returns a list of profile fields available for issues. This is the request
GET /{object}/profiles/fields
where the object is "issues".
Update a Profile Value on an Issue
See the profiles section for a sample request
PUT /issues/{issue_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular issue,specified by its issue_id
. This is the request
PUT/{object}/{object_id}/profiles/values/{profile_value_id}
where the object is "issues",
and whose id is the {issue_id}
.
Set a Profile Value on an Issue
See the profiles section for a sample request
POST /issues/{issue_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for an issue, specified by its issue_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "issues",
and whose value is {issue_id}
.
List Issue Extension Fields
See the extension section for an example
GET /issues/extensions/fields
This request returns a list of extension fields available for an issue, specified by its
issue_id
. This is the request GET /{object}/extensions/fields
, where the
object is "issues".
List an Issue's Extension Field Values
See the extension section for an example
GET /issues/{issue_id}/extensions/values
This request returns a list of extension values for an issue, specified by its
issue_id
. This is the request GET /{object}/{object_id}/extensions/values
, where the object is "issues", and whose id is the {issue_id}
.
List all Extension Field Values on Issues
See the extension section for an example
GET /issues/extensions/values
This request returns a list of extension field values on issues.
This is the request GET /{object}/extensions/values
, where the object is "issues".
Update an Extension Field Value on an Issue
See the extension section for an example
PUT /issues/{issue_id}/extensions/values/{extension_value_id}
This request updates the value of an extension field value, specified by its
extension_value_id
, of an issue, specified by its issue_id
. This is the request
PUT{object}/{object_id}/extensions/values/{extension_value_id}
, where the object is "issues",
and whose id is {issue_id}
Set an Extension Field Value on an Issue
Sample Request:
POST /issues/{issue_id}/extensions/fields/{extension_field_id}
This request sets and returns the value of an extension field, specified by its extension_field_id
, of an issue,
specified by its issue_id
. This request is the request
POST/{object}/{object_id}/extensions/fields/{extension_field_id}
where our object is "issues"
whose id is issue_id
.
List Available Progressions on an Issue
See the progressions section for a sample request
GET /issues/{issue_id}/progressions
This request returns a list of available progressions for an issue, specified by its
issue_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "issues" whose id is {issue_id}
.
Auto Run a Progression on an Issue
See the progressions section for a sample request
[POST|PUT] /issues/{issue_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress an issue, specified by its
issue_id
. This is the request [POST|PUT] /{object}/{object_id}/progressions/{progression_id}/auto
where the object is "issues" whose id is {issue_id}
.
List an Issue's Resource Collections
See the resources (attachments) section for an example
GET /issues/{issue_id}/collections
This request returns a list of resource collections against an issue,
specified by its issue_id
. This is the request GET /{object}/{object_id}/collections
where the object is "issues" and hose id is {issue_id}
.
Upload a Resource (Attachment) to a Collection on an Issue
See the resources (attachments) section for an example
POST /issues/{issue_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of an
issue specified by its issue_id
. This is the request
POST/{object}/{object_id}/collections/{collection_id}/resources
where the
object is "issues" whose id is {issue_id}.
Jobs (Projects)
Resource URI:
api/v0/jobs
Jobs (or Projects) help you to plan, delegate and track client and internal projects. Projects can be as simple or complex as you like, see the support documentation for more information.
The Job Object
Example job object:
{
"date_modified": "1495681796",
"modified_by": "14",
"status": "5",
"staff_bookmarked": "1",
"type": "3",
"job_type": "3",
"against": "companies/65",
"date_completed": null,
"against_id": "39",
"against_type": "company",
"company": "39",
"id": "2",
"date_due": "1495245600",
"rate": "3",
"date_created": "1495238402",
"standing": "active",
"date_started": "1495245600",
"title": "New Logo Design",
"paused": "0",
"date_last_interacted": "1495686301",
"manager": "7",
"rate_charged": "125.00",
"date_commenced": "1494209132",
"affiliation": "77",
"custom_id": "TIM#42"
}
The jobs object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the job. |
title | string | A name for the job. |
against_type | string | The type of object the job is against. |
against_id | unsigned | The unique identifier of the object the job is against. |
against | string | The API URI of the object the job is against, that is,against_type and against_id concatenated with a "/". |
custom_id | string | The custom id for this job. |
paused | integer | The number of days the jobs has been paused. |
staff_bookmarked | boolean | Whether the current user has bookmarked the job on the deployment. |
date_created | unix ts | The date the project was created. |
date_modified | unix ts | The date the project was last modified. |
date_commenced | unix ts | The date the job started, that is, when its status moved from "setup" to "active" |
date_started | unix ts | The date the job is scheduled to start. |
date_due | unix ts | The date the job is scheduled to be completed. |
date_completed | unix ts | The date the job was completed. |
date_last_interacted | unix ts | The date the job was last interacted with. |
type | unsigned or object | The job type object of the job. Deprecated, please use job_type . |
job_type | unsigned or object | The job type associated with the job. |
rate | unsigned or object | The rate object associated with the job. |
rate_charged | decimal | The rate charged for billable work, this is part of the rate object. |
status | unsigned or object | The status associated with the job |
standing | string | The standing of the project. This is part of the status. |
manager | unsigned or object | The staff manager managing the job. |
modified_by | unsigned or object | The staff member who last modified the job. |
company | unsigned or object | The company against the job, if any. |
affiliation | unsigned or object | The affiliation against the job. |
job_object_budget | unsigned or object | The object budget associated with the job. |
job_contract | unsigned or object | The contract associated with the job, if any. |
The Job Type
Example job type:
{
"id": "3",
"title": "Internal",
"standing": "active",
"ordering": "0"
}
You may set up and configure different job types to suit your business processes, general information on types can be found in the support documentation. For jobs, the type object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the job type. |
title | string | A name for the job type. |
standing | select | Either "active" or "inactive", the standing of the job type. |
ordering | integer | An integer representing the type's order as displayed on the deployment. |
Note: Requesting the job type object via type()
is deprecated, please instead
request it via job_type()
, this object will have an additional field:
Field | Type | Description |
---|---|---|
has_custom_id | boolean | Either "1" or "0", whether the job type has a custom id. |
Get Job
Sample Request:
GET /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
-H 'authorization: Bearer {access_token}'
GET /jobs/{job_id}
This request returns a single job, specified by its job_id
.
Configuring the Response
This request supports requesting additional fields and linked resources from the job object using
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single job with its default fields and any additional fields requested through _fields
.
List Jobs
Sample Request:
GET /api/v0/jobs HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs \
-H 'authorization: Bearer {access_token}'
GET /jobs
This request returns a list of jobs on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Object
This request supports requesting additional fields and linked objects from the jobs object using the
_fields
parameter. This request also supports breadcrumbs.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
against_id | |
against_type | |
paused | |
type | Filter by the type_id of the job. Deprecated, please use job_type . |
job_type | Filter by the job_type_id . |
manager | Filter by the staff_id of the job manager. |
modified_by | Filter by the staff_id of the last staff member to modify the job. |
status | Filter by the status_id . |
rate | Filter by the rate_id . |
affiliation | Filter by the affiliation_id . |
custom_id |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
dated_created |
date_modified |
date_started |
date_commenced |
date_due |
date_completed |
Order Filters
This request supports order filters over the following fields:
Filter Name | Notes |
---|---|
date_started | |
date_created | |
date_commenced | |
date_due | |
date_completed | |
date_modified | |
date_last_interacted | |
id | |
title | |
standing | |
status | Order by the status_id . |
custom_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
against_id | |
type | Range by the type_id . Deprecated, please use job_type . |
job_type | Range by the job_type_id . |
manager | Range by the staff_id of the manager of the job. |
affiliation | Range by the affiliation_id . |
modified_by | Range by the staff_id of the last staff member to modify the job. |
status | Range by the status_id . |
rate | Range by the rate_id . |
rate_charged | |
contract | Range by the contract_id of any contract associated with the job. |
plan_modified_by | Range by the staff_id of the last staff member to modify the job plan. |
custom_id |
Object Filters
This request supports the following object filters:
Filter | Description |
---|---|
against | Filter by jobs against these objects. |
Searching
This request supports the _search
filter to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of job objects containing the default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters or searches used.
Count Jobs
Sample Request:
GET /api/v0/jobs/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/count \
-H 'authorization: Bearer {access_token}'
GET /jobs/count
This request will return a count of jobs in a list defined by any available searches or filters. With no searches or filters this will be a count of all jobs on the deployment. This request returns a single field:
Field | Type | Value |
---|---|---|
count | unsigned | A count of jobs listed. |
List Recent Jobs
Sample Request:
GET /api/v0/jobs/recent HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/recent \
-H 'authorization: Bearer {access_token}'
GET /jobs/recent
This request returns a list of job on the deployment, sorted by the most recently created, that is
in descending order of date_created
.
Configuring the Response
The response to this response may be configured as per GET /jobs
, although any order filters
used will have no impact on the response.
Handling the Response
This request will return a list of job objects on the deployment with their default fields and any
additional fields requested through _fields
, displayed in descending order of date_created
and according to any
pagination parameters, filters, or searches used.
List Latest Modified Jobs
Sample Request:
GET /api/v0/jobs/newest HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/newest \
-H 'authorization: Bearer {access_token}'
GET /jobs/newest
This request returns a list of jobs on the deployment, sorted by the most recently modified, that
is, in descending order of date_modified
.
Configuring the Response
The response to this response may be configured as per GET /jobs
, although any order filters
used will have no impact on the response.
Handling the Response
This request will return a list of job objects on the deployment with their default fields and any
additional fields requested through _fields
, displayed in descending order of date_modified
and according to any
pagination parameters, filters, or searches used.
Get Job Type
Sample request:
GET /api/v0/jobs/types/{job_type_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_fields=standing,has_custom_id
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/types/{job_type_id} \
-H 'authorization: Bearer {access_token}' \
-d '_fields=standing,has_custom_id'
GET /jobs/types/{job_type_id}
This request returns a job type specified by its unique id.
Configuring the Response
This request supports requesting additional fields and linked objects from the job type object using the
_fields
parameter.
Handling the Response
The response will contain a single job type with its default fields and any additional fields requested through
_fields
.
List Job Types
Sample request:
GET /api/v0/jobs/types HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
_fields=standing,has_custom_id
_filters=standing(active)
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/types \
-H 'authorization: Bearer {access_token}' \
-d '_fields=standing,has_custom_id' \
-d '_filters=standing(active)'
GET /jobs/types
This request returns a list of job types.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the job type using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
standing |
Order Filters
This request supports order filters over the following fields:
Field |
---|
id |
title |
standing |
Range Filters
This request supports range filters over the following fields:
Field |
---|
id |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
Handling the Response
The response will be a list of job types with their default fields and any additional fields requested
through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Get Job Status
Sample Request:
GET /api/v0/jobs/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/statuses/{status_id} \
-H 'authorization: Bearer {access_token}'
GET /jobs/statuses/{status_id}
This request returns the job status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a job status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Job Statuses
Sample request:
GET /api/v0/jobs/statuses HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/jobs/statuses \
-H 'authorization: Bearer {access_token}' \
GET/jobs/statuses
This request returns a list of job statuses.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter | Notes |
---|---|
id | |
title | |
standing | |
color |
Order Filters
This request supports order filters over the following fields:
Filter | Notes |
---|---|
id | |
title | |
standing | |
color | |
ordering |
Searching
This request supports the _search
parameter to search over the following
fields:
Field |
---|
title |
Handling the Response
The response will be a list of statuses with their default fields and any additional fields requested
through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Job Statuses
Sample Request:
GET /api/v0/jobs/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/statuses/count \
-H 'authorization: Bearer {access_token}' \
GET /jobs/statuses/count
This request will return a count of job statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all job statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed job statuses. |
List Job Milestones
Sample Request:
GET /api/v0/jobs/{job_id}/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id}/milestones \
-H 'authorization: Bearer {access_token}'
GET /jobs/{job_id}/milestones
This request returns a list of milestones of a job, specified by its job_id
. This request is handled
and configured in the same way as GET /milestones
.
Update a Job
Sample Request:
PUT /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
PUT /jobs/{job_id}
This request updates and returns a job, specified by its job_id
.
Configuring the Job
The following fields from the job object may be updated with this request:
Filter Name | Notes |
---|---|
title | |
engagement_table | The against_type for the job |
engagement_id | The against_id for the job. |
manager_id | The staff_id of the staff member to be assigned manager. |
status_id | MUST point to a valid job status. |
contract_id | The contract_id of a contract to be linked to the job |
affiliation_id | The affiliation_id of an affiliation to be linked to the job. |
rate_id | |
rate_charged | |
date_due | |
date_created |
Configuring the Response
This request supports requesting additional fields and linked resources from the jobs object through
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single, updated job with its default fields and any additional fields
requested through _fields
.
Create a Job
Sample Request:
POST /api/v0/jobs/ HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/\
-H 'authorization: Bearer {access_token}' \
-H 'Content-Type: application/x-www-form-urlencoded'
POST /jobs
This request creates and returns a new job.
Configuring the Job
The following fields may be set through this request:
Filter Name | Notes |
---|---|
against_type | The against_type for the job. |
against_id | The against_id for the job. |
manager_id | The staff_id of the staff member to be assigned manager. This MUST point to a valid staff. |
type_id* | MUST point to a valid job type. |
title | |
rate_id | |
status_id | MUST point to a valid job status. |
contract_id | The contract_id of a contract to be linked to the job. |
affiliation_id | The affiliation_id of an affiliation to be linked to the job. |
rate_charged | |
date_due | |
date_started | |
date_created | If this is not sent it will default to the current time. |
is_billable | If the job is billable or nonbillable |
Configuring the Response
This request supports requesting additional fields and linked resources from the jobs object through
the _fields
parameter. This request also supports breadcrumbs.
Handling the Response
The response will be the single, created job with its default fields and any additional fields
requested through _fields
.
Delete a Job
Sample Request:
DELETE /api/v0/jobs/{job_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/jobs/{job_id} \
-H 'authorization: Bearer {access_token}'
DELETE /jobs/{job_id}
This request deletes a job from the deployment, specified by its job_id
. This request takes no arguments and returns
no resources.
List a Job's Profile Field Values
See the profiles section for a sample request
GET /jobs/{job_id}/profiles/values
This request returns a list of profile values of a job, specified by its
job_id
. This is the request GET /{object}/{object_id}/profiles/values
, where
the object is "jobs", and whose id is {job_id}
.
List all Profile Field Values on a Job
See the profiles section for a sample request
GET /jobs/profiles/values
This request returns a list of all profile field values on jobs. This
is the request GET /{object}/profiles/values
, where the object is "jobs".
List Jobs Profile Fields
See the profiles section for a sample request
GET /jobs/profiles/fields
This request returns a list of profile fields available for jobs. This is the request
GET/{object}/profiles/fields
where the object is "jobs".
Update a Profile Value on a Job
See the profiles section for a sample request
PUT /jobs/{job_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular job, specified by its job_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "jobs", and
whose value is {job_id}
.
Set a Profile Value on a Job
See the profiles section for a sample request
POST /jobs/{job_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for a "job", specified by its job_id
. This is the request
POST/{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is "jobs", and
whose value is {job_id}
.
List Job Extension Fields
See the extension section for an example
GET /jobs/extensions/fields
This request returns a list of extension fields available for any job.
This is the request GET /{object}/extensions/fields
, where the object is
"jobs".
List a Job's Extension Field Values
See the extension section for an example
GET /jobs/{job_id}/extensions/values
This request returns a list of extension values for a job, specified
by its job_id
. This is the request GET /{object}/{object_id}/extensions/values
,
where the object is "jobs", and whose id is the job_id
.
List all Extension Field Values on Jobs
See the extension section for an example
GET /jobs/extensions/values
This request returns a list of extension field values on jobs.
This is the request GET /{object}/extensions/values
, where the object is "jobs".
Update an Extension Field Value on a Job
See the extension section for an example
PUT /jobs/{job_id}/extensions/values/{extension_value_id}
This request updates the value of an extension field value, specified by its
extension_value_id
, of a job, specified by its job_id
. This is the request
PUT{object}/{object_id}/extensions/values/{extension_value_id}
, where the object is "jobs",
and whose id is job_id
Set an Extension Field Value on a Job
Sample Request:
POST /jobs/{job_id}/extensions/fields/{extension_field_id}
This request sets and returns the value of an extension field, specified by its extension_field_id
, of a job,
specified by its job_id
. This request is the request
POST/{object}/{object_id}/extensions/fields/{extension_field_id}
where our object is "jobs"
whose id is job_id
.
List Available Progressions on a Job
See the progressions section for a sample request
GET /jobs/{jobs_id}/progressions
This request returns a list of available progressions for a job, specified
by its job_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "jobs" whose id is job_id
.
Auto Run Progression on a Job
See the progressions section for a sample request
[POST|PUT] /jobs/{jobs_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress a job,
specified by its jobs_id
. This is the request
[POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto
where the object is "jobs" whose id is job_id
.
List a Job's Resource Collections
See the resources (attachments) section for an example
GET /jobs/{job_id}/collections
This request returns a list of resource collections against a job,
specified by its job_id
. This is the request GET /{object}/{object_id}/collections
where the object is "jobs" and hose id is {job_id}
.
Upload a Resource (Attachment) to a Collection on a Job
See the resources (attachments) section for an example
POST jobs/{job_id}/collections/{collection_id}/resources
This request uploads a resource to a collection, specified by its collection_id
, of a job
specified by its job_id
. This is the request
POST/{object}/{object_id}/collections/{collection_id}/resources
where the
object is "jobs" whose id is {job_id}.
Ledgers
Accelo supports account ledgers, it also allows account ledger integration with certain online accounting systems (e.g. Xero). These account ledgers are described by the API through the ledger
object. For information on viewing, adding and syncing account ledgers from your deployment, please see the support documentation.
The Ledger Object (Beta)
Example ledger
{
"code": "200",
"comment": "Ledger to be used for sales",
"id": "1",
"title": "Sales",
"standing": "active",
"parent_id": "0"
}
The ledger object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the ledger. |
title | string | The ledger's title. |
code | string | The account ledger code |
parent_id | unsigned | The unique identifier of the parent ledger, defaults to "0" is there is no parent |
standing | select | The standing of the ledger, either "active" or "inactive". |
comment | string | Comments on the ledger |
Get Ledger (Beta)
GET /api/v0/ledgers/{ledger_id} HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/ledgers/{ledger_id} \
-H 'authorization: Bearer {access_token}'
GET /ledgers/{ledger_id}
This request returns a ledger identified by its unique ledger_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the ledger object using the _fields
parameter.
Handling the Response
The response wil be the single ledger with its default fields and any additional fields requested through _fields
.
List Ledgers (Beta)
GET /api/v0/ledgers HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/ledgers/ \
-H 'authorization: Bearer {access_token}'
GET /ledgers
This request returns a list of ledgers.
Configuring the Response
Pagination
This request supports all the standard pagination parameters.
Additional fields and Linked Objects
This request supports requesting additional fields and linked objects from the ledger object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
code |
parent_id |
standing |
Order Filters
This request supports the following order filters:
Filter |
---|
id |
code |
parent_id |
standing |
title |
Range Filters
This request supports the following range filters:
Filter |
---|
id |
parent_id |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
code |
Handling the Response
The response will be a list of ledgers with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Count Ledgers (Beta)
GET /api/v0/ledgers/count HTTP/1.1
Host: {deployment}.api.accelo
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/api/v0/ledgers/count \
-H 'authorization: Bearer {access_token}'
GET /ledgers/count
This request will return a count of ledgers in a list defined by any available searches or filters. With no searches or filters this will be a count of all ledgers on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of ledgers listed. |
Milestones
Resource URI:
/api/vo/milestones
Milestones are the steps on the road to a Job's (Project's) completion. They define the schedule of the job, and contain the budget for their respective portion of the job. For information on accessing milestones through the deployment, see the support documentation, milestones may also be imported through the deployment, see again the support documentation for information.
Deleting, creating, and updating milestones is only available through the deployment on the project planning screen, see the support documentation for more information.
The Milestone Object
Example milestone object:
{
"date_modified": "1494912868",
"date_completed": "1494911355",
"status": "4",
"date_due": "1495072800",
"id": "1",
"description": "Initial planning",
"standing": "complete",
"date_created": "1494286008",
"job": "2",
"rate": "3",
"title": "A milestone",
"date_started": "1494208800",
"object_budget": "12",
"milestone_object_budget": "12",
"rate_charged": "125.00",
"ordering": "1",
"parent": "0",
"manager": "21",
"date_commenced": "1494286232"
}
The milestone object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the milestone. |
title | string | A name for the milestone. |
description | string | A description of the milestone. |
ordering | integer | An integer representing the milestone's ordering on the deployment. |
parent | unsigned | The unique identifier of the parent milestone. If there is not parent this has the value "0". |
date_created | unix ts | The date the milestone was created. |
date_modified | unix ts | The date the milestone was last modified. |
date_started | unix ts | The date the milestone is scheduled to start. |
date_commenced | unix ts | The date the milestone was started, that is, when the standing was changed from "pending". |
date_due | unix ts | The date the milestone is scheduled to be completed. |
date_complete | unix ts | The date the milestone was completed. |
job | unsigned or object | The job (project) the milestone has been created for. |
manager | unsigned or object | The staff member assigned to manage the project. |
status | unsigned or object | The status of the milestone. |
standing | string | The standing of the milestone. This is part of the status object |
rate | unsigned or object | The rate associated with the milestone. |
rate_charged | decimal | The rate charged for billable work within this milestone. This is part of the rate object. |
milestone_object_budget | unsigned or object | The object budget associated with the milestone. |
object_budget | unsigned or object | Deprecated please use milestone_object_budget . |
Get Milestone
Sample Request:
GET /api/v0/milestones/{milestone_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/{milestone_id} \
-H 'authorization: Bearer {access_token}'
GET /milestones/{milestone_id}
This request returns a single milestone, identified by its milestone_id
.
Configuring the Response
This request supports requesting additional fields and linked resource from the milestone object
using the _fields
parameter.
Handling the Response
The response will be the single milestone with its default fields and any additional fields
requested through _fields
.
List Milestones
Sample Request:
GET /api/v0/milestones HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones \
-H 'authorization: Bearer {access_token}'
GET /milestones
This request returns a list of milestones on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports request additional fields and linked objects from the milestone object
using the _fields
.
Basic Filters
This request supports basic filters over the following fields:
Filter Name | Notes |
---|---|
id | |
standing | |
ordering | |
job | Filter by the job_id . |
parent | Filter by the milestone_id of the parent milestone. |
manager | Filter by the staff_id of the manager. |
rate | Filter by the rate_id . |
object_budget | Filter by the object_budget_id . |
status | Filter by the status_id . |
Date Filters
This request supports date filters over the following fields:
Filter Name |
---|
date_modified |
date_created |
date_started |
date_commenced |
date_due |
date_completed |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
job | Range by the job_id . |
manager | Range by the staff_id of the manager. |
status | Range by the status_id . |
modified_by | Range by the staff_id of the last staff to modify the milestone. |
rate | Range by the rate_id . |
rate_charged |
Searching
This request supports the _search
parameter to search over the following fields:
Filter Name |
---|
title |
Handling the Response
The response will be a list of milestones containing their default
fields and any additional fields requested through _fields
, and displayed according to any pagination parameters,
filters, or searches used.
Count Milestones
Sample Request:
GET /api/v0/milestones/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/count \
-H 'authorization: Bearer {access_token}'
GET /milestones/count
This request will return a count of milestones in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestones on the deployment. This request does not return a response object, just a single value:
Field | Type | Description |
---|---|---|
response | unsigned | A count of milestones listed. |
Get Milestone Status
Sample Request:
GET /api/v0/milestones/statuses/{status_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/statuses/{status_id} \
-H 'authorization: Bearer {access_token}' \
GET /milestones/statuses/{status_id}
This request returns the milestone status specified by its status_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the status object using the
_fields
parameter.
Handling the Response
The response will be a milestone status object for the specified status with its default fields and any
additional fields requested through _fields
.
List Milestone Statuses
Sample Request:
GET /api/v0/milestones/statuses HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/statuses \
-H 'authorization: Bearer {access_token}'
GET /milestones/statuses
This request returns a list of milestone statuses on the deployment.
Configuring the Response
Pagination
This request supports the standard pagination requests.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the milestone status object through
the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
title |
standing |
color |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
title |
standing |
color |
ordering |
Searching
This request supports the _search
parameter to search over the following fields:
Field |
---|
title |
Count Milestone Statuses
Sample Request:
GET /api/v0/milestones/statuses/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/milestones/statuses/count \
-H 'authorization: Bearer {access_token}' \
GET /milestones/statuses/count
This request will return a count of milestone statuses in a list defined by any available searches or filters. With no searches or filters this will be a count of all milestone statuses on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of the listed milestone statuses. |
List a Milestone's Profile Field Values
See the profiles section for a sample request
GET /milestones/{milestone_id}/profiles/values
This request returns a list of profile values of a milestone,
specified by its milestone_id
. This is the request GET /{object}/{object_id}/profiles/values
,
where the object is "milestones", and whose id is milestone_id
.
List all Profile Field Values on a Milestone
See the profiles section for a sample request
GET /milestones/profiles/values
This request returns a list of all profile field values on milestones.
This is the request GET /{object}/profiles/values
, where the object is "milestones".
List Milestone Profile Fields
See the profiles section) for a sample request
GET /milestones/profiles/fields
This request returns a list of profile fields available for milestones.
This is the request GET /{object}/profiles/fields
where the object is "milestones".
Update a Profile Field Value on a Milestone
See the profiles section for a sample request
PUT /milestones/{milestone_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular milestone, specified by its milestone_id
. This is the request
PUT/{object}/{object_id}/profiles/values/{profile_value_id}
where the object is
"milestones", and whose id is the milestone_id
.
Set a Profile Field Value on a Milestone
See the profiles section for a sample request
POST /milestones/{milestone_id}/profiles/fields/{profile_field_id}
This request sets and returns a profile value for a profile field, specified by its
profile_field_id
, for a milestone, specified by its milestone_id
. This is the request
POST /{object}/{object_id}/profiles/fields/{profile_field_id}
where the object is
"milestones", and whose value is milestone_id
.
List Available Progressions on a Milestone
See the progressions section for a sample request
GET /milestones/{milestone_id}/progressions
This request returns a list of available progressions for a milestone,
specified by its milestone_id
. This is the request GET /{object}/{object_id}/progressions
where the object is "milestones" whose id is milestone_id
.
Auto Run a Progression on a Milestone
See the progressions section for a sample request
PUT|POST /milestones/{milestone_id}/progressions/{progression_id}/auto
This request uses the given progression, specified by its progression_id
to progress a milestone,
specified by its milestone_id
. This is the request
[POST|PUT]/{object}/{object_id}/progressions/{progression_id}/auto
where theobject is "milestone" whose id is milestone_id
.
Object Budgets
Resource URI:
api/v0/object_budgets
Object budgets are budgets against a specific object, for example a budget against an issue or a milestone. They are able to track the time and money spent by staff and on services, as well as expenses and the cost of materials.
The Object Budget
Example object budget:
{
"charged": "45.84",
"service_time": "0",
"material_price_subtotal": "56.10",
"service_time_estimate": "0",
"service_price_subtotal_estimate": "425.00",
"billable": "1320",
"expense_price": "0.00",
"material_cost_subtotal": "35.50",
"remaining_subtotal": "180",
"object_table": "job",
"service_price_subtotal": "0.00",
"charged_subtotal": "70.84",
"logged": "1500",
"object_id": "2",
"logged_subtotal": "2100",
"is_billable": "yes",
"billable_subtotal": "1920",
"material_cost": "35.50",
"id": "11",
"service_price_estimate": "0.00",
"nonbillable": "180",
"service_price": "0.00",
"material_price": "56.10",
"service_time_subtotal_estimate": "10800",
"nonbillable_subtotal": "180"
}
The object budget resource contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the object budget. |
against_type | string | The type of object the object budget is against. |
against_id | unsigned | The unique identifier of the object the object budget is against. |
object_table | string | The type of object the object budget is against. Deprecated please use "against_type". |
object_id | unsigned | The unique identifier of the object the object budget is against.Deprecated please use "against_type". |
object | string | The API URI of the object the object budget is against. This is "{against_type} /{against_id} " |
is_billable | select | Either "yes" or "no", whether time logged against the object is billable. |
service_time_estimate | integer | The estimated total time for services against the object, in seconds. |
service_time | integer | The total time logged for services against the object, in seconds. |
service_time_subtotal_estimate | integer | The estimated total time for services against the object and its children, in seconds. |
service_price_estimate | decimal | An estimate for the total price of services against the object. |
service_price | decimal | The total price of services against the object. |
service_price_subtotal_estimate | decimal | An estimate for the total price of services against the object and all of its children. |
service_price_subtotal | decimal | The total price of services against the object and all of its children. |
expense_price | decimal | The total prices of expenses for the object. |
material_cost | decimal | The total cost of materials for the object. |
material_cost_subtotal | decimal | the total cost of materials for the object and all its children. |
material_price | decimal | The total price of materials for the object. |
material_price_subtotal | decimal | The total price of materials for the object and all its children. |
billable | integer | The total billable time logged against the object, in seconds. |
billable_subtotal | integer | The total billable time logged against the object and all its children, in seconds. |
nonbillable | integer | The total nonbillable time logged against the object, in seconds. |
nonbillable_subtotal | integer | The total nonbillable time logged against the object and all its children, in seconds. |
logged | integer | The total time logged against the object, in seconds. That is, the sum of billable and nonbillable . |
logged_subtotal | integer | The total time logged against the object and all its children, in seconds. |
charged | decimal | The total cost charged against the object. |
charged_subtotal | decimal | The total cost charged against the object, and all its children. |
remaining_subtotal | decimal | If object_table is tasks the remaining budget for the task, otherwise the sum of the remaining subtotal of all the object's children's. |
The Item Template Object
Example template object:
{
"code": "260",
"cost": "0.0000",
"cost_rate_id": null,
"description": "Other Revenue GST on Income",
"expense_type_ledger": "20",
"id": "8",
"ledger_id": "20",
"line_item_ledger": "20",
"price": "0.0000",
"price_rate_id": null,
"quantity": "1.0000",
"standing": "active",
"tax_id": "12",
"title": "Other Revenue GST on Income",
"type": "service"
}
These are templates for expenses, materials, and services. These templates allow you to easily add items to your budgets. The template object contains:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the template. |
title | string | The title of the template. |
description | string | A description of the template. |
price | decimal | The sale price. |
type | select | Either 'expense', 'material', or 'service', the type of item described by the template. |
code | string | The code given for the template |
standing | select | Either 'active' or 'inactive', the standing of the template. |
quantity | decimal | The default quantity used with this template. |
cost | Decimal | The cost (or purchase price) of the template. |
cost_rate_id | unsigned | The id of the cost rate associated with the template (if any). |
cost_tax_id | unsigned | The id of the cost tax (or purchase tax) associated with the template. |
cost_ledger_id | unsigned | The id of the cost ledger (or purchase ledger) associated with the template. |
price | decimal | The sale price of the template. |
price_rate_id | unsigned | The id of the price rate associated with the template (if any). |
tax_id | unsigned | The id of the sale tax associated with the template. |
ledger_id | unsigned | Then id of the sale ledger associated with the template. |
line_item_ledger | unsigned or object | The ledger associated with the template. |
expense_type_ledger | unsigned or object | Where type is expense , the ledger associated with the template. |
cost_tax | unsigned or object | The cost tax (or purchase tax) associated with the template. |
cost_ledger | unsigned or object | The cost ledger (or purchase ledger) associated with the template. |
The Material Object
Example material object:
{
"against_id": "201",
"against_type": "milestone",
"budget_item_template": "0",
"budget_item_template_id": "0",
"cost": "24.0000",
"date_created": "1457523796",
"id": "10",
"material_item_ledger": "0",
"material_item_ledger_id": null,
"ordering": "0",
"price": "0.9900",
"quantity": "1.0000",
"tax_id": null,
"title": "Design Tools",
"contract_period_id": null,
}
These describe instances of material templates as items on a budget. These contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the material. |
title | string | A title for the material. |
against_type | string | The type of object the material has be added against. |
against_id | unsigned | The id of the object the material has been added against. |
quantity | decimal | The quantity of the material added. |
cost | decimal | The cost (or purchase price) of the material. |
price | decimal | The sale price of the material |
date_created | unix ts | The date the material was created. |
material_ledger_id | unsigned | The unique identifier of the ledger used by the material. |
material_template_id | unsigned | The unique identifier of the item template the material is based off. |
tax_id | unsigned | The unique identifier of the tax on the material. |
material_ledger | unsigned or object | The ledger used by the material. |
material_template | unsigned or object | The item template the material is based off. |
ordering | unsigned | A number describing the order the material is displayed. |
contract_period_id | unsigned | The unique identifier for the contract period the material is linked to. |
The Service Object
Example service object:
{
"against_id": "22",
"against_type": "contract",
"budget_item_template": "8",
"budget_item_template_id": "8",
"id": "92",
"service_item_ledger": "20",
"service_item_ledger_id": "20",
"tax_id": "12"
}
These describe instances of service templates as items on a budget. These contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the service. |
against_type | string | The type of object the service has been added against. |
against_id | unsigned | The id of the object the service has been added against. |
service_ledger_id | unsigned | The unique identifier of the ledger used by the service. |
service_template_id | unsigned | The unique identifier of the template used by the service. |
tax_id | unsigned | The unique identifier of the tax used by the service. |
service_ledger | unsigned or object | The ledger used by the service. |
service_template | unsigned of object | The template used by the service. |
Get Object budget
Sample Request:
GET /api/v0/object_budgets/{object_budget_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/object_budgets/{object_budget_id} \
-H 'authorization: Bearer {access_token}'
GET /object_budgets/{object_budget_id}
This request returns an object budget identified by its object_budget_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the object budget using the _fields
parameter.
Handling the Response
The response will be the single object budget with its default fields and any additional fields requested through _fields
.
List Object Budgets
Sample Request:
GET /api/v0/object_budgets HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/object_budgets \
-H 'authorization: Bearer {access_token}'
GET /object_budgets
This request returns a list of object budgets on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the object budget using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name |
---|
id |
against_id |
against_type |
Order Filters
This request supports the following order filters:
Filter Name |
---|
id |
Object Filters
This request supports the following object filters:
Filter Name |
---|
against |
Handling the Response
The response will be a list of object budgets with their default fields and any additional fields requested through _fields
, and displayed according to any pagination requests used.
Count Object Budgets
Sample Request:
GET /api/v0/object_budgets/count HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/object_budgets/count \
-H 'authorization: Bearer {access_token}'
GET /object_budgets/count
This request will return a count of object budgets in a list defined by any available searches or filters. With no searches or filters this will be a count of all object budgets on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of object budgets listed. |
List Item Templates
Sample request:
GET /api/v0/object_budgets/templates HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/object_budgets/templates \
-H 'authorization: Bearer {access_token}' \
GET /object_budgets/templates
This request returns a list of item templates on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the
item template object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name | Notes |
---|---|
id | |
type | |
standing | |
ledger_id | |
cost_ledger_id | |
cost_tax_id | |
tax_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
price | |
cost |
Order Filters
This request supports the following order filters:
Filter Name | Notes |
---|---|
id | |
cost | |
title | |
price | |
standing |
Empty Filters
This request supports empty filters over the following fields:
Filter Name | Notes |
---|---|
title |
Searching
This request supports the _search
parameter
to search over the following fields:
Field |
---|
title |
description |
code |
Handling the Response
The response will be a list of item templates with their default fields and any additional
fields requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
List Materials
Sample request:
GET /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
-H 'authorization: Bearer {access_token}' \
GET /object_budgets/materials
This request returns a list of materials on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the material object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name | Notes |
---|---|
id | |
against_id | |
against_type | |
material_ledger_id | |
material_template_id | |
quantity | |
cost | |
price | |
tax_id | |
contract_period_id |
Date Filters
This request supports date filters over the following fields:
Filter Name | Notes |
---|---|
date_created |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id | |
cost | |
price | |
quantity |
Order Filters
This request supports the following order filters:
Filter Name | Notes |
---|---|
id | |
quantity | |
price | |
cost | |
date_created |
Searching
This request supports the _search
parameter
to search over the following fields:
Field |
---|
title |
Handling the Response
The response will be a list of materials with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
List Services
Sample request:
GET /api/v0/object_budgets/services HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deployment}.api.accelo.com/api/v0/object_budgets/services \
-H 'authorization: Bearer {access_token}' \
GET/object_budgets/services
This request returns a list of services on the deployment.
Configuring the Response
Pagination
This request supports all the pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the service object using the
_fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter Name | Notes |
---|---|
id | |
against_id | |
against_type | |
service_template_id | |
service_ledger_id | |
tax_id |
Range Filters
This request supports range filters over the following fields:
Filter Name | Notes |
---|---|
id |
Object Filters
This request supports the following object filters:
Filter Name | Notes |
---|---|
against |
Order Filters
This request supports the following order filters:
Filter Name | Notes |
---|---|
id |
Handling the Response
The response will be a list of services with their default fields and any additional fields
requested through _fields
, and displayed according to any pagination parameters, filters, or searches used.
Update a Material
Sample request:
PUT /api/v0/object_budgets/materials/{material_id} HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
quantity=10
price=20
curl -X PUT \
https://{deployment}.api.accelo.com/api/v0/object_budgets/materials/{material_id} \
-H 'authorization: Bearer {access_token}' \
-d 'quantity=10'
-d 'price=20'
PUT /object_budgets/materials/{material_id}
This request updates and returns the material with the given material_id
Configuring the Response
The following fields may be used to update the material:
Field Name | Notes |
---|---|
title | |
quantity | |
price | |
cost | |
template_id |
Configuring the Response
This request supports requesting additional fields and linked objects from the material object
using the _fields
parameter.
Handling the Response
The response will be the update material with its default fields and any additional fields requested through_fields
.
Create a Material
Sample request:
POST /api/v0/object_budgets/materials HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
authorization: Bearer {access_token}
against_type=contract_period
against_id=123
title=Shovels for digging
quantity=12
cost=10
price=2
template_id=4
curl -X POST \
https://{deployment}.api.accelo.com/api/v0/object_budgets/materials \
-H 'authorization: Bearer {access_token}' \
-d 'against_type=contract_period' \
-d 'against_id=123' \
-d 'title=Shovels for digging' \
-d 'quantity=12' \
-d 'cost=10' \
-d 'price=2' \
-d 'template_id=4'
POST /object_budgets/materials
This request creates and returns a material.
Configuring the Response
The following fields may be set when creating the material:
Field Name | Notes |
---|---|
against_type | Supports: 'job', 'issue', 'milestone', 'contract_period' |
against_id | |
title | |
quantity | |
price | |
cost | |
template_id |
Handling the Response
The response will be the newly created material with its default fields and any additional fields requested through_fields
.
Object Schedules
An object schedule is a schedule against a specific object. For example, the schedule on a given task.
The Object Schedule
Sample JSON object:
{
"date_planned_due": "1362618000",
"against_id": "24",
"date_planned_start": "1362358800",
"id": "113",
"against_type": "task"
}
The object schedule budget contains the following
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the object schedule. |
against_id | unsigned | The unique identifier of the object the schedule is against. |
against_type | string | The type of object the schedule is against. |
date_planned_start | unix ts | The planned start date. |
date_planned_due | unix ts | The planned due date. |
date_predicted_start | unix ts | The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations. |
date_predicted_end | unix ts | The predicted start date computed by Accelo based on current progress, the dates of any dependencies and planned durations. |
date_commenced | unix ts | The actual commenced date. |
date_completed | unix ts | The actual completed date. |
date_user_estimated_start | unix ts | The date the assignee has scheduled to start the work. |
date_user_estimated_due | unix ts | The date the assignee has scheduled to complete the work. |
date_targeted_start | unix ts | The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations. |
date_targeted_due | unix ts | The date the assignee becomes responsible for the work, based on current progress, planned dates, and the planned durations. |
date_fixed_start | unix ts | The fixed start date. |
date_fixed_due | unix ts | The fixed deadline for the due date. |
There are no endpoints associated with this object.
Payments
Resource URI
/api/v0/payments
Payments made, for example against an invoice, are stored under the payments
object through the API. Attached to these payments are methods, receipts, and the currency used.
The Payment Object (Beta)
Sample payment object:
{
"payment_method": "2",
"receipt_id": "28945",
"id": "30507",
"currency_id": "0",
"direction": "credit",
"created_by_staff_id": "1055",
"method_id": "2",
"amount": "79.00",
"against_id": "31347",
"date_created": "1496887498",
"payment_currency": "0",
"against_type": "account_invoice",
"payment_receipt": "28945"
}
The payment object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the payment. |
receipt_id | unsigned | The unique identifer of the receipt associated with the payment. |
amount | decimal | The amount paid through the payment. |
currency_id | unsigned | The unique identifier of the currency used. |
method_id | unsigned | The unique identifier of the payment method. |
against_id | unsigned | The unique identifier of the object the payment is against. |
against_type | string | The type of object the payment is against. |
date_created | unix ts | The date the payment was created. |
created_by_staff_id | unsigned | The unique identifier of the staff member who entered the payment. |
direction | select | Either "debit" or "credit", defaults to "credit". |
payment_currency | unsigned or object | The currency used for the payment. |
payment_method | unsigned or object | The method of the payment. |
payment_receipt | unsigned or objects | The receipt for the payment. |
The Payment Receipt Object (Beta)
Sample receipt object:
{
"owner_type": "staff",
"owner_id": "1055",
"id": "28945",
"affiliation_id": "152348",
"amount": "79.00"
}
Where a payment object stores the information on a payment made against a single object, a receipt may be issued for a single payment, or a collection of payments. For information on accessing receipts from the deployment and receiving receipts from an integrated accounting system see the support documentation. The receipt object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | The unique identifier of the receipt. |
amount | decimal | The amount the receipt is for. |
affiliation_id | unsigned | The unique id of the affiliation associated with the receipt. |
owner_id | unsigned | The unique identifier of the owner. |
owner_type | select | Either "staff" or "contact", the type of owner of the receipt. |
The Payment Method Object (Beta)
Sample payment method object:
{
"id": "2",
"title": "Visa",
"standing": "active"
}
The payment method describes the different methods payment may be given, for example via cash or via mastercard. Payments from online billing systems should automatically update the method, see the support documentation for more information. The payment method object contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the method. |
title | string | A name for the method. |
standing | select | Either "active" or "inactive", the standing of the method. |
The Currency Object (Beta)
Sample currency object:
{
"rate": "1",
"id": "1",
"symbol": "$",
"title": "Australian Dollars",
"code": "AUD"
}
The different currencies that may be handled by your deployment are stored in the currency object, this contains the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the currency. |
title | string | A name for the currency. |
code | string | A short code for the currency. |
symbol | character | The symbol used for the currency. |
rate | decimal | The rate, generally pulled from an external accounting system. |
Get Payment (Beta)
Sample request, list payments against a specific invoice:
GET /payments/{payment_id} HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
filters=against(account_invoice(133))
curl -X GET \
https://{deplyoment}.api.accelo.com/payments/{payment_id} \
-H 'authorization: Bearer {access_token}' \
-d 'filters=against(account_invoice(133))
GET /payments/{payment_id}
This request returns a payment identified by its unique payment_id
.
Configuring the Response
This request supports requesting additional fields and linked object from the payment object using the _fields
parameter.
Handling the Response
The response will be the single payment object with its default fields and any additional fields requested through _fields
.
List Payments (Beta)
Sample request:
GET /payments/ HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/payments/ \
-H 'authorization: Bearer {access_token}'
GET /payments
This request returns a list of payments on the deployment.
Configuring the Response
Pagination
This request supports all the standard pagination parameters.
Additional Fields and Linked Objects
This request supports requesting additional fields and linked object from the payment object using the _fields
parameter.
Basic Filters
This request supports the following basic filters:
Filter |
---|
id |
currency_id |
method_id |
receipt_id |
created_by_staff_id |
against_id |
against_type |
Date Filters
This request supports date filters over the following fields:
Field |
---|
date_created |
Order Filters
This request supports the following order filters:
Filter |
---|
id |
currency_id |
method_id |
receipt_id |
created_by_staff_id |
amount |
date_created |
direction |
against_id |
Range Filters
This request supports the following range filters:
Filter |
---|
id |
currency_id |
method_id |
receipt_id |
created_by_staff_id |
amount |
against_id |
Object Filters
This request supports the following object filters:
Filter | Description |
---|---|
against | Filter by the object the payment is against. |
Handling the Response
The response will be a list of payments with their default fields and any additional fields requested through _fields
, and displayed according to any pagination parameters or filters used.
Count Payments (Beta)
Sample request:
GET /payments/count HTTP/1.1
Host: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X GET \
https://{deplyoment}.api.accelo.com/payments/count \
-H 'authorization: Bearer {access_token}'
GET /payments/count
This request will return a count of payments in a list defined by any available searches or filters. With no searches or filters this will be a count of all payments on the deployment. This request returns a single field:
Field | Type | Description |
---|---|---|
count | unsigned | A count of payments listed. |
Profiles
Profile fields are objects used for tracking extra information from your Accelo deployment. See the support documentation for further information about profile fields. Currently, custom profile fields are supported on the following objects:
The Profile Field Object
Example profile field:
{
"link_type": "company",
"required": "no",
"parent_id": "0",
"description": "These are the companies opening hours in the form \"HH-HH\", use 24h time.",
"id": "12",
"lookup_type": null,
"confidential": "no",
"field_name": "Opening Hours",
"restrictions": "all",
"field_type": "text",
"exported": "no"
}
These are objects describing the custom fields on the deployment, they contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the profile field. |
field_name | string | A name for the profile field. |
field_type | select | The type of the profile field. This can be "text", "integer", "decimal", "date", "date_time", "currency", " lookup", "structure", "select", "multi_select", or "hyperlink". |
parent_id | unsigned | The unique identifier of the parent profile field. If there is no parent this has a value of "0". |
link_type | string | The type of object this profile field is against. For example "contact". |
required | select | Either "yes" or "no", whether this profile field is required for the object it is against. |
restrictions | select | Who is able to edit the value of this field. May be one of "all", "edit", "process", "admin". For example, if set to "process", only users with "process" permission for custom fields will be able to edit this field. See the support documentation for information on setting permissions. |
exported | select | Either "yes" or "no", whether this profile field will be included when you export the against object. |
lookup_type | string | When field_type is "lookup", this will contain the lookup type, e.g. "company". |
options | array | When field_type is either "select" or "multi_select" this will contain the possible values. |
confidential | select | Either "yes" or "no", whether this is a confidential profile field. These are profile fields viewable only within confidential relationships, see the support documentation for more information. |
description | string | A description of the profile field. |
The Profile Value Object
Example profile value object:
{
"value_type": null,
"id": "128",
"field_type": "multi_select",
"value": "one, two",
"values": ["one", "two"],
"date_modified": "1495669367",
"field_name": "Implementation Phases",
"field_id": "12",
"modified_by": "14",
"link_type": "issues",
"link_id": "45"
}
These are objects describing a value of a given profile field, identified by the
field_id
, they contain the following:
Field | Type | Description |
---|---|---|
id | unsigned | A unique identifier for the profile field value. |
field_type | string | The profile field type for this value, see the profile field object for possible values. |
field_name | string | The name for the profile field. |
value_type | string | For fields of type lookup this is the type of the lookup object. For example "company", "contact". Otherwise it is null . |
value | dynamic | The value of the profile field. The type will change according to the field_type , for example if the field type is "date" this will be a unix ts. If it's a "multi_select" this will be all values joined by a comma. e.g, "one, two" for ["one", "two"] |
values* | array | When the field type is "multi_select", this will contain an array of the selected values. e.g, ["one", "two"] |
date_modified | unix ts | The date this profile field value was last modified. |
modified_by | unsigned or object | The staff member who last modified this profile field value. |
field_id | unsigned | The unique identifier of the profile field this value is for. |
link_type | string | The object the profile value was created against. |
link_id | unsigned | The unique identifier of the object the profile value is against. |
* The values
field is only returned when the field_type
is "multi_select".
When it's "multi_select", it's returned by default.
List Profile Fields
Sample Request:
GET /api/v0/{issues}/profiles/fields HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/profiles/fields \
-H 'authorization: Bearer {access_token}'
GET /{object}/profiles/fields
This request returns a list of profile fields available for the given object.
Configuring the Response
This request supports requesting additional fields and linked objects from the profile field object
using the _fields
parameter.
Handling the Response
This response will be a list of profile fields with their default fields, and any
additional fields requested through _fields
.
List Object Profile Values
Sample Request:
GET /api/v0/issues/{issue_id}/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/{issue_id}/profiles/values \
-H 'authorization: Bearer {access_token}'
GET /{object}/{object_id}/profiles/values
This request returns a list of profile values for the given object
of identified by object_id
.
Configuring the Response
This request supports requesting additional fields and linked objects from the profile value object
using the _fields
parameter.
Handling the Response
This response will be a list of profile values with their default fields, and any
additional fields requested through _fields
.
List Profile Values
Sample Request:
GET /api/v0/issues/profiles/values HTTP/1.1
HOST: {deployment}.api.accelo.com
Authorization: Bearer {access_token}
curl -X get \
https://{deployment}.api.accelo.com/api/v0/issues/profiles/values \
-H 'authorization: Bearer {access_token}'
GET /{object}/profiles/values
This request returns a list of profile values for the given object
.
Configuring the Response
Pagination
This request supports all of the pagination parameters
Additional Fields and Linked Objects
This request supports requesting additional fields and linked objects from the profile value object
using the _fields
parameter.
Basic Filter
This request supports basic filters over the following fields:
Filter Name |
---|
unified |
field_id |
link_id |
link_type |
Order Filters
This request supports order filters over the following fields:
Filter Name |
---|
field_id |
link_id |
link_type |
value_type |
date_modified |
Range Filters
This request supports range filters over the following fields:
Filter Name |
---|
field_id |
link_id |
Searching
This request supports the _search
parameter to search over the following fields:
Filter Name |
---|
title |
Update a Profile Value
Example, a business has changed its opening hours:
curl -X put \
https://{deployment}.api.accelo.com/api/v0/companies/{company_id}/profiles/values/128 \
-H 'authorization: Bearer {access_token}' \
-H 'content-type: application/x-www-form-urlencoded' \
-d 'value=09-18'
PUT /{object}/{object_id}/profiles/values/{profile_value_id}
This request updates and returns a profile value, specified by its profile_value_id
, of a
particular object, specified by its object_id
, of a particular type, specified by object
.
Configuring the Profile Value
This request updates the value
of a profile value, since this object is dynamic the field we send will depend on the
type of value
:
Field Name | Type | Description |
---|---|---|
value_int | int | If field_type is "integer", update the value with this integer. |
value_date | string | If field_type is "date", update the value with this string. This field supports values as both unix timestamps and in ISO8601 form, for ease of readability we recommend ISO8601. |
value_id | integer | If field_type is "lookup", update the value with this integer, representing an object id. |
value_type | string | If field_type is "lookup", update the value_type with this string. |
value | string | If field_type is none of the above, update the value with this string. |
Configuring the Response
This request supports requesting additional fields and linked objects from the profile value object
using the _fields
parameter.
Handling the Response
The response will be the single, updated profile value with its default fields, and any
additional fields requested through _fields
.
Create a Profile Value
Example, a company has give us their business h