> For the complete documentation index, see [llms.txt](https://kb.craftformswp.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kb.craftformswp.com/documentation/for-developers/data-api.md).

# Data API

*CraftForms PRO 2.4 and later.*

The Data API lets other software read and create your forms' submissions, orders and bookings, catalog items and people, and hear about new ones the moment they happen. It is what the Zapier, Make and n8n apps use, and you can call it from your own scripts or a partner's system.

It is a REST API under your site's address:

```
https://example.com/wp-json/craftforms/data/v1/
```

On a site without pretty permalinks, use `https://example.com/?rest_route=/craftforms/data/v1/…` instead.

### API keys

Create keys in **CraftForms → Settings → API Keys → Create an API key**:

* **Name**, and **Who uses it** (a company, agency or partner, e.g. "Zapier", "Hotel Royal"): later shows who sent a booking or a submission.
* **What it may do**: pick a ready-made choice (**Read only**, **Bookings**, **Enquiries**, **Everything**), or open **Customize** and set each area to **None**, **Read** or **Read and change** (for **Email customers**: **None**, **Draft** or **Draft and send**).
* **Forms**: **All forms**, or **Only these forms, their submissions and orders**.
* **Catalog items**: **All catalog items**, or **Only these items** (see [Limit a key to some catalog items](#limit-a-key-to-some-catalog-items)).
* **Requests per minute** (default 120).

The key starts with `cfk_` and is shown **once**: CraftForms keeps a fingerprint of it, not the key itself. **Revoke** stops it at once.

**Change access** on a key's row changes its name, what it may do, and its forms and items later, without a new key. The change counts from the key's next request. This works for apps connected by sign-in too (rows named "… (signed in)"), so you can narrow what an AI app sees after you connected it.

| Area                        | Read                                                                                    | Read and change                                                                                     |
| --------------------------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Forms (names and fields)    | `forms:read`                                                                            | –                                                                                                   |
| Submissions                 | `submissions:read`                                                                      | **Read, add and update**: add submissions, set their inbox status, assign them: `submissions:write` |
| Orders and bookings         | `orders:read`                                                                           | also change their status, no-show, mark as paid, reschedule: `orders:write`                         |
| Catalog items               | `catalog:read` (and availability)                                                       | also change prices and stock, block dates: `catalog:write`                                          |
| People                      | `people:read`                                                                           | –                                                                                                   |
| Notes, tasks and own fields | –                                                                                       | add and change notes, tasks and properties (stages, tags, own fields): `records:write`              |
| Email customers             | **Draft**: write replies that wait on the enquiry for a person to send: `replies:draft` | **Draft and send**: also email replies to customers: `replies:send`                                 |

**Email customers** can be given only by someone who may manage CraftForms settings, even at **Draft**. Keys made before 2.4 keep exactly what they had: none of them can draft or send until you change their access.

The ready-made choices:

| Choice         | Gives                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| **Read only**  | Read forms, submissions, orders and bookings, catalog items, people                                    |
| **Bookings**   | Read and change orders and bookings and catalog items; read people and forms; add notes and tasks      |
| **Enquiries**  | Read, add and update submissions; read people and forms; add notes and tasks; draft replies (not send) |
| **Everything** | Every area at its highest level, sending replies included                                              |

#### Limit a key to some catalog items

With **Only these items**, the key sees:

* **Catalog items**: only those items, in lists, one by one, their availability, and changing their price and stock.
* **Orders and bookings**: only those made for one of the items. An order without a catalog item stays hidden.
* **Submissions**: only those made for one of the items. A submission without an item stays hidden. The key can add submissions only for its items (send `item_id`).
* **People**: only people with at least one order or submission the key sees. Their counts and dates cover only those.
* **Notes, tasks and properties**: only on the orders, submissions and people it sees.
* **Forms**: the forms its items belong to (names and fields, not other forms' guests).
* **Webhooks**: only events about records it sees.

A form limit and an item limit together: a record must pass both. Anything outside the limits answers **404**, as if it didn't exist. `GET /me` lists the items (`item_ids`, and `items` with their names).

### Sign requests

Send the key in a header:

```
Authorization: Bearer cfk_…
```

`X-CraftForms-Key: cfk_…` works too. A WordPress **application password** (HTTP Basic, user + application password) is also accepted: a user who can manage CraftForms settings gets every scope, one with CraftForms access the read scopes.

A key that is wrong, revoked or expired answers **401**, even for a logged-in user.

```bash
curl https://example.com/wp-json/craftforms/data/v1/me \
  -H "Authorization: Bearer cfk_…"
```

`GET /me` answers with the key's name, scopes, form limit (`form_ids`), catalog item limit (`item_ids`, and `items` with id, label and type), the site's name, address, time zone and currency.

### How answers look

* **Lists** answer `{ "data": [ … ], "next_cursor": "…" }`. Ask for more with `?cursor=` until `next_cursor` is `null`. `limit` is 1–100 (default 25). Newest first; `order=asc` with `created_since` or `updated_since` is how a sync catches up.
* **Times** are ISO 8601 in UTC (`2026-11-18T10:00:00Z`); dates are `YYYY-MM-DD`. **Ids** are numbers.
* **Errors** answer `{ "code": "…", "message": "…", "data": { "status": 400 } }`. The message is written to be shown to a person (`Field "email" is required.`).
* A record outside the key's forms or catalog items answers **404**, as if it didn't exist. Lists leave such records out, and their pages stay full.
* **Rate limit**: `X-RateLimit-Limit` and `X-RateLimit-Remaining` on every answer; over the limit, **429** with `Retry-After`.

### Read

| Request                                | Scope                               | Notes                                                                                                                                                                                                                                           |
| -------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /forms`                           | `forms:read`                        | `search`                                                                                                                                                                                                                                        |
| `GET /forms/{id}`                      | `forms:read`                        | With `fields`: name, label, type, kind, and `options` (value, label) for choice fields                                                                                                                                                          |
| `GET /submissions`                     | `submissions:read`                  | `form_id`, `person_id`, `status`, `channel`, `created_since`, `property[key]=value`                                                                                                                                                             |
| `GET /submissions/{id}`                | `submissions:read`                  | Answers as `fields` (name, label, value, display)                                                                                                                                                                                               |
| `GET /orders`                          | `orders:read`                       | `form_id`, `person_id`, `item_id`, `type` (booking, product), `status`, `created_since`, `updated_since`; bookings by date: `start_from` / `start_to` (arrivals), `active_from` / `active_to` (who is here), `end_from` / `end_to` (departures) |
| `GET /orders/{id}`                     | `orders:read`                       | Customer, line items, booking dates, total, payment status                                                                                                                                                                                      |
| `GET /catalog/items`                   | `catalog:read`                      | `type`, `form_id`, `status` (active by default), `search`                                                                                                                                                                                       |
| `GET /catalog/items/{id}`              | `catalog:read`                      | With `booking`: type, unit (night, day, time), capacity, booking window. Prices: see [How an item is priced](#how-an-item-is-priced)                                                                                                            |
| `GET /catalog/items/{id}/availability` | `catalog:read`                      | `from`, `to`, `guests`: per date `available`, `places_left`, `blocked` (closed by you), and free `times` for items booked by time. At most 366 days (62 for times). Same answer as your booking forms.                                          |
| `GET /people`                          | `people:read`                       | `search`, `email`, `created_since`                                                                                                                                                                                                              |
| `GET /people/{id}`                     | `people:read`                       | Counts and dates of their orders and submissions                                                                                                                                                                                                |
| `GET /summary`                         | each part its own read scope        | `from`, `to` (site dates, inclusive; the last 30 days by default, at most 366), `form_id`, `item_id`. See [Summary](#summary).                                                                                                                  |
| `GET /team`                            | `submissions:read`                  | Who an enquiry can be assigned to: `id`, `name`                                                                                                                                                                                                 |
| `GET /email-log`                       | `submissions:read` or `orders:read` | `submission_id` or `order_id` (and `to`): emails sent about it, with `to`, `subject`, `status` (sent, failed), `sent_at`. Never the text or attachments. Searching by `to` alone needs both read scopes and no form or item limit.              |

#### How an item is priced

A catalog item shows its price in one of three ways:

* `price`: a fixed price (a plain number).
* `price_formula`: the item's own formula.
* `form_price_formula`: the item has no price of its own and its form's formula sets it, for example `nights * nightly_rate + cleaning_fee` for a room made from the Guest Room starter.

`variables` lists the item's own Smart Variables, the numbers those formulas work with: `{"name": "nightly_rate", "label": null, "value": 95, "formula": null}`. A variable that is itself a formula (prices by season) has `value: null` and the text in `formula`.

A submission has `inbox_status` (where it stands in Enquiries: `new`, `open`, `replied`, `won`, `lost`); a booking has `no_show_at`.

Order shapes never include the customer's private order link or raw payment data.

### Write

Writes accept an **`Idempotency-Key`** header: sending the same key again within 24 hours answers with the first result instead of doing it twice. Use one whenever a retry is possible.

**Add a submission** (`submissions:write`). It goes through the form's normal path: validation, submit actions, emails, an order or booking when the form makes one. Payments aren't taken through the API.

```bash
curl -X POST https://example.com/wp-json/craftforms/data/v1/forms/6/submissions \
  -H "Authorization: Bearer cfk_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-lead-8812" \
  -d '{"fields": {"name": "Ada Lovelace", "email": "ada@example.com", "subject": "support"}}'
```

Optional: `item_id` (the catalog item, for a booking or product form) and `locale` (for a translated form). A form that isn't published answers **409**.

**Change an order's status** (`orders:write`): `POST /orders/{id}/status` with `{"status": "confirmed"}`. Statuses: `pending`, `confirmed`, `paid`, `cancelled`. A cancelled or refunded order can no longer change (**409**); refunds are made in WordPress.

**Change a catalog item** (`catalog:write`): `PATCH /catalog/items/{id}` with `price` (replaces a fixed price; an item priced by a formula answers **409**), `base_price`, `variables` and, for products, `stock`.

`variables` changes the numbers a formula prices with: `{"variables": {"nightly_rate": 120}}`. Only variables the item already has, each with a number of 0 or more. A variable that holds a formula (prices by season) answers **409** and stays as it is. An item priced by its form through its variables also answers **409** to `price`, with the variables' names: a fixed price there would replace the whole formula with one amount.

#### What the work pages do

The same rules as the work pages, so a refusal here reads as it does there. What is done to an order is written on it as a note, under the key's or the app's name.

| Request                                    | Scope               |                                                                                                                                                                                                                                       |
| ------------------------------------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /submissions/{id}/status`            | `submissions:write` | `{"status": "replied"}`: the inbox's `new`, `open` (to answer), `replied`, `won`, `lost`, or only `read` / `unread` (the outcome stays). Nothing is deleted.                                                                          |
| `POST /submissions/status`                 | `submissions:write` | `{"ids": [12, 13], "status": "read"}`, up to 100: answers `updated` and `not_found` (out of the key's reach)                                                                                                                          |
| `POST /submissions/{id}/assign`            | `submissions:write` | `{"user_id": 4}` (from `GET /team`) or `{"user_id": null}`; `tell: true` emails them a link                                                                                                                                           |
| `POST /orders/{id}/no-show`                | `orders:write`      | A current booking, from its first day on (**409** before, or for a cancelled one). The nights or places stay booked. `{"undo": true}` takes it back.                                                                                  |
| `POST /orders/{id}/paid`                   | `orders:write`      | Mark as paid outside the site: a pending or confirmed order with something to pay. `note` is kept on the order. No money moves.                                                                                                       |
| `POST /orders/{id}/reschedule`             | `orders:write`      | A stay: `from` (check-in), `to` (check-out), optionally `item_id` for another room. A time-slot booking (rentals, appointments, tours): `date` and `time`. Taken or closed dates answer **409** and nothing changes; the price stays. |
| `POST /catalog/items/{id}/blocked-dates`   | `catalog:write`     | `{"from": "2026-12-24", "to": "2026-12-26", "note": "Family"}` closes those dates (for a stay, the nights starting on them) everywhere. Dates with bookings answer **409** with those `bookings`: cancel or move them first.          |
| `DELETE /catalog/items/{id}/blocked-dates` | `catalog:write`     | `{"from": …, "to": …}` opens them again                                                                                                                                                                                               |

#### Summary

`GET /summary` adds up a period, only over what the key may read:

* `submissions` (with `submissions:read`): `total`, `by_status` (inbox statuses), `by_form`.
* `orders` (with `orders:read`): orders made in the period, `by_status` and `by_type`.
* `revenue`: the total of orders made in the period and now paid, in the site's currency (`other_currencies` apart). Refunded ones aren't counted.
* `bookings`: `arrivals` (bookings starting in the period) and `departures` (stays checking out in it).
* `occupancy`: for rooms booked as a whole, `nights_booked` of `nights_open` (the period's nights minus those you closed), per room and in all.

#### Replies to customers

| Request                              | Scope           |                                                                                                                                                                                                                                                              |
| ------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `POST /submissions/{id}/reply-draft` | `replies:draft` | `{"body": "…", "subject": "…"}`, or `{"saved_reply": "r1a2"}` filled in for this person. Kept on the enquiry as a **draft reply**: in Enquiries, **Use this draft** opens it in the reply window to check and send. Sends nothing.                           |
| `POST /submissions/{id}/reply`       | `replies:send`  | `{"subject": "…", "body": "…"}`: emailed now, as Enquiries sends it (from your business address, through the form's SMTP server or the site's email), quoted answers below, kept in Email Logs and on the enquiry, which turns **Replied**. Drafts on it go. |

Sending works only while **Enquiries → Setup → Send replies from this site** is on (**409** otherwise), only to the enquiry's own address (**409** when it has none), at most 20 an hour per key or app (**429**). Send it with an `Idempotency-Key`: the same reply sent again without one within 10 minutes is refused (**409**), never sent twice.

**Notes, tasks and properties** (`records:write`): your own fields, stages and tags on people, orders and submissions (`GET`/`PATCH …/{id}/properties`), a notes timeline (`…/{id}/notes`) and tasks (`…/{id}/tasks`, `GET /tasks`). Define properties with `GET`/`POST /properties`.

### Webhooks

Instead of asking again and again, software can subscribe to events. A key manages its own subscriptions, the way Zapier's REST hooks work:

| Request                               |                                                                                                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST /webhooks`                      | `{"url": "https://…", "events": ["submission.created"], "description": "…"}`. Answers with the subscription and its **`secret`** (`whsec_…`), shown once. |
| `GET /webhooks`, `GET /webhooks/{id}` | The key's subscriptions, with status and last delivery                                                                                                    |
| `PATCH /webhooks/{id}`                | Change `url`, `events`, or turn it back on with `status: "active"`                                                                                        |
| `DELETE /webhooks/{id}`               | Unsubscribe                                                                                                                                               |
| `POST /webhooks/{id}/ping`            | Send a test delivery now                                                                                                                                  |
| `GET /webhooks/{id}/deliveries`       | The delivery log (kept 30 days)                                                                                                                           |

Events: `submission.created`, `order.created`, `order.status_changed`. A subscription hears only what its key may read (its scopes, forms and catalog items), and goes quiet when the key is revoked. At most 25 per key. The address must be public **https**.

Each delivery is a `POST` with this body:

```json
{
  "id": "868b57b7-…",
  "type": "order.status_changed",
  "created_at": "2026-11-18T10:00:00Z",
  "data": { "id": 42, "status": "paid", "…": "the same shape as GET /orders/42" },
  "change": { "from": "confirmed", "to": "paid", "source": "admin" }
}
```

Headers: `X-CraftForms-Event`, `X-CraftForms-Event-Id`, `X-CraftForms-Delivery`, `X-CraftForms-Timestamp` and **`X-CraftForms-Signature: t={unix time},v1={signature}`**.

**Check the signature** before trusting a delivery: `v1` is the HMAC-SHA256 of `{t}.{raw body}` with the subscription's secret. Refuse it when it doesn't match, or when `t` is more than a few minutes old.

```js
const crypto = require('crypto');
function verify(header, rawBody, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  const given = Buffer.from(parts.v1 || '');
  return given.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), given);
}
```

```php
function verify($header, $raw_body, $secret) {
    parse_str(str_replace(',', '&', $header), $p);
    if (abs(time() - (int) ($p['t'] ?? 0)) > 300) return false;
    return hash_equals(hash_hmac('sha256', $p['t'] . '.' . $raw_body, $secret), $p['v1'] ?? '');
}
```

Answer with any **2xx** within 5 seconds (do slow work after answering). Other answers are retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours, then given up. Answering **410 Gone** turns the subscription off; so do 5 given-up deliveries in a row. Turn it back on with `PATCH` or under **Settings → API Keys → Webhooks**.

### Apps

* **AI apps** (Claude, ChatGPT and others): connect with a sign-in, no key to copy. See [Connect Claude, ChatGPT and other AI apps](https://kb.craftformswp.com/documentation/for-developers/connect-ai-apps.md).
* **n8n**: the CraftForms and CraftForms Trigger nodes (community package `n8n-nodes-craftforms`).
* **Zapier** and **Make**: coming with 2.4.
