The CentralPlanner API is organized around REST.
The communication takes place encrypted via the HTTPS protocol, where the desired operation is determined via the HTTP verb. The data is then transferred as JSON.
You can read resources with GET, create new ones with POST, edit them with PUT and delete them with DELETE. If you want to read up on REST first, we recommend the short overview at Wikipedia.
In our occasional developer newsletter we inform you about major changes or enhancements to our API. Please sign up to the developer newsletter, if you are building something on top of our API.
For working with the API you may want to get yourself a free account.
You’ll find all available endpoints available in our Swagger UI documentation.
Contact us in case of any questions
Feel free to reach out when questions arise around our API. Just drop us an email at dev-support [ at ] 42he.com and we'll get back to you.
Basics for using the API
Each object in CentralPlanner can be uniquely identified by its URI. It is persistent and does not change until the element is deleted. Please note that the IDs are not sequential. For example, one object can have ID 5, the next one ID 324. To get a list of all contacts in a CentralPlanner account, you can send a GET request as follows. You retrieve a JSON response.
curl -X GET https://centralplanner.net/api/contacts.json
Furthermore, there are nested routes for belonging objects (1-n relations). For example, to get all addresses of the person with ID 42, the following call is necessary:
curl -X GET https://centralplanner.net/api/contacts/42/tags.json
Authentication
The CentralPlanner API uses API keys to authenticate requests. You can view and manage your API keys in the account settings. All API requests must be made over HTTPS. API requests without authentication will fail. Every CentralPlanner admin user can create an API key in the account settings at 'External applications'. The API key must then be passed via the header “x-api-key” for each call. Passing the apikey as URL-parameter is deprecated (apikey=xyz).
Errors
Our API uses conventional HTTP response codes to indicate the success or failure of an API request.
The most common error codes are:
- 401: unauthorised
- 400: bad_request
- 404: not found
- 422: Unprocessable Entity
- 507: insufficient_storage
Rate limits
The use of the API is limited to 50 requests within 10 seconds. For requests that exceed this limit, the HTTP response code 429 (Too Many Requests) is returned. Additionally, the Retry-After header is then set. Details about Retry-After at MDN.
Pagination
Every index function is paginated, which restricts the API to return a subset instead of all records at once. The parameters perpage and page can be used to specify the number of elements per page and the number of pages accordingly. The maximum number per page is 250 entries.
For example the first 50 contacts can be retrieved using:
curl GET https://centralplanner.net/api/contacts.json?perpage=50&page=1
The number of all entries can be used separately with the COUNT function:
curl GET https://centralplanner.net/api/contacts/count.json
Inclusion of nested objects
With most endpoints, many child objects can be queried directly as well. This works via the includes parameter. The possible includes are each described in the Swagger UI, an example for all contacts in the account with their tags looks like this:
curl GET https://centralplanner.net/api/contacts.json?includes=tags
Methods for more comfort
In addition to the includes, individual information of the nested objects can be requested via methods. For the contact it may be helpful to receive salutations based on the contacts gender, which can be done using the methods parameter. The methods available per endpoint are documented in the Swagger UI.
curl GET https://centralplanner.net/api/contacts.json?methods=salutation_formal