# API Reference (/api-reference)
The reference below is generated from the LettrLabs **public** OpenAPI schema, so
it always matches the live API. Every operation lists its parameters, request and
response schemas, status codes, and the `X-API-KEY` authentication requirement —
and each page has an interactive **“try it”** console you can call with your own
key.
## Groups [#groups]
* **Profile** — your account profile (`GET /v1/me`).
* **Orders** — create, inspect, and manage direct‑mail orders, recipients,
proofs, and checkout.
* **Templates** — list the account's active templates (the `templateId` values
you pass when creating an order).
* **Fonts** — list the handwriting fonts available to the account (the
`handwritingFont` values accepted by `POST /v1/order`).
* **Conversions** — record and read back conversions for attribution.
* **Automations** — integration‑driven order endpoints.
* **Order Recipient Analytics** — recipient‑level statistics for an order.
* **Address Book** — add address‑book entries.
## Before you call [#before-you-call]
Generate a key (see [Authentication & API keys](/authentication-api-keys))
and send it in the `X-API-KEY` header. All requests use the base URL
`https://app.lettrlabs.com/api`.
## Building with an AI agent? [#building-with-an-ai-agent]
Point your agent at [`/llms.txt`](/llms.txt) for a curated index of these pages,
or [`/llms-full.txt`](/llms-full.txt) for the entire reference and guides as a
single file — so it can build against the LettrLabs API effectively.
# Attributions and Conversions (/attributions-and-conversions)
**Conversions** let you tell LettrLabs when a recipient took action after
receiving your mail — a purchase, a signup, a booked appointment — so you can
attribute outcomes to a campaign and measure return on your direct mail.
## Record conversions [#record-conversions]
Send one or more conversions in a single call to `POST /v1/conversions`. The
exact body — what identifies a recipient, the conversion value, and any
metadata — is documented on the [`POST /v1/conversions`](/api-reference/conversions/v1-conversions-post)
reference page, with a live console.
```bash
curl -X POST https://app.lettrlabs.com/api/v1/conversions \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '[ { /* see the reference for the conversion shape */ } ]'
```
## Read conversions back [#read-conversions-back]
| Action | Endpoint |
| ----------------------------- | -------------------------------------------------------------------------------------------- |
| List all conversions | [`GET /v1/conversions`](/api-reference/conversions/v1-conversions-get) |
| Check one conversion's status | [`GET /v1/conversions/{id}/status`](/api-reference/conversions/v1-conversions-id-status-get) |
| Delete conversions | [`DELETE /v1/conversions/{id}`](/api-reference/conversions/v1-conversions-id-delete) |
Each is documented in full, with parameters and response schemas, under
[API Reference](/api-reference).
## How attribution fits together [#how-attribution-fits-together]
1. You **send mail** with [an order](/creating-an-order).
2. A recipient **acts** — and your system calls `POST /v1/conversions` to record
it.
3. You **read conversions back** for reporting, or check an individual
conversion's processing status.
For richer recipient‑level reporting, see the **Order Recipient Analytics**
group in the [API Reference](/api-reference).
# Authentication & API keys (/authentication-api-keys)
The LettrLabs public API authenticates every request with a **public API key**
sent in the **`X-API-KEY`** header. You generate the key once, inside the
LettrLabs app, and use it for all subsequent calls.
## Generate an API key [#generate-an-api-key]
In the LettrLabs app:
1. Open **[Automations](https://app.lettrlabs.com/automations)**.
2. Go to **Setup**.
3. Select **OpenAPI**.
4. Click **Manage**.
5. Click **Generate Key**.
Your new key is shown **once**, at creation time — copy it immediately and store
it somewhere secure (a secret manager or your server's environment). If you lose
it, generate a new key and update your integration.
Treat the key like a password. It grants full access to your account's public
API surface. Never embed it in client‑side code, a mobile app, or a public
repository — keep it server‑side.
## Authenticate a request [#authenticate-a-request]
Send the key in the `X-API-KEY` header on every request:
```bash
curl https://app.lettrlabs.com/api/v1/me \
-H "X-API-KEY: your_api_key_here"
```
A quick way to confirm a key works is `GET /v1/me`, which returns your profile.
A missing or invalid `X-API-KEY` header returns `401 Unauthorized`.
```http
GET /v1/me HTTP/1.1
Host: app.lettrlabs.com
X-API-KEY: your_api_key_here
```
Every endpoint in the [API Reference](/api-reference) shows the same
`X-API-KEY` requirement, and the interactive console lets you paste your key and
call the endpoint live.
## Rotating keys [#rotating-keys]
To rotate, generate a new key (same steps above), deploy it to your
integration, then stop using the old one. Generating a key does not
automatically revoke previous keys.
# Automations vs. creating an order (/automations-vs-creating-an-order)
LettrLabs gives you two ways to put mail in motion. They are not competitors —
they sit at different points on the "how much do I want to run myself" scale.
## The two paths [#the-two-paths]
* **Create an order (API)** — you call [`POST /v1/order`](/api-reference/orders/v1-order-post)
yourself, attach recipients, and check out. You own the trigger, the timing,
and the recipient list. Fully programmatic, one order at a time. See
[Creating an Order](/creating-an-order).
* **Automations (app)** — you configure a rule in the LettrLabs app
([Automations](https://app.lettrlabs.com/automations)) that places orders for
you when something happens (a CRM event, a list import, a proximity trigger).
The matching API surface is the **Automations** group
(`/v1/integration-orders`, see the [API Reference](/api-reference)), used to
feed and inspect those integration‑driven orders.
## Which should I use? [#which-should-i-use]
| Use **Create an Order** when… | Use **Automations** when… |
| ------------------------------------------- | ------------------------------------------------------ |
| Your own system decides when to mail | A recurring or event‑driven rule should mail for you |
| You want full control of each order in code | You want the app to manage the trigger and cadence |
| One‑off or batch sends on your schedule | Ongoing campaigns tied to CRM / list / location events |
## Rule of thumb [#rule-of-thumb]
If you can answer *"my code decides exactly when and to whom"*, create orders
directly. If you'd rather *"set it up once and let an event drive it"*, use
Automations. Many integrations use both — Automations for the steady‑state flow,
direct order creation for the exceptions.
# Creating an Order (/creating-an-order)
An **order** is a batch of direct mail generated from one of your templates and
addressed to a set of recipients. You create orders with a single call to
`POST /v1/order`, referencing a template you have already designed in the
LettrLabs app.
## Before you start [#before-you-start]
* A **public API key** — see [Authentication & API keys](/authentication-api-keys).
* A **template** built in the LettrLabs app. Its numeric **template ID** is what
you pass as `templateId`.
## Create an order from a template [#create-an-order-from-a-template]
The only required field is `templateId`. The full request body — recipients,
mailing options, and template merge fields — is documented, field by field, on
the [`POST /v1/order`](/api-reference/orders/v1-order-post) reference page, where you can also
fire the request live with your own key.
```bash
curl -X POST https://app.lettrlabs.com/api/v1/order \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"templateId": 12345
}'
```
A successful call returns the created order. Keep the returned **order ID** — you
use it to manage recipients, pull proofs, and check out the order.
## Work with an order after it's created [#work-with-an-order-after-its-created]
Each of these is documented in full under [API Reference](/api-reference):
| Action | Endpoint |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| List orders | [`GET /v1/order`](/api-reference/orders/v1-order-get) |
| Review an order's recipients | [`GET /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-get) |
| Add or update recipients | [`PUT /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-put) |
| Remove recipients | [`DELETE /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-delete) |
| Preview a proof | [`GET /v1/order/{id}/proof`](/api-reference/orders/v1-order-id-proof-get) |
| Check out (confirm + pay) | [`POST /v1/order/{id}/checkout`](/api-reference/orders/v1-order-id-checkout-post) |
| Cancel an order | [`DELETE /v1/order/{id}`](/api-reference/orders/v1-order-id-delete) |
## Idempotency [#idempotency]
Re‑sending the same `POST /v1/order` request creates a **new** order each time —
there is no automatic de‑duplication. If a request times out, fetch
`GET /v1/order` to check whether the order was created before retrying, so you
don't mail the same batch twice.
# Inbound webhooks (/inbound-webhooks)
Inbound webhooks let **your** systems (or a third party) push data **to**
LettrLabs. You configure a webhook in the LettrLabs app, which gives you a
unique endpoint, and your sender posts events to it.
These are **inbound** webhooks — data flowing *into* LettrLabs. LettrLabs does
not currently emit outbound event webhooks; that is planned for a future
release.
## Endpoint [#endpoint]
Post your payload to the webhook's unique URL:
```
POST /v1/webhooks/{guid}
```
`{guid}` is the identifier of the webhook you created in the app. The full
request goes to:
```
https://app.lettrlabs.com/api/v1/webhooks/{guid}
```
## Security: signature verification and API key [#security-signature-verification-and-api-key]
Each webhook can independently require **either, both, or neither** of two
protections, configured per webhook in the app:
### Optional HMAC‑SHA256 signature [#optional-hmacsha256-signature]
When signature verification is enabled, the sender computes an
**HMAC‑SHA256** of the raw request body using the webhook's shared secret and
sends it in a standard signature header. The endpoint accepts any of these four
headers:
* `X-Signature-256`
* `X-Hub-Signature-256`
* `X-Signature`
* `X-Hub-Signature`
The signature value is the lowercase hex digest, prefixed with **`sha256=`**:
```
X-Signature-256: sha256=3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b
```
Compute it over the **exact raw bytes** of the request body (before any
parsing). In Node.js:
```js
import { createHmac } from 'node:crypto';
const signature =
'sha256=' + createHmac('sha256', webhookSecret).update(rawBody).digest('hex');
```
Send the resulting `signature` in one of the four accepted headers (for example
`X-Signature-256`). LettrLabs recomputes the digest over the received body and
rejects the request if it does not match.
### Optional per‑webhook API key [#optional-perwebhook-api-key]
A webhook can also require an API key. When enabled, include your
**`X-API-KEY`** header on the request (see
[Authentication & API keys](/authentication-api-keys)). A webhook may
require the API key, the signature, both, or neither — whatever you configured.
## Example [#example]
```bash
curl -X POST https://app.lettrlabs.com/api/v1/webhooks/your-webhook-guid \
-H "Content-Type: application/json" \
-H "X-Signature-256: sha256=" \
-H "X-API-KEY: your_api_key_here" \
--data-binary @payload.json
```
If verification is enabled and the signature header is missing or wrong, or a
required API key is absent, the request is rejected.
# Introduction (/)
The LettrLabs API lets you drive real, physical direct mail from your own
systems: create orders from a template, target recipients, track delivery and
conversions, and receive events as they happen. Everything the LettrLabs app
does for direct‑mail automation is available over a simple HTTPS + JSON API.
**Building with an AI agent?** Point it at [`/llms.txt`](/llms.txt) for a
curated index of these docs, or [`/llms-full.txt`](/llms-full.txt) for the
full content as a single file — so it can build against the LettrLabs API
effectively.
## What you can do [#what-you-can-do]
* **Create orders** from a template and a recipient list — handwritten cards and
printed mail, sent on your schedule (see [Creating an Order](/creating-an-order)).
* **Attribute and convert** — record conversions against the mail you send and
read them back for reporting (see [Attributions & Conversions](/attributions-and-conversions)).
* **Manage your address book and recipients** — add entries and adjust an order's
recipients before it mails.
* **React to events** — receive inbound webhooks when something happens, with
optional HMAC signature verification (see [Inbound webhooks](/inbound-webhooks)).
## Base URL [#base-url]
All requests go to:
```
https://app.lettrlabs.com/api
```
Every endpoint is documented under [API Reference](/api-reference), grouped
by area, with parameters, request and response schemas, status codes, and an
interactive **“try it”** console you can call with your own key.
## Authentication in one line [#authentication-in-one-line]
Every request carries your public API key in the `X-API-KEY` header:
```bash
curl https://app.lettrlabs.com/api/v1/me \
-H "X-API-KEY: your_api_key_here"
```
You generate that key inside the LettrLabs app — the full walk‑through is in
[Authentication & API keys](/authentication-api-keys).
## Next steps [#next-steps]
1. [Generate an API key](/authentication-api-keys) and make your first
authenticated call to `GET /v1/me`.
2. Follow the [order of operations](/order-of-operations) to send your first
order end to end.
3. Not sure whether to drive orders yourself or let the app? See
[Automations vs. creating an order](/automations-vs-creating-an-order).
4. Explore the full [API Reference](/api-reference) and try requests live.
# Order of operations (/order-of-operations)
This walkthrough puts the API calls in the order you actually make them: start
from a template, create an order, attach recipients, then confirm and pay. Each
step links to the full reference, where you can fire the request live with your
own key.
New here? Skim [Authentication & API keys](/authentication-api-keys) first —
every call below sends your key in the `X-API-KEY` header.
## 1. Get a template ID [#1-get-a-template-id]
Orders are generated from a **template** you design in the LettrLabs app
(handwritten cards, printed mail, and so on). Open the template in the app; its
numeric **template ID** is the `templateId` you pass when creating an order.
You can also list your account's templates — and read their IDs — with
[`GET /v1/templates`](/api-reference/templates/v1-templates-get).
## 2. Create the order [#2-create-the-order]
Create the order with [`POST /v1/order`](/api-reference/orders/v1-order-post). The only required
field is `templateId`; recipients and mailing options can be set now or added in
the next step.
```bash
curl -X POST https://app.lettrlabs.com/api/v1/order \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{ "templateId": 12345 }'
```
Keep the returned **order ID** — every later step uses it.
## 3. Add recipients [#3-add-recipients]
Attach (or replace) the order's recipients with
[`PUT /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-put). Review what's currently
attached with [`GET /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-get).
```bash
curl -X PUT https://app.lettrlabs.com/api/v1/order/ORDER_ID/recipients \
-H "X-API-KEY: your_api_key_here" \
-H "Content-Type: application/json" \
-d '[ { /* see the reference for the recipient shape */ } ]'
```
## 4. Preview a proof (optional) [#4-preview-a-proof-optional]
Before you pay, pull a rendered proof with
[`GET /v1/order/{id}/proof`](/api-reference/orders/v1-order-id-proof-get) to confirm the mail looks right.
## 5. Check out [#5-check-out]
Confirm and pay for the order with
[`POST /v1/order/{id}/checkout`](/api-reference/orders/v1-order-id-checkout-post). Until you check out, the order
is a draft and nothing mails.
```bash
curl -X POST https://app.lettrlabs.com/api/v1/order/ORDER_ID/checkout \
-H "X-API-KEY: your_api_key_here"
```
## After it mails [#after-it-mails]
* Track recipient‑level delivery and engagement with **Order Recipient
Analytics** (see the [API Reference](/api-reference)).
* Record outcomes with conversions — see
[Attributions & Conversions](/attributions-and-conversions).
Re‑sending `POST /v1/order` creates a **new** order every time — there is no
automatic de‑duplication. See the idempotency note in
[Creating an Order](/creating-an-order) before adding retries.
# Retrieve the authenticated profile (/api-reference/profile/v1-me-get)
Returns profile data for the user authenticated by the supplied API key.
## `GET /v1/me`
### Responses
- `200` — Contains the authenticated profile data.
- `401` — Authorization key not valid
# List conversions (/api-reference/conversions/v1-conversions-get)
Returns all conversions recorded for the authenticated account, with their processing status.
## `GET /v1/conversions`
### Responses
- `200` — Returns all conversions with metadata about the response. The Metadata may include pagination details and total record counts.
- `400` — Bad Request
- `401` — Authorization key not valid
# Create conversions (/api-reference/conversions/v1-conversions-post)
Submits conversion events for matchback and attribution. Returns validation information and processes the valid records even when some records are invalid.
## `POST /v1/conversions`
### Request body
Content type: `application/json` (required)
_Array of objects with the following fields:_
- `firstName` (string | null, required)
- `lastName` (string | null, required)
- `fullName` (string | null, required)
- `businessName` (string | null, required)
- `primaryAddress` (`ConversionAddressViewModel`, required)
- `secondaryAddress` (`ConversionAddressViewModel`, required)
- `couponCode` (string | null, required)
- `primaryPhoneNumber` (string | null, required)
- `secondaryPhoneNumber` (string | null, required)
- `primaryEmail` (string | null (email), required)
- `secondaryEmail` (string | null (email), required)
- `revenue` (string | null, required)
- `type` (string | null, required)
- `orderId` (string | null, required)
- `storeId` (string | null, required)
- `uniqueId` (string | null, required)
- `crmId` (string | null, required)
- `customerId` (string | null, required)
- `eventDate` (string | null (date-time), required)
### Responses
- `200` — Returns processed conversions with validation statistics in Metadata. The Metadata includes TotalRecords, ValidRecords, InvalidRecords, PrimaryEmails, SecondaryEmails, PrimaryAddresses, SecondaryAddresses, PrimaryPhones, SecondaryPhones, CouponCodes, and may include DetailedErrors and DetailedWarnings with specific validation data.
- `400` — Invalid format or processing errors occurred.
- `401` — Authorization key not valid
- `422` — All records are invalid. Check Metadata for validation details and Warnings for specific validation failures.
- `499` — The operation was canceled by the client.
# Delete a conversion (/api-reference/conversions/v1-conversions-id-delete)
Marks a conversion for deletion after validating its status. Deletion is asynchronous — check its progress via the conversion status endpoint.
## `DELETE /v1/conversions/{id}`
### Parameters
- `id` (path, required)
### Responses
- `200` — Specified conversion has been validated and queued for deletion process
- `400` — Bad Request
- `401` — Unauthorized
# Retrieve a conversion's status (/api-reference/conversions/v1-conversions-id-status-get)
Returns the processing status of one conversion by its ID, including whether it has been matched or is pending deletion.
## `GET /v1/conversions/{id}/status`
### Parameters
- `id` (path, required) — The ID of the conversion to check
### Responses
- `200` — Returns the status of the specified conversion with metadata. The Metadata may include processing timestamps and status details.
- `400` — Bad Request
- `401` — Authorization key not valid
- `404` — Specified conversion ID does not exist
# List handwriting fonts (/api-reference/fonts/v1-fonts-get)
Lists the LettrLabs handwriting fonts available to the authenticated account. Every returned name is accepted by POST /v1/order's handwritingFont field.
## `GET /v1/fonts`
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# List orders (/api-reference/orders/v1-order-get)
Returns the account's orders with their status, product, postage, and delivery progress. Supports the id, status, paid, product, postage, and showRecipients filters, plus pageNumber/pageSize pagination.
## `GET /v1/order`
### Parameters
- `id` (query) — Filter orders by a list of order IDs separated by comma.
- `status` (query) — Filter orders by status (e.g., 'Draft', 'Mailed').
- `paid` (query) — Filter orders by whether they are paid or not.
- `product` (query) — Filter orders by product type.
- `postage` (query) — Filter orders by postage type.
- `showRecipients` (query) — Filter whether to return recipient information.
- `pageNumber` (query) — Used for pagination, the page number. Defaults to 0.
- `pageSize` (query) — Used for pagination, the number of records to retrieve. Defaults to 100.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Create an order (/api-reference/orders/v1-order-post)
Creates a new order from an existing template, copying its design and product settings, and returns the new order's ID. Add recipients and execute checkout separately to send the order.
## `POST /v1/order`
### Request body
Content type: `application/json` (required)
- `templateId` (integer (int32), required)
- `useQr` (boolean | null, required)
- `qrUrl` (string | null, required)
- `handwritingFont` (string | null, required)
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
- `500` — Internal Server Error
# Retrieve a recipient's delivery status (/api-reference/orders/v1-order-id-recipient-delivery-status-get)
Returns the latest carrier delivery status for one recipient on an order, identified by the recipient's first and last name, or by their address line.
## `GET /v1/order/{id}/recipient-delivery-status`
### Parameters
- `id` (path, required)
- `firstName` (query) — Recipient first name (use with lastName).
- `lastName` (query) — Recipient last name (use with firstName).
- `address` (query) — Recipient address line (Address1 or Address2). Use instead of firstName/lastName.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
- `404` — No matching recipient was found on the order
- `409` — Multiple recipients match the supplied name or address; refine your query
# Delete an order (/api-reference/orders/v1-order-id-delete)
Deletes an order that has not entered production. Only orders in Draft or Needs Edits status can be deleted.
## `DELETE /v1/order/{id}`
### Parameters
- `id` (path, required) — The Id of the order to delete.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Retrieve an order proof (/api-reference/orders/v1-order-id-proof-get)
Renders and returns the order's proof as a PDF document. The proof is generated for the first mailable recipient on the order (the lowest-ID recipient not marked do-not-mail), substituting that recipient's mail-merge fields.
## `GET /v1/order/{id}/proof`
### Parameters
- `id` (path, required) — The Id of the order to generate proof.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Retrieve a recipient's proof (/api-reference/orders/v1-order-id-proof-recipient-get)
Renders and returns a proof PDF for one specific recipient on the order, substituting that recipient's mail-merge fields. The recipient must belong to the order.
## `GET /v1/order/{id}/proof/{recipient}`
### Parameters
- `id` (path, required) — The Id of the order to generate proof.
- `recipient` (path, required) — Recipient Id to substitute mail merge fields.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Retrieve order analytics (/api-reference/orders/v1-order-analytics-get)
Returns engagement statistics — including per-recipient QR code scans — for the orders named in the Id query parameter (a comma-separated list of order IDs). Orders that cannot be processed are reported per-order with an error status rather than failing the whole request.
## `GET /v1/order/analytics`
### Parameters
- `Id` (query, required) — Comma-separated list of campaign ids.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Retrieve order transactions (/api-reference/orders/v1-order-transaction-get)
Returns the financial transactions recorded for the orders named in the Id query parameter (a comma-separated list of order IDs), including transaction type, amounts, and discounts. Orders that cannot be processed are reported per-order with an error status rather than failing the whole request.
## `GET /v1/order/transaction`
### Parameters
- `Id` (query, required) — Comma-separated list of campaign ids.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Preview an order checkout (/api-reference/orders/v1-order-id-checkout-get)
Calculates the line-item cost, production, and estimated delivery details for an order so they can be reviewed before checking out. Calling this endpoint is not required before executing a checkout.
## `GET /v1/order/{id}/checkout`
### Parameters
- `id` (path, required) — The Id of the order to calculate checkout details.
- `postage` (query) — The type of postage for the order. Available values: Standard, FirstClass.
- `production` (query) — The speed of production for the order. Available values: Normal, ExpeditedFaster, ExpeditedFastest.
- `holdUntilDate` (query) — The date to hold order production until. This date must be further in the future than the normal estimated production completion date.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Execute an order checkout (/api-reference/orders/v1-order-id-checkout-post)
Executes checkout for an order with the supplied postage type, production speed, and optional hold-until date, charging payment and submitting the order for production.
## `POST /v1/order/{id}/checkout`
### Parameters
- `id` (path, required) — The Id of the order to execute checkout and finalize the transaction.
### Request body
Content type: `application/json` (required)
- `postageType` (string, required)
- `productionSpeed` (string, required)
- `holdUntilDate` (string | null (date-time), required)
- `autoBill` (boolean, required)
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# List an order's recipients (/api-reference/orders/v1-order-id-recipients-get)
Returns the recipients on an order with their address and mail-merge data. Supports a query filter on recipient name, address, or organization, plus pageNumber/pageSize pagination.
## `GET /v1/order/{id}/recipients`
### Parameters
- `id` (path, required) — The Id of the order to retrieve the recipient list from.
- `query` (query) — Search filter for recipient data. Filter by recipient name, address or organization.
- `pageNumber` (query) — For pagination: Page number.
- `pageSize` (query) — For pagination: Number of records to retrieve.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Delete an order's recipients (/api-reference/orders/v1-order-id-recipients-delete)
Removes the specified recipients from an order. Pass the IDs of the recipients to remove in the request body.
## `DELETE /v1/order/{id}/recipients`
### Parameters
- `id` (path, required) — Order id.
### Request body
Content type: `application/json` (required)
- `recipientsIds` (array of integer (int32), required)
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Append recipients to an order (/api-reference/orders/v1-order-id-recipients-put)
Adds recipients to an existing order without replacing the ones already on it. Accepts up to 5,000 recipients per request.
## `PUT /v1/order/{id}/recipients`
### Parameters
- `id` (path, required) — The Id of the order to add recipients to.
### Request body
Content type: `application/json` (required)
- `recipients` (array of `ExternalOrdersRecipientVm`, required)
- `id` (integer (int32), required)
- `address` (`ExternalOrdersRecipientAddressVm`, required)
- `address1` (string | null, required)
- `address2` (string | null, required)
- `city` (string | null, required)
- `state` (string | null, required)
- `zipCode` (string | null, required)
- `zip4` (string | null, required)
- `zip2` (string | null, required)
- `country` (string | null, required)
- `personal` (`ExternalOrdersRecipientPersonalDataVm`, required)
- `firstName` (string | null, required)
- `lastName` (string | null, required)
- `toOrganization` (string | null, required)
- `salutation` (string | null, required)
- `metadata` (`ExternalOrdersRecipientMetadataVm`, required)
- `dpvConfirmationCode` (string | null, required)
- `custom1` (string | null, required)
- `custom2` (string | null, required)
- `custom3` (string | null, required)
- `custom4` (string | null, required)
- `custom5` (string | null, required)
- `custom6` (string | null, required)
- `image1` (string | null, required)
- `image2` (string | null, required)
- `image3` (string | null, required)
- `image4` (string | null, required)
- `image5` (string | null, required)
- `image6` (string | null, required)
- `salutation` (string | null, required)
- `returnTitle` (string | null, required)
- `returnFirstName` (string | null, required)
- `returnLastName` (string | null, required)
- `returnOrganization` (string | null, required)
- `returnAddress1` (string | null, required)
- `returnAddress2` (string | null, required)
- `returnCity` (string | null, required)
- `returnZip` (string | null, required)
- `returnState` (string | null, required)
- `email` (string | null, required)
- `qrUrl` (string | null, required)
- `text` (string, required)
- `text2` (string, required)
- `radiusPinStreet` (string | null, required)
- `radiusPinAddress` (string | null, required)
- `fullAddress` (string, required)
- `deliveryStatus` (string | null, required)
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# List templates (/api-reference/templates/v1-templates-get)
Lists the authenticated account's active templates — the set usable as templateId when creating an order. Paginated; preview image URLs are time-limited.
## `GET /v1/templates`
### Parameters
- `pageNumber` (query) — Page number (0-based). Defaults to 0.
- `pageSize` (query) — Page size. Defaults to 100.
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
# Retrieve a template (/api-reference/templates/v1-templates-id-get)
Returns one of the authenticated account's active templates: metadata and preview image URLs only (no design/scene definition).
## `GET /v1/templates/{id}`
### Parameters
- `id` (path, required)
### Responses
- `200` — Successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Profile's subscription tier does not have access to OpenAPI integrations
- `404` — Template not found for this account
# List integration orders (/api-reference/automations/v1-integration-orders-get)
Returns the account's integration orders (automations) — standing orders that mail each recipient added to them — with their template and configuration details.
## `GET /v1/integration-orders`
### Responses
- `200` — successful operation
- `401` — Authorization key not valid
- `403` — Forbidden
# Add a recipient to an integration order (/api-reference/automations/v1-integration-orders-id-recipients-post)
Adds one recipient to an integration order, validating and standardizing the address before queueing the mail piece for that recipient.
## `POST /v1/integration-orders/{id}/recipients`
### Parameters
- `id` (path, required) — ID of integration order to add recipient to.
### Request body
Content type: `application/json` (required)
- `id` (integer (int32), required)
- `firstName` (string | null, required)
- `lastName` (string | null, required)
- `toOrganization` (string | null, required)
- `address1` (string | null, required)
- `address2` (string | null, required)
- `city` (string | null, required)
- `state` (string | null, required)
- `zipCode` (string | null, required)
- `country` (string | null, required)
- `custom1` (string | null, required)
- `custom2` (string | null, required)
- `custom3` (string | null, required)
- `custom4` (string | null, required)
- `custom5` (string | null, required)
- `custom6` (string | null, required)
- `image1` (string | null, required)
- `image2` (string | null, required)
- `image3` (string | null, required)
- `image4` (string | null, required)
- `image5` (string | null, required)
- `image6` (string | null, required)
- `salutation` (string | null, required)
- `birthDay` (string | null (date-time), required)
- `anniversary` (string | null (date-time), required)
- `returnTitle` (string | null, required)
- `returnFirstName` (string | null, required)
- `returnLastName` (string | null, required)
- `returnOrganization` (string | null, required)
- `returnAddress1` (string | null, required)
- `returnAddress2` (string | null, required)
- `returnCity` (string | null, required)
- `returnState` (string | null, required)
- `returnZip` (string | null, required)
- `qrUrl` (string | null, required)
- `email` (string | null, required)
- `fullAddress` (string | null, required)
### Responses
- `200` — successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
- `403` — Forbidden
- `422` — Input is not in a valid format
# Request a proximity mailing (/api-reference/automations/v1-integration-orders-id-by-proximity-post)
Finds addresses around a point or address using the supplied filters and queues them as recipients on the integration order. Recipient discovery runs asynchronously after the request is accepted.
## `POST /v1/integration-orders/{id}-by-proximity`
### Parameters
- `id` (path, required) — ID of integration order add recipients to.
### Request body
Content type: `application/json` (required)
- `Name` (string, required)
- `OwnerOrRenterFilter` (integer (enum: 0, 1, 2), required)
- `PropertyTypeFilter` (integer (enum: 0, 1, 2), required)
- `HouseHoldIncomeFilter` (`HouseholdIncome`, required)
- `LengthOfResidenceFilter` (`LengthOfResidence`, required)
- `YearBuiltFilter` (`YearBuilt`, required)
- `HomePriceFilter` (`HomePrice`, required)
- `Addresses` (array of `Address`, required)
- `address1` (string, required)
- `address2` (string, required)
- `city` (string, required)
- `state` (string, required)
- `zip` (string, required)
- `DesiredCount` (integer (int32), required)
- `MultiUse` (boolean | null, required)
### Responses
- `200` — successful operation
- `400` — Parameters does not contain proper data. Check Errors from the response for more data.
- `401` — Authorization key not valid
- `403` — Forbidden
# Record a QR code scan (/api-reference/order-recipient-analytics/v1-order-recipients-statistics-post)
Records a QR code scan event against an order recipient, updating that recipient's engagement statistics. Processing is asynchronous — the scan is queued and applied shortly after the request succeeds.
## `POST /v1/order-recipients-statistics`
### Request body
Content type: `application/json` (required)
- `orderId` (integer (int32), required)
- `statisticName` (integer (enum: 0), required)
- `statisticValue` (string, required)
- `orderRecipientId` (integer (int32), required)
- `orderRecipient` (`OrderRecipient`, required)
- `id` (integer (int32), required)
- `firstName` (string | null, required)
- `lastName` (string | null, required)
- `toOrganization` (string | null, required)
- `fullAddress` (string | null, required)
- `address1` (string | null, required)
- `address2` (string | null, required)
- `city` (string | null, required)
- `state` (string | null, required)
- `zipCode` (string | null, required)
- `country` (string | null, required)
- `createdDate` (string (date-time), required)
- `qrCode` (string | null, required)
- `qrUrl` (string | null, required)
- `qrCodeScanCount` (integer (int32), required)
- `customerEmail` (string | null, required)
- `customerName` (string | null, required)
- `customerOrganization` (string | null, required)
- `salespersonName` (string | null, required)
### Responses
- `200` — successful operation
- `400` — Something went wrong
- `401` — Authorization key not valid
# Add an address book entry (/api-reference/address-book/v1-zapieractions-address-book-post)
Adds a recipient to the account's address book, validating and standardizing the supplied address before saving it.
## `POST /v1/zapierActions/address-book`
### Request body
Content type: `application/json` (required)
- `firstName` (string, required)
- `lastName` (string, required)
- `toOrganization` (string, required)
- `address1` (string, required)
- `address2` (string, required)
- `city` (string, required)
- `state` (string, required)
- `zip` (string, required)
- `phoneNumber` (string | null, required)
### Responses
- `200` — successful operation
- `400` — Parameters does not contain proper data. Check Errors from the response for more data.
- `401` — Authorization key not valid
- `403` — Forbidden
- `404` — Not Found