Tenderely BPM API
Read and write records of your Tenderely BPM forms, move process steps forward and receive record events in real time. This API powers the official Zapier and Make integrations, and you can call it from any system.
- Using Tenderely in Zapier
- Using Tenderely in n8n
- Authentication
- Base URL, limits, errors
- Connection test
- Forms (schema)
- Records
- Searching records
- Process steps
- REST hook subscriptions
- Webhook payload
- Verifying signatures
- MCP server (AI assistants)
- Error codes
Using Tenderely in Zapier
Tenderely is listed in the Zapier app directory. You can connect your BPM forms to other apps there without calling this API yourself.
- In Tenderely, open Process Design → Integrations → API keys and create a key. Give it access only to the forms Zapier should see.
- In Zapier, create a Zap, choose Tenderely as the app and paste the key when asked to connect.
- Pick a trigger or an action. Forms and fields are loaded from your account, so you choose them from lists.
| Type | Name in Zapier | What it does |
|---|---|---|
| Trigger | New Record | A record is created in a form. |
| Trigger | Updated Record | A record in a form is updated. |
| Trigger | Completed Record | A record's process is completed. |
| Action | Create Record | Creates a record in a form. If the form has a process, it starts. |
| Action | Update Record | Updates an existing record. Only the fields you fill in are changed. |
| Action | Complete Process Step | Completes the open step of a record's process, optionally with a decision and a comment. |
| Search | Find Record | Finds a record by a field value, for example an e-mail or an order number. |
Triggers are delivered instantly through REST hook subscriptions opened with your key. In Tenderely they appear on the Webhooks tab with a note that Zapier opened them; they are managed from Zapier. If you revoke the key, every Zap that uses it stops.
If a Zap does not work as expected, contact Zapier support. They have the context of your Zap and forward integration issues to us.
Using Tenderely in n8n
The n8n-nodes-tenderely community package adds two nodes to n8n. Source code and example workflows are on GitHub.
- In n8n, open Settings → Community Nodes → Install and enter
n8n-nodes-tenderely. - In Tenderely, open BPM → Integrations → API keys and create a key. Turn on Allow writing if your workflows will create or update records.
- In n8n, create a Tenderely API credential and paste the key.
- Add a Tenderely node and choose a form. Its fields are loaded from your account.
| Node | Operation | What it does |
|---|---|---|
| Tenderely Trigger | Record Created / Updated / Completed / Deleted | Starts the workflow instantly for one form. |
| Tenderely | Create | Creates a record in a form. If the form has a process, it starts. |
| Tenderely | Update | Updates a record. Only the fields you fill in are changed. |
| Tenderely | Get / Get Many | Reads a record, or lists records filtered by a field value and status. |
| Tenderely | Complete Step | Completes the open step of a record's process, optionally with a decision and a comment. |
The trigger opens a REST hook subscription when you activate the workflow and removes it when you deactivate it. Every delivery is signed and the node rejects requests with a missing or wrong signature.
Self-hosted n8n: Tenderely only delivers to public HTTPS addresses on port 443. Run n8n behind a
reverse proxy and set WEBHOOK_URL (for example https://n8n.example.com/); otherwise the trigger
cannot be activated. n8n Cloud needs no setup.
Authentication
Create an API key in Tenderely: BPM → Integrations → API keys. The key is shown only once.
Send it in the x-api-key header (or as Authorization: Bearer <key>).
Each key belongs to one company and can be limited:
- Forms — all forms of the company, or only the forms you select.
- Allow writing — off by default. Needed to create or update records and to complete steps.
- Sensitive forms — forms marked as holding sensitive data are closed to keys unless explicitly allowed.
- Include restricted fields — off by default. While off, the form's field permissions apply: restricted fields never appear in responses and cannot be written.
Revoking a key stops every request and every webhook subscription opened with it.
Base URL, limits, errors
https://appbackend.tenderely.com/bpm/api/v1
- Requests and responses are JSON. Dates are ISO 8601 (UTC).
- Each key has a per-minute request limit (60 by default). Responses carry
X-RateLimit-Limit,X-RateLimit-RemainingandX-RateLimit-Reset; over the limit you get429 RATE_LIMITED. - Errors return a non-2xx status and
{"success": false, "code": "…"}, sometimes withmessage,errorsorfields. See Error codes.
Connection test
GET/me — returns the company and the key's permissions.
curl https://appbackend.tenderely.com/bpm/api/v1/me \
-H "x-api-key: tkb_…"
{ "success": true,
"company": { "_id": "…", "name": "Acme Ltd" },
"apiKey": { "_id": "…", "name": "Zapier", "prefix": "tkb_1a2b3c4d",
"canWrite": true, "allowSensitive": false, "formIds": [] } }
Forms (schema)
GET/forms — published forms the key can access, with their fields.
GET/forms/{formId} — one form.
{ "_id": "…", "name": "Service requests",
"fields": [
{ "key": "email", "label": "E-mail", "type": "email", "required": true,
"readOnly": false, "inputType": "email", "searchable": true, "options": [] },
{ "key": "status", "label": "Status", "type": "select", "required": false,
"readOnly": false, "inputType": "select", "searchable": true,
"options": [ { "label": "New", "value": "new" }, { "label": "Done", "value": "done" } ] }
] }
keyis what you use in recorddata.readOnlyfields are calculated by the server and cannot be written.inputTypeisnullwhen the field cannot be written from outside (calculated, files, references, signatures, or restricted for this key). Otherwise one oftext,longtext,email,url,number,boolean,date,select,multiselect.- For
select/multiselectsend the optionvalue.
Records
GET/forms/{formId}/records
| Query | Meaning |
|---|---|
limit | 1–500, default 100. |
after | Cursor: pass paging.nextAfter from the previous page (newest first). |
status | Comma separated, e.g. running,completed. |
from, to | Creation date range. |
updatedSince | Incremental sync: records updated since this time, oldest first.
Pass back both paging.nextAfter and paging.nextAfterUpdatedAt as
after and afterUpdatedAt. |
field[key] | See Searching records. |
GET/forms/{formId}/records/{recordId}
{ "success": true,
"record": { "_id": "…", "title": "Service request", "status": "running",
"currentNodeKeys": ["approval"], "data": { "email": "customer@example.com" },
"createdAt": "…", "updatedAt": "…", "completedAt": null } }
POST/forms/{formId}/records
Creates a record. If the form has a process, it starts. Requires Allow writing.
Send Idempotency-Key to make retries safe: a repeated key returns the existing record
(200, header Idempotent-Replay: true) instead of a duplicate.
curl -X POST https://appbackend.tenderely.com/bpm/api/v1/forms/{formId}/records \
-H "x-api-key: tkb_…" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-10045" \
-d '{ "title": "Order 10045", "data": { "email": "customer@example.com", "quantity": 2 } }'
201 { "success": true, "instance": { "_id": "…", "status": "running", "data": { … } },
"form": { "_id": "…", "name": "Orders" } }
PATCH/forms/{formId}/records/{recordId}
Updates only the fields you send. The whole record is validated as in the app.
The response lists the changed fields.
-d '{ "data": { "status": "done" } }'
Searching records
Add up to three equality conditions to the list endpoint. Text comparison ignores letter case.
Only fields the key can see, of type text, e-mail, phone, URL, choice, auto number, number,
currency or yes/no (searchable: true).
GET /forms/{formId}/records?field[email]=customer%40example.com&limit=1
GET /forms/{formId}/records?fieldKey=email&fieldValue=customer%40example.com
The second form is for clients that cannot build bracketed query keys. An empty fieldKey means no filter.
Process steps
POST/forms/{formId}/records/{recordId}/advance
Completes the open step of the record's process — for decisions taken outside Tenderely (payment confirmed, parcel delivered). The process engine is the same as in the app: conditional branches, assignments and history apply. The acting user is the key's owner.
-d '{ "nodeKey": "approval", "action": "approve", "comment": "Paid", "data": { "invoiceNo": "A-77" } }'
200 { "success": true, "status": "completed", "currentNodeKeys": [] }
nodeKey is needed only when more than one step is open. action is the decision
of the step, if the step has decisions. data may only contain fields that the step lets you edit.
REST hook subscriptions
Instead of polling, subscribe to record events of a form. Tenderely then POSTs each event to your URL.
POST/hooks
-d '{ "targetUrl": "https://example.com/tenderely", "event": "record.created", "formId": "…" }'
201 { "success": true, "id": "…", "secret": "whsec_…", "event": "record.created", "formId": "…" }
event:record.created,record.updated,record.completed,record.deleted.targetUrlmust be a public HTTPS address (private and internal networks are rejected).- Keep
secretto verify signatures; it is shown once. - Up to 100 active subscriptions per key. A subscription follows the key's current permissions: if the key is revoked the subscription stops; if the form leaves the key's scope its events are not sent.
GET/hooks/{id}
Returns the subscription opened with this key: { "id", "url", "event", "formId", "isActive", "disabledReason" }.
Use it to check that a subscription still exists and is active; it may have been deleted or disabled in Tenderely.
404 means it is gone.
DELETE/hooks/{id}
Unsubscribes. Only the key that opened the subscription can delete it. 404 means it is already gone.
Delivery: one retry on failure; after 20 consecutive failures the subscription is disabled. Bursts above the company's per-minute limit are queued and delivered later, not dropped.
Webhook payload
POST https://example.com/tenderely
Content-Type: application/json
X-Tenderely-Event: record.created
X-Tenderely-Signature: t=1760000000,v1=5f0c…
{ "event": "record.created",
"occurredAt": "2026-10-13T09:00:00.000Z",
"companyId": "…",
"record": {
"id": "…", "formId": "…", "formName": "Service requests",
"title": "Service request", "status": "running",
"data": { "email": "customer@example.com" },
"createdAt": "…", "updatedAt": "…", "completedAt": null,
"url": "https://app.tenderely.com/#/bpm/instance/…"
} }
Answer with any 2xx status. Events of sensitive forms are sent only if the key allows sensitive forms.
Verifying signatures
The signature is HMAC-SHA256 of "{t}.{raw body}" with your subscription secret, hex encoded.
Compute it over the raw request body (not re-serialised JSON) and compare in constant time.
Reject old timestamps (for example older than 5 minutes) to prevent replays.
// Node.js
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(',').map(p => p.split('=')));
const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return fresh && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 || ''));
}
MCP server (AI assistants)
Tenderely BPM is also a Model Context Protocol server, so an AI assistant can look up and update your records in plain language (“which service requests from ACME are still open?”, “approve request 1042”).
POSThttps://appbackend.tenderely.com/bpm/mcp
Streamable HTTP, stateless. Authenticate with the same API key:
Authorization: Bearer tkb_…. It works with MCP clients that let you set a request header.
# Claude Code
claude mcp add --transport http tenderely https://appbackend.tenderely.com/bpm/mcp \
--header "Authorization: Bearer tkb_…"
// Cursor (~/.cursor/mcp.json) · VS Code (.vscode/mcp.json uses "servers" and "type": "http")
{ "mcpServers": { "tenderely": {
"url": "https://appbackend.tenderely.com/bpm/mcp",
"headers": { "Authorization": "Bearer tkb_…" } } } }
| Tool | What it does |
|---|---|
tenderely_whoami | Company, key name, write access and form scope. |
tenderely_list_forms | Published forms the key can use. |
tenderely_get_form | Field keys, types, choices; which fields the key may write. |
tenderely_search_records | Newest records, optionally matching one field value and/or status. |
tenderely_get_record | One record with its open process steps. |
tenderely_create_record | Creates a record (its process starts). Supports an idempotency key. |
tenderely_update_record | Writes only the given fields. |
tenderely_complete_step | Completes the open step, with an optional decision and comment. |
- The tools call this API with your key, so every rule above applies unchanged: form scope, sensitive forms, field permissions, read-only keys and rate limits. Use a read-only key if the assistant should only look.
- There is no delete tool.
- Record contents are returned marked as data, and the assistant is told not to follow instructions found inside records — text written into a record cannot steer the assistant.
- Calls through MCP are counted once against the key's per-minute limit.
Error codes
| Status | Code | Meaning |
|---|---|---|
| 401 | API_KEY_REQUIRED, API_KEY_INVALID | Missing, wrong or revoked key. |
| 403 | WRITE_NOT_ALLOWED | The key is read-only. |
| 403 | FORM_OUT_OF_SCOPE | The key is limited to other forms. |
| 403 | SENSITIVE_FORM_NOT_ALLOWED | The form holds sensitive data and the key does not allow it. |
| 400 | FIELD_NOT_WRITABLE | The key may not write the fields listed in fields. |
| 400 | FORM_INVALID | Required fields missing or values invalid (see message / errors). |
| 400 | DATA_REQUIRED | An update without data. |
| 400 | FIELD_FILTER_INVALID, FIELD_FILTER_UNSUPPORTED | The search field is unknown, hidden or of an unsupported type. |
| 400 | UPDATED_SINCE_INVALID | updatedSince is not a valid date. |
| 400 | EVENT_INVALID, FORM_REQUIRED | Invalid subscription request. |
| 404 | NOT_FOUND | Form, record or subscription not found (or not published). |
| 409 | FORM_NOT_PUBLISHED | The form is a draft. |
| 409 | DUPLICATE_VALUE | A unique field already has this value. |
| 409 | NO_OPEN_STEP, NOT_RUNNING, STEP_AMBIGUOUS, STEP_NOT_FOUND | The step cannot be completed: none open, process not running, several open steps (send nodeKey), or wrong nodeKey. |
| 409 | HOOK_LIMIT_REACHED | 100 active subscriptions for this key. |
| 429 | RATE_LIMITED | Too many requests this minute. |
Questions: contact us from the app. © 2026 Tenderely Global LLC · Dover City, Delaware, USA · Credits