The CentralStationCRM 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 CentralStationCRM 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 people in a CentralStationCRM account, you can send a GET request as follows. You retrieve a JSON response.
curl -X GET https://accountname.centralstationcrm.net/api/people.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://accountname.centralstationcrm.net/api/people/42/addrs.json
Authentication
The CentralStationCRM 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 CentralStationCRM user can create an API key in "My settings". The API key must then be passed via the header “X-apikey” 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 people can be retrieved using:
curl GET https://accountname.centralstationcrm.net/api/people.json?perpage=50&page=1
The number of all entries can be used separately with the COUNT function:
curl GET https://accountname.centralstationcrm.net/api/people/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 people in the account with their companies and tags might look like this:
curl GET https://example.centralstationcrm.net/api/people.json?includes=companies tags
Methods for more comfort
In addition to the includes, individual information of the nested objects can be requested via methods. For many objects (e.g. people, companies, tasks) there is a user_id field for instance, which refers to the responsible or acting user. In order to not always have to load the names of the users separately, it can be included via the method responsible_user_natural_name. The methods available per endpoint are documented in the Swagger UI.
curl GET https://example.centralstationcrm.net/api/people.json?methods=backlink salutation_formal