Docs have moved to https://api.accelo.com/docs/ |
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! |
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.
An application can only have one type. If your application requires multiple types, please register multiple API applications through Accelo as appropriate. |
Before you dive in, it is important that you familiarise yourself with the fundamentals.
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.
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.
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.
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
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_offse
t - the resource to return from. Default: 0_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.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.
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:
/companies/12.json?_fields=website,phone
/companies/12.json?_fields=status(),contact(status(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 |
/companies?_fields=_ALL,contact(_ALL) |
Linked resources and optional fields can be found in detail on the endpoints resource page.
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 |
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 |
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.