The Simplicate REST API

This is the documentation for the Simplicate v2 API. Read the contents of this page carefully. We make changes to the APIs from time to time. For more information, see API Changes. Endpoints are documented with the HTTP method for the request and a partial resource identifier.
Example:
GET /api/v2/crm/organization.json
Prepend your Simplicate URL to the resource identifier to get the full endpoint URL:
https://{yourdomain}.simplicate.nl/api/v2/crm/organization.json
The examples in the docs are cURL statements. You can run the statements on a command line to try out different API requests. To learn more, see Installing and using cURL. In Windows, you'll need to modify some of the examples in the docs to make them work. When documenting a resource, we use curly braces, {}, for identifiers.
Example: https://{yourdomain}.simplicate.nl/api/v2/crm/organization.json

Security and Authentication

This is an SSL-only API, regardless of how your account is configured.

You can authorize against the API using a tokenized approached based on API Key and Secret. You can create multiple API tokens for various purposes. API tokens are managed in the General settings under the API section in your Simplicate environment. The page lets you view, add, or delete tokens. More than one token can be active at the same time. Every API token has it's own expiration date and time and it's own separate rights (Create, Read, Update and Delete). Deleting a token deactivates it permanently.

Add the following authentication variables with every request header:
Authentication-Key: {API Key}
Authentication-Secret: {API Secret}
Example

curl -H “Authentication-Key: {API Key}” -H “Authentication-Secret:{API secret}” https://{subdomain}.simplicate.nl/api/v2/crm/organization.json

Rate Limiting

This API is rate limited. We only allow a certain number of requests per minute. We reserve the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients. As an API consumer, you should expect to be able to make at least 120 requests per minute. If the rate limit is exceeded, Simplicate responds with a HTTP 429 Too Many Requests

Request Format

The Simplicate API is a JSON-only API. You must supply a Content-Type: application/json in all requests. You may get a text/plain response in case of an error like a bad request. You should treat this as an error you need to resolve.

Response Format

Simplicate responds to successful requests with HTTP status codes in the 200 range. When you create a resource, depending on the resource Simplicate renders the resulting created resource ID in the response body.

Simplicate responds to unsuccessful requests with HTTP status codes in the 400 range. The content type of the response may be text/plain for API-level error messages, such as when trying to call the API without SSL. The content type is application/json for business-level error messages because the response includes a JSON object with information about the error:
{
data: null
-errors: [1]
    0:  "No country code provided at the visiting address"
debug: null
}
 
If you experience responses with status codes in the 500 range, Simplicate may be experiencing internal issues or undergoing scheduled maintenance, during which we send a 503 Service Unavailable status code. When building an API client, we recommend treating any 500 status codes as a warning or temporary state. However, if the status persists and we don't have a publicly announced maintenance or service disruption, contact us at support@simplicate.nl.

Filtering

With your request you can add several filter parameters in the request URL.
fields parameter - A comma-separated list of fields to filter on
q parameter - The filter to apply to fields. If this is an Associative Array, the key will be used as fields to search on.
If this is a normal Array, an OR-search will be done on the given fields.
Wildcards are allowed by means of '*' : q[name]=Don*.
NULL values may be searched with 'NULL' : q[name]=NULL
Non NULL values may be searched with '*' : q[name]=*

Use case: Search for all entries in 'name' that have '%Jos%' from offset 11 with max 10 records, order by 'name' descending:
fields=name&q=*Jos*&offset=11&limit=10&sort=-name
OR
q[name]=*Jos*&offset=11&limit=10&sort=-name
Use case: Search for all entries in 'name' that have 'Remmelt' OR 'Niels', max 10 records, order by name:
q[name][]=Remmelt&q[name][]=Niels&limit=10&sort=name
Use case: Search for all entries in 'name' that have 'Remmelt' AND entries in 'email' that have 'gmail.com', max 10 records, order by name:
q[name]=Remmelt&q[email]=*gmail.com&limit=10&sort=name
Use case: Search for all entries in 'name' that have 'Remmelt' OR entries in 'email' that have 'gmail.com', max 10 records, order by name:
q[name]=Remmelt&q[or][email]=*gmail.com&limit=10&sort=name

Return limit and pagination

By default, most GET requests return a maximum of 100 records. You can change the number of records on a per-request basis by passing a limit parameter in the request URL parameters. Example: limit=50. However, you can't exceed 100 records per page on most requests. When the results exceed the limit, you can iterate through the records by incrementing the offset parameter.

Use case: Search for all entries in 'name' that have '%Jos%' from offset 11 with max 10 records, order by 'name' descending:
fields=name&q=*Jos*&offset=11&limit=10&sort=-name

Sorting your results

You can pass a sort paratmater in the request URL. This parameter should consinst with a list of fields where to sort on. Standard ascending, by adding a prefixed minus (-) the sort is descending.

Use case: Search for all entries in 'name' that have 'Remmelt' OR entries in 'email' that have 'gmail.com', max 10 records, order by name:
q[name]=Remmelt&q[or][email]=*gmail.com&limit=10&sort=name

Questions and support

If you have any questions regarding the use op the API, please contact us at support@simplicate.nl