Connecting a workflow tool to a register

A workflow tool such as Zapier, Make or n8n can write rows into a register without anyone opening Alchex. It does this with an API key that belongs to your workspace, not to a person. This page is for the person setting that up.

Create a key

1. Open Settings → General and find API keys.
2. Create a key and give it a name you will recognise in the register's history, such as "Zapier — new customers". The name is what Alchex shows as the sender of every row that key adds.
3. Give it only the permissions it needs:
   • registers:rows:add — may add rows.
   • registers:rows:change — may change an existing row.
4. Copy the key when it is shown. You cannot see it again; create a new one if it is lost.

Only a workspace admin can create keys. A key can add and change rows. It cannot archive or delete one, and it cannot touch anything but register rows.

The four addresses

Send the key as Authorization: Bearer <key> and a JSON body. All addresses start with /api/v1/registers on your Alchex address. A register is named by its id, its code or its name.

Read the columns first: a row is a set of cells, keyed by column name.

{ "rows": [ { "cells": { "Customer": "Acme", "Risk": "High" }, "quote": "Email from Acme, 3 Nov" } ] }

• At most 50 rows in one request. The optional quote says where the row came from.
• A field the API does not know is refused, not ignored, so a typo shows up in the tool's log.
• Changing a row sends only the cells to change: { "cells": { "Risk": "Low" } }.
• A reply in plain words says what went wrong. 400 is a request to fix, 401 a missing or invalid key, 403 a key without the permission, 404 a register or row that is not there.

Sending the same thing twice is safe

Workflow tools retry. Add an Idempotency-Key header with a value that is the same for the same event and different for different ones, such as the id of the record in the tool that triggered the run. A repeat with the same key does not add the rows again: it answers 200 with replayed: true and the ids of the rows from the first time.

The rate limit

A key may make 60 requests a minute. Past that the answer is 429 with a Retry-After header saying how many seconds to wait; most workflow tools retry on their own. Sending several rows in one request, rather than one request per row, keeps you well inside it.

Do the rows go in live, or as suggestions?

By default rows from an API key arrive as suggestions: they wait in the register for someone to accept them, and nothing in the table changes until then. See Suggested and confirmed. The request still succeeds, with 202.

To let a trusted workflow write straight into the table, open the register, open Properties and turn on Accept rows from API keys straight in. Turn it off and new rows go back to being suggestions; rows already added stay.

• The switch belongs to one register, so a key you trust for one table does not reach the others live.
• Only a workspace admin, or an admin of the team that owns the register, can change it. Everyone else sees the switch but cannot move it, with the note "Only an admin can change this."
• The register's history records who turned it on or off.

Is the key being used?

Settings → General → API keys has a Last received list showing, for each key, when Alchex last received a request from it. Use it to check a new workflow is reaching Alchex, or to find a key nobody uses any more and remove it.

The time can be up to a minute old: Alchex notes a key at most once a minute. The list is visible to admins only. "No key has sent anything yet" means just that, so check the key and the address.