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

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

https://{yourdomain}.simplicate.nl/api/v2/crm/organization

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

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} 

Example

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

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 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 support@simplicate.nl.

Filtering

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:
q[name]=*Bob*
Use case: Search for all entries in 'name' that have the value of 'Alice' OR 'Charlie' 
q[name][]=Alice&q[name][]=Charlie
Use case: Search for all entries in 'name' that are of value 'Alice' AND values in 'email' that end with 'gmail.com' 
q[name]=Alice&q[email]=*gmail.com
Use case: Search for all entries in 'name' that have 'Alice' OR values in 'email' that end with 'gmail.com' 
q[name]=Alice&q[or][email]=*gmail.com&limit=10&sort=name

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': 
/api/v2/projects/project?q[organization.name]=Google
Use case: Find projects related to your own organization by the name of 'My Company': 
/api/v2/projects/project?q[my_organization_profile.organization.name]=My%20Company

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 July 28th, 2020, max 10 records, order by 'updated_at' date in descending order: 
q[updated_at][ge]=2020-07-28&limit=10&sort=-updated_at
Use case: Search for all entries where they were created between July 21st, 2020, and July 28th, 2020, max 10 records, order by 'created_at' in descending order: 
q[created_at][ge]=2020-07-21&q[created_at][le]=2020-07-28&limit=10&sort=-created_at
Use case: Find all services for projects that have invoice method 'Hours' or 'FixedFee', order by budget descending: 
/projects/services?q[invoice_method][in]=FixedFee,Subscription&sort=-budget

Custom fields

Custom fields are a special something 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. Please see questions on how to contact us to let your wish be known to us to support these.

Entity URL Filtering supported?
Projects /projects/project Yes
Organizations /crm/organization Yes
Person /crm/person No
Sales /sales/sale No
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 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"

q[custom_fields.external_link]=*docs.google.com*

 

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.

q[custom_fields.part_of_country][nin]=*
Use case: Find all projects that have no 'part_of_country' set yet, created after August 9th, 2020, show only the id, name, and project_manager fields, order by updated_at descending. 
q[custom_fields.part_of_country][nin]=*&q[created_at][ge]=2020-08-09&select=id,name,project_manager.employee_id,project_manager.name&sort=-updated_at

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: 
q[name]=*Bob*&offset=11&limit=10&sort=-name

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 'gmail.com', max 10 records, order by name ascending: 
q[name]=Alice&q[or][email]=*gmail.com&limit=10&sort=name
Use case: Search for all entries in 'name' that have 'Alice' OR entries in 'email' that have 'gmail.com', max 10 records, order by name *descending*: 
q[name]=Alice&q[or][email]=*gmail.com&limit=10&sort=-name

Metadata

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 
q[name]=*my*&limit=10&metadata=count,limit

Questions and support

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

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):

/invoices/document?q[linked_to.invoice_id]=invoice:abcdef

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:

/documents/download/document:abcdef

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.