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 January 7th, 2021, max 10 records,
order by 'updated_at
' date in descending order:
q[updated_at][ge]=2021-01-07&limit=10&sort=-updated_at
Use case: Search for all entries where they were created between December 31st, 2020, and January 7th, 2021, max 10 records, order by 'created_at
' in descending order:
q[created_at][ge]=2020-12-31&q[created_at][le]=2021-01-07&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 January 19th, 2021, 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]=2021-01-19&select=id,name,project_manager.employee_id,project_manager.name&sort=-updated_at
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
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.