← Tenderely

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

Tenderely is listed in the Zapier app directory. You can connect your BPM forms to other apps there without calling this API yourself.

  1. In Tenderely, open Process Design → Integrations → API keys and create a key. Give it access only to the forms Zapier should see.
  2. In Zapier, create a Zap, choose Tenderely as the app and paste the key when asked to connect.
  3. Pick a trigger or an action. Forms and fields are loaded from your account, so you choose them from lists.
TypeName in ZapierWhat it does
TriggerNew RecordA record is created in a form.
TriggerUpdated RecordA record in a form is updated.
TriggerCompleted RecordA record's process is completed.
ActionCreate RecordCreates a record in a form. If the form has a process, it starts.
ActionUpdate RecordUpdates an existing record. Only the fields you fill in are changed.
ActionComplete Process StepCompletes the open step of a record's process, optionally with a decision and a comment.
SearchFind RecordFinds 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.

  1. In n8n, open Settings → Community Nodes → Install and enter n8n-nodes-tenderely.
  2. In Tenderely, open BPM → Integrations → API keys and create a key. Turn on Allow writing if your workflows will create or update records.
  3. In n8n, create a Tenderely API credential and paste the key.
  4. Add a Tenderely node and choose a form. Its fields are loaded from your account.
NodeOperationWhat it does
Tenderely TriggerRecord Created / Updated / Completed / DeletedStarts the workflow instantly for one form.
TenderelyCreateCreates a record in a form. If the form has a process, it starts.
TenderelyUpdateUpdates a record. Only the fields you fill in are changed.
TenderelyGet / Get ManyReads a record, or lists records filtered by a field value and status.
TenderelyComplete StepCompletes 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:

Revoking a key stops every request and every webhook subscription opened with it.

Base URL, limits, errors

https://appbackend.tenderely.com/bpm/api/v1

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" } ] }
  ] }

Records

GET/forms/{formId}/records

QueryMeaning
limit1–500, default 100.
afterCursor: pass paging.nextAfter from the previous page (newest first).
statusComma separated, e.g. running,completed.
from, toCreation date range.
updatedSinceIncremental 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" } }'

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": "…" }

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_…" } } } }
ToolWhat it does
tenderely_whoamiCompany, key name, write access and form scope.
tenderely_list_formsPublished forms the key can use.
tenderely_get_formField keys, types, choices; which fields the key may write.
tenderely_search_recordsNewest records, optionally matching one field value and/or status.
tenderely_get_recordOne record with its open process steps.
tenderely_create_recordCreates a record (its process starts). Supports an idempotency key.
tenderely_update_recordWrites only the given fields.
tenderely_complete_stepCompletes the open step, with an optional decision and comment.

Error codes

StatusCodeMeaning
401API_KEY_REQUIRED, API_KEY_INVALIDMissing, wrong or revoked key.
403WRITE_NOT_ALLOWEDThe key is read-only.
403FORM_OUT_OF_SCOPEThe key is limited to other forms.
403SENSITIVE_FORM_NOT_ALLOWEDThe form holds sensitive data and the key does not allow it.
400FIELD_NOT_WRITABLEThe key may not write the fields listed in fields.
400FORM_INVALIDRequired fields missing or values invalid (see message / errors).
400DATA_REQUIREDAn update without data.
400FIELD_FILTER_INVALID, FIELD_FILTER_UNSUPPORTEDThe search field is unknown, hidden or of an unsupported type.
400UPDATED_SINCE_INVALIDupdatedSince is not a valid date.
400EVENT_INVALID, FORM_REQUIREDInvalid subscription request.
404NOT_FOUNDForm, record or subscription not found (or not published).
409FORM_NOT_PUBLISHEDThe form is a draft.
409DUPLICATE_VALUEA unique field already has this value.
409NO_OPEN_STEP, NOT_RUNNING, STEP_AMBIGUOUS, STEP_NOT_FOUNDThe step cannot be completed: none open, process not running, several open steps (send nodeKey), or wrong nodeKey.
409HOOK_LIMIT_REACHED100 active subscriptions for this key.
429RATE_LIMITEDToo many requests this minute.

Questions: contact us from the app. © 2026 Tenderely Global LLC · Dover City, Delaware, USA · Credits