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.


GET /api/v2/crm/organization

Prepend your Simplicate URL to the resource identifier to get the full endpoint URL:


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}

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 its own expiration date and time and its 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}


curl -H "Authentication-Key: {API Key}" -H "Authentication-Secret:{API secret}" https://{subdomain}

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 60 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 header 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": [
    "No country code given in the visiting_address property"
  "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


Filtering is allowed on almost all endpoints through the use of the q parameter, expressed as an array.

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 contain 'Bob' somewhere in its value:
Use case: Search for all entries in 'name' that have the value of 'Alice' OR 'Charlie'
Use case: Search for all entries in 'name' that are of value 'Alice' AND values in 'email' that end with ''
Use case: Search for all entries in 'name' that have 'Alice' OR values in 'email' that end with ''

Filtering on nested values

Nested values, sometimes even several layers deep, can be filtered on as well. A simplified example response of /api/v2/projects/project is as follows:
  "data": [
      "id": "project:abc",
      "name": "My First Project",
      "organization": {
        "id": "organization:xyz",
        "name": "Google"
      "my_organization_profile": {
        "id": "myorganizationprofile:123",
        "organization": {
          "id": "organization:456",
          "name": "My Company"
Use case: Find projects related to an organization by the name of 'Google':
Use case: Find projects related to your own organization by the name of 'My Company':

Advanced filtering

Advanced filtering is available with these options:

Additional operators

There are additional operators to be used:
operator in URL Math operator Explanation
ge >= greater than or equals
gt > greater than
le <= less than or equals
lt < less than
in IN column with a value that matches one of the values in a comma separated list of values
nin NOT IN same as above, but negating
Use case: Search for all entries where they were last modified since November 20th, 2021, max 10 records, order by 'updated_at' date in descending order:
Use case: Search for all entries where they were created between November 13th, 2021, and November 20th, 2021, max 10 records, order by 'created_at' in descending order:
Use case: Find all services for projects that have invoice method 'Hours' or 'FixedFee', order by budget descending:

Custom fields

Custom fields is a module independent entity within Simplicate. Please see this support article for more information (in Dutch).

There are 5 entities that support custom fields. All of them are available through the API, though not all of them can be filtered on yet.

Entity URL Filtering supported?
Projects /projects/project Yes
Organizations /crm/organization Yes
Person /crm/person Yes
Sales /sales/sale Yes
Employee /hrm/employee No

Each custom field has a property called 'name'. This name must be used to filter on. See the results of each respective listing call to find out what the custom field names are.

Use case: Find all projects that have a link to Google Docs in the custom field 'external_link':

This use case assumes there is a custom field named "External link" for "Projects"



The following 2 use cases assume there is a custom field named 'Part of country' for 'Projects', with 5 possible values: (North, East, South, West, Centre).

Use case: Find all projects that have no 'part_of_country' set yet

This use case combines custom field filtering with the advanced operators found here.

Use case: Find all projects that have no 'part_of_country' set yet, created after December 2nd, 2021, show only the id, name, and project_manager fields, order by updated_at descending.

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 almost all 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 '%Bob%' from offset 11 with max 10 records, order by 'name' descending:

Sorting your results

You can pass a sort parameter in the request URL. This parameter should contain a list of fields where to sort on. By default, the sort order is ascending. This can be reversed by prefixing the column with a minus (-).

Use case: Search for all entries in 'name' that have 'Alice' OR entries in 'email' that have '', max 10 records, order by name ascending:
Use case: Search for all entries in 'name' that have 'Alice' OR entries in 'email' that have '', max 10 records, order by name *descending*:


It is possible to receive metadata with your request. Below are the accepted values, separated by a comma.

Metadata Purpose
count Shows the count of the entire collection, ignoring the limit & offset parameters, but taking into account all query parameters. Useful for pagination
limit Returns the limit that's also set in the request parameters
offset Returns the offset that's also set in the request parameters
Use case: Find all entries with name like *my*, limit by 10, but show the count & limit in the metadata property

Questions and support

If you have any questions regarding the use of the API, please contact us at

Use cases

Obtaining the PDF of an invoice

After obtaining an invoice ID from /invoices/invoice, use /invoices/document to find the relevant document(s):


You'll find a list of documents pertaining to the invoice. Locate the document you wish to download. In the result set you'll find a download_url property. Please note that this URL requires a valid web session on the Simplicate application. To programmatically download the documents, please continue.

From the result of /invoices/document, use the id (as document:abcdef), to proceed to:


This is the location of the actual document. If the document is a PDF, the API will respond with a Content-Type: application/pdf header. In all other cases, the API will respond with Content-Type: application/octet-stream header.

Please note: the /invoices/document and /documents/download API's are protected by all the relevant rights in the Simplicate application. When trying to download documents, please make sure you're using the API keys of a user who has access to these documents.

Uploading, linking, and using files
Uploading files

When uploading documents to Simplicate, you'll follow this flow:

  • Let the API know your intentions; what's the file name, of what file size
  • Upload the file (repeatedly if need be), in chunks of max 500 kB.
  • The API will let you know you've uploaded all you needed, and that the file is complete
  • You'll be able to create a document, and link to this file, or use it as an attachment in timeline messages

Start by letting the API know you're about to submit a file. For this example, we'll upload this image: Logo of Simplicate. Send the following body to /upload/chunked.

POST /api/v2/upload/chunked

    "file_name": "simplicate-logo.png",
    "file_size": 1044

Note that file size is in bytes. The result will be like:

200 OK

    "data": {
        "chunked_upload_id": "chunkedupload:a00a5662be4cf8b54da2058e5c846d06"

We're going to use this ID to start uploading the actual contents of the file. Please note that the file contents must be base64 encoded, and each chunk must not exceed 500 kB (base64 encoded).

PUT /api/v2/upload/chunked/chunkedupload:a00a5662be4cf8b54da2058e5c846d06

    "chunk": "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAOpSURBVEhLnZVrTBRXFMf/81hY0F0eImVRitgPKAXcRmuC1JDSL8aqLVaNa6KxfmjSqDVWjbTpVykJabRVY+MHkdoYH4H4amrrq4lQFVmlkKZolKQWQVC6i0QW2WVuz525bBl2drT9JWfuOefee87OuWfuSrCjriUXkrQWjC0iK5sWp+061TiJ9IckrSQtiqzW7qzf1E26JdYJ6lpy6LmDZC1JKneNUXWqUWgm9suSXFPZ8Mmfwo4ii/Ff6vwf0LONZDOJKbgNGzWm3auq2FMh7CimBEUnvtkCsKOkvmzg8agkDZTkQ8M0iCbwnfFtKHReqylwNicI1//l0JfLv35f6EYC31lfLg1fkTjmJF0FJeFuE6kJCma5E+Ge6hKe+DDGamtW7J/BdYU/itYU7aahhOucLMcDaPTGjyPTkOJQUD13Og6XzsD217Mwf+kbmPeuF0yjVrrTI3bE4KQzSb3Ucf60RKXhmXjLpehT4/gttBAr899DZWEWqtsf4cxfQXz+eyemvpqOsjULUF99Dneb74vVsUiQ8iQqz2dgqBK+GGrKv8XNfg0VvxiBxto0JdONgb6num7DVpmCzxeGJbz2birTRF4iOKeMH7LX0K3xP/Kj3OPC7jdz4JTtP3wLSpViX9Eu2pbAt1pJ++M2ZCRNwarXCvBFsQfO5ET0d/Xj+dAIzdojUStIwStzQqQ7DVd8FFchHOmrkZi3RLcDDcfRe4A3ny0hpXK9h18Jkw07PuHuvzHU2oSBqz9ATcmEu2wp5ORkPPPfECss6ZIlSW9RWyJPVER6HboefvIAfd/vQCTQDVfZO7ovHlTiNlljaBK2JdrQK9Hg4xnp7qDJsLDicpv6gu0VRgyOjGVIW/wTJpd8LDwGSfmlcM6ch2ftVC4PfdLWDNAb1PFGAR10LQ3ruT6GURYVroWfIrl4le4bHewBizCoadkY7vSj78g2aMODiDxUEOkx3/wU+MisizfW6QkCl72psswCjOlzpppz5EkZSMwtoTET4cAwQh2NGOm9x281sYL2mJMEmarOLTjf1Kkn4ASueMupXJcmBp9IqCt+/4skYfqbXTf7wvVj3BdNmfZ262UtoG62C/4i1Gmjz+V0adNYcI6pcOnL/fuYJC+OvtZ/I0jyUf6J6wcN08B8MoRn468/jioJ0ynJYeF6EUH6ln6GpHjzqm99J3xRbH9s74G3sqFFeAstols3n440h85gkGz6tdJdOrMmTVZPzqxq/kPfEAPwD+WsL9kvRlL9AAAAAElFTkSuQmCC"

As this file is way smaller than 500 kB, the API will set the state to 'done', and no new chunks will be accepted:

200 OK

    "data": {
        "pointer": 1,
        "state": "done",
        "upload_queue_id": "uploadqueue:7de64ec93190dd457a9bfc4dc6429b75",
        "file_size_current": 1044,
        "file_size_expected": 1044,
        "download_url": "/download?name=simplicate-logo.png"
    "errors": null,
    "debug": null

If you're uploading a larger file, the API will respond like below, and you'll need to send the remaining chunks, until the file is completely uploaded:

200 OK

    "data": {
        "pointer": 1,
        "state": "in_progress",
        "file_size_current": 384000,
        "file_size_expected": 3781286
    "errors": null,
    "debug": null
Converting to document

With the upload_queue_id in hand, we can convert this file to a document, with a title, a document type id, and link it to an existing entity (Person, Organization, Sales, Project, Invoice)

POST /api/v2/documents/document

    "upload_queue_id": "uploadqueue:7de64ec93190dd457a9bfc4dc6429b75",
    "title": "simplicate-logo.png",
    "document_type_id": "documenttype:b423eae1f54f879041c55b3092b4a1f8",
    "linked_to": {
        "person_id": "person:b1c692b0993bb602eb694ed52cdf49ac"


200 OK

    "data": {
        "id": "document:91b5a2aee0d60fae298fdc63dd8ada0b"

This file can now be found in its linked entity, on the tab 'Documents'.

As a timeline message attachment

Additionally, if you wish to link this document to a timeline message, then please see POST /timeline/attachment, and send the following request:

POST /api/v2/timeline/attachment

    "message_id": "message:914edc4509a28e23ccd1f796716510b1",
    "document_id": "document:91b5a2aee0d60fae298fdc63dd8ada0b"

That's it for uploading files, and using them as documents!

PHP example for uploading chunks

A PHP example for uploading a file, in chunks:

function uploadFileToApi(string $fileName, string $filePath): string
    $uploadId = $this->callSimplicate('POST', '/upload/chunked', [
        'file_name' => $fileName,
        'file_size' => filesize($filePath),
    $chunkSize = 500 * 1000; // 500 kB, times a thousand, for bytes, to err on the side of caution

    $base64String = base64_encode(file_get_contents($filePath));
    $offset = 0;

    while (true) {
        $chunk = substr($base64String, $offset, $chunkSize);
        $offset += $chunkSize;

        $apiResponse = $this->callSimplicate('PUT', '/upload/chunked/' . $uploadId, [
            'chunk' => $chunk,

        if (!isset($apiResponse['data']) || !isset($apiResponse['data']['state'])) {
            throw new Exception('Expected a succesful API resonse, with data and data.state');

        if ($apiResponse['data']['state'] === 'done') {
            return $apiResponse['data']['upload_queue_id'];

$uploadQueueId = uploadFileToApi('simplicate-logo.png', '/path/to/simplicate-logo-24x24px.png');