Quickstart

Four steps to your first call of the Workist API.

1. Create an API key

API keys are managed by users with the IT or Admin role (see Users and roles).

1. In the Workbench, click Settings in the left navigation bar and choose Integrations. The API Integrations page opens.
2. In the Quick Create API Integration card, enter an Integration name, e.g. the name of the system that uses the API, and click Create Integration.
3. The new integration appears in the table. Copy the key from the API Key column and store it securely. It is only shown once.
4. Optional: click Edit integration to restrict the key to individual channels per document type (instead of Grant access to all channels) or to set an Expiration Date. From that day on, the API rejects the key.

Add Integration creates an integration with channels and expiration date right away. The table then doesn't show the key. In that case, click Renew API key to generate and display a key.

Good to know:

• A key belongs to your organisation, not to a person. It keeps working when the user who created it leaves the company.
• Renew API key (icon in the table) generates a new key. The old one stops working immediately.
• An expired key works again as soon as you move or remove the expiration date via Edit integration.

2. Send your first request

Send the key in the Authorization header with the prefix Bearer:

curl -H "Authorization: Bearer <your API key>" \
  "https://api.workist.com/v1/orders?finished=true&imported=false"

Alternatively, test the API in the Swagger UI: click Authorize, enter your key and run GET /orders.

No trailing slash

Paths end without /. GET /orders works, GET /orders/ returns 404.

3. Switch the channel to API

If your system pulls the results through the API, set the delivery method to API in the channel under Manage channel → Upload. Otherwise Workist also transfers the results via SFTP, and successfully transferred documents no longer appear under imported=false.

4. Set up the flow

1. Documents reach the channel by email, through the Workbench or via POST /orders (see Upload a document).
2. Workist processes the documents. Documents that Workist cannot finish automatically are assisted by your staff in the Workbench.
3. Your system requests all finished orders that have not been handed over yet:

   GET /orders?finished=true&imported=false

   The response contains at most 10 documents. Follow the link in next until it is null (see Pages).
4. For each order:
   • a) Import into your system, e.g. as a sales order in the ERP.
   • b) Report the result with PUT /orders/{id}/mark_imported:

     {"status": "SUCCEEDED", "external_reference": "SO-2026-0815"}

     If your system rejects the order, report "status": "FAILED" with the cause in external_message. The order then goes back to the Workbench (see What happens after FAILED).

The same steps apply to invoices, order confirmations, requests for quotation, delivery notes and lists of services, each with its own resource. Instead of polling, you can have a webhook notify you.

Errors

On errors the API answers with JSON, e.g. {"detail": "Invalid token"}. The most common causes:

• 401: key missing, wrong or expired (Integration has expired).
• 404: path with a trailing /, or the document belongs to a channel the key cannot see.
• 400 on mark_imported: the document is not finished yet (Record not finished yet) or was already reported with SUCCEEDED.

All errors are described in the Document API.

Master Data API

For transferring master data via API, see Using the Master Data API.