# Quickstart

Four steps to your first call of the Workist API.

## 1. Create an API key {#api-schluessel}

API keys are managed by users with the IT or Admin role (see [Users and roles](/en/docs/administration/users-and-roles.md)).

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 {#erster-aufruf}

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

```bash
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](https://api.workist.com/v1/swagger/): click **Authorize**, enter your key and run `GET /orders`.

:::warning No trailing slash
Paths end without `/`. `GET /orders` works, `GET /orders/` returns `404`.
:::

## 3. Switch the channel to API {#kanal}

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 {#ablauf}

1. Documents reach the channel by email, through the Workbench or via `POST /orders` (see [Upload a document](/en/docs/api-documentation/document-api.md#hochladen)).
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](/en/docs/api-documentation/document-api.md#seiten)).
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`:
     ```json
     {"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`](/en/docs/api-documentation/document-api.md#failed)).

The same steps apply to invoices, order confirmations, requests for quotation, delivery notes and lists of services, each with its own [resource](/en/docs/api-documentation/document-api.md#ressourcen). Instead of polling, you can have a [webhook](/en/docs/data-exchange/webhooks.md) notify you.

## Errors {#fehler}

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](/en/docs/api-documentation/document-api.md#fehler).

## Master Data API {#stammdaten-api}

For transferring master data via API, see [Using the Master Data API](/en/docs/api-documentation/master-data-api.md).