# 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.
* **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.
There is no public endpoint that lists templates — the ID comes from the app.
## 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.
# Returns the authenticated user's 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 all conversions (/api-reference/conversions/v1-conversions-get)
Retrieves all conversions for the authenticated user
## `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
# Post multiple conversions (/api-reference/conversions/v1-conversions-post)
Posts multiple conversions with validation. Returns validation information and processes valid records even if some 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 conversions (/api-reference/conversions/v1-conversions-id-delete)
Marks a specific conversion for deletion by validating its status and preparing for removal. Client must subsequently check deletion status via 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
# Check the status of a specific conversion (/api-reference/conversions/v1-conversions-id-status-get)
Returns the processing status of a specified conversion by its ID
## `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
# Retrieve all open API orders (/api-reference/orders/v1-order-get)
Retrieve all open API orders
## `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
# Generate an order using a specified template ID (/api-reference/orders/v1-order-post)
Generate an order using a specified template ID
## `POST /v1/order`
### Request body
Content type: `application/json` (required)
- `templateId` (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
# Deletes an order that is in draft or edits needs status (/api-reference/orders/v1-order-id-delete)
Deletes an order that is in draft or edits needs status
## `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 the PDF proof document for a specified order (/api-reference/orders/v1-order-id-proof-get)
Retrieve the PDF proof document for a specified order
## `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 the PDF proof document for a specified order (/api-reference/orders/v1-order-id-proof-recipient-get)
Retrieve the PDF proof document for a specified 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 statistics from order ids (/api-reference/orders/v1-order-analytics-get)
Retrieve statistics from order ids
## `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 financial data from order ids (/api-reference/orders/v1-order-transaction-get)
Retrieve financial data from order ids
## `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
# Checkout Summary (/api-reference/orders/v1-order-id-checkout-get)
Calculate and retrieves the line item cost, production and estimated delivery details for a specific order for review prior to executing the checkout. This is not required to be called 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
# Initiates the checkout process for a specified order using its unique Order ID (/api-reference/orders/v1-order-id-checkout-post)
Initiates the checkout process for a specified order using its unique Order ID
## `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
# Retrieve a list of recipients associated from a specific order (/api-reference/orders/v1-order-id-recipients-get)
Retrieve a list of recipients associated from a specific order.
## `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 recipients associated with a specific order (/api-reference/orders/v1-order-id-recipients-delete)
Delete recipients associated with a specific order.
## `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 a specified order using its unique Order ID (/api-reference/orders/v1-order-id-recipients-put)
Append recipients to a specified order using its unique Order ID
## `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
# Gets Integration Orders (/api-reference/automations/v1-integration-orders-get)
Gets the integration orders of the logged in
## `GET /v1/integration-orders`
### Responses
- `200` — successful operation
- `401` — Authorization key not valid
- `403` — Forbidden
# Post a recipient into a integration order (/api-reference/automations/v1-integration-orders-id-recipients-post)
Posts recipient in the specified integration order
## `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
# Post a request for Proximity search around point (lat, lng) (/api-reference/automations/v1-integration-orders-id-by-proximity-post)
Post a request for Proximity search around an address tied to specified integration order
## `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
# Updates order recipients statistics when a QR Code is scanned (/api-reference/order-recipient-analytics/v1-order-recipients-statistics-post)
Updates order recipients statistics when a QR Code is scanned
## `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
# Post a request to add a new recipient into address book (/api-reference/address-book/v1-zapieractions-address-book-post)
Post a request to add a new recipient into address book
## `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