All pages

Connect a partner's own system

Give a business you work with an API key, so its own system adds and reads the same records as its portal login without anybody typing them in twice, and is told when one changes.

A key is made for one partner login and does exactly what that login does in its app: it adds rows to the tables the app adds to, and reads the rows linked to that partner's contact. It never reads another contact's rows, your other tables, or your people, and it cannot change or delete a row.

On this page

Make a key

Open the partner's contact and click Portal access. Under the login the key is for, in API keys, click New API key, name it after the system it is for and click Make key.

Click Copy and send the key to them in a way only they can read. It is shown once. The list afterwards shows only its name, its last four characters and when it was last used.

To stop a key, click Remove beside it. It stops on its next request. Removing the login stops every key made for it.

Send the key with every request

Every request carries the key as a header: Authorization: Bearer dpk_.... The addresses all start with https://diract.io/api/partner/v1.

A missing, wrong or removed key answers 401. Over 120 requests a minute for one key answers 429: wait a moment and send it again.

See which tables and fields it can use

GET /api/partner/v1/tables lists each table with can_read, can_create and its fields. Each field has a key, which is what you send and what rows come back with, its type, whether it is required, and the options of a choice field.

Fields marked filled_automatically are left out of a new row. One of them is the field linking a row to the partner, which is always set to their own contact.

For example: curl https://diract.io/api/partner/v1/tables -H "Authorization: Bearer dpk_...".

Add a row

POST /api/partner/v1/tables/{table}/rows with a JSON body of {"values": {"<field key>": value}}. {table} is the id or slug from the list of tables.

For example: curl -X POST https://diract.io/api/partner/v1/tables/orders/rows -H "Authorization: Bearer dpk_..." -H "Content-Type: application/json" -d '{"values": {"reference": "000123", "notes": "Back door"}}'.

It answers 201 with the new row, and its number when the table numbers its rows. The row appears in the partner's portal and on your own board straight away.

A field the table does not have, a value that is not one of a choice field's options, or a required field left out is refused with 400 and a sentence naming the field. Nothing is saved.

Read their rows and their status

GET /api/partner/v1/tables/{table}/rows lists the rows linked to the partner, newest first, 50 at a time. Each row has id, created_at, updated_at and values, keyed by field key. A link to another record reads as that record's id.

Narrow the list by any field key, such as ?status=Done. Add updated_since=2026-11-15T09:00:00Z to fetch only rows changed since you last looked, which is how to follow a status as it moves.

When there are more rows, the answer has a next_cursor. Send it back as ?cursor= for the next page. limit takes 1 to 100.

GET /api/partner/v1/tables/{table}/rows/{id} reads one row. A row not linked to the partner answers 404, the same as one that does not exist.

Tell their system when a row changes

In Portal access, under the key, click Tell their system about changes (webhook), type the https address their system receives changes at and click Save. Copy the signing secret shown under it and send it to them with the key. It is shown once.

Within a minute of a row linked to them being added or changed, we send a POST to that address with a JSON body: {"id", "type": "rows.changed", "sent_at", "events": [...]}. Each event has type (row.created or row.updated), the table and the row, the same shape the list returns. One delivery carries up to 100 events, oldest change first.

Every delivery carries a Diract-Signature header, t=<seconds>,v1=<signature>. Their system works out the HMAC SHA-256 of the seconds, a full stop and the exact body, with the signing secret as the key, and checks it matches v1 and that the seconds are within five minutes of now. With the secret whsec_test, the seconds 1 and the body {}, the signature starts 7500d5d4.

Their system answers with any 2xx status to accept it. Anything else, or no answer within 10 seconds, is sent again after 1 minute, then 2, 4 and so on up to every 6 hours, with the rows as they are by then. Use Diract-Delivery, the delivery's id, to ignore one already handled.

Click Send a test to send an empty ping delivery and see what their system answered.