Documentation has moved homes

Docs have moved to https://api.accelo.com/docs/

Introduction to the Accelo API

Below is Accelo's getting started guide. It will get you deep into the API with a few simple introductory steps and details. If you have an questions or feel any sections are left short, please let us know.

Please use the API responsibly and report any bugs or inaccuracies to support, and follow our blog for important news and announcements. Questions can be asked on our forum. Enjoy!

Contents

What you need to start

To gain access, you must first obtain a client_id and client_secret by registering an application with Accelo. We currently offer three types of applications. You must select an application type upon first registering.

Installed Application - Android, iOS, and desktop applications. These use a one-time pin or QRCode to authorise a grant request.
Web Application - Web application assumed to be able to keep a secret (PHP, Ruby, Perl, etc). These use a redirection with a token to authorise a grant request.
Service Application - These are not run from an end-user and thus do not require a grant. The client's secret is used to obtain an access_token.

An application can only have one type. If your application requires multiple types, please register multiple API applications through Accelo as appropriate.

Getting familiar with the basics

Before you dive in, it is important that you familiarise yourself with the fundamentals.

Deployment Hostname

Each Accelo deployment has a unique hostname. It will be used in the URI of each API request. For installed and web applications this is the end-user's deployment, not the applications deployment. In the documentation, we will refer to the deployment host as {deployment}. So please substitute the deployment's host appropriately in examples.

Base URI Structure

The base URI is an important one and is used in every single resource request. It is simply the URI for the end-users deployment with some extra sugar.

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

For example,

https://bobs-burgers.api.accelo.com/api/v0

For information regarding the formation of an OAuth URI, please see OAuth 2.0 Authentication.

Response Structure

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

Table of response structure.

meta

The meta object contains:

In production it is sometimes necessary or mandatory to suppress certain response objects. The following arguments can be used to suppress meta responses:

response

The requested response data.

Sample response suppressing nothing

{
 	"meta" : {
 		"version" : 0.1.1, 
 		"status" : "ok",
 		"message" : "Everything executed as expected."
 	}, 
 	"response" : { ... }
}

Sample response using _suppress_message=yes and _suppress_http_status=yes

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

Handling both HTTP and Accelo API statuses is important. We suggest reading about the statuses and what they mean at Accelo Status Codes

Pagination of lists

Accelo has the capacity to hold tens of thousands of resources. When requesting lists of resources, it is important to keep this in mind. You can paginate through resource lists using the _page paramater.

_page - The page of results to retrieve. For example, 1, 2, 3, N. Each page contains 10 resources.

Alternatively you can paginate through the list using the _limit and _offset paramaters.

_limit - The max number of resources to return. This is not the number of resources returned. Default: 10, Max: 50
_offset - the resource to return from. Default: 0

Tip: You can use the _limit paramater in conjunction with _page to alter the number of items returned per page. Be sure that you include the limit in all subsequent page requests, otherwise, you will receive inaccurate page data.

Filtering and Searching lists

Most Accelo API resource endpoints support a _filters and _search paramater that allows you to filter through lists of that resource. The supported filters will vary between resources. Please see the Resource Endpoint for supported filters.

Companies, support the created and modified range filters as well as the manager filter. For example:

GET /api/v0/companies HTTP/1.1
Host: hq.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
 
_filters=created_before({unix_timestamp}),modified_after({unix_timestamp}),manager_id(10,20)

Would return the companies within the unix timestamp ranges and with manager whose id is either 10 or 20.

Contacts allow you to use the basic _search parameter to lookup contacts.

GET /api/v0/contacts HTTP/1.1
Host: hq.api.accelo.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer {access_token}
 
_search=kurt+wagner

Will find any contacts where kurt and wagner is found in the first name, surname, mobile or email.

Requesting optional fields and linked resources

By default each resource returns the minimal required fields. These fields are underlined in the response table of that endpoints informational page. You can request the additional optional fields and even linked resources using the _fields paramater.

The field argument has two uses:

Optional Fields: include optional fields from a given resource.
1. For Example: /companies/12.json?_fields=website,phone
2. Would return the company's default fields including the company's website and phone number.
Linked Resources: resources linked to other resources
1. For example: /companies/12.json?_fields=status(),contact(status(color))
2. would return the companies default fields, including linked resources status and contact. It will also return the linked contacts status with optional extra field color.

If you would like all optional fields, please use the "_ALL" keyword. It will return all public fields for the given object. For example, if you would like to get all fields of a company, you would use,

/companies?_fields=_ALL

If you would also like to get all fields linked to a contact that is linked to a company, you would use

/companies?_fields=_ALL,contact(_ALL)

Linked resources and optional fields can be found in detail on the endpoints resource page.

Overriding 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. For example, the following requests are all identical. Each returns the response as XML.

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

JSON Content Types

We also accept JSON requests. This can greatly simplify the client side implementation as it offers filters and fields that translate well to programatic structures. For example, if you would like to get all contacts with either email "pepper@test.com" or "salt@test.com" and return their mobile and linked statuses color, id and title, you would use

curl https://<deployment>.api.accelo.com/api/v0/contacts -H "Content-Type: application/json" -d'{
    "_bearer_token": "_iaePUx3W4AUsZ7p.u4aUSrfgWF6esiy",
    "_filters": { "email": ["pepper@test.com", "salt@test.com"] },
    "_fields": ["status.title", "status.id", "status.color", "mobile"],
    "_method": "get"
}'

which is similar to saying

/contacts?_filters=email(pepper@test.com,salt@test.com),_fields=status(title,id,color),mobile

What's Next?

Now that you have dabbled in the basics of the API, it is time that you checkout OAuth 2.0 Authentication. This will introduce you to grants, bearer tokens and application specific application authorization flows.