Getting started with API v3

API v3 is the new Simplicate API, built following our API-first approach. Instead of reading and writing resources through generic CRUD endpoints, v3 exposes specific commands and queries, each with a clear, focused use case. Every endpoint is documented in the Reference section, generated from the OpenAPI specification.

info

API v3 offers a limited number of endpoints. For everything not yet available in v3, keep using API v2. Both versions can be used side by side, see API v2 vs. v3.

Endpoints

Endpoints are named after the action they perform. Most endpoints follow the form {entity}.{action} (employee.list) or {entity}.{scope}.{action} (project.acquisition.approve). Prepend your Simplicate URL and /api/v3 to get the full endpoint URL:

GET https://{yourdomain}.simplicate.app/api/v3/employee.list
POST https://{yourdomain}.simplicate.app/api/v3/project.acquisition.approve

• Queries (.get, .list, ...) read data and never change it. They mostly use GET.
• Commands (.create, .approve, .close, ...) perform one specific change. They mostly use POST.

Authentication

API v3 uses the same API tokens as API v2. Tokens are managed in the General settings under the API section in your Simplicate environment. Every API token inherits its rights from the user it was created for. To view more information about managing API tokens in Simplicate see our support article.

Send the key and secret as a bearer token in the Authorization header:

Authorization: Bearer {API-Key}:{API-Secret}

curl -H "Authorization: Bearer {API-Key}:{API-Secret}" https://{yourdomain}.simplicate.app/api/v3/employee.list

Request and response format

API v3 is a JSON-only API. Send request bodies with a Content-Type: application/json header.

Pagination

Collection queries return their results in pages. Use the following query parameters to page through a result set:

Parameter	Default	Description
page	1	The page number to return, starting at 1.
itemsPerPage	30	The number of items per page. The maximum is 30.

GET https://{yourdomain}.simplicate.app/api/v3/employee.list?page=2&itemsPerPage=30

Filtering

Filters are passed as query parameters, for example id=… for an exact match or id[]=…&id[]=… to match any of several values. Which filters are available is documented per endpoint.

Tracking changes

To keep track of what is created, updated or deleted in Simplicate, use webhooks instead of polling the API. Simplicate sends an HTTP POST request to your endpoint the moment a subscribed event occurs. Webhooks can be managed through API v3, for example with webhook.create.

• Webhooks documentation: how webhooks work, verifying signatures and all available events.
• Support article on webhooks: setting up webhooks in Simplicate.

Identifiers

Treat all identifiers as opaque strings and don't rely on a specific format. You may encounter UUIDs (123e4567-e89b-12d3-a456-426614174000) or entity hashes (project:1234abcd). Identifiers are the same in v2 and v3, so you can use them interchangeably between both versions.

Errors

Errors are returned as problem details with the application/problem+json content type:

{
  "type": "/errors/403",
  "title": "An error occurred",
  "status": 403,
  "detail": "Access Denied."
}

When a request is understood but rejected, Simplicate responds with 422 Unprocessable Entity. A failed input validation lists, per property, what to correct in violations:

{
  "type": "/validation_errors/c1051bb4-d103-4f74-8988-acbcafc7fdc3",
  "title": "An error occurred",
  "status": 422,
  "detail": "name: This value should not be blank.",
  "violations": [
    {
      "propertyPath": "name",
      "message": "This value should not be blank.",
      "code": "c1051bb4-d103-4f74-8988-acbcafc7fdc3"
    }
  ]
}

A request rejected by a business rule explains why in detail and has no violations:

{
  "type": "/errors/422",
  "title": "An error occurred",
  "status": 422,
  "detail": "Invalid project service: invoice in installments requires invoice method fixed_price, not time_and_expenses"
}