# Table of Contents
- [Lob API documentation](#lob-api-documentation)
---
# Lob API documentation
* Overview
* Introduction
* Authentication
* API Keys
* Getting Started
* SDKs and Tools
* Address Book
* Addresses
* getList
* postCreate
* getRetrieve
* delDelete
* National Change of Address
* NCOALink Live Environment
* NCOALink Test Environment
* Print and Mail API
* Postcards
* getRetrieve
* delCancel
* getList
* postCreate
* Self Mailers
* getRetrieve
* delDelete
* getList
* postCreate
* Letters
* getRetrieve
* delCancel
* getList
* postCreate
* Checks
* getList
* postCreate
* getRetrieve
* delCancel
* Snap Packs
* getRetrieve
* delDelete
* getList
* postCreate
* Booklets
* getRetrieve
* delDelete
* getList
* postCreate
* Bank Accounts
* postVerify
* getRetrieve
* delDelete
* getList
* postCreate
* Templates
* getRetrieve
* postUpdate
* delDelete
* getList
* postCreate
* Resource Proofs
* getRetrieve
* patchUpdate
* postCreate
* Template Versions
* getRetrieve
* postUpdate
* delDelete
* getList
* postCreate
* Template Design
* HTML Templates
* HTML Examples
* Image Prepping
* Standard PDF Fonts
* Manage Mail
* Cancellation Windows
* Scheduled Mailings
* Campaigns API (BETA)
* Campaigns
* getList
* postCreate
* getRetrieve
* patchUpdate
* delDelete
* postSend Campaign
* Creatives
* postCreate
* getRetrieve
* patchUpdate
* Uploads
* getList
* postCreate
* getRetrieve
* patchUpdate
* delDelete
* postUpload file
* postCreate Export
* getRetrieve Line Item Report
* getRetrieve Export
* Informed Delivery Campaign API
* Informed Delivery Campaign
* getList
* postCreate
* getRetrieve
* patchUpdate
* Address Verification API
* US Verifications
* US Verifications Test Env
* postBulk Verify
* postSingle Verify
* US Verification Types
* US Autocompletions
* Autocompletion Test Env
* postAutocomplete
* Reverse Geocode Lookups
* postReverse Geocode Lookup
* Zip Lookups
* postLookups
* Identity Validation
* postIdentity Validation
* Intl Verifications
* Intl Verifications Test Env
* postBulk Verify
* postSingle Verify
* Webhooks
* Webhooks
* Events
* EventEvents
* Tracking Events
* EventTracking Events
* Special Features
* Billing Groups
* getRetrieve
* postUpdate
* getList
* postCreate
* Buckslips
* getList
* postCreate
* getRetrieve
* patchUpdate
* delDelete
* Buckslip Orders
* getRetrieve
* postCreate
* Cards
* getList
* postCreate
* getRetrieve
* postUpdate
* delDelete
* Card Orders
* getRetrieve
* postCreate
* QR Codes
* getList
* URL Shortener
* getRetrieve a domain
* delDelete a Domain
* postCreate Domain
* getList all domains
* getRetrieve a link
* patchUpdate a Link
* delDelete Link
* postCreate Link
* getList all links
* Appendix
* Beta Program
* Errors
* Rate Limiting
* Requests and Responses
* Asset URLs
* Query Parameters
* Idempotent Requests
* Metadata
* Request Body
* Test and Live Environments
* Versioning and Changelog
[API docs by Redocly](https://redocly.com/redoc/)
Lob (1.21.0)
============
Lob Developer Experience: [lob-openapi@lob.com](mailto:lob-openapi@lob.com)
URL: [https://support.lob.com/](https://support.lob.com/)
License: [MIT](https://mit-license.org/)
[Terms of Service](https://www.lob.com/legal)
The Lob API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and uses HTTP response codes to indicate any API errors.
[](https://docs.lob.com/#tag/Introduction)
Introduction
=======================================================
Lob's Print & Mail and Address Verification APIs help companies transform outdated, manual print-and-mail processes; save 1,000s of hours in processing time by sending mail much more quickly; and increase ROI on offline communications.
Automate direct mail by triggering on-demand postcards, letters, and checks directly from your CRM or customer data systems.
Address Verification corrects, standardizes, and cleanses address data for assured delivery with instant verification across 240+ countries and territories.
Lob's print delivery network eliminates the hassle of vendor management with automated production and postage across a global network of vetted commercial printers.
Tracking & Analytics gives you complete visibility of production and delivery for each piece of mail you send to meet compliance requirements and measure campaign performance.
[](https://docs.lob.com/#tag/Authentication)
Authentication
===========================================================
Requests made to the API are protected with [HTTP Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
. In order to properly authenticate with the API you must use your API key as the username while leaving the password blank. Requests not properly authenticated will return a `401` [error code](https://docs.lob.com/#tag/Errors)
. You can find your account's API keys in your [Dashboard Settings](https://dashboard.lob.com/settings/api-keys)
.
### Example Request
curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password). One of our test API keys has been filled into all the examples on the page, so you can test out any example right away.
curl https://api.lob.com/v1/addresses \
-u test_0dc8dXXXXXXXXXXXXXXXXXXXXXX5b0cc:
[](https://docs.lob.com/#tag/Authentication/API-Keys)
API Keys
--------------------------------------------------------------
Lob authenticates your API requests using your account's API keys. If you do not include your key when making an API request, or use one that is incorrect or outdated, Lob returns an error with a `401` HTTP response code. You can find all API keys in your dashboard under [Settings](https://dashboard.lob.com/settings/api-keys)
. There are two types of API keys: _secret_ and _publishable_.
* **Secret API keys** should be kept confidential and only stored on your own servers. Your account's secret API key can perform any API request to Lob without restriction.
* **Publishable API keys** are limited to US verifications, international verifications, and US autocomplete requests. For maximum security, we encourage you to not expose your secret key. You can include the publishable keys in JavaScript code or in an Android or iPhone app without exposing your Lob Print and Mail account services or your secret key. Publishable keys are always prefixed with `[environment]_pub`. Every type comes with a pair of keys: one for the testing environment and one for the live environment. We recommend reading [Test and Live Environments](https://docs.lob.com/#tag/Test-and-Live-Environments)
for more information.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Getting-Started)
Getting Started
=============================================================
### 1\. Get Setup
* Create an account at [Lob.com](https://dashboard.lob.com/#/register)
* Obtain your API keys in the Lob dashboard [settings](https://dashboard.lob.com/settings/api-keys)
* You'll use the format, `test_*.` for your Test API key and `live_*.` for your Live API key.
### 2\. Explore
* Try out in Postman:
Run in Postman
* Launch your terminal and copy/paste a CURL command.
curl https://api.lob.com/v1/addresses \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
* Download a [Lob SDK](https://docs.lob.com/#tag/SDKs-and-Tools)
into your favorite IDE (integrated development environment)
### 3\. Learn more
Try our quick start (TypeScript, Python, PHP, Java or Ruby):
* [Send your first Postcards](https://help.lob.com/developer-docs/quickstart-guide)
Use Case guides
* [Mass Deletion Setup](https://help.lob.com/developer-docs/use-case-guides/mass-deletion-setup)
* [NCOA Restrictions](https://help.lob.com/developer-docs/use-case-guides/ncoa-restrictions)
* [Override Cancellation Window](https://help.lob.com/developer-docs/use-case-guides/override-cancellation-window)
* [Visibility of Address Changes](https://help.lob.com/developer-docs/use-case-guides/visibility-of-address-changes)
* [Ingesting Tracking Events with Webhooks](https://help.lob.com/developer-docs/use-case-guides/ingesting-tracking-events-with-webhooks)
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/SDKs-and-Tools)
SDKs and Tools
===========================================================
Please visit our [Github](https://www.github.com/lob)
for a list of our supported libraries.
* [Typescript](https://github.com/lob/lob-typescript-sdk)
* [PHP](https://github.com/lob/lob-php)
* [Python](https://github.com/lob/lob-python)
* [Java](https://github.com/lob/lob-java)
* [Ruby](https://github.com/lob/lob-ruby/tree/main)
* [CSharp](https://github.com/lob/lob-dotnet)
* [Elixir](https://github.com/lob/lob-elixir)
* [Go](https://github.com/lob/lob-go)
* [Node.js (legacy)](https://github.com/lob/lob-node)
* [Java (legacy)](https://github.com/lob/lob-java/tree/12.3.7-Legacy)
* [PHP (legacy)](https://github.com/lob/lob-php/tree/v3-legacy)
* [Python (Legacy)](https://github.com/lob/lob-python/tree/legacy_v4)
* [Ruby (Legacy)](https://github.com/lob/lob-ruby/tree/legacy-v5)
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Addresses)
Addresses
=================================================
To add an address to your address book, you create a new address object. You can retrieve and delete individual addresses as well as get a list of addresses. Addresses are identified by a unique random ID.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Addresses/operation/addresses_list)
List
---------------------------------------------------------------------
Returns a list of your addresses. The addresses are returned sorted by creation date, with the most recently created addresses appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` addresses. Each entry in the array is a separate address object. The previous and next page of address entries can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more addresses are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address)
list of addresses |
**default**
Error
get/addresses
production
https://api.lob.com/v1/addresses
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/addresses?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "adr_e68217bd744d65c8", * "description": "Harry - Office", * "name": "HARRY ZHANG", * "company": "LOB", * "phone": "5555555555", * "email": "harry@lob.com", * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2019-08-12T00:16:00.361Z", * "date_modified": "2019-08-12T00:16:00.361Z", * "object": "address" }, * { * "id": "adr_asdi2y3riuasasoi", * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "phone": "5555555555", * "email": "harry@lob.com", * "metadata": { }, * "address_line1": "370 WATER ST", * "address_line2": "", * "address_city": "SUMMERSIDE", * "address_state": "PRINCE EDWARD ISLAND", * "address_zip": "C1N 1C4", * "address_country": "CANADA", * "date_created": "2019-09-20T00:14:00.361Z", * "date_modified": "2019-09-20T00:14:00.361Z", * "object": "address" } ], * "object": "list", * "next_url": "[https://api.lob.com/v1/addresses?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wN1QyMTo1OTo0Ni43NjRaIiwiaWRPZmZzZXQiOiJhZHJfODMwYmYwZWFiZGFhYTQwOSJ9](https://api.lob.com/v1/addresses?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wN1QyMTo1OTo0Ni43NjRaIiwiaWRPZmZzZXQiOiJhZHJfODMwYmYwZWFiZGFhYTQwOSJ9) ", * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Addresses/operation/address_create)
Create
-----------------------------------------------------------------------
Creates a new address given information
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
One of
address\_editable\_usaddress\_editable\_intl
Any of
address obj with \`name\` definedaddress obj with \`company\` defined
| | |
| --- | --- |
| name
required | string or null <= 40 characters
Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. |
| address\_line1
required | string <= 64 characters
The primary number, street name, and directional information. |
| address\_city
required | string <= 200 characters |
| address\_state
required | string^\[a-zA-Z\]{2}$
2 letter state short-name code |
| address\_zip
required | string^\\d{5}(-\\d{4})?$
Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`. |
| address\_line2 | string or null <= 64 characters
An optional field containing any information which can't fit into line 1. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| company | string or null (company) <= 40 characters
Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc). |
| phone | string or null <= 40 characters
Must be no longer than 40 characters. |
| email | string or null <= 100 characters
Must be no longer than 100 characters. |
| address\_country | string
Default: "US"
Value: "US" |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
### Responses
**200**
Echos the writable fields of a newly created address object.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
One of
address\_usaddress\_intl
Any of
address obj with \`name\` definedaddress obj with \`company\` defined
| | |
| --- | --- |
| name
required | string or null <= 40 characters
Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "address"
Value: "address"
Value is resource type. |
| id
required | string (adr\_id) ^adr\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `adr_`. |
| address\_line1
required | string <= 64 characters
The primary number, street name, and directional information. |
| address\_city
required | string <= 200 characters |
| address\_state
required | string^\[a-zA-Z\]{2}$
2 letter state short-name code |
| address\_zip
required | string^\\d{5}(-\\d{4})?$
Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| company | string or null <= 40 characters
Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc). |
| phone | string or null <= 40 characters
Must be no longer than 40 characters. |
| email | string or null <= 100 characters
Must be no longer than 100 characters. |
| address\_line2 | string or null <= 64 characters
An optional field containing any information which can't fit into line 1. |
| address\_country | string \= 13 characters
Value: "UNITED STATES"
Full name of country |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| recipient\_moved | boolean or null
Only returned for accounts on certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
. Value is `true` if the address was altered because the recipient filed for a [National Change of Address Linkage (NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
, `false` if the NCOALink check was run but no altered address was found, and `null` if the NCOALink check was not run. The NCOALink check does not happen for non-US addresses, for non-deliverable US addresses, or for addresses created before the NCOALink feature was added to your account. |
**default**
Error
post/addresses
production
https://api.lob.com/v1/addresses
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Example
full\_usncoa\_us\_testfull\_intlfull\_us
Copy
`{ * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107", * "address_country": "US" }`
### Response samples
* 200
* default
Content type
application/json
Example
full\_usfull\_intlncoa\_us\_livencoa\_us\_testfull\_us
Copy
Expand all Collapse all
`{ * "id": "adr_d3489cd64c791ab5", * "description": "Harry - Office", * "name": "HARRY ZHANG", * "company": "LOB", * "phone": "5555555555", * "email": "harry@lob.com", * "address_line1": "210 KING ST STE 6100", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "address" }`
[](https://docs.lob.com/#tag/Addresses/operation/address_retrieve)
Retrieve
---------------------------------------------------------------------------
Retrieves the details of an existing address. You need only supply the unique identifier that was returned upon address creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| adr\_id
required | string (adr\_id) ^adr\_\[a-zA-Z0-9\]+$
id of the address |
### Responses
**200**
Returns an address object if a valid identifier was provided.
##### Response Schema: application/json
One of
address\_usaddress\_intl
Any of
address obj with \`name\` definedaddress obj with \`company\` defined
| | |
| --- | --- |
| name
required | string or null <= 40 characters
Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "address"
Value: "address"
Value is resource type. |
| id
required | string (adr\_id) ^adr\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `adr_`. |
| address\_line1
required | string <= 64 characters
The primary number, street name, and directional information. |
| address\_city
required | string <= 200 characters |
| address\_state
required | string^\[a-zA-Z\]{2}$
2 letter state short-name code |
| address\_zip
required | string^\\d{5}(-\\d{4})?$
Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| company | string or null <= 40 characters
Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc). |
| phone | string or null <= 40 characters
Must be no longer than 40 characters. |
| email | string or null <= 100 characters
Must be no longer than 100 characters. |
| address\_line2 | string or null <= 64 characters
An optional field containing any information which can't fit into line 1. |
| address\_country | string \= 13 characters
Value: "UNITED STATES"
Full name of country |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| recipient\_moved | boolean or null
Only returned for accounts on certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
. Value is `true` if the address was altered because the recipient filed for a [National Change of Address Linkage (NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
, `false` if the NCOALink check was run but no altered address was found, and `null` if the NCOALink check was not run. The NCOALink check does not happen for non-US addresses, for non-deliverable US addresses, or for addresses created before the NCOALink feature was added to your account. |
**default**
Error
get/addresses/{adr\_id}
production
https://api.lob.com/v1/addresses/{adr\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl https://api.lob.com/v1/addresses/adr\_fa85158b26c3eb7c \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Example
address\_usaddress\_intladdress\_us
Copy
Expand all Collapse all
`{ * "id": "adr_e68217bd744d65c8", * "description": "Harry - Office", * "name": "HARRY ZHANG", * "company": "LOB", * "phone": "5555555555", * "email": "harry@lob.com", * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "recipient_moved": false, * "date_created": "2019-08-12T00:16:00.361Z", * "date_modified": "2019-08-12T00:16:00.361Z", * "object": "address" }`
[](https://docs.lob.com/#tag/Addresses/operation/address_delete)
Delete
-----------------------------------------------------------------------
Deletes the details of an existing address. You need only supply the unique identifier that was returned upon address creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| adr\_id
required | string (adr\_id) ^adr\_\[a-zA-Z0-9\]+$
id of the address |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (adr\_id) ^adr\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `adr_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/addresses/{adr\_id}
production
https://api.lob.com/v1/addresses/{adr\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/addresses/adr\_43769b47aed248c2 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "adr_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/National-Change-of-Address)
National Change of Address
===================================================================================
National Change of Address Linkage (NCOALink) is a service offered by the USPS, which allows individuals or businesses who have recently moved to have any mail forwarded from their previous address to their new address.
As a CASS-certified Address Verification Provider, Lob also offers NCOALink functionality to our Print & Mail customers. With the Lob NCOALink feature enabled, Postcards, Letters, Checks and Addresses can automatically be corrected to reflect an individual's or business's new address in the case that they have moved (only if they have registered for NCOALink with the USPS).
Due to privacy concerns and USPS constraints, for customers with NCOALink enabled, our API responses for a limited set of endpoints differ slightly in the case when an address has been changed through NCOALink.
**NOTE**: This feature is exclusive to certain customers. Upgrade to the appropriate [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
to gain access.
For more information, see our [NCOALink guide](https://help.lob.com/print-and-mail/all-about-addresses#national-change-of-address-ncoa-7)
.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/National-Change-of-Address/NCOALink-Live-Environment)
NCOALink Live Environment
------------------------------------------------------------------------------------------------------------
Though there are no changes to API requests, there are significant changes to our API responses, but only in the event that an address has been changed through NCOALink. If an address has not been changed through NCOALink, the response would be identical to our standard responses, except the addition of a `recipient_moved` field, which is `false` for unchanged addresses.
If an address has been changed through NCOALink, we are required to suppress the following response fields for that address:
* `address_line1`
* `address_line2`
* The +4 portion of the ZIP+4 (5-digit ZIP code will still be present)
See the `ncoa_us_live` example under [Response samples](https://docs.lob.com/#operation/address_create)
within the "Create an Address" section in Addresses
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/National-Change-of-Address/NCOALink-Test-Environment)
NCOALink Test Environment
------------------------------------------------------------------------------------------------------------
In addition to sending live requests, you may also want to simulate what an NCOALink response might look like so that you can ensure your application behaves as expected. The behavior of NCOALink in Lob's Test Environment is very similar to our [US Verifications Test Mode](https://docs.lob.com/#section/US-Verifications-Test-Env)
.
To simulate an NCOALink request, send a POST request to any of the four endpoints below with an `address_line1` field equal to `NCOA`:
* `POST /v1/addresses`
* `POST /v1/checks`
* `POST /v1/letters`
* `POST /v1/postcards`
* `POST /v1/self_mailers`
A static address will always be returned, as documented in the `ncoa_us_test` example under [Response samples](https://docs.lob.com/#operation/address_create)
within the "Create an Address" section in Addresses (along with the corresponding request under "Request samples").
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Postcards)
Postcards
=================================================
The postcards endpoint allows you to easily print and mail postcards. The API provides endpoints for creating postcards, retrieving individual postcards, canceling postcards, and retrieving a list of postcards.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Postcards/operation/postcard_retrieve)
Retrieve
----------------------------------------------------------------------------
Retrieves the details of an existing postcard. You need only supply the unique customer identifier that was returned upon postcard creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| psc\_id
required | string (psc\_id) ^psc\_\[a-zA-Z0-9\]+$
id of the postcard |
### Responses
**200**
Returns a postcard object
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (psc\_id) ^psc\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `psc_`. |
| front\_template\_id
required | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
| back\_template\_id
required | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (postcard\_size)
Default: "4x6"
Enum: "4x6" "6x9" "6x11"
Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| front\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
| back\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
| tracking\_events | Array of objects or null (tracking\_event\_normal)
An array of tracking\_event objects ordered by ascending `time`. Will not be populated for postcards created in test mode. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| use\_type | string or null (psc\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "postcard"
Value: "postcard"
Value is resource type. |
**default**
Error
get/postcards/{psc\_id}
production
https://api.lob.com/v1/postcards/{psc\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl https://api.lob.com/v1/postcards/psc\_5c002b86ce47537a \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Example
basicfullbasic
Copy
Expand all Collapse all
`{ * "id": "psc_208e45e48d271294", * "description": null, * "metadata": { }, * "to": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": null, * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "url": "[https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA](https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA) ", * "carrier": "USPS", * "front_template_id": null, * "back_template_id": null, * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "postcard" }`
[](https://docs.lob.com/#tag/Postcards/operation/postcard_delete)
Cancel
------------------------------------------------------------------------
Completely removes a postcard from production. This can only be done if the postcard has a `send_date` and the `send_date` has not yet passed. If the postcard is successfully canceled, you will not be charged for it. Read more on [cancellation windows](https://docs.lob.com/#section/Cancellation-Windows)
and [scheduling](https://docs.lob.com/#section/Scheduled-Mailings)
. Scheduling and cancellation is a premium feature. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| psc\_id
required | string (psc\_id) ^psc\_\[a-zA-Z0-9\]+$
id of the postcard |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (psc\_id) ^psc\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `psc_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/postcards/{psc\_id}
production
https://api.lob.com/v1/postcards/{psc\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/postcards/psc\_5c002b86ce47537a \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "psc_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/Postcards/operation/postcards_list)
List
---------------------------------------------------------------------
Returns a list of your postcards. The addresses are returned sorted by creation date, with the most recently created addresses appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Filters resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the render status:
* `processed` - the rendering process is currently underway.
* `rendered` - the rendering process has completed successfully.
* `failed` - the rendering process has failed. |
| size | Array of strings (postcard\_size)
Items Enum: "4x6" "6x9" "6x11"
Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations. |
| scheduled | boolean
* `true` - only return orders (past or future) where `send_date` is greater than `date_created`
* `false` - only return orders where `send_date` is equal to `date_created` |
| send\_date | string or string (send\_date)
Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type: \* `usps_first_class` - (default) \* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| sort\_by | object or object
Sorts items by ascending or descending dates. Use either `date_created` or `send_date`, not both. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` postcards. Each entry in the array is a separate postcard. The previous and next page of postcards can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more postcards are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (postcard)
list of postcards |
**default**
Error
get/postcards
production
https://api.lob.com/v1/postcards
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/postcards?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "psc_208e45e48d271294", * "description": null, * "metadata": { }, * "to": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "url": "[https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA](https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA) ", * "carrier": "USPS", * "front_template_id": null, * "back_template_id": null, * "front_template_version_id": null, * "back_template_version_id": null, * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "use_type": "marketing", * "fsc": false, * "object": "postcard" }, * { * "id": "psc_0e03d1ad7d31f151", * "description": null, * "metadata": { }, * "to": { * "id": "adr_c7cb63d68f8d6", * "description": null, * "name": "JANE DOE", * "company": "LOB", * "phone": "5555555555", * "email": "jane.doe@lob.com", * "address_line1": "370 WATER ST", * "address_line2": "", * "address_city": "SUMMERSIDE", * "address_state": "PE", * "address_zip": "C1N 1C4", * "address_country": "CANADA", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address", * "recipient_moved": false }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "url": "[https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA](https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA) ", * "carrier": "USPS", * "front_template_id": null, * "back_template_id": null, * "front_template_version_id": null, * "back_template_version_id": null, * "tracking_events": [ ], * "size": "6x11", * "mail_type": "usps_first_class", * "merge_variables": { }, * "thumbnails": [ * { * "small": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha) ", * "medium": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF) ", * "large": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW) " } ], * "expected_delivery_date": "2021-03-30", * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "use_type": "marketing", * "fsc": false, * "object": "postcard" } ], * "object": "list", * "previous_url": null, * "next_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Postcards/operation/postcard_create)
Create
------------------------------------------------------------------------
Creates a new postcard given information
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| idempotency\_key | string <= 256 characters
Example: idempotency\_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### header Parameters
| | |
| --- | --- |
| Idempotency-Key | string <= 256 characters
Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| to
required | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))))))
Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Depending on your [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
, US addresses may also be run through [National Change of Address Linkage(NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s [US Mail strictness setting](https://dashboard.lob.com/#/settings/account)
, the request will fail. [Lob Guide: Verification of Mailing Addresses](https://help.lob.com/print-and-mail/all-about-addresses) |
| front
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string) (psc\_front)
The artwork to use as the front of your postcard.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to the specified `size`.
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| back
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string) (psc\_back)
The artwork to use as the back of your postcard.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to the specified `size`.
* Be sure to leave room for address and postage information by following the templates provided here:
* [4x6 template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/4x6_postcard.pdf)
* [6x9 template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x9_postcard.pdf)
* [6x11 template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x11_postcard.pdf)
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| use\_type
required | string or null (psc\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (postcard\_size)
Default: "4x6"
Enum: "4x6" "6x9" "6x11"
Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations. |
| from | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))
_Required_ if `to` address is international. Must either be an address ID or an inline object with correct address parameters. Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| billing\_group\_id | string (billing\_group\_id)
An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See [Billing Group API](https://docs.lob.com/#tag/Billing-Groups)
for more information. |
| qr\_code | object (qr\_code)
Customize and place a QR code on the creative at the required position. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes. |
### Responses
**200**
Returns a postcard object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (psc\_id) ^psc\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `psc_`. |
| front\_template\_id
required | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
| back\_template\_id
required | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (postcard\_size)
Default: "4x6"
Enum: "4x6" "6x9" "6x11"
Specifies the size of the postcard. Only `4x6` postcards can be sent to international destinations. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| front\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
| back\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
| tracking\_events | Array of objects or null (tracking\_event\_normal)
An array of tracking\_event objects ordered by ascending `time`. Will not be populated for postcards created in test mode. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| use\_type | string or null (psc\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `4x6` or `A5` postcard sizes. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "postcard"
Value: "postcard"
Value is resource type. |
**default**
Error
post/postcards
production
https://api.lob.com/v1/postcards
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "demo", * "to": { * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107", * "address_country": "US" }, * "from": { * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107", * "address_country": "US" }, * "front": "tmpl_a1234dddg", * "back": "tmpl_a1234dddg", * "size": "6x9", * "mail_type": "usps_first_class", * "merge_variables": { * "name": "Harry" }, * "metadata": { * "spiffy": "true" }, * "send_date": "2017-11-01T00:00:00.000Z", * "use_type": "marketing", * "qr_code": { * "position": "relative", * "redirect_url": "[https://www.lob.com](https://www.lob.com/) ", * "width": "2.5", * "top": "2.5", * "right": "2.5", * "pages": "front,back" }, * "fsc": true, * "print_speed": "core" }`
### Response samples
* 200
* default
Content type
application/json
Example
basicfullbasic
Copy
Expand all Collapse all
`{ * "id": "psc_208e45e48d271294", * "description": null, * "metadata": { }, * "to": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": null, * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "url": "[https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA](https://lob-assets.com/postcards/psc_208e45e48d271294.pdf?version=v1&expires=1619218302&signature=NfHHLBSr5tOHA_Z4kij4dKqZG8f3vMDtwvuFVeeF9pV_lylcjLsVVODhNCE5hR6-2slUr6t9WMNsi429Pj7_DA) ", * "carrier": "USPS", * "front_template_id": null, * "back_template_id": null, * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "postcard" }`
[](https://docs.lob.com/#tag/Self-Mailers)
Self Mailers
=======================================================
The self mailer endpoint allows you to easily print and mail self mailers. The API provides endpoints for creating self mailers, retrieving individual self mailers, canceling self mailers, and retrieving a list of self mailers.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Self-Mailers/operation/self_mailer_retrieve)
Retrieve
----------------------------------------------------------------------------------
Retrieves the details of an existing self\_mailer. You need only supply the unique self\_mailer identifier that was returned upon self\_mailer creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| sfm\_id
required | string (sfm\_id) ^sfm\_\[a-zA-Z0-9\]+$
id of the self\_mailer |
### Responses
**200**
Returns a self\_mailer object
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (sfm\_id) ^sfm\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `sfm_`. |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| use\_type
required | string or null (sfm\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (self\_mailer\_size)
Default: "6x18\_bifold"
Enum: "6x18\_bifold" "11x9\_bifold" "12x9\_bifold" "17.75x9\_trifold"
Specifies the size of the self mailer. The `17.75x9_trifold` size is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| outside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the outside of the self mailer. |
| inside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the inside of the self mailer. |
| outside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the outside of the self mailer. |
| inside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the inside of the self mailer. |
| object | string
Default: "self\_mailer"
Value: "self\_mailer"
Value is resource type. |
| tracking\_events | Array of objects (tracking\_event\_certified)
An array of certified tracking events ordered by ascending `time`. Not populated in test mode. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `11x9_bifold` self-mailer size. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
**default**
Error
get/self\_mailers/{sfm\_id}
production
https://api.lob.com/v1/self\_mailers/{sfm\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/self\_mailers/sfm\_8ffbe811dea49dcf" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "sfm_8ffbe811dea49dcf", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_bae820679f3f536b", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "url": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " }, * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw) " } ], * "merge_variables": { * "name": null }, * "size": "6x18_bifold", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "self_mailer" }`
[](https://docs.lob.com/#tag/Self-Mailers/operation/self_mailer_delete)
Delete
------------------------------------------------------------------------------
Completely removes a self mailer from production. This can only be done if the self mailer's `send_date` has not yet passed. If the self mailer is successfully canceled, you will not be charged for it. This feature is exclusive to certain customers. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| sfm\_id
required | string (sfm\_id) ^sfm\_\[a-zA-Z0-9\]+$
id of the self\_mailer |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (sfm\_id) ^sfm\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `sfm_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/self\_mailers/{sfm\_id}
production
https://api.lob.com/v1/self\_mailers/{sfm\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/self\_mailers/sfm\_8ffbe811dea49dcf \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "sfm_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/Self-Mailers/operation/self_mailers_list)
List
---------------------------------------------------------------------------
Returns a list of your self\_mailers. The self\_mailers are returned sorted by creation date, with the most recently created self\_mailers appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
| size | Array of strings (self\_mailer\_size)
Items Enum: "6x18\_bifold" "11x9\_bifold" "12x9\_bifold" "17.75x9\_trifold"
The self mailer sizes to be returned. |
| scheduled | boolean
* `true` - only return orders (past or future) where `send_date` is greater than `date_created`
* `false` - only return orders where `send_date` is equal to `date_created` |
| send\_date | string or string (send\_date)
Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type: \* `usps_first_class` - (default) \* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| sort\_by | object or object
Sorts items by ascending or descending dates. Use either `date_created` or `send_date`, not both. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Filters resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the render status:
* `processed` - the rendering process is currently underway.
* `rendered` - the rendering process has completed successfully.
* `failed` - the rendering process has failed. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` self\_mailers. Each entry in the array is a separate self\_mailer. The previous and next page of self\_mailers can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more self\_mailers are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (self\_mailer)
list of self\_mailers |
**default**
Error
get/self\_mailers
production
https://api.lob.com/v1/self\_mailers
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/self\_mailers?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "sfm_7239rhwqkrfaskas", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_asdi2y3riuasasoi", * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "phone": "5555555555", * "email": "harry@lob.com", * "metadata": { }, * "address_line1": "370 WATER ST", * "address_line2": "", * "address_city": "SUMMERSIDE", * "address_state": "PRINCE EDWARD ISLAND", * "address_zip": "C1N 1C4", * "address_country": "CANADA", * "recipient_moved": false, * "date_created": "2019-09-20T00:14:00.361Z", * "date_modified": "2019-09-20T00:14:00.361Z", * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": null, * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "url": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618781264&signature=YP_bCwrgVA2lz1Gr1YVCJN1f-WspUGsH0aJp2ihjfLXU7lDUV12_xRv4uPch0mfWeOOxEqpyP8hGpgvjmQKNAw](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618781264&signature=YP_bCwrgVA2lz1Gr1YVCJN1f-WspUGsH0aJp2ihjfLXU7lDUV12_xRv4uPch0mfWeOOxEqpyP8hGpgvjmQKNAw) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618781264&signature=A7q5HbRO53sUYYnwGlmP5mTS6ylLE7kS2mYhfcEOdexjyqG7UseK0MD26DppE4Q0aE4u2msDVMxd5ukjMerYCg](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618781264&signature=A7q5HbRO53sUYYnwGlmP5mTS6ylLE7kS2mYhfcEOdexjyqG7UseK0MD26DppE4Q0aE4u2msDVMxd5ukjMerYCg) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618781264&signature=b9pynuawVpU_vrhnT_mTpksdE-FLF_ZjdIBOFR_ltIzEGlx-VKD4VvZrqP98lG2D8V7UKQ7SdRr2nUAk4LxvCg](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618781264&signature=b9pynuawVpU_vrhnT_mTpksdE-FLF_ZjdIBOFR_ltIzEGlx-VKD4VvZrqP98lG2D8V7UKQ7SdRr2nUAk4LxvCg) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618781264&signature=g2jifhCselPqIj8au6lsbJMNFN8ZX3aM6GkLoAXiHBCS8X5mF9nhVbmO0odpnmwNlV1CWIp-MXVsZkC3NmxqBQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618781264&signature=g2jifhCselPqIj8au6lsbJMNFN8ZX3aM6GkLoAXiHBCS8X5mF9nhVbmO0odpnmwNlV1CWIp-MXVsZkC3NmxqBQ) " }, * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618781264&signature=biJY4-ZbNNRydPYg3cZkq7wxjILbPBK_nIVyoyQsg5X5q4jlsa-2fzeMa48V9jprUetsC6WEuYvasHosRfG_DQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618781264&signature=biJY4-ZbNNRydPYg3cZkq7wxjILbPBK_nIVyoyQsg5X5q4jlsa-2fzeMa48V9jprUetsC6WEuYvasHosRfG_DQ) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618781264&signature=xEAX7bURyc8fSphacuo5yb7iVIpT8Xvq05KgMaNQS4r3aCpx0z1p42wbPmW758B5Ae0li1YDYvVyzS7qJIoWAw](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618781264&signature=xEAX7bURyc8fSphacuo5yb7iVIpT8Xvq05KgMaNQS4r3aCpx0z1p42wbPmW758B5Ae0li1YDYvVyzS7qJIoWAw) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618781264&signature=NieHDnoQ7STZUvofHrFt7S987CzIkUJWpaSgpVQPZw-C3_wwTPsIrvxYdXEuFrr6ciTUcxRBFPlE0lurmMkyCA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618781264&signature=NieHDnoQ7STZUvofHrFt7S987CzIkUJWpaSgpVQPZw-C3_wwTPsIrvxYdXEuFrr6ciTUcxRBFPlE0lurmMkyCA) " } ], * "merge_variables": { * "name": null }, * "size": "6x18_bifold", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:41:06.691Z", * "send_date": "2021-03-16T18:45:40.493Z", * "deleted": true, * "use_type": "marketing", * "fsc": false, * "object": "self_mailer" }, * { * "id": "sfm_8ffbe811dea49dcf", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_f9228b743884ff98", * "description": null, * "name": "AYA", * "company": null, * "phone": null, * "email": null, * "address_line1": "2812 PARK RD", * "address_line2": null, * "address_city": "CHARLOTTE", * "address_state": "NC", * "address_zip": "28209-1314", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2021-03-16T18:40:40.410Z", * "date_modified": "2021-03-16T18:40:40.410Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": null, * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "url": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618781264&signature=YP_bCwrgVA2lz1Gr1YVCJN1f-WspUGsH0aJp2ihjfLXU7lDUV12_xRv4uPch0mfWeOOxEqpyP8hGpgvjmQKNAw](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618781264&signature=YP_bCwrgVA2lz1Gr1YVCJN1f-WspUGsH0aJp2ihjfLXU7lDUV12_xRv4uPch0mfWeOOxEqpyP8hGpgvjmQKNAw) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618781264&signature=A7q5HbRO53sUYYnwGlmP5mTS6ylLE7kS2mYhfcEOdexjyqG7UseK0MD26DppE4Q0aE4u2msDVMxd5ukjMerYCg](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618781264&signature=A7q5HbRO53sUYYnwGlmP5mTS6ylLE7kS2mYhfcEOdexjyqG7UseK0MD26DppE4Q0aE4u2msDVMxd5ukjMerYCg) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618781264&signature=b9pynuawVpU_vrhnT_mTpksdE-FLF_ZjdIBOFR_ltIzEGlx-VKD4VvZrqP98lG2D8V7UKQ7SdRr2nUAk4LxvCg](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618781264&signature=b9pynuawVpU_vrhnT_mTpksdE-FLF_ZjdIBOFR_ltIzEGlx-VKD4VvZrqP98lG2D8V7UKQ7SdRr2nUAk4LxvCg) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618781264&signature=g2jifhCselPqIj8au6lsbJMNFN8ZX3aM6GkLoAXiHBCS8X5mF9nhVbmO0odpnmwNlV1CWIp-MXVsZkC3NmxqBQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618781264&signature=g2jifhCselPqIj8au6lsbJMNFN8ZX3aM6GkLoAXiHBCS8X5mF9nhVbmO0odpnmwNlV1CWIp-MXVsZkC3NmxqBQ) " }, * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618781264&signature=biJY4-ZbNNRydPYg3cZkq7wxjILbPBK_nIVyoyQsg5X5q4jlsa-2fzeMa48V9jprUetsC6WEuYvasHosRfG_DQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618781264&signature=biJY4-ZbNNRydPYg3cZkq7wxjILbPBK_nIVyoyQsg5X5q4jlsa-2fzeMa48V9jprUetsC6WEuYvasHosRfG_DQ) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618781264&signature=xEAX7bURyc8fSphacuo5yb7iVIpT8Xvq05KgMaNQS4r3aCpx0z1p42wbPmW758B5Ae0li1YDYvVyzS7qJIoWAw](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618781264&signature=xEAX7bURyc8fSphacuo5yb7iVIpT8Xvq05KgMaNQS4r3aCpx0z1p42wbPmW758B5Ae0li1YDYvVyzS7qJIoWAw) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618781264&signature=NieHDnoQ7STZUvofHrFt7S987CzIkUJWpaSgpVQPZw-C3_wwTPsIrvxYdXEuFrr6ciTUcxRBFPlE0lurmMkyCA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618781264&signature=NieHDnoQ7STZUvofHrFt7S987CzIkUJWpaSgpVQPZw-C3_wwTPsIrvxYdXEuFrr6ciTUcxRBFPlE0lurmMkyCA) " } ], * "merge_variables": { * "name": null }, * "size": "6x18_bifold", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:41:06.691Z", * "send_date": "2021-03-16T18:45:40.493Z", * "deleted": true, * "use_type": "marketing", * "fsc": true, * "object": "self_mailer" } ], * "object": "list", * "next_url": null, * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Self-Mailers/operation/self_mailer_create)
Create
------------------------------------------------------------------------------
Creates a new self\_mailer given information
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| idempotency\_key | string <= 256 characters
Example: idempotency\_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### header Parameters
| | |
| --- | --- |
| Idempotency-Key | string <= 256 characters
Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| to
required | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))))))
Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Depending on your [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
, US addresses may also be run through [National Change of Address Linkage(NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s [US Mail strictness setting](https://dashboard.lob.com/#/settings/account)
, the request will fail. [Lob Guide: Verification of Mailing Addresses](https://help.lob.com/print-and-mail/all-about-addresses) |
| inside
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string)
The artwork to use as the inside of your self mailer.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 6"x18" at 300 DPI, while supplied HTML will be rendered to the specified `size`.
* Be sure to leave room for address and postage information by following the templates provided here:
* [6x18 bifold template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/6x18_sfm_bifold_template.pdf)
* [12x9 bifold template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/12x9_sfm_bifold_template.pdf)
* [17.75x9 trifold template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/self_mailers/17_75x9_trifold_sfm_template.pdf)
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| outside
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string)
The artwork to use as the outside of your self mailer.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 6"x18" at 300 DPI, while supplied HTML will be rendered to the specified `size`.
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| use\_type
required | string or null (sfm\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (self\_mailer\_size)
Default: "6x18\_bifold"
Enum: "6x18\_bifold" "11x9\_bifold" "12x9\_bifold" "17.75x9\_trifold"
Specifies the size of the self mailer. The `17.75x9_trifold` size is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. |
| from | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))
_Required_ if `to` address is international. Must either be an address ID or an inline object with correct address parameters. Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| billing\_group\_id | string (billing\_group\_id)
An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See [Billing Group API](https://docs.lob.com/#tag/Billing-Groups)
for more information. |
| qr\_code | object (qr\_code)
Customize and place a QR code on the creative at the required position. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `11x9_bifold` self-mailer size. |
### Responses
**200**
Returns a self\_mailer object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (sfm\_id) ^sfm\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `sfm_`. |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| use\_type
required | string or null (sfm\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (self\_mailer\_size)
Default: "6x18\_bifold"
Enum: "6x18\_bifold" "11x9\_bifold" "12x9\_bifold" "17.75x9\_trifold"
Specifies the size of the self mailer. The `17.75x9_trifold` size is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| outside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the outside of the self mailer. |
| inside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the inside of the self mailer. |
| outside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the outside of the self mailer. |
| inside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the inside of the self mailer. |
| object | string
Default: "self\_mailer"
Value: "self\_mailer"
Value is resource type. |
| tracking\_events | Array of objects (tracking\_event\_certified)
An array of certified tracking events ordered by ascending `time`. Not populated in test mode. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `11x9_bifold` self-mailer size. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
**default**
Error
post/self\_mailers
production
https://api.lob.com/v1/self\_mailers
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "Demo Self Mailer job", * "to": "adr_bae820679f3f536b", * "from": "adr_210a8d4b0b76d77b", * "inside": "[https://lob.com/selfmailerinside.pdf](https://lob.com/selfmailerinside.pdf) ", * "outside": "[https://lob.com/selfmaileroutside.pdf](https://lob.com/selfmaileroutside.pdf) ", * "size": "12x9_bifold", * "metadata": { * "spiffy": "true" }, * "mail_type": "usps_standard", * "merge_variables": { * "name": "Harry" }, * "send_date": "2017-11-01T00:00:00.000Z", * "use_type": "marketing", * "qr_code": { * "position": "relative", * "redirect_url": "[https://www.lob.com](https://www.lob.com/) ", * "width": "2.5", * "top": "2.5", * "right": "2.5", * "pages": "inside,outside" }, * "fsc": true, * "print_speed": "core" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "sfm_8ffbe811dea49dcf", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_bae820679f3f536b", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "url": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " }, * { * "small": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ) ", * "medium": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA) ", * "large": "[https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw](https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw) " } ], * "merge_variables": { * "name": null }, * "size": "6x18_bifold", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "self_mailer" }`
[](https://docs.lob.com/#tag/Letters)
Letters
=============================================
The letters endpoint allows you to easily print and mail letters. The API provides endpoints for creating letters, retrieving individual letters, canceling letters, and retrieving a list of letters.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Letters/operation/letter_retrieve)
Retrieve
------------------------------------------------------------------------
Retrieves the details of an existing letter. You need only supply the unique letter identifier that was returned upon letter creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| ltr\_id
required | string (ltr\_id) ^ltr\_\[a-zA-Z0-9\]+$
id of the letter |
### Responses
**200**
Returns a letter object
##### Response Schema: application/json
One of
regularregisteredcertified
| | |
| --- | --- |
| color
required | boolean (color)
Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white. |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (ltr\_id) ^ltr\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `ltr_`. |
| from
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| use\_type
required | string or null (ltr\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| tracking\_events | Array of objects (tracking\_event\_normal)
An array of tracking events ordered by ascending `time`. |
| cards | Array of objects or null (card)
An array of cards associated with a specific letter |
| buckslips | Array of objects or null (buckslip)
An array of buckslip(s) associated with a specific letter |
| return\_address | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))))))) (return\_address)
Specifies the address the return envelope will be sent back to. This is an optional argument that is available if an account is signed up for the return envelope tracking beta, and has `return_envelope`, and `perforated_page` fields populated in the API request. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| double\_sided | boolean (double\_sided)
Default: true
Set this attribute to `true` for double sided printing, or `false` for for single sided printing. Defaults to `true`. |
| address\_placement | string (address\_placement)
Default: "top\_first\_page"
Enum: "top\_first\_page" "insert\_blank\_page" "bottom\_first\_page\_center" "bottom\_first\_page"
Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template. Some values are exclusive to certain customers. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
* `top_first_page` - (default) print address information at the top of your provided first page
* `insert_blank_page` - insert a blank address page at the beginning of your file (you will be charged for the extra page)
* `bottom_first_page_center` - **(exclusive, deprecation planned within a few months)** print address information at the bottom center of your provided first page
* `bottom_first_page` - **(exclusive)** print address information at the bottom of your provided first page |
| return\_envelope | boolean or object (return\_envelope\_returned) |
| perforated\_page | integer or null
Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our [perforation guide](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf)
. |
| custom\_envelope | object or null (custom\_envelope\_returned)
A nested custom envelope object containing more information about the custom envelope used or `null` if a custom envelope was not used. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| url | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the letter. |
| template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the letter. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `A4` letter size. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "letter"
Value: "letter"
Value is resource type. |
**default**
Error
get/letters/{ltr\_id}
production
https://api.lob.com/v1/letters/{ltr\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl https://api.lob.com/v1/letters/ltr\_4868c3b754655f90 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "ltr_4868c3b754655f90", * "description": "Demo Letter", * "metadata": { }, * "to": { * "id": "adr_d3489cd64c791ab5", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_b8fb5acf3a2b55db", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "color": true, * "double_sided": true, * "address_placement": "top_first_page", * "return_envelope": false, * "perforated_page": null, * "custom_envelope": null, * "extra_service": null, * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=8r94fse8uam7wGWmW5baxXulU88X2CA](https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=8r94fse8uam7wGWmW5baxXulU88X2CA) ", * "carrier": "USPS", * "tracking_number": null, * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha) ", * "medium": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF) ", * "large": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW) " } ], * "merge_variables": { * "name": "Harry" }, * "expected_delivery_date": "2017-09-12", * "date_created": "2017-09-05T15:54:53.346Z", * "date_modified": "2017-09-05T15:54:53.346Z", * "send_date": "2017-09-05T15:54:53.346Z", * "cards": [ * { * "id": "card_c51ae96f5cebf3e", * "account_id": "fa9ea650fc7b31a89f92", * "description": null, * "url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "2.125x3.375", * "auto_reorder": false, * "reorder_quantity": null, * "raw_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 10000, * "pending_quantity": 0, * "countries": null, * "status": "rendered", * "mode": "test", * "orientation": "horizontal", * "threshold_amount": 0, * "date_created": "2017-08-05T15:54:53.346Z", * "date_modified": "2017-08-05T15:54:53.346Z", * "object": "card" } ], * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "letter" }`
[](https://docs.lob.com/#tag/Letters/operation/letter_cancel)
Cancel
--------------------------------------------------------------------
Completely removes a letter from production. This can only be done if the letter has a `send_date` and the `send_date` has not yet passed. If the letter is successfully canceled, you will not be charged for it. Read more on [cancellation windows](https://docs.lob.com/#section/Cancellation-Windows)
and [scheduling](https://docs.lob.com/#section/Scheduled-Mailings)
. Scheduling and cancellation is a premium feature. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| ltr\_id
required | string (ltr\_id) ^ltr\_\[a-zA-Z0-9\]+$
id of the letter |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (ltr\_id) ^ltr\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `ltr_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/letters/{ltr\_id}
production
https://api.lob.com/v1/letters/{ltr\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/letters/ltr\_4868c3b754655f90 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "ltr_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/Letters/operation/letters_list)
List
-----------------------------------------------------------------
Returns a list of your letters. The letters are returned sorted by creation date, with the most recently created letters appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Filters resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the render status:
* `processed` - the rendering process is currently underway.
* `rendered` - the rendering process has completed successfully.
* `failed` - the rendering process has failed. |
| color | boolean
Set to `true` to return only color letters. Set to `false` to return only black & white letters. |
| scheduled | boolean
* `true` - only return orders (past or future) where `send_date` is greater than `date_created`
* `false` - only return orders where `send_date` is equal to `date_created` |
| send\_date | string or string (send\_date)
Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type: \* `usps_first_class` - (default) \* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| sort\_by | object or object
Sorts items by ascending or descending dates. Use either `date_created` or `send_date`, not both. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` letters. Each entry in the array is a separate letter. The previous and next page of letters can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively. If no more letters are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of regular (object) or registered (object) or certified (object) (letter)
list of letters |
**default**
Error
get/letters
production
https://api.lob.com/v1/letters
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/letters?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "ltr_5ba44b462c79f07c", * "description": "Demo Letter", * "metadata": { }, * "to": { * "id": "adr_asdi2y3riuasasoi", * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "phone": "5555555555", * "email": "harry@lob.com", * "metadata": { }, * "address_line1": "370 WATER ST", * "address_line2": "", * "address_city": "SUMMERSIDE", * "address_state": "PRINCE EDWARD ISLAND", * "address_zip": "C1N 1C4", * "address_country": "CANADA", * "recipient_moved": false, * "date_created": "2019-09-20T00:14:00.361Z", * "date_modified": "2019-09-20T00:14:00.361Z", * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "color": true, * "double_sided": false, * "address_placement": "top_first_page", * "return_envelope": false, * "perforated_page": null, * "extra_service": "certified", * "custom_envelope": null, * "template_id": "tmpl_a", * "template_version_id": "vrsn_a", * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/letters/ltr_5ba44b462c79f07c.pdf?version=v1&expires=1568239830&signature=Ob-DUPLJLM4scWQeCDNadPJ4j33MZw16pykOxwv2us-bA7utTYi6oZ8WrEtBYDBBo09XkapR3gdJf0NEr90xAA](https://lob-assets.com/letters/ltr_5ba44b462c79f07c.pdf?version=v1&expires=1568239830&signature=Ob-DUPLJLM4scWQeCDNadPJ4j33MZw16pykOxwv2us-bA7utTYi6oZ8WrEtBYDBBo09XkapR3gdJf0NEr90xAA) ", * "merge_variables": null, * "carrier": "USPS", * "tracking_number": "92071902358909000011275538", * "tracking_events": [ * { * "id": "evnt_9e84094c9368cfb", * "type": "certified", * "name": "Delivered", * "details": { * "event": "delivered", * "description": "Package has been delivered.", * "notes": "Delivered, Front Desk/Reception/Mail Room", * "action_required": false }, * "location": "33408", * "time": "2019-10-08T19:41:00Z", * "date_created": "2019-10-08T19:41:00Z", * "date_modified": "2019-10-08T19:41:00Z", * "object": "tracking_event" } ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_small_1.png?version=v1&expires=1568239830&signature=xZUmE8rq8wSECHPEb9c37cUDZBzGUO3XK5LsIPZhI6dOXgm6zJEn8_7tKuZ3JWBmvNJNXdTl_ufkNu4avjQUDw](https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_small_1.png?version=v1&expires=1568239830&signature=xZUmE8rq8wSECHPEb9c37cUDZBzGUO3XK5LsIPZhI6dOXgm6zJEn8_7tKuZ3JWBmvNJNXdTl_ufkNu4avjQUDw) ", * "medium": "[https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_medium_1.png?version=v1&expires=1568239830&signature=H7354Qpcm9S4aXbrMsBe6QJ6lSNi9IWPgMJtLWLi4Kyx9tHF8Mp9YEc_IL9x89Jfw4-yRzKDXA410X4W0PssBQ](https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_medium_1.png?version=v1&expires=1568239830&signature=H7354Qpcm9S4aXbrMsBe6QJ6lSNi9IWPgMJtLWLi4Kyx9tHF8Mp9YEc_IL9x89Jfw4-yRzKDXA410X4W0PssBQ) ", * "large": "[https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_large_1.png?version=v1&expires=1568239830&signature=54LUIDKZyItA9pnC87d1pJVAuw8bhKLCsMpNWkB3LgdVWxPxxb_c1IyIWAbSR-dyOYEOlDBCc40J4Kns-O_mAg](https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_large_1.png?version=v1&expires=1568239830&signature=54LUIDKZyItA9pnC87d1pJVAuw8bhKLCsMpNWkB3LgdVWxPxxb_c1IyIWAbSR-dyOYEOlDBCc40J4Kns-O_mAg) " } ], * "expected_delivery_date": "2019-08-16", * "date_created": "2019-08-08T17:09:14.514Z", * "date_modified": "2019-08-08T17:09:16.850Z", * "send_date": "2019-08-08", * "use_type": "marketing", * "fsc": false, * "object": "letter" }, * { * "id": "ltr_da8267c6a6545cd6", * "description": "Demo Letter", * "metadata": { }, * "to": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "color": true, * "double_sided": false, * "address_placement": "top_first_page", * "return_envelope": false, * "perforated_page": null, * "extra_service": null, * "custom_envelope": null, * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/letters/ltr_da8267c6a6545cd6.pdf?version=v1&expires=1568239830&signature=HH-5RnbD4x0eJcnEC9HhqKSvQGsbkjovzvqSKgBijUHKIXwEKQJ4CbYhKs_U2q2A1k20Xefcaw7bfdPKozuqCQ](https://lob-assets.com/letters/ltr_da8267c6a6545cd6.pdf?version=v1&expires=1568239830&signature=HH-5RnbD4x0eJcnEC9HhqKSvQGsbkjovzvqSKgBijUHKIXwEKQJ4CbYhKs_U2q2A1k20Xefcaw7bfdPKozuqCQ) ", * "merge_variables": null, * "carrier": "USPS", * "tracking_number": null, * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_small_1.png?version=v1&expires=1568239830&signature=C1Rs83187HpWGhsg_pJIOhDIKlDtC_IgBBxHiocCEzJ8CncJwqrq5yHke-p97Dv7o81G_pfhFmirai589O6DCw](https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_small_1.png?version=v1&expires=1568239830&signature=C1Rs83187HpWGhsg_pJIOhDIKlDtC_IgBBxHiocCEzJ8CncJwqrq5yHke-p97Dv7o81G_pfhFmirai589O6DCw) ", * "medium": "[https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_medium_1.png?version=v1&expires=1568239830&signature=gz63l0yi3sK_sXjYfIVdLSvkknJFr_O5TWRulo_iKIgS-PosIl6J0tDR6bx_Tv5Ab_w7DABg3qdKZ846MZ7TCw](https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_medium_1.png?version=v1&expires=1568239830&signature=gz63l0yi3sK_sXjYfIVdLSvkknJFr_O5TWRulo_iKIgS-PosIl6J0tDR6bx_Tv5Ab_w7DABg3qdKZ846MZ7TCw) ", * "large": "[https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_large_1.png?version=v1&expires=1568239830&signature=4Y1OIymaWkSO3aBIHCeshFAVnF-pDcF2FFqkx_jovaUFuk4FT1SI24L7_POwTRXQHlETMGlzkP_CGgqselRUAA](https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_large_1.png?version=v1&expires=1568239830&signature=4Y1OIymaWkSO3aBIHCeshFAVnF-pDcF2FFqkx_jovaUFuk4FT1SI24L7_POwTRXQHlETMGlzkP_CGgqselRUAA) " } ], * "expected_delivery_date": "2019-08-16", * "date_created": "2019-08-08T17:08:12.224Z", * "date_modified": "2019-08-08T17:08:13.990Z", * "send_date": "2019-08-08T17:08:12.224Z", * "cards": null, * "use_type": "marketing", * "fsc": true, * "object": "letter" } ], * "object": "list", * "next_url": "[https://api.lob.com/v1/letters?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wOFQxNzowODoxMi4yMjRaIiwiaWRPZmZzZXQiOiJsdHJfZGE4MjY3YzZhNjU0NWNkNiJ9](https://api.lob.com/v1/letters?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wOFQxNzowODoxMi4yMjRaIiwiaWRPZmZzZXQiOiJsdHJfZGE4MjY3YzZhNjU0NWNkNiJ9) ", * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Letters/operation/letter_create)
Create
--------------------------------------------------------------------
Creates a new letter given information
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| idempotency\_key | string <= 256 characters
Example: idempotency\_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### header Parameters
| | |
| --- | --- |
| Idempotency-Key | string <= 256 characters
Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
| Lob-Version | string^\[0-9\]{4}-\[0-9\]{2}-\[0-9\]{2}$
Example: 2024-01-01
A string representing the version of the API being used. Specifically for letters, if this header is set to `2024-01-01` and above, the `size` property is automatically included with the default value of `us_letter`. Refer to `size` for all possible values. For more information on versioning, refer to our [Versioning and Changelog](https://docs.lob.com/#tag/Versioning-and-Changelog)
documentation. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| to
required | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))))))
Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Depending on your [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
, US addresses may also be run through [National Change of Address Linkage(NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s [US Mail strictness setting](https://dashboard.lob.com/#/settings/account)
, the request will fail. [Lob Guide: Verification of Mailing Addresses](https://help.lob.com/print-and-mail/all-about-addresses) |
| from
required | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))))))
Must either be an address ID or an inline object with correct address parameters. Must be a US address unless using a `custom_envelope`. All addresses will be standardized into uppercase without being modified by verification. |
| file
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or string (ltr\_file)
Notes:
* HTML merge variables should not include delimiting whitespace.
* All pages of a supplied PDF file must be sized at 8.5"x11", while supplied HTML will be rendered and trimmed to as many 8.5"x11" pages as necessary.
* For design specifications, please see our [PDF](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_template.pdf)
and [HTML](https://docs.lob.com/#section/HTML-Examples)
templates.
* If a `custom_envelope` is used, follow [this template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_custom_envelope.pdf)
.
* For domestic destinations, the file limit is 60 pages single-sided or 120 pages double-sided. For international destinations, the file limit is 6 pages single-sided or 12 pages double-sided. PDFs that surpass the file limit will error, while HTML that renders more pages than the file limit will be trimmed.
* Any letters over 6 pages single-sided or 12 pages double-sided will be placed in a [flat envelope](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_flat_template.pdf)
instead of the standard double window envelope.
See [pricing](https://lob.com/pricing/print-mail#compare)
for extra costs incurred. |
| color
required | boolean
Default: false
Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white. |
| use\_type
required | string or null (ltr\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| extra\_service | string or null (extra\_service)
Enum: "certified" "certified\_return\_receipt" "registered" null
Add an extra service to your letter. Can only be non-`null` if `mail_type` isn't `usps_standard`. See [pricing](https://www.lob.com/pricing/print-mail#compare)
for extra costs incurred.
* `certified` - track and confirm delivery for domestic destinations. An extra sheet (1 PDF page single-sided or 2 PDF pages double-sided) is added to the beginning of your letter for address and barcode information. See here for templates: [#10 envelope](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_template.pdf)
and [flat envelope](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_certified_flat_template.pdf)
(used for letters over 6 pages single-sided or 12 pages double-sided). You will not be charged for this extra sheet.
* `certified_return_receipt` - request an electronic copy of the recipient's signature to prove delivery of your certified letter
* `registered` - provides tracking and confirmation for international addresses
Not available for `us_legal` letter size. |
| cards | Array of strings or null (card\_id) \[ 0 .. 1 \] items
A single-element array containing an existing card id in a string format. See [cards](https://docs.lob.com/#tag/Cards)
for more information. Not available for `us_legal` letter size. |
| double\_sided | boolean (double\_sided)
Default: true
Set this attribute to `true` for double sided printing, or `false` for for single sided printing. Defaults to `true`. |
| address\_placement | string (address\_placement)
Default: "top\_first\_page"
Enum: "top\_first\_page" "insert\_blank\_page" "bottom\_first\_page\_center" "bottom\_first\_page"
Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template. Some values are exclusive to certain customers. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
* `top_first_page` - (default) print address information at the top of your provided first page
* `insert_blank_page` - insert a blank address page at the beginning of your file (you will be charged for the extra page)
* `bottom_first_page_center` - **(exclusive, deprecation planned within a few months)** print address information at the bottom center of your provided first page
* `bottom_first_page` - **(exclusive)** print address information at the bottom of your provided first page |
| return\_envelope | boolean or string (return\_envelope\_user\_provided)
Default: false
Indicates if a return envelope is requested for the letter. The value corresponding to this field is by default a boolean. But if the account is signed up for custom return envelopes, the value is of type string and is `no_9_single_window` for a standard return envelope and a custom `return_envelope_id` for non-standard return envelopes.
To include a return envelope with your letter, set to `true` and specify the `perforated_page`. See [pricing](https://www.lob.com/pricing/print-mail#compare)
for extra costs incurred. |
| perforated\_page | integer or null
Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our [perforation guide](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf)
. |
| custom\_envelope | string or null (user\_provided) ^env\_\[a-zA-Z0-9\]+$
Accepts an envelope ID for any customized envelope with available inventory. If no inventory is available for the specified ID, the letter will not be sent, and an error will be returned. If the letter has more than 6 sheets, it will be sent in a blank flat envelope. Custom envelopes may be created and ordered from the dashboard. This feature is exclusive to certain customers. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access. |
| billing\_group\_id | string (billing\_group\_id)
An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See [Billing Group API](https://docs.lob.com/#tag/Billing-Groups)
for more information. |
| qr\_code | object (qr\_code)
Customize and place a QR code on the creative at the required position. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `A4` and `us_legal` letter size. |
| size | string (ltr\_size)
Default: "us\_letter"
Enum: "us\_letter" "us\_legal"
Specifies the size of the letter. It accepts two values `us_letter` and `us_legal`. If the [Lob-Version header](https://docs.lob.com/#tag/Versioning-and-Changelog)
in the request is set to `2024-01-01` and above, the `size` property is automatically included with the default value of `us_letter`, unless explicitly specified.
Please note that attempting to include the `size` property in the request with the `Lob-Version` header predating to `2024-01-01` will result in an error. |
### Responses
**200**
Returns a letter object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
One of
regularregisteredcertified
| | |
| --- | --- |
| color
required | boolean (color)
Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white. |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (ltr\_id) ^ltr\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `ltr_`. |
| from
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| use\_type
required | string or null (ltr\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| tracking\_events | Array of objects (tracking\_event\_normal)
An array of tracking events ordered by ascending `time`. |
| cards | Array of objects or null (card)
An array of cards associated with a specific letter |
| buckslips | Array of objects or null (buckslip)
An array of buckslip(s) associated with a specific letter |
| return\_address | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))))))) (return\_address)
Specifies the address the return envelope will be sent back to. This is an optional argument that is available if an account is signed up for the return envelope tracking beta, and has `return_envelope`, and `perforated_page` fields populated in the API request. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| double\_sided | boolean (double\_sided)
Default: true
Set this attribute to `true` for double sided printing, or `false` for for single sided printing. Defaults to `true`. |
| address\_placement | string (address\_placement)
Default: "top\_first\_page"
Enum: "top\_first\_page" "insert\_blank\_page" "bottom\_first\_page\_center" "bottom\_first\_page"
Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template. Some values are exclusive to certain customers. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
* `top_first_page` - (default) print address information at the top of your provided first page
* `insert_blank_page` - insert a blank address page at the beginning of your file (you will be charged for the extra page)
* `bottom_first_page_center` - **(exclusive, deprecation planned within a few months)** print address information at the bottom center of your provided first page
* `bottom_first_page` - **(exclusive)** print address information at the bottom of your provided first page |
| return\_envelope | boolean or object (return\_envelope\_returned) |
| perforated\_page | integer or null
Required if `return_envelope` is `true`. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to `1`. The blank page added by `address_placement=insert_blank_page` will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our [perforation guide](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_perf_template.pdf)
. |
| custom\_envelope | object or null (custom\_envelope\_returned)
A nested custom envelope object containing more information about the custom envelope used or `null` if a custom envelope was not used. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| url | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the letter. |
| template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the letter. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `A4` letter size. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "letter"
Value: "letter"
Value is resource type. |
**default**
Error
post/letters
production
https://api.lob.com/v1/letters
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "demo", * "to": { * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107", * "address_country": "US" }, * "from": { * "name": "Harry", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107" }, * "file": "HTML Letter for {{name}}", * "color": true, * "cards": [ * "card_c51ae96f5cebf3e" ], * "double_sided": false, * "address_placement": "bottom_first_page", * "mail_type": "usps_first_class", * "return_envelope": true, * "perforated_page": 1, * "merge_variables": { * "name": "Harry" }, * "metadata": { * "spiffy": "true" }, * "send_date": "2017-11-01T00:00:00.000Z", * "extra_service": "registered", * "custom_envelope": null, * "use_type": "marketing", * "qr_code": { * "position": "relative", * "redirect_url": "[https://www.lob.com](https://www.lob.com/) ", * "width": "2", * "top": "2", * "right": "2", * "pages": "1-2,4-5" }, * "fsc": true, * "print_speed": "core" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "ltr_4868c3b754655f90", * "description": "Demo Letter", * "metadata": { }, * "to": { * "id": "adr_d3489cd64c791ab5", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_b8fb5acf3a2b55db", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "color": true, * "double_sided": true, * "address_placement": "top_first_page", * "return_envelope": false, * "perforated_page": null, * "custom_envelope": null, * "extra_service": null, * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=8r94fse8uam7wGWmW5baxXulU88X2CA](https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=8r94fse8uam7wGWmW5baxXulU88X2CA) ", * "carrier": "USPS", * "tracking_number": null, * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha) ", * "medium": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF) ", * "large": "[https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW](https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW) " } ], * "merge_variables": { * "name": "Harry" }, * "expected_delivery_date": "2017-09-12", * "date_created": "2017-09-05T15:54:53.346Z", * "date_modified": "2017-09-05T15:54:53.346Z", * "send_date": "2017-09-05T15:54:53.346Z", * "cards": [ * { * "id": "card_c51ae96f5cebf3e", * "account_id": "fa9ea650fc7b31a89f92", * "description": null, * "url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "2.125x3.375", * "auto_reorder": false, * "reorder_quantity": null, * "raw_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 10000, * "pending_quantity": 0, * "countries": null, * "status": "rendered", * "mode": "test", * "orientation": "horizontal", * "threshold_amount": 0, * "date_created": "2017-08-05T15:54:53.346Z", * "date_modified": "2017-08-05T15:54:53.346Z", * "object": "card" } ], * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "letter" }`
[](https://docs.lob.com/#tag/Checks)
Checks
===========================================
Checks allow you to send payments via physical checks. The API provides endpoints for creating checks, retrieving individual checks, canceling checks, and retrieving a list of checks.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Checks/operation/checks_list)
List
---------------------------------------------------------------
Returns a list of your checks. The checks are returned sorted by creation date, with the most recently created checks appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
| scheduled | boolean
* `true` - only return orders (past or future) where `send_date` is greater than `date_created`
* `false` - only return orders where `send_date` is equal to `date_created` |
| send\_date | string or string (send\_date)
Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type: \* `usps_first_class` - (default) \* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| sort\_by | object or object
Sorts items by ascending or descending dates. Use either `date_created` or `send_date`, not both. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the render status:
* `processed` - the rendering process is currently underway.
* `rendered` - the rendering process has completed successfully.
* `failed` - the rendering process has failed. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` checks. Each entry in the array is a separate check. The previous and next page of checks can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more checks are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (check)
list of checks |
**default**
Error
get/checks
production
https://api.lob.com/v1/checks
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/checks?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "chk_0176bf6197100185", * "description": "Demo Check", * "metadata": { }, * "check_number": 12559, * "memo": "rent", * "amount": 22.5, * "url": "[https://lob-assets.com/checks/chk_0176bf6197100185.pdf?version=v1&expires=1568239682&signature=aqKV5lmg_ktxzyl-qEwIf8-7DbvcguLO0LrfFcyMrUDDt6hxX_da0MEEpElxKR876VUaZrpHq_i_ayDWrsK3BA](https://lob-assets.com/checks/chk_0176bf6197100185.pdf?version=v1&expires=1568239682&signature=aqKV5lmg_ktxzyl-qEwIf8-7DbvcguLO0LrfFcyMrUDDt6hxX_da0MEEpElxKR876VUaZrpHq_i_ayDWrsK3BA) ", * "to": { * "id": "adr_bae820679f3f536b", * "description": "Harry - Office", * "name": "HARRY ZHANG", * "company": "LOB", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 KING ST STE 6100", * "address_line2": "", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:08:43.446Z", * "date_modified": "2018-12-08T03:08:43.446Z", * "object": "address", * "recipient_moved": false }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "name": "LEORE AVIDAR", * "address_line1": "210 KING ST STE 6100", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "bank_account": { * "id": "bank_8cad8df5354d33f", * "description": "Test Bank Account", * "metadata": { }, * "routing_number": "322271627", * "account_number": "123456789", * "account_type": "individual", * "signatory": "John Doe", * "bank_name": "J.P. MORGAN CHASE BANK, N.A.", * "verified": true, * "date_created": "2015-11-06T19:24:24.440Z", * "date_modified": "2015-11-06T19:41:28.312Z", * "object": "bank_account", * "signature_url": "[https://lob-assets.com/bank-accounts/asd_asdfghjkqwertyui.pdf?expires=1234567890&signature=aksdf](https://lob-assets.com/bank-accounts/asd_asdfghjkqwertyui.pdf?expires=1234567890&signature=aksdf) " }, * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/checks/chk_0176bf6197100185_thumb_small_1.png?version=v1&expires=1568239682&signature=T8DfMm_mxJJzIPgm8I0lvYY4Z6I8aFjsGsrEAicEqw8Ei_FaOtiGQKGeY16rdugAt8lmS_iX0lveBoG2RgWDDw](https://lob-assets.com/checks/chk_0176bf6197100185_thumb_small_1.png?version=v1&expires=1568239682&signature=T8DfMm_mxJJzIPgm8I0lvYY4Z6I8aFjsGsrEAicEqw8Ei_FaOtiGQKGeY16rdugAt8lmS_iX0lveBoG2RgWDDw) ", * "medium": "[https://lob-assets.com/checks/chk_0176bf6197100185_thumb_medium_1.png?version=v1&expires=1568239682&signature=-iJD7C58xOCD8eQ01StqSlw9WbDymL0Ygze9twfTs9s17zQppr2Zx363_Z4bP3ATHNhF3osjHuAxIasI2Wf6DQ](https://lob-assets.com/checks/chk_0176bf6197100185_thumb_medium_1.png?version=v1&expires=1568239682&signature=-iJD7C58xOCD8eQ01StqSlw9WbDymL0Ygze9twfTs9s17zQppr2Zx363_Z4bP3ATHNhF3osjHuAxIasI2Wf6DQ) ", * "large": "[https://lob-assets.com/checks/chk_0176bf6197100185_thumb_large_1.png?version=v1&expires=1568239682&signature=VJlOkVDPKZThstdd632r3Grm2WhoyPkC-pffpcePTw1i1NkpAObDSRaItKMOQgeWkAcUud3SH0tYcVOadaNiCw](https://lob-assets.com/checks/chk_0176bf6197100185_thumb_large_1.png?version=v1&expires=1568239682&signature=VJlOkVDPKZThstdd632r3Grm2WhoyPkC-pffpcePTw1i1NkpAObDSRaItKMOQgeWkAcUud3SH0tYcVOadaNiCw) " }, * { * "small": "[https://lob-assets.com/checks/chk_0176bf6197100185_thumb_small_2.png?version=v1&expires=1568239682&signature=XpCkOjy2zIKXkuc0s-UAYGNwpD_pgt7c9FKTDUCYbyqXupAg1MV1l2tdqevr0L0LT5FJqrGZH9khD5QRMQTkAA](https://lob-assets.com/checks/chk_0176bf6197100185_thumb_small_2.png?version=v1&expires=1568239682&signature=XpCkOjy2zIKXkuc0s-UAYGNwpD_pgt7c9FKTDUCYbyqXupAg1MV1l2tdqevr0L0LT5FJqrGZH9khD5QRMQTkAA) ", * "medium": "[https://lob-assets.com/checks/chk_0176bf6197100185_thumb_medium_2.png?version=v1&expires=1568239682&signature=sdgnJMzusEfndu7dNmk37eKc0AV7Hmqev6TQAqkCESs5pg7j6dDTsp7v4pnDvhsj8d7SIMcahl1aGiysoom0CA](https://lob-assets.com/checks/chk_0176bf6197100185_thumb_medium_2.png?version=v1&expires=1568239682&signature=sdgnJMzusEfndu7dNmk37eKc0AV7Hmqev6TQAqkCESs5pg7j6dDTsp7v4pnDvhsj8d7SIMcahl1aGiysoom0CA) ", * "large": "[https://lob-assets.com/checks/chk_0176bf6197100185_thumb_large_2.png?version=v1&expires=1568239682&signature=ybe8ovBh8Gf-AWKGRs4CB4XkU-erPVbY66umXARhTiJG2Dg1QlyCb9WmBXWt0tBCwD5NGMl20mHeAgHwecLxBA](https://lob-assets.com/checks/chk_0176bf6197100185_thumb_large_2.png?version=v1&expires=1568239682&signature=ybe8ovBh8Gf-AWKGRs4CB4XkU-erPVbY66umXARhTiJG2Dg1QlyCb9WmBXWt0tBCwD5NGMl20mHeAgHwecLxBA) " } ], * "expected_delivery_date": "2019-08-16", * "mail_type": "usps_first_class", * "date_created": "2019-08-08T19:34:47.571Z", * "date_modified": "2019-08-08T19:34:49.612Z", * "send_date": "2019-08-08", * "message": "pancakes are good", * "object": "check", * "check_bottom_template_id": "tmpl_a", * "attachment_template_id": "tmpl_a", * "check_bottom_template_version_id": "vrsn_a", * "attachment_template_version_id": "vrsn_a", * "merge_variables": { }, * "use_type": "operational", * "deleted": true }, * { * "id": "chk_92b9a6714bc0557c", * "description": "Demo Check", * "metadata": { }, * "check_number": 12558, * "memo": "rent", * "amount": 22.5, * "url": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c.pdf?version=v1&expires=1568239682&signature=jCct5PvzU58Iz2pSo58nf6rgsMRcJfMbUWThmm6lztFl5Vn2Y204b9h7gvw0vJvkDK2ThfaYqaUbWc0KzTpvAg](https://lob-assets.com/checks/chk_92b9a6714bc0557c.pdf?version=v1&expires=1568239682&signature=jCct5PvzU58Iz2pSo58nf6rgsMRcJfMbUWThmm6lztFl5Vn2Y204b9h7gvw0vJvkDK2ThfaYqaUbWc0KzTpvAg) ", * "to": { * "id": "adr_bae820679f3f536b", * "name": "HARRY ZHANG", * "address_line1": "210 KING ST STE 6100", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:08:43.446Z", * "date_modified": "2018-12-08T03:08:43.446Z", * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "name": "LEORE AVIDAR", * "address_line1": "210 KING ST STE 6100", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "bank_account": { * "id": "bank_8cad8df5354d33f", * "description": "Test Bank Account", * "metadata": { }, * "routing_number": "322271627", * "account_number": "123456789", * "account_type": "individual", * "signatory": "John Doe", * "bank_name": "J.P. MORGAN CHASE BANK, N.A.", * "verified": true, * "date_created": "2015-11-06T19:24:24.440Z", * "date_modified": "2015-11-06T19:41:28.312Z", * "object": "bank_account" }, * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_1.png?version=v1&expires=1568239682&signature=ublquO_xAdvAkAwGJuOjgZQwcz7c3Ao4NHWHeDVTBEBjcrQr8LavxWEwUc1KU105Zex3SajRQLd6hqJOrDl0Bw](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_1.png?version=v1&expires=1568239682&signature=ublquO_xAdvAkAwGJuOjgZQwcz7c3Ao4NHWHeDVTBEBjcrQr8LavxWEwUc1KU105Zex3SajRQLd6hqJOrDl0Bw) ", * "medium": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_1.png?version=v1&expires=1568239682&signature=vHyuOtsanX4HnY_0LNft6ZJ8C67JnbI8ZVCjA2d9nR0Rd6lCl0Nk1s6BAhefbBkzecX9Yp0B8NWN9Q5v1Z4ICw](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_1.png?version=v1&expires=1568239682&signature=vHyuOtsanX4HnY_0LNft6ZJ8C67JnbI8ZVCjA2d9nR0Rd6lCl0Nk1s6BAhefbBkzecX9Yp0B8NWN9Q5v1Z4ICw) ", * "large": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_1.png?version=v1&expires=1568239682&signature=SzCLKJ5m_TKJPLlL9PMw-zW9wo5mVYEK1jCtHwWRwwEaNU2v4Aehy-YHtus3TFJIt8RD2M-0Y3MtCxHwhqSABg](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_1.png?version=v1&expires=1568239682&signature=SzCLKJ5m_TKJPLlL9PMw-zW9wo5mVYEK1jCtHwWRwwEaNU2v4Aehy-YHtus3TFJIt8RD2M-0Y3MtCxHwhqSABg) " }, * { * "small": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_2.png?version=v1&expires=1568239682&signature=iElagODaOCkF_lCUxIw-lK50GhEU1ar_odmslCazZqD4Fsd_rQLx3M4Q5HzYWp4evfzuCoFvk4oAQVuIAaguAw](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_2.png?version=v1&expires=1568239682&signature=iElagODaOCkF_lCUxIw-lK50GhEU1ar_odmslCazZqD4Fsd_rQLx3M4Q5HzYWp4evfzuCoFvk4oAQVuIAaguAw) ", * "medium": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_2.png?version=v1&expires=1568239682&signature=2vwvm_QsfmdtkAa-_F4uk-0yeUPRascyhfwOr-OX1ya9i_8gdFQAxMTrP-FfNBVSYFXeknFm6IUPJHggfgeiBg](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_2.png?version=v1&expires=1568239682&signature=2vwvm_QsfmdtkAa-_F4uk-0yeUPRascyhfwOr-OX1ya9i_8gdFQAxMTrP-FfNBVSYFXeknFm6IUPJHggfgeiBg) ", * "large": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_2.png?version=v1&expires=1568239682&signature=NQf7tP9F4rP66S16hQ8duFpZSbTjaGBGK61Sr3H5D4CWtRyaPdoQlIpT2Jw-eKRcuYRkDEtQse_oWtL5gPqXDQ](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_2.png?version=v1&expires=1568239682&signature=NQf7tP9F4rP66S16hQ8duFpZSbTjaGBGK61Sr3H5D4CWtRyaPdoQlIpT2Jw-eKRcuYRkDEtQse_oWtL5gPqXDQ) " }, * { * "small": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_3.png?version=v1&expires=1568239682&signature=dbjFd44H9TyZsc3d0fqKon5e0GqZ6GA1dT26MH6WnoX8lrQor2CA6sZJ5qmu0Z4SAFlMKAzb-twqN7faLjEbDQ](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_3.png?version=v1&expires=1568239682&signature=dbjFd44H9TyZsc3d0fqKon5e0GqZ6GA1dT26MH6WnoX8lrQor2CA6sZJ5qmu0Z4SAFlMKAzb-twqN7faLjEbDQ) ", * "medium": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_3.png?version=v1&expires=1568239682&signature=vSgwVs7T9E6KKBK7XU-6jRL9i0jvgTqvNxkdRARFf0UNlryJFm8l_t_x5mPH0sCTFZcLp7ouRaR5hhdHC6vZBQ](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_3.png?version=v1&expires=1568239682&signature=vSgwVs7T9E6KKBK7XU-6jRL9i0jvgTqvNxkdRARFf0UNlryJFm8l_t_x5mPH0sCTFZcLp7ouRaR5hhdHC6vZBQ) ", * "large": "[https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_3.png?version=v1&expires=1568239682&signature=If4tXlN13WYy7JDPpFkWw0HAQpYNJHqi2UstiPHxUA_8IAj6vXORb-22acI124Pd1bR1QSjBHAW1gbiJ0kjiAQ](https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_3.png?version=v1&expires=1568239682&signature=If4tXlN13WYy7JDPpFkWw0HAQpYNJHqi2UstiPHxUA_8IAj6vXORb-22acI124Pd1bR1QSjBHAW1gbiJ0kjiAQ) " } ], * "merge_variables": null, * "expected_delivery_date": "2019-08-16", * "mail_type": "usps_first_class", * "date_created": "2019-08-08T19:34:27.802Z", * "date_modified": "2019-08-08T19:34:30.582Z", * "send_date": "2019-08-08T19:34:27.802Z", * "use_type": "operational", * "object": "check" } ], * "object": "list", * "next_url": "[https://api.lob.com/v1/checks?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wOFQxOTozNDoyNy44MDJaIiwiaWRPZmZzZXQiOiJjaGtfOTJiOWE2NzE0YmMwNTU3YyJ9](https://api.lob.com/v1/checks?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wOFQxOTozNDoyNy44MDJaIiwiaWRPZmZzZXQiOiJjaGtfOTJiOWE2NzE0YmMwNTU3YyJ9) ", * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Checks/operation/check_create)
Create
------------------------------------------------------------------
Creates a new check with the provided properties.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| idempotency\_key | string <= 256 characters
Example: idempotency\_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### header Parameters
| | |
| --- | --- |
| Idempotency-Key | string <= 256 characters
Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
One of
words at check bottomimage at check bottom
| | |
| --- | --- |
| message
required | string <= 400 characters
Max of 400 characters to be included at the bottom of the check page. |
| bank\_account
required | string^bank\_\[a-zA-Z0-9\]+$
The id for a verified bank account. |
| to
required | adr\_id (string) or (inline\_address\_us\_chk (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))
Must either be an address ID or an inline object with correct address parameters. Checks cannot be sent internationally (`address_country` must be `US`). The total string of the sum of `address_line1` and `address_line2` must be no longer than 50 characters combined. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine, and returned back with an ID. Depending on your [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
, addresses may also be run through [National Change of Address (NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
. If an address used does not meet your account’s [US Mail Strictness Setting](https://dashboard.lob.com/#/settings/account)
, the request will fail. [More about verification of mailing addresses](https://help.lob.com/print-and-mail/all-about-addresses) |
| from
required | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))
Must either be an address ID or an inline object with correct address parameters. Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| amount
required | number <= 999999.99
The payment amount to be sent in US dollars. Amounts will be rounded to two decimal places. |
| use\_type
required | string or null
Enum: "marketing" "operational" null
TThe use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| mail\_type | string
Default: "usps\_first\_class"
Value: "usps\_first\_class"
Checks must be sent `usps_first_class` |
| memo | string or null <= 40 characters
Text to include on the memo line of the check. |
| check\_number | integer \[ 1 .. 500000000 \]
An integer that designates the check number. If `check_number` is not provided, checks created from a new `bank_account` will start at `10000` and increment with each check created with the `bank_account`. A provided `check_number` overrides the defaults. Subsequent checks created with the same `bank_account` will increment from the provided check number. |
| logo | string or string
Accepts a remote URL or local file upload to an image to print (in grayscale) in the upper-left corner of your check. Image requirements:
* RGB or CMYK
* square
* minimum size: 100px x 100px
* transparent backgrond
* `png` or `jpg` |
| check\_bottom | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string) (check\_bottom)
The artwork to use on the bottom of the check page.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 8.5"x11" at 300 DPI, while supplied HTML will be rendered and trimmed to fit on a 8.5"x11" page.
* The check bottom will always be printed in black & white.
* Must conform to [this template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/check_bottom_template.pdf)
.
Need more help? Consult our [HTML examples](https://docs.lob.com/#section/HTML-Examples)
. |
| attachment | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string)
A document to include with the check.
Notes:
* HTML merge variables should not include delimiting whitespace.
* All pages of PDF, PNG, and JPGs must be sized at 8.5"x11" at 300 DPI, while supplied HTML will be rendered and trimmed to as many 8.5"x11" pages as necessary.
* If a PDF is provided, it must be 6 pages or fewer.
* The attachment will be printed double-sided in black & white and will be included in the envelope after the check page.
* Please follow these [design guidelines](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/check_attachment_template.pdf)
.
See [pricing](https://lob.com/pricing/print-mail#compare)
for extra costs incurred. Need more help? Consult our [HTML examples](https://docs.lob.com/#section/HTML-Examples)
. |
| billing\_group\_id | string (billing\_group\_id)
An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See [Billing Group API](https://docs.lob.com/#tag/Billing-Groups)
for more information. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
### Responses
**200**
Returns a check object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| bank\_account
required | object (bank\_account) |
| id
required | string (chk\_id) ^chk\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `chk_`. |
| amount
required | number decimal places <= 2 <= 999999.99
The payment amount to be sent in US dollars. |
| to
required | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (to\_address\_us\_chk) |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| use\_type
required | string or null
Enum: "marketing" "operational" null
TThe use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| mail\_type | string
Default: "usps\_first\_class"
Value: "usps\_first\_class"
Checks must be sent `usps_first_class` |
| memo | string or null <= 40 characters
Text to include on the memo line of the check. |
| check\_number | integer \[ 1 .. 500000000 \]
An integer that designates the check number. If `check_number` is not provided, checks created from a new `bank_account` will start at `10000` and increment with each check created with the `bank_account`. A provided `check_number` overrides the defaults. Subsequent checks created with the same `bank_account` will increment from the provided check number. |
| message | string <= 400 characters
Max of 400 characters to be included at the bottom of the check page. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| check\_bottom\_template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the check bottom. |
| attachment\_template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the attachment. |
| check\_bottom\_template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the check bottom. |
| attachment\_template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the attachment. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| tracking\_events | Array of objects or null (tracking\_event\_normal)
An array of tracking\_event objects ordered by ascending `time`. Will not be populated for checks created in test mode. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "check"
Value: "check"
Value is resource type. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
post/checks
production
https://api.lob.com/v1/checks
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "Demo Check", * "to": { * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107", * "address_country": "US" }, * "from": { * "name": "Leore Avidar", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107-1741" }, * "bank_account": "bank_8cad8df5354d33f", * "amount": 22.5, * "memo": "rent", * "logo": "[https://s3-us-west-2.amazonaws.com/public.lob.com/assets/check_logo.png](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/check_logo.png) ", * "check_bottom": "tmpl_23668b406d5afef", * "merge_variables": { * "name": "Harry" }, * "metadata": { * "memo": "rafting trip" }, * "attachment": "./cool.pdf", * "send_date": "2017-11-01T00:00:00.000Z", * "use_type": "operational", * "mail_type": "usps_first_class", * "check_number": 10001, * "print_speed": "core" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "chk_534f10783683daa0", * "description": "Demo Check", * "metadata": { }, * "check_number": 10062, * "memo": "rent", * "amount": 22.5, * "url": "[https://lob-assets.com/checks/chk_534f10783683daa0.pdf?expires=1540372221&signature=Ty3IV2bGPEoQfrdraYHlNYTaarnHLXb](https://lob-assets.com/checks/chk_534f10783683daa0.pdf?expires=1540372221&signature=Ty3IV2bGPEoQfrdraYHlNYTaarnHLXb) ", * "to": { * "id": "adr_bae820679f3f536b", * "description": "Harry - Office", * "name": "HARRY ZHANG", * "company": "LOB", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 KING ST STE 6100", * "address_line2": "", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:08:43.446Z", * "date_modified": "2018-12-08T03:08:43.446Z", * "object": "address", * "recipient_moved": false }, * "from": { * "id": "adr_b8fb5acf3a2b55db", * "name": "LEORE AVIDAR", * "address_line1": "210 KING ST STE 6100", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "address" }, * "bank_account": { * "id": "bank_8cad8df5354d33f", * "description": "Test Bank Account", * "metadata": { }, * "routing_number": "322271627", * "account_number": "123456789", * "signatory": "John Doe", * "bank_name": "J.P. MORGAN CHASE BANK, N.A.", * "verified": true, * "account_type": "company", * "date_created": "2015-11-06T19:24:24.440Z", * "date_modified": "2015-11-06T19:41:28.312Z", * "object": "bank_account", * "signature_url": "[https://lob-assets.com/bank-accounts/asd_asdfghjkqwertyui.pdf?expires=1234567890&signature=aksdf](https://lob-assets.com/bank-accounts/asd_asdfghjkqwertyui.pdf?expires=1234567890&signature=aksdf) " }, * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/checks/chk_534f10783683daa0_thumb_small_1.png?expires=1540372221&signature=ShhPpH74wYkNiAj7Il9B6q8ZKkzlGd4](https://lob-assets.com/checks/chk_534f10783683daa0_thumb_small_1.png?expires=1540372221&signature=ShhPpH74wYkNiAj7Il9B6q8ZKkzlGd4) ", * "medium": "[https://lob-assets.com/checks/chk_534f10783683daa0_thumb_medium_1.png?expires=1540372221&signature=tmIOq6aAyKgzAECp7STj1rvJuMS5Svd](https://lob-assets.com/checks/chk_534f10783683daa0_thumb_medium_1.png?expires=1540372221&signature=tmIOq6aAyKgzAECp7STj1rvJuMS5Svd) ", * "large": "[https://lob-assets.com/checks/chk_534f10783683daa0_thumb_large_1.png?expires=1540372221&signature=04nLEwE9d2qgQJNgJYWSOgPnU0FZbEv](https://lob-assets.com/checks/chk_534f10783683daa0_thumb_large_1.png?expires=1540372221&signature=04nLEwE9d2qgQJNgJYWSOgPnU0FZbEv) " } ], * "merge_variables": { * "name": "Harry" }, * "expected_delivery_date": "2017-09-12", * "mail_type": "usps_first_class", * "date_created": "2017-09-05T17:47:53.896Z", * "date_modified": "2017-09-05T17:47:53.896Z", * "send_date": "2017-09-05T17:47:53.896Z", * "object": "check", * "message": "pancakes are good", * "check_bottom_template_id": "tmpl_a", * "attachment_template_id": "tmpl_a", * "check_bottom_template_version_id": "vrsn_a", * "attachment_template_version_id": "vrsn_a", * "use_type": "operational", * "sla": "2", * "deleted": true }`
[](https://docs.lob.com/#tag/Checks/operation/check_retrieve)
Retrieve
----------------------------------------------------------------------
Retrieves the details of an existing check. You need only supply the unique check identifier that was returned upon check creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| chk\_id
required | string (chk\_id) ^chk\_\[a-zA-Z0-9\]+$
id of the check |
### Responses
**200**
Returns a check object
##### Response Schema: application/json
| | |
| --- | --- |
| bank\_account
required | object (bank\_account) |
| id
required | string (chk\_id) ^chk\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `chk_`. |
| amount
required | number decimal places <= 2 <= 999999.99
The payment amount to be sent in US dollars. |
| to
required | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (to\_address\_us\_chk) |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| use\_type
required | string or null
Enum: "marketing" "operational" null
TThe use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| mail\_type | string
Default: "usps\_first\_class"
Value: "usps\_first\_class"
Checks must be sent `usps_first_class` |
| memo | string or null <= 40 characters
Text to include on the memo line of the check. |
| check\_number | integer \[ 1 .. 500000000 \]
An integer that designates the check number. If `check_number` is not provided, checks created from a new `bank_account` will start at `10000` and increment with each check created with the `bank_account`. A provided `check_number` overrides the defaults. Subsequent checks created with the same `bank_account` will increment from the provided check number. |
| message | string <= 400 characters
Max of 400 characters to be included at the bottom of the check page. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| check\_bottom\_template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the check bottom. |
| attachment\_template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the attachment. |
| check\_bottom\_template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the check bottom. |
| attachment\_template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the attachment. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| tracking\_events | Array of objects or null (tracking\_event\_normal)
An array of tracking\_event objects ordered by ascending `time`. Will not be populated for checks created in test mode. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "check"
Value: "check"
Value is resource type. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
get/checks/{chk\_id}
production
https://api.lob.com/v1/checks/{chk\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl https://api.lob.com/v1/checks/chk\_534f10783683daa0 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "chk_534f10783683daa0", * "description": "Demo Check", * "metadata": { }, * "check_number": 10062, * "memo": "rent", * "amount": 22.5, * "url": "[https://lob-assets.com/checks/chk_534f10783683daa0.pdf?expires=1540372221&signature=Ty3IV2bGPEoQfrdraYHlNYTaarnHLXb](https://lob-assets.com/checks/chk_534f10783683daa0.pdf?expires=1540372221&signature=Ty3IV2bGPEoQfrdraYHlNYTaarnHLXb) ", * "to": { * "id": "adr_bae820679f3f536b", * "description": "Harry - Office", * "name": "HARRY ZHANG", * "company": "LOB", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 KING ST STE 6100", * "address_line2": "", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:08:43.446Z", * "date_modified": "2018-12-08T03:08:43.446Z", * "object": "address", * "recipient_moved": false }, * "from": { * "id": "adr_b8fb5acf3a2b55db", * "name": "LEORE AVIDAR", * "address_line1": "210 KING ST STE 6100", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "address" }, * "bank_account": { * "id": "bank_8cad8df5354d33f", * "description": "Test Bank Account", * "metadata": { }, * "routing_number": "322271627", * "account_number": "123456789", * "signatory": "John Doe", * "bank_name": "J.P. MORGAN CHASE BANK, N.A.", * "verified": true, * "account_type": "company", * "date_created": "2015-11-06T19:24:24.440Z", * "date_modified": "2015-11-06T19:41:28.312Z", * "object": "bank_account", * "signature_url": "[https://lob-assets.com/bank-accounts/asd_asdfghjkqwertyui.pdf?expires=1234567890&signature=aksdf](https://lob-assets.com/bank-accounts/asd_asdfghjkqwertyui.pdf?expires=1234567890&signature=aksdf) " }, * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/checks/chk_534f10783683daa0_thumb_small_1.png?expires=1540372221&signature=ShhPpH74wYkNiAj7Il9B6q8ZKkzlGd4](https://lob-assets.com/checks/chk_534f10783683daa0_thumb_small_1.png?expires=1540372221&signature=ShhPpH74wYkNiAj7Il9B6q8ZKkzlGd4) ", * "medium": "[https://lob-assets.com/checks/chk_534f10783683daa0_thumb_medium_1.png?expires=1540372221&signature=tmIOq6aAyKgzAECp7STj1rvJuMS5Svd](https://lob-assets.com/checks/chk_534f10783683daa0_thumb_medium_1.png?expires=1540372221&signature=tmIOq6aAyKgzAECp7STj1rvJuMS5Svd) ", * "large": "[https://lob-assets.com/checks/chk_534f10783683daa0_thumb_large_1.png?expires=1540372221&signature=04nLEwE9d2qgQJNgJYWSOgPnU0FZbEv](https://lob-assets.com/checks/chk_534f10783683daa0_thumb_large_1.png?expires=1540372221&signature=04nLEwE9d2qgQJNgJYWSOgPnU0FZbEv) " } ], * "merge_variables": { * "name": "Harry" }, * "expected_delivery_date": "2017-09-12", * "mail_type": "usps_first_class", * "date_created": "2017-09-05T17:47:53.896Z", * "date_modified": "2017-09-05T17:47:53.896Z", * "send_date": "2017-09-05T17:47:53.896Z", * "object": "check", * "message": "pancakes are good", * "check_bottom_template_id": "tmpl_a", * "attachment_template_id": "tmpl_a", * "check_bottom_template_version_id": "vrsn_a", * "attachment_template_version_id": "vrsn_a", * "use_type": "operational", * "sla": "2", * "deleted": true }`
[](https://docs.lob.com/#tag/Checks/operation/check_cancel)
Cancel
------------------------------------------------------------------
Completely removes a check from production. This can only be done if the check has a `send_date` and the `send_date` has not yet passed. If the check is successfully canceled, you will not be charged for it. Read more on [cancellation windows](https://docs.lob.com/#section/Cancellation-Windows)
and [scheduling](https://docs.lob.com/#section/Scheduled-Mailings)
. Scheduling and cancellation is a premium feature. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| chk\_id
required | string (chk\_id) ^chk\_\[a-zA-Z0-9\]+$
id of the check |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (chk\_id) ^chk\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `chk_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/checks/{chk\_id}
production
https://api.lob.com/v1/checks/{chk\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/checks/chk\_534f10783683daa0 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "chk_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/Snap-Packs)
Snap Packs
===================================================
[](https://docs.lob.com/#tag/Snap-Packs/operation/snap_pack_retrieve)
Retrieve
------------------------------------------------------------------------------
Retrieves the details of an existing snap\_pack. You need to only supply the unique snap\_pack identifier that was returned upon snap\_pack creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| snap\_pack\_id
required | string (snap\_pack\_id) ^ord\_\[0-9a-f\]{26}$
id of the snap\_pack |
### Responses
**200**
Returns a snap\_pack object
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (snap\_pack\_id) ^ord\_\[0-9a-f\]{26}$
Unique identifier prefixed with `ord_`. |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| use\_type
required | string or null (snap\_pack\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (snap\_pack\_size)
Default: "8.5x11"
Value: "8.5x11"
Specifies the size of the snap pack. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| outside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the outside of the snap pack. |
| inside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the inside of the snap pack. |
| outside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the outside of the snap pack. |
| inside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the inside of the snap pack. |
| object | string
Default: "snap\_pack"
Value: "snap\_pack"
Value is resource type. |
| tracking\_events | Array of objects (tracking\_event\_normal)
An array of tracking events ordered by ascending `time`. Not populated in test mode. |
| fsc | boolean
Default: false
Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for snap\_pack currently. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| color | boolean (color)
Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white. |
**default**
Error
get/snap\_packs/{snap\_pack\_id}
production
https://api.lob.com/v1/snap\_packs/{snap\_pack\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/snap\_packs/ord\_0d6a16a3fff6318ac8f8008dc1" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "description": "April Campaign", * "to": { * "id": "adr_bae820679f3f536b", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "url": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " }, * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw) " } ], * "merge_variables": { * "name": null }, * "size": "8.5x11", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "color": false, * "sla": "2", * "object": "snap_pack" }`
[](https://docs.lob.com/#tag/Snap-Packs/operation/snap_pack_delete)
Delete
--------------------------------------------------------------------------
Completely removes a snap pack from production. This can only be done if the snap pack's `send_date` has not yet passed. If the snap pack is successfully canceled, you will not be charged for it.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| snap\_pack\_id
required | string (snap\_pack\_id) ^ord\_\[0-9a-f\]{26}$
id of the snap\_pack |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (snap\_pack\_id) ^ord\_\[0-9a-f\]{26}$
Unique identifier prefixed with `ord_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/snap\_packs/{snap\_pack\_id}
production
https://api.lob.com/v1/snap\_packs/{snap\_pack\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/snap\_packs/ord\_0d6a16a3fff6318ac8f8008dc1 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "deleted": true }`
[](https://docs.lob.com/#tag/Snap-Packs/operation/snap_packs_list)
List
-----------------------------------------------------------------------
Returns a list of your snap\_packs. The snap\_packs are returned sorted by creation date, with the most recently created snap\_packs appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
| send\_date | string or string (send\_date)
Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type: \* `usps_first_class` - (default) \* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| sort\_by | object or object
Sorts items by ascending or descending dates. Use either `date_created` or `send_date`, not both. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Filters resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the render status:
* `processed` - the rendering process is currently underway.
* `rendered` - the rendering process has completed successfully.
* `failed` - the rendering process has failed. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` snap\_packs. Each entry in the array is a separate self\_mailer. The previous and next page of snap\_packs can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more snap\_packs are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (snap\_pack)
list of snap\_packs |
**default**
Error
get/snap\_packs
production
https://api.lob.com/v1/snap\_packs
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/snap\_packs?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "description": "April Campaign", * "to": { * "id": "adr_bae820679f3f536b", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "url": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " }, * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw) " } ], * "merge_variables": { * "name": null }, * "size": "8.5x11", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "color": false, * "object": "snap_pack" }, * { * "id": "ord_851100000f31bb1a872f794cee", * "description": "April Campaign", * "to": { * "id": "adr_f9228b743884ff98", * "description": null, * "name": "AYA", * "company": null, * "phone": null, * "email": null, * "address_line1": "2812 PARK RD", * "address_line2": null, * "address_city": "CHARLOTTE", * "address_state": "NC", * "address_zip": "28209-1314", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2021-03-16T18:40:40.410Z", * "date_modified": "2021-03-16T18:40:40.410Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": null, * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "url": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " }, * { * "small": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ) ", * "medium": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA) ", * "large": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw) " } ], * "merge_variables": { * "name": null }, * "size": "8.5x11", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "color": false, * "object": "snap_pack" } ], * "object": "list", * "next_url": null, * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Snap-Packs/operation/snap_pack_create)
Create
--------------------------------------------------------------------------
Creates a new snap\_pack given information
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| idempotency\_key | string <= 256 characters
Example: idempotency\_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### header Parameters
| | |
| --- | --- |
| Idempotency-Key | string <= 256 characters
Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### Request Body schema:
application/jsonmultipart/form-dataapplication/json
| | |
| --- | --- |
| to
required | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))))))
Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Depending on your [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
, US addresses may also be run through [National Change of Address Linkage(NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s [US Mail strictness setting](https://dashboard.lob.com/#/settings/account)
, the request will fail. [Lob Guide: Verification of Mailing Addresses](https://help.lob.com/print-and-mail/all-about-addresses) |
| inside
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string)
The artwork to use as the inside of your snap pack.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 8.5"x11" at 300 DPI, while supplied HTML will be rendered to the specified `size`.
* Be sure to leave room for address and postage information by following the template provided here:
* [8.5x11 snap pack template](https://s3.us-west-2.amazonaws.com/public.lob.com/assets/8.5x11_Snappack_template_address.pdf)
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| outside
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or local\_file\_path (string)
The artwork to use as the outside of your snap pack.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 6"x18" at 300 DPI, while supplied HTML will be rendered to the specified `size`.
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| use\_type
required | string or null (snap\_pack\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (snap\_pack\_size)
Default: "8.5x11"
Value: "8.5x11"
Specifies the size of the snap pack. |
| from | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))
_Required_ if `to` address is international. Must either be an address ID or an inline object with correct address parameters. Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| billing\_group\_id | string (billing\_group\_id)
An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See [Billing Group API](https://docs.lob.com/#tag/Billing-Groups)
for more information. |
| color | boolean
Default: false
Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white. |
| qr\_code | object (qr\_code)
Customize and place a QR code on the creative at the required position. |
### Responses
**200**
Returns a snap\_pack object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (snap\_pack\_id) ^ord\_\[0-9a-f\]{26}$
Unique identifier prefixed with `ord_`. |
| url
required | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| use\_type
required | string or null (snap\_pack\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| size | string (snap\_pack\_size)
Default: "8.5x11"
Value: "8.5x11"
Specifies the size of the snap pack. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| from | address obj with \`name\` defined (object) or address obj with \`company\` defined (object) (address\_us) |
| outside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the outside of the snap pack. |
| inside\_template\_id | string or null^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the inside of the snap pack. |
| outside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the outside of the snap pack. |
| inside\_template\_version\_id | string or null^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the inside of the snap pack. |
| object | string
Default: "snap\_pack"
Value: "snap\_pack"
Value is resource type. |
| tracking\_events | Array of objects (tracking\_event\_normal)
An array of tracking events ordered by ascending `time`. Not populated in test mode. |
| fsc | boolean
Default: false
Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for snap\_pack currently. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| color | boolean (color)
Set this key to `true` if you would like to print in color. Set to `false` if you would like to print in black and white. |
**default**
Error
post/snap\_packs
production
https://api.lob.com/v1/snap\_packs
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "Demo Snap Pack Job", * "to": "adr_bae820679f3f536b", * "from": "adr_210a8d4b0b76d77b", * "inside": "[https://lob.com/snappackinside.pdf](https://lob.com/snappackinside.pdf) ", * "outside": "[https://lob.com/snappackoutside.pdf](https://lob.com/snappackoutside.pdf) ", * "size": "8.5x11", * "metadata": { * "spiffy": "true" }, * "mail_type": "usps_standard", * "merge_variables": { * "name": "Harry" }, * "send_date": "2017-11-01T00:00:00.000Z", * "use_type": "marketing", * "print_speed": "core" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "description": "April Campaign", * "to": { * "id": "adr_bae820679f3f536b", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "deleted": true, * "object": "address" }, * "url": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "outside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_id": "tmpl_a3cb937f26d7eec", * "inside_template_version_id": "vrsn_bfdf70893b00a85", * "outside_template_version_id": "vrsn_bfdf70893b00a85", * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " }, * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw) " } ], * "merge_variables": { * "name": null }, * "size": "8.5x11", * "mail_type": "usps_first_class", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "color": false, * "sla": "2", * "object": "snap_pack" }`
[](https://docs.lob.com/#tag/Booklets)
Booklets
===============================================
[](https://docs.lob.com/#tag/Booklets/operation/booklet_retrieve)
Retrieve
--------------------------------------------------------------------------
Retrieves the details of an existing booklet. You need to only supply the unique booklet identifier that was returned upon booklet creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| booklet\_id
required | string (booklet\_id) ^ord\_\[0-9a-f\]{26}$
id of the booklet |
### Responses
**200**
Returns a booklet object
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (booklet\_id) ^ord\_\[0-9a-f\]{26}$
Unique identifier prefixed with `ord_`. |
| from
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| use\_type
required | string or null (booklet\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| tracking\_events | Array of objects (tracking\_event\_normal)
An array of tracking events ordered by ascending `time`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| url | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the booklet. |
| template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the booklet. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| size | string (booklet\_size)
Default: "8.375x5.375"
Value: "8.375x5.375"
Specifies the size of the booklet. |
| pages | integer (booklet\_pages)
Pages specifies the total number of pages in a booklet, where four pages make up one sheet. Pages must always be in increments of four to maintain booklet integrity. For a booklet with dimensions of 8.375x5.375 inches, we allow for 8, 12, 16, 20, 24, 28, or 32 pages. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| source\_material | string (booklet\_source\_material)
Default: "60# Gloss Text"
Value: "60# Gloss Text"
Defines the material used to create the mail piece, specifically for booklets. This property is directly tied to the size of the booklet, ensuring that the appropriate material is selected based on the booklet's dimensions. For booklets with `size` equal to `8.375x5.375` inches, the default source material is `60# Gloss Text`. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "booklet"
Value: "booklet"
Value is resource type. |
**default**
Error
get/booklets/{booklet\_id}
production
https://api.lob.com/v1/booklets/{booklet\_id}
### Request samples
* CURL
Copy
curl -X GET "https://api.lob.com/v1/booklets/ord\_0d6a16a3fff6318ac8f8008dc1" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_d3489cd64c791ab5", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_b8fb5acf3a2b55db", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "carrier": "USPS", * "tracking_number": null, * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " } ], * "merge_variables": { * "name": "Harry" }, * "size": "8.375x5.375", * "pages": 8, * "source_material": "60# Gloss Text", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "booklet" }`
[](https://docs.lob.com/#tag/Booklets/operation/booklet_delete)
Delete
----------------------------------------------------------------------
Completely removes a booklet from production. This can only be done if the booklet's `send_date` has not yet passed. If the booklet is successfully canceled, you will not be charged for it.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| booklet\_id
required | string (booklet\_id) ^ord\_\[0-9a-f\]{26}$
id of the booklet |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (booklet\_id) ^ord\_\[0-9a-f\]{26}$
Unique identifier prefixed with `ord_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/booklets/{booklet\_id}
production
https://api.lob.com/v1/booklets/{booklet\_id}
### Request samples
* CURL
Copy
curl -X DELETE https://api.lob.com/v1/booklets/ord\_0d6a16a3fff6318ac8f8008dc1 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "deleted": true }`
[](https://docs.lob.com/#tag/Booklets/operation/booklets_list)
List
-------------------------------------------------------------------
Returns a list of your booklets. The booklets are returned sorted by creation date, with the most recently created booklets appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
| send\_date | string or string (send\_date)
Filter by ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type: \* `usps_first_class` - (default) \* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| sort\_by | object or object
Sorts items by ascending or descending dates. Use either `date_created` or `send_date`, not both. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Filters resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the render status:
* `processed` - the rendering process is currently underway.
* `rendered` - the rendering process has completed successfully.
* `failed` - the rendering process has failed. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` booklets. Each entry in the array is a separate booklet. The previous and next page of booklets can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively. If no more booklets are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (booklet)
list of booklets |
**default**
Error
get/booklets
production
https://api.lob.com/v1/booklets
### Request samples
* CURL
Copy
curl -X GET "https://api.lob.com/v1/booklets?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_d3489cd64c791ab5", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_b8fb5acf3a2b55db", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "carrier": "USPS", * "tracking_number": null, * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " } ], * "merge_variables": { * "name": "Harry" }, * "size": "8.375x5.375", * "pages": 8, * "source_material": "60# Gloss Text", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "object": "booklet" }, * { * "id": "ord_851100000f31bb1a872f794cee", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_f9228b743884ff98", * "description": null, * "name": "AYA", * "company": null, * "phone": null, * "email": null, * "address_line1": "2812 PARK RD", * "address_line2": null, * "address_city": "CHARLOTTE", * "address_state": "NC", * "address_zip": "28209-1314", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2021-03-16T18:40:40.410Z", * "date_modified": "2021-03-16T18:40:40.410Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_210a8d4b0b76d77b", * "description": null, * "name": null, * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2018-12-08T03:01:07.651Z", * "date_modified": "2018-12-08T03:01:07.651Z", * "object": "address" }, * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "carrier": "USPS", * "tracking_number": null, * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_851100000f31bb1a872f794cee_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " } ], * "merge_variables": { * "name": "Harry" }, * "size": "8.375x5.375", * "pages": 8, * "source_material": "60# Gloss Text", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "object": "booklet" } ], * "object": "list", * "next_url": null, * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Booklets/operation/booklet_create)
Create
----------------------------------------------------------------------
Creates a new booklet.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| idempotency\_key | string <= 256 characters
Example: idempotency\_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### header Parameters
| | |
| --- | --- |
| Idempotency-Key | string <= 256 characters
Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5
A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| to
required | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))))))
Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Depending on your [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
, US addresses may also be run through [National Change of Address Linkage(NCOALink)](https://docs.lob.com/#tag/National-Change-of-Address)
. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s [US Mail strictness setting](https://dashboard.lob.com/#/settings/account)
, the request will fail. [Lob Guide: Verification of Mailing Addresses](https://help.lob.com/print-and-mail/all-about-addresses) |
| from
required | adr\_id (string) or (inline\_address ((address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (inline\_address\_intl ((address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_editable\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object)))))))
Must either be an address ID or an inline object with correct address parameters. Must be a US address unless using a `custom_envelope`. All addresses will be standardized into uppercase without being modified by verification. |
| file
required | html\_string (string) or tmpl\_id (string) or remote\_file\_url (string) or string (booklet\_file)
Notes:
* HTML merge variables should not include delimiting whitespace.
* All pages of a supplied PDF file must be sized per the `size` attribute, while supplied HTML will be rendered and trimmed to as many `size` pages as necessary.
* For design specifications, please see our [PDF](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/letter_template.pdf)
and [HTML](https://docs.lob.com/#section/HTML-Examples)
templates. See [pricing](https://lob.com/pricing/print-mail#compare)
for extra costs incurred. |
| use\_type
required | string or null (booklet\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| pages
required | integer (booklet\_pages)
Pages specifies the total number of pages in a booklet, where four pages make up one sheet. Pages must always be in increments of four to maintain booklet integrity. For a booklet with dimensions of 8.375x5.375 inches, we allow for 8, 12, 16, 20, 24, 28, or 32 pages. |
| size
required | string (booklet\_size)
Default: "8.375x5.375"
Value: "8.375x5.375"
Specifies the size of the booklet. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| mail\_type | string
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| print\_speed | string or null
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
| billing\_group\_id | string (billing\_group\_id)
An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See [Billing Group API](https://docs.lob.com/#tag/Billing-Groups)
for more information. |
| qr\_code | object (qr\_code)
Customize and place a QR code on the creative at the required position. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. Not available for `A4` and `us_legal` letter size. |
| source\_material | string (booklet\_source\_material)
Default: "60# Gloss Text"
Value: "60# Gloss Text"
Defines the material used to create the mail piece, specifically for booklets. This property is directly tied to the size of the booklet, ensuring that the appropriate material is selected based on the booklet's dimensions. For booklets with `size` equal to `8.375x5.375` inches, the default source material is `60# Gloss Text`. |
### Responses
**200**
Returns a booklet object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| to
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| carrier
required | string
Default: "USPS"
Value: "USPS" |
| id
required | string (booklet\_id) ^ord\_\[0-9a-f\]{26}$
Unique identifier prefixed with `ord_`. |
| from
required | (address\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) or (address\_intl (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (address) |
| use\_type
required | string or null (booklet\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| tracking\_events | Array of objects (tracking\_event\_normal)
An array of tracking events ordered by ascending `time`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| merge\_variables | object or null (merge\_variables) <= 25000 characters
You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: `{{variable_name}}`, pass in `{"variable_name": "Harry"}` to render `Harry`. `merge_variables` must be an object. Any type of value is accepted as long as the object is valid JSON; you can use `strings`, `numbers`, `booleans`, `arrays`, `objects`, or `null`. The max length of the object is 25,000 characters. If you call `JSON.stringify` on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: `!`, `"`, `#`, `%`, `&`, `'`, `(`, `)`, `*`, `+`, `,`, `/`, `;`, `<`, `=`, `>`, `@`, `[`, `\`, `]`, `^`, `` ` ``, `{`, `\|`, `}`, `~`. More instructions can be found in [our guide to using html and merge variables](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#using-html-and-merge-variables-10)
. Depending on your [Merge Variable strictness](https://dashboard.lob.com/#/settings/account)
setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs. |
| send\_date | string or string (send\_date)
A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the letter off for production. Setting a send date overrides the default [cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
applied to the mailpiece. Until the `send_date` has passed, the mailpiece can be canceled. If a date in the format `2017-11-01` is passed, it will evaluate to midnight UTC of that date (`2017-11-01T00:00:00.000Z`). If a datetime is passed, that exact time will be used. A `send_date` passed with no time zone will default to UTC, while a `send_date` passed with a time zone will be converted to UTC. |
| mail\_type | string (mail\_type)
Default: "usps\_first\_class"
Enum: "usps\_first\_class" "usps\_standard"
A string designating the mail postage type:
* `usps_first_class` - (default)
* `usps_standard` - a [cheaper option](https://lob.com/pricing/print-mail#compare)
which is less predictable and takes longer to deliver. `usps_standard` cannot be used with `4x6` postcards or for any postcards sent outside of the United States. |
| thumbnails | Array of objects (thumbnail) |
| expected\_delivery\_date | string (expected\_delivery\_date)
A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its `send_date`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| url | string (signed\_link) ^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
| template\_id | string^tmpl\_\[a-zA-Z0-9\]+$
The unique ID of the HTML template used for the booklet. |
| template\_version\_id | string^vrsn\_\[a-zA-Z0-9\]+$
The unique ID of the specific version of the HTML template used for the booklet. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Denotes resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| size | string (booklet\_size)
Default: "8.375x5.375"
Value: "8.375x5.375"
Specifies the size of the booklet. |
| pages | integer (booklet\_pages)
Pages specifies the total number of pages in a booklet, where four pages make up one sheet. Pages must always be in increments of four to maintain booklet integrity. For a booklet with dimensions of 8.375x5.375 inches, we allow for 8, 12, 16, 20, 24, 28, or 32 pages. |
| fsc | boolean
Default: false
This is in beta. Contact [support@lob.com](mailto:support@lob.com)
or your account contact to learn more. |
| status | string (status)
Enum: "processed" "rendered" "failed"
A string describing the PDF render status:
* `processed` - the rendering process is currently in progress.
* `rendered` - a PDF has been successfully rendered of the mailpiece.
* `failed` - one or more issues has caused the rendering process to fail. |
| source\_material | string (booklet\_source\_material)
Default: "60# Gloss Text"
Value: "60# Gloss Text"
Defines the material used to create the mail piece, specifically for booklets. This property is directly tied to the size of the booklet, ensuring that the appropriate material is selected based on the booklet's dimensions. For booklets with `size` equal to `8.375x5.375` inches, the default source material is `60# Gloss Text`. |
| failure\_reason | object or null
An object describing the reason for failure if the resource failed to render. |
| object | string
Default: "booklet"
Value: "booklet"
Value is resource type. |
**default**
Error
post/booklets
production
https://api.lob.com/v1/booklets
### Request samples
* Payload
* CURL
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "demo", * "to": { * "description": "Harry - Office", * "name": "Harry Zhang", * "company": "Lob", * "email": "harry@lob.com", * "phone": "5555555555", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107", * "address_country": "US" }, * "from": { * "name": "Harry", * "address_line1": "210 King St", * "address_line2": "# 6100", * "address_city": "San Francisco", * "address_state": "CA", * "address_zip": "94107" }, * "file": "HTML Booklet for {{name}}", * "mail_type": "usps_first_class", * "merge_variables": { * "name": "Harry" }, * "metadata": { * "spiffy": "true" }, * "send_date": "2017-11-01T00:00:00.000Z", * "use_type": "marketing", * "qr_code": { * "position": "relative", * "redirect_url": "[https://www.lob.com](https://www.lob.com/) ", * "width": "2", * "top": "2", * "right": "2", * "pages": "1-2,4-5" }, * "fsc": true, * "size": "8.375x5.375", * "print_speed": "core" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "ord_0d6a16a3fff6318ac8f8008dc1", * "description": "April Campaign", * "metadata": { }, * "to": { * "id": "adr_d3489cd64c791ab5", * "description": null, * "name": "HARRY ZHANG", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "from": { * "id": "adr_b8fb5acf3a2b55db", * "description": null, * "name": "LEORE AVIDAR", * "company": null, * "phone": null, * "email": null, * "address_line1": "210 KING ST STE 6100", * "address_line2": null, * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107-1741", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2017-09-05T15:54:53.264Z", * "date_modified": "2017-09-05T15:54:53.264Z", * "deleted": true, * "object": "address" }, * "mail_type": "usps_first_class", * "url": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA) ", * "carrier": "USPS", * "tracking_number": null, * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA) ", * "medium": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ) ", * "large": "[https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg](https://lob-assets.com/order-creatives/ord_0d6a16a3fff6318ac8f8008dc1_comp_a20fd48ba4efda76ee827400d_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg) " } ], * "merge_variables": { * "name": "Harry" }, * "size": "8.375x5.375", * "pages": 8, * "source_material": "60# Gloss Text", * "expected_delivery_date": "2021-03-24", * "date_created": "2021-03-16T18:40:40.504Z", * "date_modified": "2021-03-16T18:40:40.504Z", * "send_date": "2021-03-16T18:45:40.493Z", * "use_type": "marketing", * "fsc": false, * "sla": "2", * "object": "booklet" }`
[](https://docs.lob.com/#tag/Bank-Accounts)
Bank Accounts
=========================================================
Bank Accounts allow you to store your bank account securely in our system. The API provides endpoints for creating bank accounts, deleting bank accounts, verifying bank accounts, retrieving individual bank accounts, and retrieving a list of bank accounts.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Bank-Accounts/operation/bank_account_verify)
Verify
--------------------------------------------------------------------------------
Verify a bank account in order to create a check.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| bank\_id
required | string (bank\_id) ^bank\_\[a-zA-Z0-9\]+$
id of the bank account to be verified |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| amounts
required | Array of integers (cents) \= 2 items \[ items \[ 1 .. 100 \] \]
In live mode, an array containing the two micro deposits (in cents) placed in the bank account. In test mode, no micro deposits will be placed, so any two integers between `1` and `100` will work. |
### Responses
**200**
Returns a bank\_account object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| routing\_number
required | string \= 9 characters
Must be a [valid US routing number](https://www.frbservices.org/)
. |
| account\_number
required | string <= 17 characters |
| account\_type
required | string
Enum: "company" "individual"
The type of entity that holds the account. |
| signatory
required | string <= 30 characters
The signatory associated with your account. This name will be printed on checks created with this bank account. If you prefer to use a custom signature image on your checks instead, please create your bank account from the [Dashboard](https://dashboard.lob.com/#/login)
. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "bank\_account"
Value: "bank\_account"
Value is resource type. |
| id
required | string (bank\_id) ^bank\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bank_`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| check\_template | string
Enum: "common" "jpm"
The check template used for printing. The defualt value is `common`. If you bank with JP Morgan Chase and wish to use Positive Pay use the `jpm` template. `jpm` requires additional information to be provided. |
| fractional\_routing\_number | string
The fractional routing number for your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the fractional routing number associated with your home bank institution. |
| city | string
The city associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the city associated with your home bank institution. |
| state | string
The state associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the state associated with your home bank institution. |
| zipcode | string
The zipcode associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the zipcode associated with your home bank institution. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| signature\_url | string or null^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
to the signature image. |
| bank\_name | string
The name of the bank based on the provided routing number, e.g. `JPMORGAN CHASE BANK`. |
| verified | boolean
Default: false
A bank account must be verified before a check can be created. More info [here](https://docs.lob.com/#operation/bank_account_verify)
. |
**default**
Error
post/bank\_accounts/{bank\_id}/verify
production
https://api.lob.com/v1/bank\_accounts/{bank\_id}/verify
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "amounts": [ * 1, * 100 ] }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "bank_8cad8df5354d33f", * "signature_url": "[https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a](https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a) ", * "description": "Test Bank Account", * "metadata": { }, * "routing_number": "322271627", * "fractional_routing_number": "25-3/440", * "check_template": "jpm", * "account_number": "123456789", * "account_type": "company", * "signatory": "John Doe", * "bank_name": "J.P. MORGAN CHASE BANK, N.A.,", * "bank_city": "Columbus", * "bank_state": "OH", * "bank_zip": "43240", * "verified": false, * "date_created": "2015-11-06T19:24:24.440Z", * "date_modified": "2015-11-06T19:24:24.440Z", * "object": "bank_account" }`
[](https://docs.lob.com/#tag/Bank-Accounts/operation/bank_account_retrieve)
Retrieve
------------------------------------------------------------------------------------
Retrieves the details of an existing bank account. You need only supply the unique bank account identifier that was returned upon bank account creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| bank\_id
required | string (bank\_id) ^bank\_\[a-zA-Z0-9\]+$
id of the bank account |
### Responses
**200**
Returns a bank account object
##### Response Schema: application/json
| | |
| --- | --- |
| routing\_number
required | string \= 9 characters
Must be a [valid US routing number](https://www.frbservices.org/)
. |
| account\_number
required | string <= 17 characters |
| account\_type
required | string
Enum: "company" "individual"
The type of entity that holds the account. |
| signatory
required | string <= 30 characters
The signatory associated with your account. This name will be printed on checks created with this bank account. If you prefer to use a custom signature image on your checks instead, please create your bank account from the [Dashboard](https://dashboard.lob.com/#/login)
. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "bank\_account"
Value: "bank\_account"
Value is resource type. |
| id
required | string (bank\_id) ^bank\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bank_`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| check\_template | string
Enum: "common" "jpm"
The check template used for printing. The defualt value is `common`. If you bank with JP Morgan Chase and wish to use Positive Pay use the `jpm` template. `jpm` requires additional information to be provided. |
| fractional\_routing\_number | string
The fractional routing number for your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the fractional routing number associated with your home bank institution. |
| city | string
The city associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the city associated with your home bank institution. |
| state | string
The state associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the state associated with your home bank institution. |
| zipcode | string
The zipcode associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the zipcode associated with your home bank institution. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| signature\_url | string or null^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
to the signature image. |
| bank\_name | string
The name of the bank based on the provided routing number, e.g. `JPMORGAN CHASE BANK`. |
| verified | boolean
Default: false
A bank account must be verified before a check can be created. More info [here](https://docs.lob.com/#operation/bank_account_verify)
. |
**default**
Error
get/bank\_accounts/{bank\_id}
production
https://api.lob.com/v1/bank\_accounts/{bank\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl https://api.lob.com/v1/bank\_accounts/bank\_8cad8df5354d33f \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "bank_8cad8df5354d33f", * "signature_url": "[https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a](https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a) ", * "description": "Test Bank Account", * "metadata": { }, * "routing_number": "322271627", * "fractional_routing_number": "25-3/440", * "check_template": "jpm", * "account_number": "123456789", * "account_type": "company", * "signatory": "John Doe", * "bank_name": "J.P. MORGAN CHASE BANK, N.A.,", * "bank_city": "Columbus", * "bank_state": "OH", * "bank_zip": "43240", * "verified": false, * "date_created": "2015-11-06T19:24:24.440Z", * "date_modified": "2015-11-06T19:24:24.440Z", * "object": "bank_account" }`
[](https://docs.lob.com/#tag/Bank-Accounts/operation/bank_account_delete)
Delete
--------------------------------------------------------------------------------
Permanently deletes a bank account. It cannot be undone.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| bank\_id
required | string (bank\_id) ^bank\_\[a-zA-Z0-9\]+$
id of the bank account |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (bank\_id) ^bank\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bank_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/bank\_accounts/{bank\_id}
production
https://api.lob.com/v1/bank\_accounts/{bank\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/bank\_accounts/bank\_3e64d9904356b20 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "bank_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/Bank-Accounts/operation/bank_accounts_list)
List
-----------------------------------------------------------------------------
Returns a list of your bank accounts. The bank accounts are returned sorted by creation date, with the most recently created bank accounts appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` bank\_accounts. Each entry in the array is a separate bank\_account. The previous and next page of bank\_accounts can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more bank\_accounts are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (bank\_account)
list of bank\_accounts |
**default**
Error
get/bank\_accounts
production
https://api.lob.com/v1/bank\_accounts
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/bank\_accounts?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "bank_0e3fb07eba0b35b", * "signature_url": "[https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a](https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a) ", * "description": "Example bank account", * "metadata": { }, * "routing_number": "122100024", * "account_number": "1234564789", * "account_type": "company", * "signatory": "John Doe", * "bank_name": "JPMORGAN CHASE BANK, NA", * "verified": true, * "date_created": "2019-03-30T13:13:22.200Z", * "date_modified": "2019-03-30T13:13:23.385Z", * "object": "bank_account" }, * { * "id": "bank_eba93f7de3c02d9", * "description": "Example bank account", * "metadata": { }, * "routing_number": "122100024", * "account_number": "1234564789", * "account_type": "company", * "signatory": "John Doe", * "bank_name": "JPMORGAN CHASE BANK, NA", * "verified": true, * "date_created": "2019-03-30T13:11:06.809Z", * "date_modified": "2019-03-30T13:11:07.872Z", * "object": "bank_account" } ], * "object": "list", * "next_url": "[https://api.lob.com/v1/bank_accounts?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0zMFQxMzoxMTowNi44MDlaIiwiaWRPZmZzZXQiOiJiYW5rX2ViYTkzZjdkZTNjMDJkOSJ9](https://api.lob.com/v1/bank_accounts?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0zMFQxMzoxMTowNi44MDlaIiwiaWRPZmZzZXQiOiJiYW5rX2ViYTkzZjdkZTNjMDJkOSJ9) ", * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Bank-Accounts/operation/bank_account_create)
Create
--------------------------------------------------------------------------------
Creates a new bank account with the provided properties. Bank accounts created in live mode will need to be verified via micro deposits before being able to send live checks. The deposits will appear in the bank account in 2-3 business days and have the description "VERIFICATION".
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| routing\_number
required | string \= 9 characters
Must be a [valid US routing number](https://www.frbservices.org/)
. |
| account\_number
required | string <= 17 characters |
| account\_type
required | string
Enum: "company" "individual"
The type of entity that holds the account. |
| signatory
required | string <= 30 characters
The signatory associated with your account. This name will be printed on checks created with this bank account. If you prefer to use a custom signature image on your checks instead, please create your bank account from the [Dashboard](https://dashboard.lob.com/#/login)
. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| check\_template | string
Enum: "common" "jpm"
The check template used for printing. The defualt value is `common`. If you bank with JP Morgan Chase and wish to use Positive Pay use the `jpm` template. `jpm` requires additional information to be provided. |
| fractional\_routing\_number | string
The fractional routing number for your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the fractional routing number associated with your home bank institution. |
| city | string
The city associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the city associated with your home bank institution. |
| state | string
The state associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the state associated with your home bank institution. |
| zipcode | string
The zipcode associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the zipcode associated with your home bank institution. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
### Responses
**200**
Returns a bank\_account object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| routing\_number
required | string \= 9 characters
Must be a [valid US routing number](https://www.frbservices.org/)
. |
| account\_number
required | string <= 17 characters |
| account\_type
required | string
Enum: "company" "individual"
The type of entity that holds the account. |
| signatory
required | string <= 30 characters
The signatory associated with your account. This name will be printed on checks created with this bank account. If you prefer to use a custom signature image on your checks instead, please create your bank account from the [Dashboard](https://dashboard.lob.com/#/login)
. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "bank\_account"
Value: "bank\_account"
Value is resource type. |
| id
required | string (bank\_id) ^bank\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bank_`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| check\_template | string
Enum: "common" "jpm"
The check template used for printing. The defualt value is `common`. If you bank with JP Morgan Chase and wish to use Positive Pay use the `jpm` template. `jpm` requires additional information to be provided. |
| fractional\_routing\_number | string
The fractional routing number for your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the fractional routing number associated with your home bank institution. |
| city | string
The city associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the city associated with your home bank institution. |
| state | string
The state associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the state associated with your home bank institution. |
| zipcode | string
The zipcode associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the zipcode associated with your home bank institution. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| signature\_url | string or null^https://lob-assets.com/(letters\|postcards\|ba...Show pattern
A [signed link](https://docs.lob.com/#section/Asset-URLs)
to the signature image. |
| bank\_name | string
The name of the bank based on the provided routing number, e.g. `JPMORGAN CHASE BANK`. |
| verified | boolean
Default: false
A bank account must be verified before a check can be created. More info [here](https://docs.lob.com/#operation/bank_account_verify)
. |
**default**
Error
post/bank\_accounts
production
https://api.lob.com/v1/bank\_accounts
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "Test Bank Account", * "routing_number": "322271627", * "account_number": "123456789", * "signatory": "Jane Doe", * "account_type": "individual", * "metadata": { * "spiffy": "true" } }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "bank_8cad8df5354d33f", * "signature_url": "[https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a](https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a) ", * "description": "Test Bank Account", * "metadata": { }, * "routing_number": "322271627", * "fractional_routing_number": "25-3/440", * "check_template": "jpm", * "account_number": "123456789", * "account_type": "company", * "signatory": "John Doe", * "bank_name": "J.P. MORGAN CHASE BANK, N.A.,", * "bank_city": "Columbus", * "bank_state": "OH", * "bank_zip": "43240", * "verified": false, * "date_created": "2015-11-06T19:24:24.440Z", * "date_modified": "2015-11-06T19:24:24.440Z", * "object": "bank_account" }`
[](https://docs.lob.com/#tag/Templates)
Templates
=================================================
These API endpoints allow you to create, retrieve, update and delete reusable HTML templates for use with the Print & Mail API.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Templates/operation/template_retrieve)
Retrieve
----------------------------------------------------------------------------
Retrieves the details of an existing template. You need only supply the unique template identifier that was returned upon template creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
id of the template |
### Responses
**200**
Returns a template object
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `tmpl_`. ID of a saved [HTML template](https://docs.lob.com/#section/HTML-Templates)
. |
| versions
required | Array of objects (template\_version)
An array of all non-deleted [version objects](https://docs.lob.com/#tag/Template-Versions)
associated with the template. |
| published\_version
required | object (template\_version)
The template's currently published version. This version will be used in any Print & Mail API requests that reference the specified template. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| object | string
Default: "template"
Value: "template"
Value is resource type. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
get/templates/{tmpl\_id}
production
https://api.lob.com/v1/templates/{tmpl\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl https://api.lob.com/v1/templates/tmpl\_c94e83ca2cd5121 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "tmpl_c94e83ca2cd5121", * "description": "Test Template", * "versions": [ * { * "id": "vrsn_362184d96d9b0c9", * "suggest_json_editor": true, * "description": "Test Template", * "engine": "legacy", * "html": "HTML for {{name}}", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "version" } ], * "published_version": { * "id": "vrsn_362184d96d9b0c9", * "suggest_json_editor": false, * "description": "Test Template", * "engine": "handlebars", * "html": "HTML for {{name}}", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "version" }, * "metadata": { }, * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "template" }`
[](https://docs.lob.com/#tag/Templates/operation/template_update)
Update
------------------------------------------------------------------------
Updates the description and/or published version of the template with the given id. To update the template's html, create a new version of the template.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
id of the template |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| published\_version | string^vrsn\_\[a-zA-Z0-9\]+$
The ID of the published version of a template you'd like to update. The published version is the one that will be used in any Print & Mail API requests that reference the specified template. Will err if the referenced `published_version` has been deleted or does not exist. |
### Responses
**200**
Returns the updated template object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `tmpl_`. ID of a saved [HTML template](https://docs.lob.com/#section/HTML-Templates)
. |
| versions
required | Array of objects (template\_version)
An array of all non-deleted [version objects](https://docs.lob.com/#tag/Template-Versions)
associated with the template. |
| published\_version
required | object (template\_version)
The template's currently published version. This version will be used in any Print & Mail API requests that reference the specified template. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| object | string
Default: "template"
Value: "template"
Value is resource type. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
post/templates/{tmpl\_id}
production
https://api.lob.com/v1/templates/{tmpl\_id}
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Updated Example", * "published_version": "vrsn_a" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "tmpl_c94e83ca2cd5121", * "description": "Test Template", * "versions": [ * { * "id": "vrsn_362184d96d9b0c9", * "suggest_json_editor": true, * "description": "Test Template", * "engine": "legacy", * "html": "HTML for {{name}}", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "version" } ], * "published_version": { * "id": "vrsn_362184d96d9b0c9", * "suggest_json_editor": false, * "description": "Test Template", * "engine": "handlebars", * "html": "HTML for {{name}}", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "version" }, * "metadata": { }, * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "template" }`
[](https://docs.lob.com/#tag/Templates/operation/template_delete)
Delete
------------------------------------------------------------------------
Permanently deletes a template. Deleting a template also deletes its associated versions. Deleted templates can not be used to create postcard, letter, or check resources.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
id of the template |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `tmpl_`. ID of a saved [HTML template](https://docs.lob.com/#section/HTML-Templates)
. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/templates/{tmpl\_id}
production
https://api.lob.com/v1/templates/{tmpl\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/templates/tmpl\_df934eeda694203 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "value": { * "id": "tmpl_123456789", * "deleted": true } }`
[](https://docs.lob.com/#tag/Templates/operation/templates_list)
List
---------------------------------------------------------------------
Returns a list of your templates. The templates are returned sorted by creation date, with the most recently created templates appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Filter by metadata key-value pair\`. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` templates. Each entry in the array is a separate template. The previous and next page of templates can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more templates are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (template)
list of templates |
**default**
Error
get/templates
production
https://api.lob.com/v1/templates
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/templates?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "tmpl_d5a5a89da9106f8", * "description": "Test Template", * "versions": [ * { * "id": "vrsn_232a02fb8224791", * "suggest_json_editor": true, * "description": "Test Template", * "engine": "legacy", * "html": "HTML for ", * "date_created": "2019-07-27T23:49:01.512Z", * "date_modified": "2019-07-27T23:49:01.512Z", * "object": "version" } ], * "published_version": { * "id": "vrsn_232a02fb8224791", * "suggest_json_editor": false, * "description": "Test Template", * "engine": "handlebars", * "html": "HTML for ", * "date_created": "2019-07-27T23:49:01.512Z", * "date_modified": "2019-07-27T23:49:01.512Z", * "object": "version" }, * "metadata": { }, * "date_created": "2019-07-27T23:49:01.511Z", * "date_modified": "2019-07-27T23:49:01.511Z", * "object": "template" }, * { * "id": "tmpl_59b2150ae120887", * "description": "Test Template", * "versions": [ * { * "id": "vrsn_2a7eb63ccb795b9", * "description": "Test Template", * "html": "HTML for ", * "date_created": "2019-03-29T10:22:34.643Z", * "date_modified": "2019-03-29T10:22:34.643Z", * "object": "version" } ], * "published_version": { * "id": "vrsn_2a7eb63ccb795b9", * "description": "Test Template", * "html": "HTML for ", * "date_created": "2019-03-29T10:22:34.643Z", * "date_modified": "2019-03-29T10:22:34.643Z", * "object": "version" }, * "metadata": { }, * "date_created": "2019-03-29T10:22:34.642Z", * "date_modified": "2019-03-29T10:22:34.642Z", * "object": "template" } ], * "object": "list", * "previous_url": null, * "next_url": "[https://api.lob.com/v1/templates?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0yOVQxMDoyMjozNC42NDJaIiwiaWRPZmZzZXQiOiJ0bXBsXzU5YjIxNTBhZTEyMDg4NyJ9](https://api.lob.com/v1/templates?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0yOVQxMDoyMjozNC42NDJaIiwiaWRPZmZzZXQiOiJ0bXBsXzU5YjIxNTBhZTEyMDg4NyJ9) ", * "count": 2 }`
[](https://docs.lob.com/#tag/Templates/operation/create_template)
Create
------------------------------------------------------------------------
Creates a new template for use with the Print & Mail API. In Live mode, you can only have as many non-deleted templates as allotted in your current [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
. If you attempt to create a template past your limit, you will receive a `403` error. There is no limit in Test mode.
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| html
required | string (template\_html) <= 100000 characters
An HTML string of less than 100,000 characters to be used as the `published_version` of this template. See [here](https://docs.lob.com/#section/HTML-Examples)
for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
* [Postcards](https://docs.lob.com/#operation/postcard_create)
- `front` and `back`
* [Self Mailers](https://docs.lob.com/#operation/self_mailer_create)
- `inside` and `outside`
* [Letters](https://docs.lob.com/#operation/letter_create)
- `file`
* [Checks](https://docs.lob.com/#operation/check_create)
- `check_bottom` and `attachment`
* [Cards](https://docs.lob.com/#operation/card_create)
- `front` and `back`
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a `{{#users}}` opening tag without the corresponding closing tag `{{/users}}`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| engine | string or null (engine)
Default: "legacy"
Enum: "legacy" "handlebars"
The engine used to combine HTML template with merge variables.
* `legacy` - Lob's original engine
* `handlebars` |
| required\_vars | Array of strings (template\_required\_vars)
An array of required variables to be used in a template. Only available for `handlebars` templates. |
### Responses
**200**
Returns a template object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `tmpl_`. ID of a saved [HTML template](https://docs.lob.com/#section/HTML-Templates)
. |
| versions
required | Array of objects (template\_version)
An array of all non-deleted [version objects](https://docs.lob.com/#tag/Template-Versions)
associated with the template. |
| published\_version
required | object (template\_version)
The template's currently published version. This version will be used in any Print & Mail API requests that reference the specified template. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| object | string
Default: "template"
Value: "template"
Value is resource type. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
post/templates
production
https://api.lob.com/v1/templates
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "description": "demo", * "html": "HTML for {{name}}", * "metadata": { * "spiffy": "true" }, * "engine": "handlebars" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "tmpl_c94e83ca2cd5121", * "description": "Test Template", * "versions": [ * { * "id": "vrsn_362184d96d9b0c9", * "suggest_json_editor": true, * "description": "Test Template", * "engine": "legacy", * "html": "HTML for {{name}}", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "version" } ], * "published_version": { * "id": "vrsn_362184d96d9b0c9", * "suggest_json_editor": false, * "description": "Test Template", * "engine": "handlebars", * "html": "HTML for {{name}}", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "version" }, * "metadata": { }, * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "template" }`
[](https://docs.lob.com/#tag/Resource-Proofs)
Resource Proofs
=============================================================
The resource proofs endpoint allows you to create a final rendering of any template. This is best practice to ensure that you are visually validating your creative before any mail pieces use the template. The API provides endpoints for creating, updating, and retrieving template proofs.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Resource-Proofs/operation/resource_proof_retrieve)
Retrieve
----------------------------------------------------------------------------------------
Retrieves the details of an existing resource proof. You need only supply the unique resource proof identifier.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| res\_prf\_id
required | string (res\_prf\_id) ^res\_prf\_\[a-zA-Z0-9\]+$
id of the resource proof |
### Responses
**200**
Returns a resource proof object
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (res\_prf\_id) ^res\_prf\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `res_prf_`. |
| resource\_type
required | string (res\_prf\_resource\_type)
Enum: "postcard" "letter" "self\_mailer"
The type of resource to generate a proof for. |
| status
required | string (res\_prf\_status)
Enum: "processing" "completed" "failed"
The processing status of the resource proof. |
| thumbnails
required | Array of objects (thumbnail)
Thumbnail images of the resource proof. |
| errors
required | Array of objects (issue\_entry)
Errors encountered during processing. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "resource\_proof"
Value is resource type. |
| template\_id | string or null
The template ID associated with the resource proof, if any. |
| url | string or null
A URL to the resource proof PDF. |
**default**
Error
get/resource\_proofs/{res\_prf\_id}
production
https://api.lob.com/v1/resource\_proofs/{res\_prf\_id}
### Request samples
* CURL
Copy
curl https://api.lob.com/v1/resource\_proofs/res\_prf\_example123 \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "res_prf_example123", * "template_id": null, * "resource_type": "postcard", * "status": "completed", * "thumbnails": [ * { * "small": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_small_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_small_1.png) ", * "medium": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_medium_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_medium_1.png) ", * "large": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_large_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_large_1.png) " } ], * "url": "[https://lob-assets.com/resource-proofs/res_prf_example123.pdf](https://lob-assets.com/resource-proofs/res_prf_example123.pdf) ", * "errors": [ ], * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "resource_proof" }`
[](https://docs.lob.com/#tag/Resource-Proofs/operation/resource_proof_update)
Update
------------------------------------------------------------------------------------
Updates the specified resource proof.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| res\_prf\_id
required | string (res\_prf\_id) ^res\_prf\_\[a-zA-Z0-9\]+$
id of the resource proof |
##### Request Body schema: application/json
| | |
| --- | --- |
| template\_id | string or null
The template ID to associate with the resource proof. |
### Responses
**200**
Returns an updated resource proof object
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (res\_prf\_id) ^res\_prf\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `res_prf_`. |
| resource\_type
required | string (res\_prf\_resource\_type)
Enum: "postcard" "letter" "self\_mailer"
The type of resource to generate a proof for. |
| status
required | string (res\_prf\_status)
Enum: "processing" "completed" "failed"
The processing status of the resource proof. |
| thumbnails
required | Array of objects (thumbnail)
Thumbnail images of the resource proof. |
| errors
required | Array of objects (issue\_entry)
Errors encountered during processing. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "resource\_proof"
Value is resource type. |
| template\_id | string or null
The template ID associated with the resource proof, if any. |
| url | string or null
A URL to the resource proof PDF. |
**default**
Error
patch/resource\_proofs/{res\_prf\_id}
production
https://api.lob.com/v1/resource\_proofs/{res\_prf\_id}
### Request samples
* Payload
* CURL
Content type
application/json
Copy
`{ * "template_id": "tmpl_a1234dddg" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "res_prf_example123", * "template_id": null, * "resource_type": "postcard", * "status": "completed", * "thumbnails": [ * { * "small": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_small_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_small_1.png) ", * "medium": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_medium_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_medium_1.png) ", * "large": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_large_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_large_1.png) " } ], * "url": "[https://lob-assets.com/resource-proofs/res_prf_example123.pdf](https://lob-assets.com/resource-proofs/res_prf_example123.pdf) ", * "errors": [ ], * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "resource_proof" }`
[](https://docs.lob.com/#tag/Resource-Proofs/operation/resource_proof_create)
Create
------------------------------------------------------------------------------------
Creates a new resource proof with the provided properties.
##### Authorizations:
_basicAuth_
##### Request Body schema: application/json
| | |
| --- | --- |
| template\_id | string or null
The template ID to associate with the resource proof. |
| resource\_type | string
The type of resource to generate a proof for.
self\_mailerletterpostcardpostcard |
| resource\_parameters | object (postcard\_resource\_parameters) |
### Responses
**201**
Returns a resource proof object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (res\_prf\_id) ^res\_prf\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `res_prf_`. |
| resource\_type
required | string (res\_prf\_resource\_type)
Enum: "postcard" "letter" "self\_mailer"
The type of resource to generate a proof for. |
| status
required | string (res\_prf\_status)
Enum: "processing" "completed" "failed"
The processing status of the resource proof. |
| thumbnails
required | Array of objects (thumbnail)
Thumbnail images of the resource proof. |
| errors
required | Array of objects (issue\_entry)
Errors encountered during processing. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "resource\_proof"
Value is resource type. |
| template\_id | string or null
The template ID associated with the resource proof, if any. |
| url | string or null
A URL to the resource proof PDF. |
**default**
Error
post/resource\_proofs
production
https://api.lob.com/v1/resource\_proofs
### Request samples
* Payload
* CURL
Content type
application/json
Copy
Expand all Collapse all
`{ * "resource_type": "postcard", * "resource_parameters": { * "front": "tmpl_a1234dddg", * "back": "tmpl_a1234dddg", * "to": "adr_a1234dddg" } }`
### Response samples
* 201
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "res_prf_example123", * "template_id": null, * "resource_type": "postcard", * "status": "completed", * "thumbnails": [ * { * "small": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_small_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_small_1.png) ", * "medium": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_medium_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_medium_1.png) ", * "large": "[https://lob-assets.com/resource-proofs/res_prf_example123_thumb_large_1.png](https://lob-assets.com/resource-proofs/res_prf_example123_thumb_large_1.png) " } ], * "url": "[https://lob-assets.com/resource-proofs/res_prf_example123.pdf](https://lob-assets.com/resource-proofs/res_prf_example123.pdf) ", * "errors": [ ], * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "resource_proof" }`
[](https://docs.lob.com/#tag/Template-Versions)
Template Versions
=================================================================
These API endpoints allow you to create, retrieve, update and delete versions of reusable HTML templates for use with the Print & Mail API.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Template-Versions/operation/template_version_retrieve)
Retrieve
--------------------------------------------------------------------------------------------
Retrieves the template version with the given template and version ids.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
The ID of the template to which the version belongs. |
| vrsn\_id
required | string (vrsn\_id) ^vrsn\_\[a-zA-Z0-9\]+$
id of the template\_version |
### Responses
**200**
Returns the template version with the given template and version ids.
##### Response Schema: application/json
| | |
| --- | --- |
| html
required | string (template\_html) <= 100000 characters
An HTML string of less than 100,000 characters to be used as the `published_version` of this template. See [here](https://docs.lob.com/#section/HTML-Examples)
for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
* [Postcards](https://docs.lob.com/#operation/postcard_create)
- `front` and `back`
* [Self Mailers](https://docs.lob.com/#operation/self_mailer_create)
- `inside` and `outside`
* [Letters](https://docs.lob.com/#operation/letter_create)
- `file`
* [Checks](https://docs.lob.com/#operation/check_create)
- `check_bottom` and `attachment`
* [Cards](https://docs.lob.com/#operation/card_create)
- `front` and `back`
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a `{{#users}}` opening tag without the corresponding closing tag `{{/users}}`. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "version"
Value: "version"
Value is resource type. |
| id
required | string (vrsn\_id) ^vrsn\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `vrsn_`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| engine | string or null (engine)
Default: "legacy"
Enum: "legacy" "handlebars"
The engine used to combine HTML template with merge variables.
* `legacy` - Lob's original engine
* `handlebars` |
| required\_vars | Array of strings (template\_required\_vars)
An array of required variables to be used in a template. Only available for `handlebars` templates. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| suggest\_json\_editor | boolean
Used by frontend, true if the template uses advanced features. |
| merge\_variables | object
Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings. |
**default**
Error
get/templates/{tmpl\_id}/versions/{vrsn\_id}
production
https://api.lob.com/v1/templates/{tmpl\_id}/versions/{vrsn\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl https://api.lob.com/v1/templates/tmpl\_c94e83ca2cd5121/versions/vrsn\_534e339882d2282 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "vrsn_534e339882d2282", * "description": "Second Version", * "html": "Second HTML for {{name}}", * "date_created": "2017-11-09T04:49:38.016Z", * "date_modified": "2017-11-09T04:49:38.016Z", * "object": "version" }`
[](https://docs.lob.com/#tag/Template-Versions/operation/template_version_update)
Update
----------------------------------------------------------------------------------------
Updates the template version with the given template and version ids.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
The ID of the template to which the version belongs. |
| vrsn\_id
required | string (vrsn\_id) ^vrsn\_\[a-zA-Z0-9\]+$
id of the template\_version |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| engine | string or null (engine)
Default: "legacy"
Enum: "legacy" "handlebars"
The engine used to combine HTML template with merge variables.
* `legacy` - Lob's original engine
* `handlebars` |
| required\_vars | Array of strings (template\_required\_vars)
An array of required variables to be used in a template. Only available for `handlebars` templates. |
### Responses
**200**
Returns the template version with the given template and version ids.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| html
required | string (template\_html) <= 100000 characters
An HTML string of less than 100,000 characters to be used as the `published_version` of this template. See [here](https://docs.lob.com/#section/HTML-Examples)
for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
* [Postcards](https://docs.lob.com/#operation/postcard_create)
- `front` and `back`
* [Self Mailers](https://docs.lob.com/#operation/self_mailer_create)
- `inside` and `outside`
* [Letters](https://docs.lob.com/#operation/letter_create)
- `file`
* [Checks](https://docs.lob.com/#operation/check_create)
- `check_bottom` and `attachment`
* [Cards](https://docs.lob.com/#operation/card_create)
- `front` and `back`
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a `{{#users}}` opening tag without the corresponding closing tag `{{/users}}`. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "version"
Value: "version"
Value is resource type. |
| id
required | string (vrsn\_id) ^vrsn\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `vrsn_`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| engine | string or null (engine)
Default: "legacy"
Enum: "legacy" "handlebars"
The engine used to combine HTML template with merge variables.
* `legacy` - Lob's original engine
* `handlebars` |
| required\_vars | Array of strings (template\_required\_vars)
An array of required variables to be used in a template. Only available for `handlebars` templates. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| suggest\_json\_editor | boolean
Used by frontend, true if the template uses advanced features. |
| merge\_variables | object
Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings. |
**default**
Error
post/templates/{tmpl\_id}/versions/{vrsn\_id}
production
https://api.lob.com/v1/templates/{tmpl\_id}/versions/{vrsn\_id}
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Some description" }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "vrsn_534e339882d2282", * "description": "Second Version", * "html": "Second HTML for {{name}}", * "date_created": "2017-11-09T04:49:38.016Z", * "date_modified": "2017-11-09T04:49:38.016Z", * "object": "version" }`
[](https://docs.lob.com/#tag/Template-Versions/operation/template_version_delete)
Delete
----------------------------------------------------------------------------------------
Permanently deletes a template version. A template's `published_version` can not be deleted.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
The ID of the template to which the version belongs. |
| vrsn\_id
required | string (vrsn\_id) ^vrsn\_\[a-zA-Z0-9\]+$
id of the template\_version |
### Responses
**200**
Deleted
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (vrsn\_id) ^vrsn\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `vrsn_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/templates/{tmpl\_id}/versions/{vrsn\_id}
production
https://api.lob.com/v1/templates/{tmpl\_id}/versions/{vrsn\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X DELETE https://api.lob.com/v1/templates/tmpl\_4aa14648113e45b/versions/vrsn\_534e339882d2282 \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "value": { * "id": "vrsn_123456789", * "deleted": true } }`
[](https://docs.lob.com/#tag/Template-Versions/operation/template_versions_list)
List
-------------------------------------------------------------------------------------
Returns a list of template versions for the given template ID. The template versions are sorted by creation date, with the most recently created appearing first.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
The ID of the template associated with the retrieved versions |
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` template versions. Each entry in the array is a separate template version object. The previous and next page of template versions can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more template versions are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (template\_version)
list of template versions |
**default**
Error
get/templates/{tmpl\_id}/versions
production
https://api.lob.com/v1/templates/{tmpl\_id}/versions
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/templates/tmpl\_ea6e6a1abf01703/versions?limit=2" \\
-u test\_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "vrsn_4d6ff5d868bf630", * "description": "Second Version", * "html": "Second HTML for ", * "date_created": "2017-11-09T05:09:03.665Z", * "date_modified": "2018-05-22T22:01:10.479Z", * "object": "version" }, * { * "id": "vrsn_2a17159c1911919", * "description": "Test Template", * "html": "HTML for ", * "date_created": "2017-11-09T05:08:40.004Z", * "date_modified": "2018-05-22T22:01:11.309Z", * "object": "version" } ], * "object": "list", * "count": 2 }`
[](https://docs.lob.com/#tag/Template-Versions/operation/create_template_version)
Create
----------------------------------------------------------------------------------------
Creates a new template version attached to the specified template.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| tmpl\_id
required | string (tmpl\_id) ^tmpl\_\[a-zA-Z0-9\]+$
The ID of the template the new version will be attached to |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| html
required | string (template\_html) <= 100000 characters
An HTML string of less than 100,000 characters to be used as the `published_version` of this template. See [here](https://docs.lob.com/#section/HTML-Examples)
for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
* [Postcards](https://docs.lob.com/#operation/postcard_create)
- `front` and `back`
* [Self Mailers](https://docs.lob.com/#operation/self_mailer_create)
- `inside` and `outside`
* [Letters](https://docs.lob.com/#operation/letter_create)
- `file`
* [Checks](https://docs.lob.com/#operation/check_create)
- `check_bottom` and `attachment`
* [Cards](https://docs.lob.com/#operation/card_create)
- `front` and `back`
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a `{{#users}}` opening tag without the corresponding closing tag `{{/users}}`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| engine | string or null (engine)
Default: "legacy"
Enum: "legacy" "handlebars"
The engine used to combine HTML template with merge variables.
* `legacy` - Lob's original engine
* `handlebars` |
| required\_vars | Array of strings (template\_required\_vars)
An array of required variables to be used in a template. Only available for `handlebars` templates. |
### Responses
**200**
Returns the template version with the given template and version ids.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| html
required | string (template\_html) <= 100000 characters
An HTML string of less than 100,000 characters to be used as the `published_version` of this template. See [here](https://docs.lob.com/#section/HTML-Examples)
for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
* [Postcards](https://docs.lob.com/#operation/postcard_create)
- `front` and `back`
* [Self Mailers](https://docs.lob.com/#operation/self_mailer_create)
- `inside` and `outside`
* [Letters](https://docs.lob.com/#operation/letter_create)
- `file`
* [Checks](https://docs.lob.com/#operation/check_create)
- `check_bottom` and `attachment`
* [Cards](https://docs.lob.com/#operation/card_create)
- `front` and `back`
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a `{{#users}}` opening tag without the corresponding closing tag `{{/users}}`. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "version"
Value: "version"
Value is resource type. |
| id
required | string (vrsn\_id) ^vrsn\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `vrsn_`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| engine | string or null (engine)
Default: "legacy"
Enum: "legacy" "handlebars"
The engine used to combine HTML template with merge variables.
* `legacy` - Lob's original engine
* `handlebars` |
| required\_vars | Array of strings (template\_required\_vars)
An array of required variables to be used in a template. Only available for `handlebars` templates. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| suggest\_json\_editor | boolean
Used by frontend, true if the template uses advanced features. |
| merge\_variables | object
Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings. |
**default**
Error
post/templates/{tmpl\_id}/versions
production
https://api.lob.com/v1/templates/{tmpl\_id}/versions
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Some Description", * "html": "HTML for {{name}}" }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "vrsn_534e339882d2282", * "description": "Second Version", * "html": "Second HTML for {{name}}", * "date_created": "2017-11-09T04:49:38.016Z", * "date_modified": "2017-11-09T04:49:38.016Z", * "object": "version" }`
[](https://docs.lob.com/#tag/Template-Design)
Template Design
=============================================================
[](https://docs.lob.com/#tag/Template-Design/HTML-Templates)
HTML Templates
---------------------------------------------------------------------------
You can save commonly used HTML as templates within Lob to more easily manage them. You can reference your saved templates in postcard, letter, and check requests instead of having to pass a long HTML string on each request. Additionally, you can make changes to your HTML templates and update them independently, without having to touch your API integration. Templates can be created, edited, and viewed on your [Dashboard](https://dashboard.lob.com/#/templates)
. To use a template in a postcard, letter, or check, see the documentation for each endpoint below. For help using templates, check out our [HTML Templates Guide](https://help.lob.com/print-and-mail/designing-mail-creatives/dynamic-personalization#html-templates-1)
or get started with a [pre-designed template from our gallery](https://lob.com/template-gallery)
. In Live mode, you can only have as many templates as allotted in your current [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
. There is no limit in Test mode.
If you'd like to interact with templates programmatically, check out our Beta Program for API access to the [HTML Templates Endpoints](https://docs.lob.com/#tag/Templates)
.
### Example Create Request using HTML Templates
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-d "description=Demo Postcard job" \
-d "to=adr_78c304d54912c502" \
-d "from=adr_61a0865c8c573139" \
-d "front=tmpl_b846a20859ae11a" \
-d "back=tmpl_01b0d396a10c268" \
-d "merge_variables[name]=Harry"
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Template-Design/HTML-Examples)
HTML Examples
-------------------------------------------------------------------------
Use a pre-designed template from our [gallery](https://lob.com/resources/template-gallery)
or follow these basic [guidelines](https://github.com/lob/examples)
as starting points for creating custom Postcards, Self Mailers, Letters, and Checks.
Please follow the standards used in these templates, such as:
* For any linked assets, you must use a performant file hosting provider with no rate limits such as Amazon S3.
* Use inline styles or an internal stylesheet, do not link to external stylesheets.
* Link to images that are 300DPI and sized at the final desired size on the physical mailing. For example, for a photo that is desired to be 1in x 1in on the final postcard, the image asset should be sized at 1in x 1in at 300DPI (which equates to 300px by 300px).
* The sum of all linked assets should not exceed 5MB in file size.
* Use `-webkit` prefixes for CSS properties when recommended [here](http://shouldiprefix.com/)
.
Because different browsers have varying user-agent styles, the HTML you see in your browser will not always look identical to what is produced through the API. It is **strongly** recommended that you test all HTML requests by reviewing the final PDF files in your Test Environment, as these are the files that will be printed.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Template-Design/Image-Prepping)
Image Prepping
---------------------------------------------------------------------------
Currently we support the following file types for all endpoints:
* PDF
* PNG
* JPEG
**Templates**
You can find pre-made templates that already adhere to all of these guidelines here:
* [Postcards](https://docs.lob.com/#tag/Postcards)
* [Letters](https://docs.lob.com/#tag/Letters)
* [Checks](https://docs.lob.com/#tag/Checks)
* [Self Mailers](https://docs.lob.com/#tag/Self-Mailers)
**Prepping All Images**
The following guidelines apply to image types:
* Images should be 300 dpi or higher - PNG/JPEG files with less than 300 dpi will be rejected.
* Your artwork should include a 1/8" border around the final trim size. This means your final file size will be a total of 0.25" larger than your expected printed piece (ie, a 4"x6" postcard should be submitted as 4.25"x6.25"). There is no need to include crop marks in your submitted content.
* Include a safe zone – make sure no critical elements are within 1/8" from the edge of the final size.
* Do not include any additional postage marks or indicia.
* File sizes should be no larger than 5MB.
**Prepping PDFs**
To ensure that you are producing PDF's correctly please follow the guidelines [outlined in our help center here](https://help.lob.com/print-and-mail/designing-mail-creatives/creative-formatting/pdf-preflight-checklist#requirements-for-static-pdfs)
**Prepping PNGs/JPEGs**
To ensure that you are producing PNG's/JPEG's correctly please follow the guidelines below:
* Minimum 300 dpi. The dpi is calculated as (width of image in pixels) / (width of product in inches) and (length of image in pixels) / (length of product in inches). For Example: 1275px x 1875px image used to create a 4.25" x 6.25" postcard has a dpi of 300.
* Submitted images must have the same length to width ratio as the chosen product. Images will not be cropped or stretched by the API.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Template-Design/Standard-PDF-Fonts)
Standard PDF Fonts
-----------------------------------------------------------------------------------
Ideally, all fonts in provided PDFs should be embedded. Embedding a font in a PDF ensures that the final printed product will look as it was designed. Fonts can vary greatly in size and shape, even within the same family. If the exact font that was used to design the artwork is not used to print, the look and placement of the text is not guaranteed to be the same.
In general, requests that provide PDFs with un-embedded fonts will be rejected. We make an exception for "standard fonts", a set of fonts that we have identified as being common. PDFs that contain un-embedded fonts that are found in the list, and match the accepted [font type](https://en.wikipedia.org/wiki/Category:Font_formats)
will be accepted. Otherwise, the request will be rejected.
Font embedding is an essential part of standard PDF workflows. Fonts should be embedded automatically by PDF editing software that are compliant with PDF standards.
Please note, only standard base14 fonts can be Type 1.
| FONT NAME | TYPES |
| --- | --- |
| `Arial` | TrueType, CID TrueType |
| `Arial,Bold` | TrueType, CID TrueType |
| `Arial,BoldItalic` | TrueType, CID TrueType |
| `Arial,Italic` | TrueType, CID TrueType |
| `ArialMT` | TrueType, CID TrueType |
| `Arial-BoldMT` | TrueType |
| `Arial-BoldItalicMT` | TrueType |
| `Arial-ItalicMT` | TrueType |
| `ArialNarrow` | TrueType |
| `ArialNarrow-Bold` | TrueType |
| `Calibri` | TrueType |
| `Calibri-Bold` | TrueType |
| `Calibri-Italic` | TrueType |
| `Courier` | Type 1 |
| `Courier-Oblique` | Type 1 |
| `Courier-Bold` | Type 1 |
| `Courier-BoldOblique` | Type 1 |
| `CourierNewPSMT` | TrueType |
| `CourierNewPS-ItalicMT` | TrueType |
| `CourierNewPS-BoldMT` | TrueType |
| `Helvetica` | Type 1 |
| `Helvetica-Bold` | Type 1 |
| `Helvetica-BoldOblique` | Type 1 |
| `Helvetica-Oblique` | Type 1 |
| `LucidaConsole` | TrueType |
| `MsSansSerif` | TrueType |
| `MsSansSerif,Bold` | TrueType |
| `Symbol` | Type 1, TrueType |
| `Tahoma` | TrueType |
| `Tahoma-Bold` | TrueType |
| `Times-Bold` | Type 1 |
| `Times-BoldItalic` | Type 1 |
| `Times-Italic` | Type 1 |
| `Times-Roman` | Type 1 |
| `TimesNewRomanPS-BoldItalicMT` | TrueType |
| `TimesNewRomanPS-BoldMT` | TrueType |
| `TimesNewRomanPS-ItalicMT` | TrueType |
| `TimesNewRomanPSMT` | TrueType, CID TrueType |
| `TimesNewRomanPSMT,Bold` | TrueType |
| `Verdana` | TrueType |
| `Verdana-Bold` | TrueType |
| `Verdana,Italic` | TrueType |
| `ZapfDingbats` | Type 1 |
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Manage-Mail)
Manage Mail
=====================================================
[](https://docs.lob.com/#tag/Manage-Mail/Cancellation-Windows)
Cancellation Windows
-----------------------------------------------------------------------------------
By default, all new accounts have a 5 minute cancellation window for postcards, self mailers, letters, and checks. Within that timeframe, you can cancel mailings from production, free of charge. Once the window has passed for a postcard, self mailer, letter, or check, the mailing is no longer cancelable. In addition, certain customers can customize their cancellation windows by product in their [Dashboard Settings](https://dashboard.lob.com/#)
. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to automatically gain access to this ability. For more details on this feature, check out our [Cancellation Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#cancellation-windows-4)
.
If you schedule a postcard, self mailer, letter, or check for up to 180 days in the future by supplying the `send_date` parameter, that will override any cancellation window you may have for that product.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Manage-Mail/Scheduled-Mailings)
Scheduled Mailings
-------------------------------------------------------------------------------
Postcards, self mailers, letters, and checks can be scheduled to be sent up to 180 days in advance. You can use this feature to:
* Create automated drip campaigns (e.g. send a postcard at 15, 30, and 60 days)
* Schedule recurring sends
* Plan your mailing schedule ahead of time
Up until the time a mailing is scheduled for, it can also be canceled. If you use this feature in conjunction with [a cancellation window](https://docs.lob.com/#section/Cancellation-Windows)
, the `send_date` parameter will always take precedence.
For implementation details, see documentation below for each respective endpoint. For more help, see our [Scheduled Mailings Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/choosing-a-delivery-strategy#scheduled-mailings-15)
.
This feature is exclusive to certain customers. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
to gain access.
### Example Create Request using Send Date
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-d "description=Demo Future Postcard" \
-d "to=adr_bae820679f3f536b" \
-d "from=adr_210a8d4b0b76d77b" \
-d "front=tmpl_b846a20859ae11a" \
-d "back=tmpl_01b0d396a10c268" \
-d "merge_variables[name]=Harry" \
-d "send_date=2021-07-26"
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Campaigns)
Campaigns
=================================================
The campaigns endpoint allows you to create and view campaigns that can be used to send multiple letters or postcards. The API provides endpoints for creating campaigns, updating campaigns, retrieving individual campaigns, listing campaigns, and deleting campaigns.
[](https://docs.lob.com/#tag/Campaigns/operation/campaigns_list)
List
---------------------------------------------------------------------
Returns a list of your campaigns. The campaigns are returned sorted by creation date, with the most recently created campaigns appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` campaigns. Each entry in the array is a separate campaign. The previous and next page of campaigns can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively.
If no more campaigns are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (campaign)
list of campaigns |
get/campaigns
production
https://api.lob.com/v1/campaigns
### Request samples
* CURL
* RUBY
Copy
curl https://api.lob.com/v1/campaigns \\
-u :
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "cmp_e05ee61ff80764b", * "billing_group_id": "bg_fe3079dcdd80e5ae", * "name": "My Campaign", * "description": "My Campaign's description", * "schedule_type": "immediate", * "send_date": null, * "target_delivery_date": null, * "cancel_window_campaign_minutes": 60, * "metadata": { }, * "use_type": "marketing", * "is_draft": true, * "deleted": false, * "creatives": [ ], * "uploads": [ ], * "auto_cancel_if_ncoa": false, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "campaign" } ], * "object": "list", * "previous_url": null, * "next_url": null, * "count": 1 }`
[](https://docs.lob.com/#tag/Campaigns/operation/campaign_create)
Create
------------------------------------------------------------------------
Creates a new campaign with the provided properties. See how to launch your first campaign [here](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/launch-your-first-campaign)
.
##### Authorizations:
_basicAuth_
##### header Parameters
| | |
| --- | --- |
| x-lang-output | string
Enum: "native" "match"
* `native` - Translate response to the native language of the country in the request
* `match` - match the response to the language in the request
Default response is in English. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| name
required | string
Name of the campaign. |
| schedule\_type
required | string (cmp\_schedule\_type)
Value: "immediate"
How the campaign should be scheduled. Only value available today is `immediate`. |
| use\_type
required | string or null (cmp\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| billing\_group\_id | string or null^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| target\_delivery\_date | string or null
If `schedule_type` is `target_delivery_date`, provide a targeted delivery date for mail pieces in this campaign. |
| send\_date | string or null
If `schedule_type` is `scheduled_send_date`, provide a date to send this campaign. |
| cancel\_window\_campaign\_minutes | integer or null
A window, in minutes, within which the campaign can be canceled. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| auto\_cancel\_if\_ncoa | boolean
Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
### Responses
**200**
Campaign created successfully
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "campaign"
Value: "campaign"
Value is resource type. |
| name
required | string
Name of the campaign. |
| schedule\_type
required | string (cmp\_schedule\_type)
Value: "immediate"
How the campaign should be scheduled. Only value available today is `immediate`. |
| use\_type
required | string or null
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| description
required | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| is\_draft
required | boolean
Default: true
Whether or not the campaign is still a draft. |
| creatives
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) \>= 0 items
An array of creatives that have been associated with this campaign. |
| uploads
required | Array of objects (upload) \[ 0 .. 1 \] items
A single-element array containing the upload object that is assocated with this campaign. |
| auto\_cancel\_if\_ncoa
required | boolean
Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| billing\_group\_id | string or null^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| target\_delivery\_date | string or null
If `schedule_type` is `target_delivery_date`, provide a targeted delivery date for mail pieces in this campaign. |
| send\_date | string or null
If `schedule_type` is `scheduled_send_date`, provide a date to send this campaign. |
| cancel\_window\_campaign\_minutes | integer or null
A window, in minutes, within which the campaign can be canceled. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
**default**
Error
post/campaigns
production
https://api.lob.com/v1/campaigns
### Request samples
* Payload
* CURL
* RUBY
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "name": "My Demo Campaign", * "description": "My Campaign's description", * "schedule_type": "immediate", * "print_speed": "core" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "cmp_e05ee61ff80764b", * "billing_group_id": "bg_fe3079dcdd80e5ae", * "name": "My Campaign", * "description": "My Campaign's description", * "schedule_type": "immediate", * "cancel_window_campaign_minutes": 60, * "metadata": { }, * "use_type": "marketing", * "is_draft": true, * "deleted": false, * "creatives": [ ], * "uploads": [ ], * "auto_cancel_if_ncoa": false, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "campaign" }`
[](https://docs.lob.com/#tag/Campaigns/operation/campaign_retrieve)
Retrieve
----------------------------------------------------------------------------
Retrieves the details of an existing campaign. You need only supply the unique campaign identifier that was returned upon campaign creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| cmp\_id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
id of the campaign |
### Responses
**200**
Returns a campaign object
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "campaign"
Value: "campaign"
Value is resource type. |
| name
required | string
Name of the campaign. |
| schedule\_type
required | string (cmp\_schedule\_type)
Value: "immediate"
How the campaign should be scheduled. Only value available today is `immediate`. |
| use\_type
required | string or null
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| description
required | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| is\_draft
required | boolean
Default: true
Whether or not the campaign is still a draft. |
| creatives
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) \>= 0 items
An array of creatives that have been associated with this campaign. |
| uploads
required | Array of objects (upload) \[ 0 .. 1 \] items
A single-element array containing the upload object that is assocated with this campaign. |
| auto\_cancel\_if\_ncoa
required | boolean
Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| billing\_group\_id | string or null^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| target\_delivery\_date | string or null
If `schedule_type` is `target_delivery_date`, provide a targeted delivery date for mail pieces in this campaign. |
| send\_date | string or null
If `schedule_type` is `scheduled_send_date`, provide a date to send this campaign. |
| cancel\_window\_campaign\_minutes | integer or null
A window, in minutes, within which the campaign can be canceled. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
**default**
Error
get/campaigns/{cmp\_id}
production
https://api.lob.com/v1/campaigns/{cmp\_id}
### Request samples
* CURL
* RUBY
Copy
curl https://api.lob.com/v1/campaigns/cmp\_e05ee61ff80764b \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "cmp_e05ee61ff80764b", * "billing_group_id": "bg_fe3079dcdd80e5ae", * "name": "My Campaign", * "description": "My Campaign's description", * "schedule_type": "immediate", * "cancel_window_campaign_minutes": 60, * "metadata": { }, * "use_type": "marketing", * "is_draft": true, * "deleted": false, * "creatives": [ ], * "uploads": [ ], * "auto_cancel_if_ncoa": false, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "campaign" }`
[](https://docs.lob.com/#tag/Campaigns/operation/campaign_update)
Update
------------------------------------------------------------------------
Update the details of an existing campaign. You need only supply the unique identifier that was returned upon campaign creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| cmp\_id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
id of the campaign |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| name | string (Name) |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| schedule\_type | string (cmp\_schedule\_type)
Value: "immediate"
How the campaign should be scheduled. Only value available today is `immediate`. |
| target\_delivery\_date | string
If `schedule_type` is `target_delivery_date`, provide a targeted delivery date for mail pieces in this campaign. |
| send\_date | string
If `schedule_type` is `scheduled_send_date`, provide a date to send this campaign. |
| cancel\_window\_campaign\_minutes | integer
A window, in minutes, within which the campaign can be canceled. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| is\_draft | boolean
Whether or not the campaign is still a draft. Can either be excluded or `false`. |
| use\_type | string or null (cmp\_use\_type)
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| auto\_cancel\_if\_ncoa | boolean
Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
### Responses
**200**
Returns a campaign object
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "campaign"
Value: "campaign"
Value is resource type. |
| name
required | string
Name of the campaign. |
| schedule\_type
required | string (cmp\_schedule\_type)
Value: "immediate"
How the campaign should be scheduled. Only value available today is `immediate`. |
| use\_type
required | string or null
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| description
required | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| is\_draft
required | boolean
Default: true
Whether or not the campaign is still a draft. |
| creatives
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) \>= 0 items
An array of creatives that have been associated with this campaign. |
| uploads
required | Array of objects (upload) \[ 0 .. 1 \] items
A single-element array containing the upload object that is assocated with this campaign. |
| auto\_cancel\_if\_ncoa
required | boolean
Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| billing\_group\_id | string or null^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| target\_delivery\_date | string or null
If `schedule_type` is `target_delivery_date`, provide a targeted delivery date for mail pieces in this campaign. |
| send\_date | string or null
If `schedule_type` is `scheduled_send_date`, provide a date to send this campaign. |
| cancel\_window\_campaign\_minutes | integer or null
A window, in minutes, within which the campaign can be canceled. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
**default**
Error
patch/campaigns/{cmp\_id}
production
https://api.lob.com/v1/campaigns/{cmp\_id}
### Request samples
* Payload
* CURL
* PYTHON
* RUBY
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Test campaign" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "cmp_e05ee61ff80764b", * "billing_group_id": "bg_fe3079dcdd80e5ae", * "name": "My Campaign", * "description": "My Campaign's description", * "schedule_type": "immediate", * "cancel_window_campaign_minutes": 60, * "metadata": { }, * "use_type": "marketing", * "is_draft": true, * "deleted": false, * "creatives": [ ], * "uploads": [ ], * "auto_cancel_if_ncoa": false, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "campaign" }`
[](https://docs.lob.com/#tag/Campaigns/operation/campaign_delete)
Delete
------------------------------------------------------------------------
Delete an existing campaign. You need only supply the unique identifier that was returned upon campaign creation. Deleting a campaign also deletes any associated mail pieces that have been created but not sent. A campaign's `send_date` matches its associated mail pieces' `send_date`s.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| cmp\_id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
id of the campaign |
### Responses
**200**
Deleted the campaign.
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| deleted | boolean
True if the resource has been successfully deleted. |
**default**
Error
delete/campaigns/{cmp\_id}
production
https://api.lob.com/v1/campaigns/{cmp\_id}
### Request samples
* CURL
* RUBY
Copy
curl -X DELETE https://api.lob.com/v1/campaigns/cmp\_e05ee61ff80764b \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "cmp_e05ee61ff80764b", * "deleted": true }`
[](https://docs.lob.com/#tag/Campaigns/operation/campaign_send)
Send Campaign
-----------------------------------------------------------------------------
Sends a campaign. You need only supply the unique campaign identifier that was returned upon campaign creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| cmp\_id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
id of the campaign |
### Responses
**200**
Returns a campaign object
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "campaign"
Value: "campaign"
Value is resource type. |
| name
required | string
Name of the campaign. |
| schedule\_type
required | string (cmp\_schedule\_type)
Value: "immediate"
How the campaign should be scheduled. Only value available today is `immediate`. |
| use\_type
required | string or null
Enum: "marketing" "operational" null
The use type for each mailpiece. Can be one of marketing, operational, or null. Null use\_type is only allowed if an account default use\_type is selected in Account Settings. For more information on use\_type, see our [Help Center article](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings/declaring-mail-use-type)
. |
| id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| description
required | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| is\_draft
required | boolean
Default: true
Whether or not the campaign is still a draft. |
| creatives
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) \>= 0 items
An array of creatives that have been associated with this campaign. |
| uploads
required | Array of objects (upload) \[ 0 .. 1 \] items
A single-element array containing the upload object that is assocated with this campaign. |
| auto\_cancel\_if\_ncoa
required | boolean
Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| billing\_group\_id | string or null^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| target\_delivery\_date | string or null
If `schedule_type` is `target_delivery_date`, provide a targeted delivery date for mail pieces in this campaign. |
| send\_date | string or null
If `schedule_type` is `scheduled_send_date`, provide a date to send this campaign. |
| cancel\_window\_campaign\_minutes | integer or null
A window, in minutes, within which the campaign can be canceled. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| print\_speed | string or null (print\_speed)
Default: "core"
Value: "core"
A string designating the mail speed type:
* `core` - 2 production business days |
**default**
Error
post/campaigns/{cmp\_id}/send
production
https://api.lob.com/v1/campaigns/{cmp\_id}/send
### Request samples
* CURL
Copy
curl https://api.lob.com/v1/campaigns/cmp\_e05ee61ff80764b/send \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "cmp_e05ee61ff80764b", * "billing_group_id": "bg_fe3079dcdd80e5ae", * "name": "My Campaign", * "description": "My Campaign's description", * "schedule_type": "immediate", * "cancel_window_campaign_minutes": 60, * "metadata": { }, * "use_type": "marketing", * "is_draft": true, * "deleted": false, * "creatives": [ ], * "uploads": [ ], * "auto_cancel_if_ncoa": false, * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "campaign" }`
[](https://docs.lob.com/#tag/Creatives)
Creatives
=================================================
The creatives endpoint allows you to create and view creatives. Creatives are used to create reusable letter and postcard templates. The API provides endpoints for creating creatives, updating creatives, retrieving individual creatives, and deleting creatives.
[](https://docs.lob.com/#tag/Creatives/operation/creative_create)
Create
------------------------------------------------------------------------
Creates a new creative with the provided properties
##### Authorizations:
_basicAuth_
##### header Parameters
| | |
| --- | --- |
| x-lang-output | string
Enum: "native" "match"
* `native` - Translate response to the native language of the country in the request
* `match` - match the response to the language in the request
Default response is in English. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
One of
Postcard CreativeLetter CreativeSelf Mailer Creative
| | |
| --- | --- |
| front
required | tmpl\_id (string) or local\_file\_path (string) (crv\_front)
The artwork to use as the front of your postcard.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML template will be rendered to the specified `size`.
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| back
required | tmpl\_id (string) or local\_file\_path (string) (crv\_back)
The artwork to use as the back of your postcard creative.
Notes:
* HTML merge variables should not include delimiting whitespace.
* PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML template will be rendered to the specified `size`.
* Be sure to leave room for address and postage information by following the templates provided here:
* [4x6 template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/4x6_postcard.pdf)
* [6x9 template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x9_postcard.pdf)
* [6x11 template](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/templates/postcards/6x11_postcard.pdf)
See [here](https://docs.lob.com/#section/HTML-Examples)
for HTML examples. |
| campaign\_id
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| resource\_type
required | string
Value: "postcard"
Mailpiece type for the creative |
| details
required | object (writable)
Properties that the postcards in your Creative should have. See the `qr_code` attribute below to add a QR code to your creative. |
| from | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (From)
Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
### Responses
**200**
Creative created successfully
##### Response Schema: application/json
One of
Postcard CreativeLetter CreativeSelf Mailer Creative
| | |
| --- | --- |
| resource\_type
required | string
Value: "postcard"
Mailpiece type for the creative |
| details
required | object (returned)
Properties that the postcards in your Creative should have. See the `qr_code` attribute below to add a QR code to your creative. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "creative"
Value: "creative"
Value is resource type. |
| id
required | string (crv\_id) ^crv\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `crv_`. |
| description
required | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| from
required | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (From)
Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| metadata
required | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| template\_preview\_urls
required | object (Template Preview URLs)
Preview URLs associated with a creative's artwork asset(s) if the creative uses HTML templates as assets. An empty object will be returned if no `template_preview`s have been generated. |
| template\_previews
required | Array of objects (Template Previews)
A list of template preview objects if the creative uses HTML template(s) as artwork asset(s). An empty array will be returned if no `template_preview`s have been generated for the creative. |
| campaigns
required | Array of objects (campaign\_list)
Array of campaigns associated with the creative ID |
| deleted
required | boolean
Only returned if the resource has been successfully deleted. |
**default**
Error
post/creatives
production
https://api.lob.com/v1/creatives
### Request samples
* Payload
* Shell
* RUBY
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "campaign_id": "cmp_e05ee61ff80764b", * "resource_type": "postcard", * "description": "Our 4x6 postcard creative", * "details": { } }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "crv_2a3b096c409b32c", * "description": "Our 4x6 postcard creative", * "from": "adr_210a8d4b0b76d77b", * "resource_type": "postcard", * "details": { }, * "metadata": { }, * "template_preview_urls": { }, * "template_previews": [ ], * "campaigns": [ ], * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "creative" }`
[](https://docs.lob.com/#tag/Creatives/operation/creative_retrieve)
Retrieve
----------------------------------------------------------------------------
Retrieves the details of an existing creative. You need only supply the unique creative identifier that was returned upon creative creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| crv\_id
required | string (crv\_id) ^crv\_\[a-zA-Z0-9\]+$
Example: crv\_2a3b096c409b32c
id of the creative |
### Responses
**200**
Returns a creative object
##### Response Schema: application/json
One of
Postcard CreativeLetter CreativeSelf Mailer Creative
| | |
| --- | --- |
| resource\_type
required | string
Value: "postcard"
Mailpiece type for the creative |
| details
required | object (returned)
Properties that the postcards in your Creative should have. See the `qr_code` attribute below to add a QR code to your creative. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "creative"
Value: "creative"
Value is resource type. |
| id
required | string (crv\_id) ^crv\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `crv_`. |
| description
required | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| from
required | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (From)
Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| metadata
required | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| template\_preview\_urls
required | object (Template Preview URLs)
Preview URLs associated with a creative's artwork asset(s) if the creative uses HTML templates as assets. An empty object will be returned if no `template_preview`s have been generated. |
| template\_previews
required | Array of objects (Template Previews)
A list of template preview objects if the creative uses HTML template(s) as artwork asset(s). An empty array will be returned if no `template_preview`s have been generated for the creative. |
| campaigns
required | Array of objects (campaign\_list)
Array of campaigns associated with the creative ID |
| deleted
required | boolean
Only returned if the resource has been successfully deleted. |
**default**
Error
get/creatives/{crv\_id}
production
https://api.lob.com/v1/creatives/{crv\_id}
### Request samples
* CURL
* RUBY
Copy
curl https://api.lob.com/v1/creatives/crv\_2a3b096c409b32c \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "crv_2a3b096c409b32c", * "description": "Our 4x6 postcard creative", * "from": "adr_210a8d4b0b76d77b", * "resource_type": "postcard", * "details": { }, * "metadata": { }, * "template_preview_urls": { }, * "template_previews": [ ], * "campaigns": [ ], * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "creative" }`
[](https://docs.lob.com/#tag/Creatives/operation/creative_update)
Update
------------------------------------------------------------------------
Update the details of an existing creative. You need only supply the unique identifier that was returned upon creative creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| crv\_id
required | string (crv\_id) ^crv\_\[a-zA-Z0-9\]+$
Example: crv\_2a3b096c409b32c
id of the creative |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| from | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (From)
Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| description | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
### Responses
**200**
Returns a creative object
##### Response Schema: application/json
One of
Postcard CreativeLetter CreativeSelf Mailer Creative
| | |
| --- | --- |
| resource\_type
required | string
Value: "postcard"
Mailpiece type for the creative |
| details
required | object (returned)
Properties that the postcards in your Creative should have. See the `qr_code` attribute below to add a QR code to your creative. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "creative"
Value: "creative"
Value is resource type. |
| id
required | string (crv\_id) ^crv\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `crv_`. |
| description
required | string or null (resource\_description) <= 255 characters
An internal description that identifies this resource. Must be no longer than 255 characters. |
| from
required | adr\_id (string) or (address\_editable\_us (address obj with \`name\` defined (object) or address obj with \`company\` defined (object))) (From)
Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
| metadata
required | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| template\_preview\_urls
required | object (Template Preview URLs)
Preview URLs associated with a creative's artwork asset(s) if the creative uses HTML templates as assets. An empty object will be returned if no `template_preview`s have been generated. |
| template\_previews
required | Array of objects (Template Previews)
A list of template preview objects if the creative uses HTML template(s) as artwork asset(s). An empty array will be returned if no `template_preview`s have been generated for the creative. |
| campaigns
required | Array of objects (campaign\_list)
Array of campaigns associated with the creative ID |
| deleted
required | boolean
Only returned if the resource has been successfully deleted. |
**default**
Error
patch/creatives/{crv\_id}
production
https://api.lob.com/v1/creatives/{crv\_id}
### Request samples
* Payload
* CURL
* PYTHON
* RUBY
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Test creative" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "crv_2a3b096c409b32c", * "description": "Our 4x6 postcard creative", * "from": "adr_210a8d4b0b76d77b", * "resource_type": "postcard", * "details": { }, * "metadata": { }, * "template_preview_urls": { }, * "template_previews": [ ], * "campaigns": [ ], * "date_created": "2017-09-05T17:47:53.767Z", * "date_modified": "2017-09-05T17:47:53.767Z", * "object": "creative" }`
[](https://docs.lob.com/#tag/Uploads)
Uploads
=============================================
The uploads endpoint allows you to upload audience files that are then associated with a given campaign. At this time, only CSV files are allowed. The API provides endpoints for creating uploads, uploading audience files, and marking uploaded files as ready for processing. The API also provides endpoints for downloading files that describe the results, both successful and not, of the processing.
[](https://docs.lob.com/#tag/Uploads/operation/uploads_list)
List
-----------------------------------------------------------------
Returns a list of your uploads. Optionally, filter uploads by campaign.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| campaignId | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
id of the campaign |
### Responses
**200**
An array of matching uploads. Each entry in the array is a separate upload.
##### Response Schema: application/json
Array
| | |
| --- | --- |
| campaignId
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `upl_`. |
| accountId
required | string (Account ID)
Account ID that made the request |
| requiredAddressColumnMapping
required | object (Required Address Columns)
The mapping of column headers in your file to Lob-required fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| optionalAddressColumnMapping
required | object (Optional Address Columns)
The mapping of column headers in your file to Lob-optional fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#optional-columns-3)
for additional details. |
| metadata
required | object (Metadata)
Default: {"columns":\[\]}
The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| mergeVariableColumnMapping
required | object or null (Merge Variable Mapping)
Default: null
The mapping of column headers in your file to the merge variables present in your creative. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#step-3-map-merge-variable-data-if-applicable-7)
for additional details.
If a merge variable has the same "name" as a "key" in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects, then they **CANNOT** have a different value in this object. If a different value is provided, then when the campaign is processing it will get overwritten with the mapped value present in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects. The redirect URLs for QR codes can also be customized using this mapping. If the URL has a variable and the variable mapping existsing here, then data from the respective column in the audience file will be merged into the URL template. |
| mode
required | string
Enum: "test" "live"
The environment in which the mailpieces were created. Today, will only be `live`. |
| state
required | string (Upload State)
Default: "Draft"
Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored"
The `state` property on the `upload` object. As the file is processed, the `state` will change from `Ready for Validation` to `Validating` and then will be either `Scheduled` (successfully processed) or `Errored` (Unsuccessfully processed). |
| totalMailpieces
required | integer (Total Mailpieces)
Total number of recipients for the campaign |
| failedMailpieces
required | integer (Failed Mailpieces)
Number of mailpieces that failed to create |
| validatedMailpieces
required | integer (Validated Mailpieces)
Number of mailpieces that were successfully created |
| bytesProcessed
required | integer (Bytes Processed)
Number of bytes processed in your CSV |
| dateCreated
required | string (Date Created)
A timestamp in ISO 8601 format of the date the upload was created |
| dateModified
required | string (Date Modified)
A timestamp in ISO 8601 format of the date the upload was last modified |
| failuresUrl | string (Failures URL)
Url where your campaign mailpiece failures can be retrieved |
| originalFilename | string (Original Filename)
Filename of the upload |
get/uploads
production
https://api.lob.com/v1/uploads
### Request samples
* CURL
* RUBY
Copy
curl https://api.lob.com/v1/uploads \\
-u :
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`[ * { * "id": "upl_71be866e430b11e9", * "accountId": "fa9ea650fc7b31a89f92", * "campaignId": "cmp_1933ad629bae1408", * "mode": "test", * "failuresUrl": "[https://www.example.com](https://www.example.com/) ", * "originalFilename": "my_audience.csv", * "state": "Draft", * "totalMailpieces": 100, * "failedMailpieces": 5, * "validatedMailpieces": 95, * "bytesProcessed": 17268, * "dateCreated": "2017-09-05T17:47:53.767Z", * "dateModified": "2017-09-05T17:47:53.767Z", * "requiredAddressColumnMapping": { * "name": "recipient_name", * "address_line1": "primary_line", * "address_city": "city", * "address_state": "state", * "address_zip": "zip_code" }, * "optionalAddressColumnMapping": { * "address_line2": "secondary_line", * "company": "company", * "address_country": "country" }, * "mergeVariableColumnMapping": { * "gift_code": "code" }, * "metadata": { * "columns": [ * "recipient_name", * "zip_code" ] } } ]`
[](https://docs.lob.com/#tag/Uploads/operation/upload_create)
Create
--------------------------------------------------------------------
Creates a new upload with the provided properties.
##### Authorizations:
_basicAuth_
##### Request Body schema: application/json
| | |
| --- | --- |
| campaignId
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| requiredAddressColumnMapping | object (Required Address Columns)
The mapping of column headers in your file to Lob-required fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| optionalAddressColumnMapping | object (Optional Address Columns)
The mapping of column headers in your file to Lob-optional fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#optional-columns-3)
for additional details. |
| metadata | object (Metadata)
Default: {"columns":\[\]}
The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| mergeVariableColumnMapping | object or null (Merge Variable Mapping)
Default: null
The mapping of column headers in your file to the merge variables present in your creative. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#step-3-map-merge-variable-data-if-applicable-7)
for additional details.
If a merge variable has the same "name" as a "key" in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects, then they **CANNOT** have a different value in this object. If a different value is provided, then when the campaign is processing it will get overwritten with the mapped value present in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects. The redirect URLs for QR codes can also be customized using this mapping. If the URL has a variable and the variable mapping existsing here, then data from the respective column in the audience file will be merged into the URL template. |
### Responses
**201**
Upload created successfully
##### Response Schema: application/json
| | |
| --- | --- |
| campaignId
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `upl_`. |
| accountId
required | string (Account ID)
Account ID that made the request |
| requiredAddressColumnMapping
required | object (Required Address Columns)
The mapping of column headers in your file to Lob-required fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| optionalAddressColumnMapping
required | object (Optional Address Columns)
The mapping of column headers in your file to Lob-optional fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#optional-columns-3)
for additional details. |
| metadata
required | object (Metadata)
Default: {"columns":\[\]}
The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| mergeVariableColumnMapping
required | object or null (Merge Variable Mapping)
Default: null
The mapping of column headers in your file to the merge variables present in your creative. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#step-3-map-merge-variable-data-if-applicable-7)
for additional details.
If a merge variable has the same "name" as a "key" in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects, then they **CANNOT** have a different value in this object. If a different value is provided, then when the campaign is processing it will get overwritten with the mapped value present in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects. The redirect URLs for QR codes can also be customized using this mapping. If the URL has a variable and the variable mapping existsing here, then data from the respective column in the audience file will be merged into the URL template. |
| mode
required | string
Enum: "test" "live"
The environment in which the mailpieces were created. Today, will only be `live`. |
| state
required | string (Upload State)
Default: "Draft"
Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored"
The `state` property on the `upload` object. As the file is processed, the `state` will change from `Ready for Validation` to `Validating` and then will be either `Scheduled` (successfully processed) or `Errored` (Unsuccessfully processed). |
| totalMailpieces
required | integer (Total Mailpieces)
Total number of recipients for the campaign |
| failedMailpieces
required | integer (Failed Mailpieces)
Number of mailpieces that failed to create |
| validatedMailpieces
required | integer (Validated Mailpieces)
Number of mailpieces that were successfully created |
| bytesProcessed
required | integer (Bytes Processed)
Number of bytes processed in your CSV |
| dateCreated
required | string (Date Created)
A timestamp in ISO 8601 format of the date the upload was created |
| dateModified
required | string (Date Modified)
A timestamp in ISO 8601 format of the date the upload was last modified |
| failuresUrl | string (Failures URL)
Url where your campaign mailpiece failures can be retrieved |
| originalFilename | string (Original Filename)
Filename of the upload |
**422**
Validation Error
post/uploads
production
https://api.lob.com/v1/uploads
### Request samples
* Payload
* CURL
* RUBY
Content type
application/json
Copy
Expand all Collapse all
`{ * "campaignId": "cmp_1933ad629bae1408", * "requiredAddressColumnMapping": { * "name": "recipient_name", * "address_line1": "primary_line", * "address_city": "city", * "address_state": "state", * "address_zip": "zip_code" }, * "optionalAddressColumnMapping": { * "address_line2": "secondary_line", * "company": "company", * "address_country": "country," }, * "metadata": { * "columns": [ * "recipient_name" ] }, * "mergeVariableColumnMapping": { * "name": "recipient_name", * "gift_code": "code", * "qr_code_redirect_url": "redirect_url" } }`
### Response samples
* 201
* 422
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "upl_71be866e430b11e9", * "accountId": "fa9ea650fc7b31a89f92", * "campaignId": "cmp_1933ad629bae1408", * "mode": "live", * "failuresUrl": "[http://www.example.com](http://www.example.com/) ", * "originalFilename": "my_audience.csv", * "state": "Draft", * "totalMailpieces": 100, * "failedMailpieces": 5, * "validatedMailpieces": 95, * "bytesProcessed": 17628, * "dateCreated": "2017-09-05T17:47:53.767Z", * "dateModified": "2017-09-05T17:47:53.767Z", * "requiredAddressColumnMapping": { * "name": null, * "address_line1": null, * "address_city": null, * "address_state": null, * "address_zip": null }, * "optionalAddressColumnMapping": { * "address_line2": null, * "company": null, * "address_country": null }, * "mergeVariableColumnMapping": null, * "metadata": { * "columns": [ ] } }`
[](https://docs.lob.com/#tag/Uploads/operation/upload_retrieve)
Retrieve
------------------------------------------------------------------------
Retrieves the details of an existing upload. You need only supply the unique upload identifier that was returned upon upload creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| upl\_id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
id of the upload |
### Responses
**200**
Returns an upload object
##### Response Schema: application/json
| | |
| --- | --- |
| campaignId
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `upl_`. |
| accountId
required | string (Account ID)
Account ID that made the request |
| requiredAddressColumnMapping
required | object (Required Address Columns)
The mapping of column headers in your file to Lob-required fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| optionalAddressColumnMapping
required | object (Optional Address Columns)
The mapping of column headers in your file to Lob-optional fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#optional-columns-3)
for additional details. |
| metadata
required | object (Metadata)
Default: {"columns":\[\]}
The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| mergeVariableColumnMapping
required | object or null (Merge Variable Mapping)
Default: null
The mapping of column headers in your file to the merge variables present in your creative. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#step-3-map-merge-variable-data-if-applicable-7)
for additional details.
If a merge variable has the same "name" as a "key" in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects, then they **CANNOT** have a different value in this object. If a different value is provided, then when the campaign is processing it will get overwritten with the mapped value present in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects. The redirect URLs for QR codes can also be customized using this mapping. If the URL has a variable and the variable mapping existsing here, then data from the respective column in the audience file will be merged into the URL template. |
| mode
required | string
Enum: "test" "live"
The environment in which the mailpieces were created. Today, will only be `live`. |
| state
required | string (Upload State)
Default: "Draft"
Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored"
The `state` property on the `upload` object. As the file is processed, the `state` will change from `Ready for Validation` to `Validating` and then will be either `Scheduled` (successfully processed) or `Errored` (Unsuccessfully processed). |
| totalMailpieces
required | integer (Total Mailpieces)
Total number of recipients for the campaign |
| failedMailpieces
required | integer (Failed Mailpieces)
Number of mailpieces that failed to create |
| validatedMailpieces
required | integer (Validated Mailpieces)
Number of mailpieces that were successfully created |
| bytesProcessed
required | integer (Bytes Processed)
Number of bytes processed in your CSV |
| dateCreated
required | string (Date Created)
A timestamp in ISO 8601 format of the date the upload was created |
| dateModified
required | string (Date Modified)
A timestamp in ISO 8601 format of the date the upload was last modified |
| failuresUrl | string (Failures URL)
Url where your campaign mailpiece failures can be retrieved |
| originalFilename | string (Original Filename)
Filename of the upload |
**404**
Not Found Error
**422**
Validation Error
get/uploads/{upl\_id}
production
https://api.lob.com/v1/uploads/{upl\_id}
### Request samples
* CURL
* RUBY
Copy
curl https://api.lob.com/v1/uploads/upl\_71be866e430b11e9 \\
-u : \\
### Response samples
* 200
* 404
* 422
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "upl_71be866e430b11e9", * "accountId": "fa9ea650fc7b31a89f92", * "campaignId": "cmp_1933ad629bae1408", * "mode": "live", * "failuresUrl": "[http://www.example.com](http://www.example.com/) ", * "originalFilename": "my_audience.csv", * "state": "Draft", * "totalMailpieces": 100, * "failedMailpieces": 5, * "validatedMailpieces": 95, * "bytesProcessed": 17628, * "dateCreated": "2017-09-05T17:47:53.767Z", * "dateModified": "2017-09-05T17:47:53.767Z", * "requiredAddressColumnMapping": { * "name": null, * "address_line1": null, * "address_city": null, * "address_state": null, * "address_zip": null }, * "optionalAddressColumnMapping": { * "address_line2": null, * "company": null, * "address_country": null }, * "mergeVariableColumnMapping": null, * "metadata": { * "columns": [ ] } }`
[](https://docs.lob.com/#tag/Uploads/operation/upload_update)
Update
--------------------------------------------------------------------
Update the details of an existing upload. You need only supply the unique identifier that was returned upon upload creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| upl\_id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
id of the upload |
##### Request Body schema: application/json
| | |
| --- | --- |
| originalFilename | string (Original Filename)
Original filename provided when the upload is created. |
| requiredAddressColumnMapping | object (Required Address Columns)
The mapping of column headers in your file to Lob-required fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| optionalAddressColumnMapping | object (Optional Address Columns)
The mapping of column headers in your file to Lob-optional fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#optional-columns-3)
for additional details. |
| metadata | object (Metadata)
Default: {"columns":\[\]}
The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| mergeVariableColumnMapping | object or null (Merge Variable Mapping)
Default: null
The mapping of column headers in your file to the merge variables present in your creative. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#step-3-map-merge-variable-data-if-applicable-7)
for additional details.
If a merge variable has the same "name" as a "key" in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects, then they **CANNOT** have a different value in this object. If a different value is provided, then when the campaign is processing it will get overwritten with the mapped value present in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects. The redirect URLs for QR codes can also be customized using this mapping. If the URL has a variable and the variable mapping existsing here, then data from the respective column in the audience file will be merged into the URL template. |
### Responses
**200**
Returns an upload object
##### Response Schema: application/json
| | |
| --- | --- |
| campaignId
required | string (Campaign id) ^cmp\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `cmp_`. |
| id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `upl_`. |
| accountId
required | string (Account ID)
Account ID that made the request |
| requiredAddressColumnMapping
required | object (Required Address Columns)
The mapping of column headers in your file to Lob-required fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| optionalAddressColumnMapping
required | object (Optional Address Columns)
The mapping of column headers in your file to Lob-optional fields for the resource created. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#optional-columns-3)
for additional details. |
| metadata
required | object (Metadata)
Default: {"columns":\[\]}
The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#required-columns-2)
for additional details. |
| mergeVariableColumnMapping
required | object or null (Merge Variable Mapping)
Default: null
The mapping of column headers in your file to the merge variables present in your creative. See our [Campaign Audience Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide#step-3-map-merge-variable-data-if-applicable-7)
for additional details.
If a merge variable has the same "name" as a "key" in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects, then they **CANNOT** have a different value in this object. If a different value is provided, then when the campaign is processing it will get overwritten with the mapped value present in the `requiredAddressColumnMapping` or `optionalAddressColumnMapping` objects. The redirect URLs for QR codes can also be customized using this mapping. If the URL has a variable and the variable mapping existsing here, then data from the respective column in the audience file will be merged into the URL template. |
| mode
required | string
Enum: "test" "live"
The environment in which the mailpieces were created. Today, will only be `live`. |
| state
required | string (Upload State)
Default: "Draft"
Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored"
The `state` property on the `upload` object. As the file is processed, the `state` will change from `Ready for Validation` to `Validating` and then will be either `Scheduled` (successfully processed) or `Errored` (Unsuccessfully processed). |
| totalMailpieces
required | integer (Total Mailpieces)
Total number of recipients for the campaign |
| failedMailpieces
required | integer (Failed Mailpieces)
Number of mailpieces that failed to create |
| validatedMailpieces
required | integer (Validated Mailpieces)
Number of mailpieces that were successfully created |
| bytesProcessed
required | integer (Bytes Processed)
Number of bytes processed in your CSV |
| dateCreated
required | string (Date Created)
A timestamp in ISO 8601 format of the date the upload was created |
| dateModified
required | string (Date Modified)
A timestamp in ISO 8601 format of the date the upload was last modified |
| failuresUrl | string (Failures URL)
Url where your campaign mailpiece failures can be retrieved |
| originalFilename | string (Original Filename)
Filename of the upload |
**404**
Not Found Error
**422**
Validation Error
patch/uploads/{upl\_id}
production
https://api.lob.com/v1/uploads/{upl\_id}
### Request samples
* Payload
* CURL
* PYTHON
* RUBY
Content type
application/json
Copy
Expand all Collapse all
`{ * "originalFilename": "string", * "requiredAddressColumnMapping": { * "name": "recipient_name", * "address_line1": "primary_line", * "address_city": "city", * "address_state": "state", * "address_zip": "zip_code" }, * "optionalAddressColumnMapping": { * "address_line2": "secondary_line", * "company": "company", * "address_country": "country," }, * "metadata": { * "columns": [ * "recipient_name" ] }, * "mergeVariableColumnMapping": { * "name": "recipient_name", * "gift_code": "code", * "qr_code_redirect_url": "redirect_url" } }`
### Response samples
* 200
* 404
* 422
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "upl_71be866e430b11e9", * "accountId": "fa9ea650fc7b31a89f92", * "campaignId": "cmp_1933ad629bae1408", * "mode": "live", * "failuresUrl": "[http://www.example.com](http://www.example.com/) ", * "originalFilename": "my_audience.csv", * "state": "Draft", * "totalMailpieces": 100, * "failedMailpieces": 5, * "validatedMailpieces": 95, * "bytesProcessed": 17628, * "dateCreated": "2017-09-05T17:47:53.767Z", * "dateModified": "2017-09-05T17:47:53.767Z", * "requiredAddressColumnMapping": { * "name": null, * "address_line1": null, * "address_city": null, * "address_state": null, * "address_zip": null }, * "optionalAddressColumnMapping": { * "address_line2": null, * "company": null, * "address_country": null }, * "mergeVariableColumnMapping": null, * "metadata": { * "columns": [ ] } }`
[](https://docs.lob.com/#tag/Uploads/operation/upload_delete)
Delete
--------------------------------------------------------------------
Delete an existing upload. You need only supply the unique identifier that was returned upon upload creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| upl\_id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
id of the upload |
### Responses
**204**
Successful Response
delete/uploads/{upl\_id}
production
https://api.lob.com/v1/uploads/{upl\_id}
### Request samples
* CURL
* RUBY
Copy
curl -X DELETE https://api.lob.com/v1/uploads/upl\_71be866e430b11e9 \\
-u :
[](https://docs.lob.com/#tag/Uploads/operation/upload_file)
Upload file
-----------------------------------------------------------------------
Upload an [audience file](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/campaign-audience-guide)
and associate it with an upload.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| upl\_id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
ID of the upload |
##### Request Body schema: multipart/form-data
| | |
| --- | --- |
| file | string |
### Responses
**202**
Successful Response
**422**
Validation Error
post/uploads/{upl\_id}/file
production
https://api.lob.com/v1/uploads/{upl\_id}/file
### Request samples
* CURL
* PYTHON
Copy
curl -X POST https://api.lob.com/v1/uploads/upl\_71be866e430b11e9/file \\
-u : \\
-F file\=@
### Response samples
* 202
* 422
Content type
application/json
Copy
`{ * "message": "File uploaded successfully", * "filename": "string" }`
[](https://docs.lob.com/#tag/Uploads/operation/upload_export_create)
Create Export
----------------------------------------------------------------------------------
Campaign Exports can help you understand exactly which records in a campaign could not be created. By initiating and retrieving an export, you will get row-by-row errors for your campaign. For a step-by-step walkthrough of creating a campaign and exporting failures, see our [Campaigns Guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/campaign-or-triggered-sends/launch-your-first-campaign)
.
Create an export file associated with an upload.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| upl\_id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
ID of the upload |
##### Request Body schema: application/json
| | |
| --- | --- |
| type | string
Enum: "all" "failures" "successes" |
### Responses
**200**
Successful Response
##### Response Schema: application/json
| | |
| --- | --- |
| message
required | string (Message)
Default: "Export is processing"
Value: "Export is processing" |
| exportId
required | string (Export ID) |
**4XX**
Create Export Error
post/uploads/{upl\_id}/exports
production
https://api.lob.com/v1/uploads/{upl\_id}/exports
### Request samples
* Payload
* CURL
* PYTHON
* RUBY
Content type
application/json
Copy
`{ * "type": "all" }`
### Response samples
* 200
* 4XX
Content type
application/json
Copy
`{ * "message": "Export is processing", * "exportId": "ex_2dafd758ed3da9c43" }`
[](https://docs.lob.com/#tag/Uploads/operation/report_retrieve)
Retrieve Line Item Report
-----------------------------------------------------------------------------------------
Retrieves the line item data for each row from the csv file associated with the upload id record. NOTE: This endpoint is currently feature flagged. Please reach out to Lob's support team if you would like access to this API endpoint.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| upl\_id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
ID of the upload |
##### query Parameters
| | |
| --- | --- |
| status | string
Enum: "Validated" "Failed" "Processing"
The status of line items to filter and retrieve. By default all line items are returned. |
| limit | integer \[ 1 .. 100 \]
Default: 100
Example: limit=10
How many results to return. |
| offset | integer
Default: 0
An integer that designates the offset at which to begin returning results. Defaults to 0. |
### Responses
**200**
Returns an report object
##### Response Schema: application/json
| | |
| --- | --- |
| data
required | Array of objects |
| count
required | integer (count)
number of resources in a set |
| total\_count
required | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| next\_url | string or null
Url of next page of items in list. |
| prev\_url | string or null
Url of previous page of items in list. |
**404**
Not Found Error
get/uploads/{upl\_id}/report
production
https://api.lob.com/v1/uploads/{upl\_id}/report
### Request samples
* CURL
* PYTHON
* RUBY
Copy
curl https://api.lob.com/v1/uploads/upl\_71be866e430b11e9/report \\
-u :
### Response samples
* 200
* 404
Content type
application/json
Copy
`{ * "id": "ex_6a94fe68fd151e0f8", * "dateCreated": "2021-07-06T22:51:42.838Z", * "dateModified": "2022-07-06T22:51:42.838Z", * "deleted": false, * "s3Url": null, * "state": "in_progress", * "type": "failures", * "uploadId": "upl_71be866e430b11e9" }`
[](https://docs.lob.com/#tag/Uploads/operation/export_retrieve)
Retrieve Export
-------------------------------------------------------------------------------
Retrieves the details of an existing export. You need only supply the unique export identifier that was returned upon export creation. If you try retrieving an export immediately after creating one (i.e., before we're done processing the export), you will get back an export object with `state = in_progress`.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| upl\_id
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
ID of the upload |
| ex\_id
required | string (ex\_id) ^ex\_\[a-zA-Z0-9\]+$
ID of the export |
### Responses
**200**
Returns an export object
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (ex\_id) ^ex\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `ex_`. |
| dateCreated
required | string
A timestamp in ISO 8601 format of the date the export was created |
| dateModified
required | string
A timestamp in ISO 8601 format of the date the export was last modified |
| deleted
required | boolean
Returns as `true` if the resource has been successfully deleted. |
| s3Url
required | string
The URL for the generated export file. |
| state
required | string
Enum: "in\_progress" "failed" "succeeded"
The state of the export file, which can be `in_progress`, `failed` or `succeeded`. |
| type
required | string
Enum: "all" "failures" "successes"
The export file type, which can be `all`, `failures` or `successes`. |
| uploadId
required | string (upl\_id) ^upl\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `upl_`. |
get/uploads/{upl\_id}/exports/{ex\_id}
production
https://api.lob.com/v1/uploads/{upl\_id}/exports/{ex\_id}
### Request samples
* CURL
* PYTHON
* RUBY
Copy
curl https://api.lob.com/v1/uploads/upl\_71be866e430b11e9/exports/ex\_6a94fe68fd151e0f8 \\
-u :
### Response samples
* 200
Content type
application/json
Copy
`{ * "id": "ex_6a94fe68fd151e0f8", * "dateCreated": "2021-07-06T22:51:42.838Z", * "dateModified": "2022-07-06T22:51:42.838Z", * "deleted": false, * "s3Url": null, * "state": "in_progress", * "type": "failures", * "uploadId": "upl_71be866e430b11e9" }`
[](https://docs.lob.com/#tag/Informed-Delivery-Campaign)
Informed Delivery Campaign
===================================================================================
The Informed Delivery campaigns API allows you to create and view Informed Delivery campaigns.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Informed-Delivery-Campaign/operation/informed_delivery_campaign_list)
List
-------------------------------------------------------------------------------------------------------
List Informed Delivery campaigns
##### Authorizations:
_basicAuth_
### Responses
**200**
A dictionary with a data property that contains an array of up to `limit` Informed Delivery campaigns. Each entry in the array is a separate campaign. The previous and next page of campaigns can be retrieved by calling the endpoint contained in the `previous_url` and `next_url` fields in the API response respectively. If no more campaigns are available beyond the current set of returned results, the `next_url` field will be empty.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (response)
list of Informed Delivery campaigns |
get/informed\_delivery\_campaigns
production
https://api.lob.com/v1/informed\_delivery\_campaigns
### Request samples
* CURL
Copy
curl https://api.lob.com/v1/informed\_delivery\_campaign \\
-u :
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "infd_234g5324g324g23", * "object": "informed_delivery_campaign", * "account_id": "xxxxxxxxxxxxxxxxxxxx", * "quantity": 20, * "usps_campaign_id": "1234567890", * "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2", * "start_date": "2024-08-31T00:00:00.000Z", * "end_date": "2024-10-15T00:00:00.000Z", * "start_serial": 3183487, * "end_serial": 3183506, * "ride_along_url": "[https://www.lob.com](https://www.lob.com/) ", * "ride_along_image_s3_link": "[https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg](https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg) ", * "representative_image_s3_link": null, * "status": "approved", * "date_created": "2024-08-30T23:30:02.980Z", * "date_modified": "2024-08-30T23:30:05.027Z", * "mode": "live", * "lob_campaign_id": null, * "deleted": false, * "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code", * "brand_name": "Lob", * "service_request_number": null }, * { * "id": "infd_23g23g234g23g42", * "object": "informed_delivery_campaign", * "account_id": "xxxxxxxxxxxxxxxxxxxx", * "quantity": 5, * "usps_campaign_id": "23452345", * "usps_title": "Campaign: 133d228e-f9e9-4056-aaea-f", * "start_date": "2024-08-31T00:00:00.000Z", * "end_date": "2024-10-15T00:00:00.000Z", * "start_serial": null, * "end_serial": null, * "ride_along_url": "[https://www.lob.com](https://www.lob.com/) ", * "ride_along_image_s3_link": "[https://lob-assets.com/informed-delivery/infd_23g23g234g23g42_ride_along.jpg](https://lob-assets.com/informed-delivery/infd_23g23g234g23g42_ride_along.jpg) ", * "representative_image_s3_link": null, * "status": "pending_approval", * "date_created": "2024-08-30T23:30:02.980Z", * "date_modified": "2024-09-30T23:30:05.027Z", * "mode": "live", * "lob_campaign_id": null, * "deleted": false, * "campaign_code": "133d228e-f9e9-4056-aaea-f+Code", * "brand_name": "Lob", * "service_request_number": null } ], * "object": "list", * "next_url": null, * "previous_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Informed-Delivery-Campaign/operation/informed_delivery_campaign_create)
Create
-----------------------------------------------------------------------------------------------------------
Creates a new Informed Delivery campaign
##### Authorizations:
_basicAuth_
##### Request Body schema: multipart/form-data
| | |
| --- | --- |
| quantity
required | integer \[ 2 .. 10000000 \]
The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
| ride\_along\_image
required | object
JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
| ride\_along\_url
required | string \[ 10 .. 255 \] characters ^https:\\/\\/.{5,247}$
To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with [https://lob.com](https://lob.com/)
then you could use any variation of [https://lob.com](https://lob.com/)
such as [https://lob.com/promotions/promo\_123](https://lob.com/promotions/promo_123) |
| start\_date
required | string
The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
| status | string
Value: "pending\_approval"
If setting a campaign to `pending_approval` the Informed Delivery campaign will not be active, and you can not send mail using it. It will be editable in this status however, and changes can be made until `approved`. **NOTE** that the default status is `approved` which makes the campaign active, but un-editable. |
| brand\_name | string
The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
| usps\_title | string
Unique title for the campaign. One will be auto generated if not provided. |
| lob\_campaign\_id | string or null^cmp\_\[a-zA-Z0-9\]+$
When sending as part of Lob’s campaign workflow, include the lob\_campaign\_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
| representative\_image | object
JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
### Responses
**200**
Creative created successfully
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (infd\_id) ^infd\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `infd_`. |
| object
required | string
Value: "informed\_delivery\_campaign"
Value is the resource type. |
| account\_id
required | string
Your Lob account id. |
| quantity
required | integer \[ 2 .. 10000000 \]
The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
| usps\_campaign\_id
required | string (usps\_campaign\_id) ^\[0-9\]+$
A numberical string up to 12 characters long. |
| usps\_title
required | string
Unique title for the campaign. One will be auto generated if not provided. |
| start\_date
required | string
The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
| end\_date
required | string
A timestamp in ISO 8601 format of the date the campaign ends. |
| start\_serial
required | integer or null
The first serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
| end\_serial
required | integer or null
The last serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
| ride\_along\_url
required | string \[ 10 .. 255 \] characters ^https:\\/\\/.{5,247}$
To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with [https://lob.com](https://lob.com/)
then you could use any variation of [https://lob.com](https://lob.com/)
such as [https://lob.com/promotions/promo\_123](https://lob.com/promotions/promo_123) |
| ride\_along\_image\_s3\_link
required | string
A URL link to the campaigns ride along image. |
| representative\_image\_s3\_link
required | string or null
A URL link to the campaigns representative image. |
| status
required | string |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| mode
required | string
Enum: "live" "test"
The mode of the Informed Delivery campaign. This is set by the API token you used to create the campaign. |
| lob\_campaign\_id
required | string or null^cmp\_\[a-zA-Z0-9\]+$
When sending as part of Lob’s campaign workflow, include the lob\_campaign\_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
| deleted
required | boolean
Whether the resource has been deleted. |
| campaign\_code
required | string
The campaign code associated with the Informed Delivery campaign. |
| brand\_name
required | string
The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
| service\_request\_number
required | string or null
The USPS promotion service request number used to create this campaign (if there was one used). |
**422**
Error
post/informed\_delivery\_campaigns
production
https://api.lob.com/v1/informed\_delivery\_campaigns
### Request samples
* CURL
Copy
curl --request POST \\
--url https://api.lob.com/v1/informed\_delivery\_campaigns \\
-u : \\
--header 'Content-Type: multipart/form-data' \\
--form ride\_along\_url\=https://www.lob.com \\
--form 'ride\_along\_image=@/path/to/ride\_along.jpg' \\
--form quantity\=2 \\
--form start\_date\=2024\-01-01 \\
--form status\=pending\_approval
### Response samples
* 200
* 422
Content type
application/json
Copy
`{ * "id": "infd_234g5324g324g23", * "object": "informed_delivery_campaign", * "account_id": "xxxxxxxxxxxxxxxxxxxx", * "quantity": 20, * "usps_campaign_id": "1234567890", * "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2", * "start_date": "2024-08-31T00:00:00.000Z", * "end_date": "2024-10-15T00:00:00.000Z", * "start_serial": 3183487, * "end_serial": 3183506, * "ride_along_url": "[https://www.lob.com](https://www.lob.com/) ", * "ride_along_image_s3_link": "[https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg](https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg) ", * "representative_image_s3_link": null, * "status": "approved", * "date_created": "2024-08-30T23:30:02.980Z", * "date_modified": "2024-08-30T23:30:05.027Z", * "mode": "live", * "lob_campaign_id": null, * "deleted": false, * "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code", * "brand_name": "Lob", * "service_request_number": null }`
[](https://docs.lob.com/#tag/Informed-Delivery-Campaign/operation/informed_delivery_campaign_retrieve)
Retrieve
---------------------------------------------------------------------------------------------------------------
Retrieves the details of an existing Informed Delivery campaign. You need only supply the `usps_campaign_id` returned in the campaign creation request.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| usps\_campaign\_id
required | string (usps\_campaign\_id) ^\[0-9\]+$
Example: 1200772869
usps\_campaign\_id of the Informed Delivery campaign |
### Responses
**200**
Returns a informed delivery campaign object
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (infd\_id) ^infd\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `infd_`. |
| object
required | string
Value: "informed\_delivery\_campaign"
Value is the resource type. |
| account\_id
required | string
Your Lob account id. |
| quantity
required | integer \[ 2 .. 10000000 \]
The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
| usps\_campaign\_id
required | string (usps\_campaign\_id) ^\[0-9\]+$
A numberical string up to 12 characters long. |
| usps\_title
required | string
Unique title for the campaign. One will be auto generated if not provided. |
| start\_date
required | string
The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
| end\_date
required | string
A timestamp in ISO 8601 format of the date the campaign ends. |
| start\_serial
required | integer or null
The first serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
| end\_serial
required | integer or null
The last serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
| ride\_along\_url
required | string \[ 10 .. 255 \] characters ^https:\\/\\/.{5,247}$
To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with [https://lob.com](https://lob.com/)
then you could use any variation of [https://lob.com](https://lob.com/)
such as [https://lob.com/promotions/promo\_123](https://lob.com/promotions/promo_123) |
| ride\_along\_image\_s3\_link
required | string
A URL link to the campaigns ride along image. |
| representative\_image\_s3\_link
required | string or null
A URL link to the campaigns representative image. |
| status
required | string |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| mode
required | string
Enum: "live" "test"
The mode of the Informed Delivery campaign. This is set by the API token you used to create the campaign. |
| lob\_campaign\_id
required | string or null^cmp\_\[a-zA-Z0-9\]+$
When sending as part of Lob’s campaign workflow, include the lob\_campaign\_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
| deleted
required | boolean
Whether the resource has been deleted. |
| campaign\_code
required | string
The campaign code associated with the Informed Delivery campaign. |
| brand\_name
required | string
The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
| service\_request\_number
required | string or null
The USPS promotion service request number used to create this campaign (if there was one used). |
**404**
Error
get/informed\_delivery\_campaigns/{usps\_campaign\_id}
production
https://api.lob.com/v1/informed\_delivery\_campaigns/{usps\_campaign\_id}
### Request samples
* CURL
Copy
curl https://api.lob.com/v1/informed\_delivery\_campaign/1200772869 \\
-u :
### Response samples
* 200
* 404
Content type
application/json
Copy
`{ * "id": "infd_234g5324g324g23", * "object": "informed_delivery_campaign", * "account_id": "xxxxxxxxxxxxxxxxxxxx", * "quantity": 20, * "usps_campaign_id": "1234567890", * "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2", * "start_date": "2024-08-31T00:00:00.000Z", * "end_date": "2024-10-15T00:00:00.000Z", * "start_serial": 3183487, * "end_serial": 3183506, * "ride_along_url": "[https://www.lob.com](https://www.lob.com/) ", * "ride_along_image_s3_link": "[https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg](https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg) ", * "representative_image_s3_link": null, * "status": "approved", * "date_created": "2024-08-30T23:30:02.980Z", * "date_modified": "2024-08-30T23:30:05.027Z", * "mode": "live", * "lob_campaign_id": null, * "deleted": false, * "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code", * "brand_name": "Lob", * "service_request_number": null }`
[](https://docs.lob.com/#tag/Informed-Delivery-Campaign/operation/informed_delivery_campaign_update)
Update
-----------------------------------------------------------------------------------------------------------
Update the details of an existing Informed Delivery campaign.
**NOTE:** you can only update a campaign in the `pending_approval` status.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| usps\_campaign\_id
required | string (usps\_campaign\_id) ^\[0-9\]+$
Example: 1200772869
usps\_campaign\_id of the Informed Delivery campaign |
##### Request Body schema: multipart/form-data
| | |
| --- | --- |
| quantity | integer \[ 2 .. 10000000 \]
The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
| status | string
Value: "approved"
After setting an Informed Delivery campaign to “approved” said campaign will activate, and you can start sending mail using it. You will no longer be able to edit an Informed Delivery campaign in this status. |
| ride\_along\_url | string \[ 10 .. 255 \] characters ^https:\\/\\/.{5,247}$
To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with [https://lob.com](https://lob.com/)
then you could use any variation of [https://lob.com](https://lob.com/)
such as [https://lob.com/promotions/promo\_123](https://lob.com/promotions/promo_123) |
| start\_date | string
The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
| brand\_name | string
The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
| usps\_title | string
Unique title for the campaign. One will be auto generated if not provided. |
| lob\_campaign\_id | string or null^cmp\_\[a-zA-Z0-9\]+$
When sending as part of Lob’s campaign workflow, include the lob\_campaign\_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
| ride\_along\_image | object
JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
| representative\_image | object
JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
### Responses
**200**
Returns an Informed Delivery campaign object
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string (infd\_id) ^infd\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `infd_`. |
| object
required | string
Value: "informed\_delivery\_campaign"
Value is the resource type. |
| account\_id
required | string
Your Lob account id. |
| quantity
required | integer \[ 2 .. 10000000 \]
The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
| usps\_campaign\_id
required | string (usps\_campaign\_id) ^\[0-9\]+$
A numberical string up to 12 characters long. |
| usps\_title
required | string
Unique title for the campaign. One will be auto generated if not provided. |
| start\_date
required | string
The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
| end\_date
required | string
A timestamp in ISO 8601 format of the date the campaign ends. |
| start\_serial
required | integer or null
The first serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
| end\_serial
required | integer or null
The last serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
| ride\_along\_url
required | string \[ 10 .. 255 \] characters ^https:\\/\\/.{5,247}$
To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with [https://lob.com](https://lob.com/)
then you could use any variation of [https://lob.com](https://lob.com/)
such as [https://lob.com/promotions/promo\_123](https://lob.com/promotions/promo_123) |
| ride\_along\_image\_s3\_link
required | string
A URL link to the campaigns ride along image. |
| representative\_image\_s3\_link
required | string or null
A URL link to the campaigns representative image. |
| status
required | string |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| mode
required | string
Enum: "live" "test"
The mode of the Informed Delivery campaign. This is set by the API token you used to create the campaign. |
| lob\_campaign\_id
required | string or null^cmp\_\[a-zA-Z0-9\]+$
When sending as part of Lob’s campaign workflow, include the lob\_campaign\_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
| deleted
required | boolean
Whether the resource has been deleted. |
| campaign\_code
required | string
The campaign code associated with the Informed Delivery campaign. |
| brand\_name
required | string
The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
| service\_request\_number
required | string or null
The USPS promotion service request number used to create this campaign (if there was one used). |
**404**
Error
**422**
Error
patch/informed\_delivery\_campaigns/{usps\_campaign\_id}
production
https://api.lob.com/v1/informed\_delivery\_campaigns/{usps\_campaign\_id}
### Request samples
* CURL
Copy
curl -X PATCH https://api.lob.com/v1/creatives/crv\_2a3b096c409b32c \\
-u : \\
-d '{"status":"approved"}'
### Response samples
* 200
* 404
* 422
Content type
application/json
Copy
`{ * "id": "infd_234g5324g324g23", * "object": "informed_delivery_campaign", * "account_id": "xxxxxxxxxxxxxxxxxxxx", * "quantity": 20, * "usps_campaign_id": "1234567890", * "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2", * "start_date": "2024-08-31T00:00:00.000Z", * "end_date": "2024-10-15T00:00:00.000Z", * "start_serial": 3183487, * "end_serial": 3183506, * "ride_along_url": "[https://www.lob.com](https://www.lob.com/) ", * "ride_along_image_s3_link": "[https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg](https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg) ", * "representative_image_s3_link": null, * "status": "approved", * "date_created": "2024-08-30T23:30:02.980Z", * "date_modified": "2024-08-30T23:30:05.027Z", * "mode": "live", * "lob_campaign_id": null, * "deleted": false, * "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code", * "brand_name": "Lob", * "service_request_number": null }`
[](https://docs.lob.com/#tag/US-Verifications)
US Verifications
===============================================================
Validate, automatically correct, and standardize the addresses in your address book based on USPS's [Coding Accuracy Support System (CASS)](https://postalpro.usps.com/certifications/cass)
.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/US-Verifications/US-Verifications-Test-Env)
US Verifications Test Env
--------------------------------------------------------------------------------------------------
When verifying US addresses, you'll likely want to test against a wide array of addresses to ensure you're handling responses correctly. With your test API key, requests that use specific values for `address` or `primary_line` and (if using `primary_line`) an arbitrary five digit number for `zip_code` (e.g. "11111") let you explore the responses to many types of addresses:
| ADDRESS TYPE FOR SAMPLE RESPONSE | DELIVERABILITY | SET `primary_line` OR `address` TO |
| --- | --- | --- |
| Commercial highrise | `deliverable` | `commercial highrise` |
| Residential highrise | `deliverable` | `residential highrise` |
| Residential house | `deliverable` | `residential house` |
| PO Box | `deliverable` | `po box` |
| Rural route | `deliverable` | `rural route` |
| Puerty Rico address w/ urbanization | `deliverable` | `puerto rico` |
| Military address | `deliverable` | `military` |
| Department of state | `deliverable` | `department of state` |
| Generic deliverable | `deliverable` | `deliverable` |
| Missing a suite number | `deliverable_missing_unit` | `missing unit` |
| Suite number doesn't exist | `deliverable_incorrect_unit` | `incorrect unit` |
| Residential house with unnecessary suite number | `deliverable_unnecessary_unit` | `unnecessary unit` |
| Undeliverable and block matched | `undeliverable` | `undeliverable block match` |
| Undeliverable and no block matched | `undeliverable` | `undeliverable no match` |
See the `test` request & response examples under [US Verification Examples](https://docs.lob.com/#operation/us_verification)
within the "Verify a US or US territory address" section in US Verifications.
You can rely on the response from these examples generally matching the response you'd see in the live environment with an address of that type (excluding the `recipient` field).
The test API key does not perform any verification, automatic correction, or standardization for addresses. If you wish to try these features out, use our [live demo](https://lob.com/address-verification)
or the free plan (see [our pricing](https://lob.com/pricing/address-verification)
for details).
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/US-Verifications/operation/bulk_us_verifications)
Bulk Verify
------------------------------------------------------------------------------------------
Verify a list of US or US territory addresses _with a live API key_. Requests to this endpoint with a test API key will return a dummy response based on the primary line you input.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| case | string
Default: "upper"
Enum: "upper" "proper"
Casing of the verified address. Possible values are `upper` and `proper` for uppercased (e.g. "PO BOX") and proper-cased (e.g. "PO Box"), respectively. Only affects `recipient`, `primary_line`, `secondary_line`, `urbanization`, and `last_line`. Default casing is `upper`. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| addresses
required | Array of US verification object with \`city\` and \`state\` (object) or US verification object with \`zip\_code\` (object) (multiple\_components) \[ 1 .. 20 \] items |
### Responses
**200**
Returns a list of US verification objects.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| addresses
required | Array of us\_verification (object) or error (object) |
| errors
required | boolean
Indicates whether any errors occurred during the verification process. |
**default**
Error
post/bulk/us\_verifications
production
https://api.lob.com/v1/bulk/us\_verifications
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "addresses": [ * { * "primary_line": "210 King Street", * "city": "San Francisco", * "state": "CA", * "zip_code": "94107" }, * { * "recipient": "Walgreens", * "primary_line": "Ave Wilson Churchill 123", * "secondary_line": "", * "urbanization": "URB FAIR OAKS", * "city": "RIO PIEDRAS", * "state": "PR", * "zip_code": "00926" } ] }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "addresses": [ * { * "id": "us_ver_c7cb63d68f8d6", * "recipient": "LOB.COM", * "primary_line": "210 KING ST", * "secondary_line": "", * "urbanization": "", * "last_line": "SAN FRANCISCO CA 94107-1702", * "deliverability": "deliverable", * "valid_address": true, * "components": { * "primary_number": "210", * "street_predirection": "", * "street_name": "KING", * "street_suffix": "ST", * "street_postdirection": "", * "secondary_designator": "", * "secondary_number": "", * "pmb_designator": "", * "pmb_number": "", * "extra_secondary_designator": "", * "extra_secondary_number": "", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107", * "zip_code_plus_4": "1702", * "zip_code_type": "standard", * "delivery_point_barcode": "941071728506", * "address_type": "commercial", * "record_type": "street", * "default_building_address": false, * "county": "SAN FRANCISCO", * "county_fips": "06075", * "carrier_route": "C032", * "carrier_route_type": "city_delivery", * "po_box_only_flag": "N", * "latitude": 37.77597542841264, * "longitude": -122.3929557343685 }, * "deliverability_analysis": { * "dpv_confirmation": "Y", * "dpv_cmra": "N", * "dpv_vacant": "N", * "dpv_active": "Y", * "dpv_inactive_reason": "", * "dpv_throwback": "N", * "dpv_non_delivery_day_flag": "N", * "dpv_non_delivery_day_values": "", * "dpv_no_secure_location": "N", * "dpv_door_not_accessible": "N", * "dpv_footnotes": [ * "AA", * "BB" ], * "ews_match": false, * "lacs_indicator": "", * "lacs_return_code": "", * "suite_return_code": "" }, * "lob_confidence_score": { * "score": 100, * "level": "high" }, * "object": "us_verification" } ], * "errors": false }`
[](https://docs.lob.com/#tag/US-Verifications/operation/us_verification)
Single Verify
--------------------------------------------------------------------------------------
Verify a US or US territory address _with a live API key_. The address can be in components (e.g. `primary_line` is "210 King Street", `zip_code` is "94107") or as a single string (e.g. "210 King Street 94107"), but not as both. Requests using a test API key validate required fields but return empty values unless specific `primary_line` values are provided. See the [US Verifications Test Environment](https://docs.lob.com/#section/US-Verifications-Test-Env)
for details.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| case | string
Default: "upper"
Enum: "upper" "proper"
Casing of the verified address. Possible values are `upper` and `proper` for uppercased (e.g. "PO BOX") and proper-cased (e.g. "PO Box"), respectively. Only affects `recipient`, `primary_line`, `secondary_line`, `urbanization`, and `last_line`. Default casing is `upper`. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
One of
multiple\_componentssingle\_line\_address
Any of
US verification object with \`city\` and \`state\`US verification object with \`zip\_code\`
| | |
| --- | --- |
| city
required | string <= 200 characters
The name of the city. `city` and `state` are required if no `zip_code` is passed. |
| state
required | string <= 50 characters
The [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US)
two letter code or subdivision name for the state. `city` and `state` are required if no `zip_code` is passed. |
| primary\_line
required | string (primary\_line\_us) <= 200 characters
The primary delivery line (usually the street address) of the address. Combination of the following applicable `components`:
* `primary_number`
* `street_predirection`
* `street_name`
* `street_suffix`
* `street_postdirection`
* `secondary_designator`
* `secondary_number`
* `pmb_designator`
* `pmb_number` |
| recipient | string or null (recipient) <= 500 characters
The intended recipient, typically a person's or firm's name. |
| secondary\_line | string (secondary\_line) <= 200 characters
The secondary delivery line of the address. This field is typically empty but may contain information if `primary_line` is too long. |
| urbanization | string (urbanization) <= 200 characters
Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See [USPS documentation](https://pe.usps.com/text/pub28/28api_008.htm#:~:text=I51.,-4%20Urbanizations&text=In%20Puerto%20Rico%2C%20identical%20street,placed%20before%20the%20urbanization%20name.)
for clarification. |
| zip\_code | string^\\d{5}((-)?\\d{4})?$
Required if `city` and `state` are not passed in. If included, must be formatted as a US ZIP or ZIP+4 (e.g. `94107`, `941072282`, `94107-2282`). |
### Responses
**200**
Returns a US verification object.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (us\_ver\_id) ^us\_ver\_\[a-zA-Z0-9\_\]+$
Unique identifier prefixed with `us_ver_`. |
| recipient | string or null (recipient) <= 500 characters
The intended recipient, typically a person's or firm's name. |
| primary\_line | string (primary\_line\_us) <= 200 characters
The primary delivery line (usually the street address) of the address. Combination of the following applicable `components`:
* `primary_number`
* `street_predirection`
* `street_name`
* `street_suffix`
* `street_postdirection`
* `secondary_designator`
* `secondary_number`
* `pmb_designator`
* `pmb_number` |
| secondary\_line | string (secondary\_line) <= 200 characters
The secondary delivery line of the address. This field is typically empty but may contain information if `primary_line` is too long. |
| urbanization | string (urbanization) <= 200 characters
Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See [USPS documentation](https://pe.usps.com/text/pub28/28api_008.htm#:~:text=I51.,-4%20Urbanizations&text=In%20Puerto%20Rico%2C%20identical%20street,placed%20before%20the%20urbanization%20name.)
for clarification. |
| last\_line | string
Combination of the following applicable `components`:
* City (`city`)
* State (`state`)
* ZIP code (`zip_code`)
* ZIP+4 (`zip_code_plus_4`) |
| deliverability | string
Enum: "deliverable" "deliverable\_unnecessary\_unit" "deliverable\_incorrect\_unit" "deliverable\_missing\_unit" "undeliverable"
Summarizes the deliverability of the `us_verification` object. For full details, see the `deliverability_analysis` field. Possible values are:
* `deliverable` – The address is deliverable by the USPS.
* `deliverable_unnecessary_unit` – The address is deliverable, but the secondary unit information is unnecessary.
* `deliverable_incorrect_unit` – The address is deliverable to the building's default address but the secondary unit provided may not exist. There is a chance the mail will not reach the intended recipient.
* `deliverable_missing_unit` – The address is deliverable to the building's default address but is missing secondary unit information. There is a chance the mail will not reach the intended recipient.
* `undeliverable` – The address is not deliverable according to the USPS. |
| valid\_address | boolean
Enum: true false
This field indicates whether an address was found in a more comprehensive address dataset that includes sources from the USPS, open source mapping data, and our proprietary mail delivery data. This field can be interpreted as a representation of whether an address is a real location or not. Additionally a valid address may contradict the deliverability field since an address can be a real valid location but the USPS may not deliver to that address. |
| components | object (us\_components)
A nested object containing a breakdown of each component of an address. |
| deliverability\_analysis | object (deliverability\_analysis)
A nested object containing a breakdown of the deliverability of an address. |
| lob\_confidence\_score | object (lob\_confidence\_score)
Lob Confidence Score is a nested object that provides a numerical value between 0-100 of the likelihood that an address is deliverable based on Lob’s mail delivery data to over half of US households. |
| object | string
Default: "us\_verification"
Value: "us\_verification"
Value is resource type. |
**default**
Error
post/us\_verifications
production
https://api.lob.com/v1/us\_verifications
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Example
basicfull\_payloadsingle\_linetestbasic
Copy
`{ * "primary_line": "210 King Street", * "city": "San Francisco", * "state": "CA", * "zip_code": "94107" }`
### Response samples
* 200
* default
Content type
application/json
Example
basictestbasic
Copy
Expand all Collapse all
`{ * "id": "us_ver_c7cb63d68f8d6", * "recipient": "LOB.COM", * "primary_line": "210 KING ST", * "secondary_line": "", * "urbanization": "", * "last_line": "SAN FRANCISCO CA 94107-1702", * "deliverability": "deliverable", * "valid_address": true, * "components": { * "primary_number": "210", * "street_predirection": "", * "street_name": "KING", * "street_suffix": "ST", * "street_postdirection": "", * "secondary_designator": "", * "secondary_number": "", * "pmb_designator": "", * "pmb_number": "", * "extra_secondary_designator": "", * "extra_secondary_number": "", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107", * "zip_code_plus_4": "1702", * "zip_code_type": "standard", * "delivery_point_barcode": "941071702108", * "address_type": "commercial", * "record_type": "street", * "default_building_address": false, * "county": "SAN FRANCISCO", * "county_fips": "06075", * "carrier_route": "C032", * "carrier_route_type": "city_delivery", * "po_box_only_flag": "N", * "latitude": 37.77597542841264, * "longitude": -122.3929557343685 }, * "deliverability_analysis": { * "dpv_confirmation": "Y", * "dpv_cmra": "N", * "dpv_vacant": "N", * "dpv_active": "Y", * "dpv_inactive_reason": "", * "dpv_throwback": "N", * "dpv_non_delivery_day_flag": "N", * "dpv_non_delivery_day_values": "", * "dpv_no_secure_location": "N", * "dpv_door_not_accessible": "N", * "dpv_footnotes": [ * "AA", * "BB" ], * "ews_match": false, * "lacs_indicator": "", * "lacs_return_code": "", * "suite_return_code": "" }, * "lob_confidence_score": { * "score": 100, * "level": "high" }, * "object": "us_verification" }`
[](https://docs.lob.com/#tag/US-Verification-Types)
US Verification Types
=========================================================================
These are detailed definitions for various fields in the [US verification object](https://docs.lob.com/#operation/us_verification)
.
### ZIP Code Types - `components[zip_code_type]`
| | |
| --- | --- |
| `standard` | The default ZIP code type. Used when none of the other types apply. |
| `po_box` | The ZIP code contains only PO Boxes. |
| `unique` | The ZIP code is uniquely assigned to a single organization (such as a government agency) that receives a large volume of mail. |
| `military` | The ZIP code contains military addresses. |
| _empty string_ | A match could not be made with the provided inputs. |
### Record Types - `components[record_type]`
| | |
| --- | --- |
| `street` | The default address type. |
| `highrise` | The address is a commercial building, apartment complex, highrise, etc. |
| `firm` | The address is of an organizational entity which receives a minimum number of mailpieces per day. |
| `po_box` | The address is a PO Box. |
| `rural_route` | The address exists on a Rural Route. This is an older system of mail delivery which is still used in some parts of the country. |
| `general_delivery` | The address is part of the USPS General Delivery service, which allows individuals without permanent addresses to receive mail. |
| _empty string_ | A match could not be made with the provided inputs. |
### Carrier Route Types - `components[carrier_route_type]`
| | |
| --- | --- |
| `city_delivery` | The default carrier route type. Used when none of the other types apply. |
| `rural_route` | The carrier route is a Rural Route. This is an older system of mail delivery which is still used in some parts of the country. |
| `highway_contract` | The carrier route is a Highway Contract Route. This is an older system of mail delivery which is still used in some parts of the country. |
| `po_box` | The carrier route consists of PO Boxes. |
| `general_delivery` | The carrier route is part of the USPS General Delivery service, which allows individuals without permanent addresses to receive mail. |
| _empty string_ | A match could not be made with the provided inputs. |
### DPV Footnotes - `deliverability_analysis[dpv_footnotes]`
| | |
| --- | --- |
| `AA` | Some parts of the address (such as the street and ZIP code) are valid. |
| `A1` | The address is invalid based on given inputs. |
| `BB` | The address is deliverable. |
| `CC` | The address is deliverable by removing the provided secondary unit designator. |
| `TA` | The address is deliverable by dropping a trailing alphabet from the primary number. |
| `IA` | The address is an [Informed Address](https://www.usps.com/business/informed-address.htm)
. The recipient and the street address is replaced with a special code provided by the USPS. |
| `N1` | The address is deliverable but is missing a secondary information (apartment, unit, etc). |
| `F1` | The address is a deliverable military address. |
| `G1` | The address is a deliverable General Delivery address. General Delivery is a USPS service which allows individuals without permanent addresses to receive mail. |
| `U1` | The address is a deliverable unique address. A unique ZIP code is assigned to a single organization (such as a government agency) that receives a large volume of mail. |
| `C1` | The primary number was confirmed whereas the secondary number is unconfirmed and required to be deliverable. |
| `M1` | The primary number is missing. |
| `M3` | The primary number is invalid. |
| `P1` | PO Box, Rural Route, or Highway Contract box number is missing. |
| `P3` | PO Box, Rural Route, or Highway Contract box number is invalid. |
| `PB` | The address is identified as PO Box street address. |
| `R1` | The address matched to a [CMRA](https://en.wikipedia.org/wiki/Commercial_mail_receiving_agency)
and private mailbox information is not present. |
| `R7` | The address matched to a Phantom Carrier Route (`carrier_route` of `R777`), which corresponds to physical addresses that are not eligible for delivery. |
| `RR` | The address matched to a [CMRA](https://en.wikipedia.org/wiki/Commercial_mail_receiving_agency)
and private mailbox information is present. |
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/US-Autocompletions)
US Autocompletions
===================================================================
Given partial address information, this endpoint returns up to 10 address suggestions.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/US-Autocompletions/Autocompletion-Test-Env)
Autocompletion Test Env
------------------------------------------------------------------------------------------------
Your test API key does not autocomplete US addresses and is used to simulate behavior. With your test API key, requests with specific values for `address_prefix` return predetermined values. When `address_prefix` is set to:
* `0 suggestions` - Returns no suggestions - `[PRIMARY NUMBER] s[uggestion]` - Returns a maximum of ten predefined suggested addresses. `[PRIMARY NUMBER]` does not have to be a valid primary number when sending a test request. Each additional letter in `suggestion` reduces the number of suggestions by one (e.g. `1 su` returns 9 suggested addresses). `[PRIMARY NUMBER]` does not affect the number of suggestions returned.
City and state filters work as expected and filter the list of predetermined suggested addresses. See the `test` request & response examples under [Autocomplete Examples](https://docs.lob.com/#operation/autocompletion)
within the "Autocomplete a partial address" section in US Autocompletions.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/US-Autocompletions/operation/autocompletion)
Autocomplete
--------------------------------------------------------------------------------------
Given an address prefix consisting of a partial primary line, as well as optional input of city, state, and zip code, this functionality returns up to 10 full US address suggestions. Not all of them will turn out to be valid addresses; they'll need to be [verified](https://docs.lob.com/#operation/verification_us)
.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| case | string
Default: "upper"
Enum: "upper" "proper"
Casing of the verified address. Possible values are `upper` and `proper` for uppercased (e.g. "PO BOX") and proper-cased (e.g. "PO Box"), respectively. Only affects `primary_line`, `city`, and `state`. Default casing is `upper`. |
| valid\_addresses | boolean
Default: false
Enum: true false
Possible values are `true` and `false`. If false, not all of the suggestions in the response will be valid addresses; they'll need to be verified in order to determine the deliverability. The valid\_addresses flag will greatly reduce the number of keystrokes needed before reaching an intended address. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| address\_prefix
required | string
Only accepts numbers and street names in an alphanumeric format. |
| city | string
An optional city input used to filter suggestions. Case insensitive and does not match partial abbreviations. |
| state | string
An optional state input used to filter suggestions. Case insensitive and does not match partial abbreviations. |
| zip\_code | string
An optional ZIP Code input used to filter suggestions. Matches partial entries. |
| geo\_ip\_sort | boolean
If `true`, sort suggestions by proximity to the IP set in the `X-Forwarded-For` header. |
### Responses
**200**
Returns a US autocompletion object.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (us\_auto\_id) ^us\_auto\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `us_auto_`. |
| suggestions | Array of objects (suggestions) \[ 0 .. 10 \] items
An array of objects representing suggested addresses. |
| object | string
Default: "us\_autocompletion"
Value: "us\_autocompletion"
Value is resource type. |
**default**
Error
post/us\_autocompletions
production
https://api.lob.com/v1/us\_autocompletions
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Example
basictestbasic
Copy
`{ * "address_prefix": "185 B", * "city": "San Francisco", * "state": "CA", * "zip_code": "94107", * "geo_ip_sort": false }`
### Response samples
* 200
* default
Content type
application/json
Example
basictestbasic
Copy
Expand all Collapse all
`{ * "id": "us_auto_a3ac97bcfbb2460ab20c", * "suggestions": [ * { * "primary_line": "185 BAYSIDE VILLAGE PL", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107" }, * { * "primary_line": "185 BRANNAN ST", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107" }, * { * "primary_line": "185 BONIFACIO ST", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107" }, * { * "primary_line": "185 BLAIR TER", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107" }, * { * "primary_line": "185 BLUXOME ST", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107" }, * { * "primary_line": "210 KING ST", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107" }, * { * "primary_line": "185 BRYANT ST", * "city": "SAN FRANCISCO", * "state": "CA", * "zip_code": "94107" } ], * "object": "us_autocompletion" }`
[](https://docs.lob.com/#tag/Reverse-Geocode-Lookups)
Reverse Geocode Lookups
=============================================================================
Find a list of zip codes associated with a valid US location via latitude and longitude.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Reverse-Geocode-Lookups/operation/reverse_geocode_lookup)
Reverse Geocode Lookup
-------------------------------------------------------------------------------------------------------------
Reverse geocode a valid US location with a live API key.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| size | integer \[ 1 .. 50 \]
Default: 5
Example: size=5
Determines the number of locations returned. Possible values are between 1 and 50 and any number higher will be rounded down to 50. Default size is a list of 5 reverse geocoded locations. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| latitude
required | number or null \[ -90 .. 90 \]
A positive or negative decimal indicating the geographic latitude of the address, specifying the north-to-south position of a location. This should be input with `longitude` to pinpoint locations on a map. |
| longitude
required | number or null \[ -180 .. 180 \]
A positive or negative decimal indicating the geographic longitude of the address, specifying the north-to-south position of a location. This should be input with `latitude` to pinpoint locations on a map. |
### Responses
**200**
Returns a zip lookup object if a valid zip was provided.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (reverse\_geocode\_id) ^us\_reverse\_geocode\_\[a-zA-Z0-9\_\]+$
Unique identifier prefixed with `us_reverse_geocode_`. |
| addresses | Array of objects (addresses)
list of addresses |
| object | string
Default: "us\_reverse\_geocode\_lookup"
Value: "us\_reverse\_geocode\_lookup"
Value is resource type. |
**default**
Error
post/us\_reverse\_geocode\_lookups
production
https://api.lob.com/v1/us\_reverse\_geocode\_lookups
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "latitude": 37.7749, * "longitude": 122.4194 }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "us_reverse_geocode_8a013f3e", * "addresses": [ * { * "components": { * "zip_code": "94107", * "zip_code_plus_4": "1702" }, * "location_analysis": { * "latitude": 37.78271, * "longitude": -122.416202, * "distance": 1.32 } }, * { * "components": { * "zip_code": "94107", * "zip_code_plus_4": "1702" }, * "location_analysis": { * "latitude": 37.782917, * "longitude": -122.416131, * "distance": 1.33 } } ] }`
[](https://docs.lob.com/#tag/Zip-Lookups)
Zip Lookups
=====================================================
Find a list of cities, states and associated information about a US ZIP code.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Zip-Lookups/operation/zip_lookup)
Lookups
----------------------------------------------------------------------
Returns information about a ZIP code
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| zip\_code
required | string^\\d{5}$
A 5-digit ZIP code. |
### Responses
**200**
Returns a zip lookup object if a valid zip was provided.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| zip\_code
required | string^\\d{5}$
A 5-digit ZIP code. |
| id
required | string (zip\_id) ^us\_zip\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `us_zip_`. |
| cities
required | Array of objects (zip\_lookup\_city)
An array of city objects containing valid cities for the `zip_code`. Multiple cities will be returned if more than one city is associated with the input ZIP code. |
| zip\_code\_type
required | string (zip\_code\_type)
Enum: "standard" "po\_box" "unique" "military" ""
A description of the ZIP code type. For more detailed information about each ZIP code type, see [US Verification Details](https://docs.lob.com/#tag/US-Verification-Types)
. |
| object
required | string
Default: "us\_zip\_lookup"
Value: "us\_zip\_lookup"
Value is resource type. |
**default**
Error
post/us\_zip\_lookups
production
https://api.lob.com/v1/us\_zip\_lookups
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "zip_code": "94107" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "us_zip_c7cb63d68f8d6", * "cities": [ * { * "city": "SAN FRANCISCO", * "state": "CA", * "county": "SAN FRANCISCO", * "county_fips": "06075", * "preferred": true } ], * "zip_code_type": "standard", * "object": "us_zip_lookup", * "zip_code": "94107" }`
[](https://docs.lob.com/#tag/Identity-Validation)
Identity Validation
=====================================================================
Validates whether a given name is associated with an address.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Identity-Validation/operation/identity_validation)
Identity Validation
---------------------------------------------------------------------------------------------------
Validates whether a given name is associated with an address.
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
One of
recipient\_inputcompany\_input
Any of
Address object with \`city\` and \`state\`Address object with \`zip\_code\`
| | |
| --- | --- |
| city
required | string <= 200 characters
The name of the city. `city` and `state` are required if no `zip_code` is passed. |
| state
required | string <= 50 characters
The [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2:US)
two letter code or subdivision name for the state. `city` and `state` are required if no `zip_code` is passed. |
| recipient
required | string or null (recipient) <= 500 characters
The intended recipient, typically a person's or firm's name. |
| primary\_line
required | string (primary\_line\_us) <= 200 characters
The primary delivery line (usually the street address) of the address. Combination of the following applicable `components`:
* `primary_number`
* `street_predirection`
* `street_name`
* `street_suffix`
* `street_postdirection`
* `secondary_designator`
* `secondary_number`
* `pmb_designator`
* `pmb_number` |
| secondary\_line | string (secondary\_line) <= 200 characters
The secondary delivery line of the address. This field is typically empty but may contain information if `primary_line` is too long. |
| urbanization | string (urbanization) <= 200 characters
Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See [USPS documentation](https://pe.usps.com/text/pub28/28api_008.htm#:~:text=I51.,-4%20Urbanizations&text=In%20Puerto%20Rico%2C%20identical%20street,placed%20before%20the%20urbanization%20name.)
for clarification. |
| zip\_code | string^\\d{5}((-)?\\d{4})?$
Required if `city` and `state` are not passed in. If included, must be formatted as a US ZIP or ZIP+4 (e.g. `94107`, `941072282`, `94107-2282`). |
### Responses
**200**
Returns the likelihood a given name is associated with an address.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
One of
recipient\_validationcompany\_validation
| | |
| --- | --- |
| id | string (identity\_validation\_id) ^id\_validation\_\[a-zA-Z0-9\_\]+$
Unique identifier prefixed with `id_validation_`. |
| recipient | string or null (identity\_validation\_recipient) <= 500 characters
The name of the person whose identity is being validated. |
| primary\_line | string (primary\_line\_us) <= 200 characters
The primary delivery line (usually the street address) of the address. Combination of the following applicable `components`:
* `primary_number`
* `street_predirection`
* `street_name`
* `street_suffix`
* `street_postdirection`
* `secondary_designator`
* `secondary_number`
* `pmb_designator`
* `pmb_number` |
| secondary\_line | string (secondary\_line) <= 200 characters
The secondary delivery line of the address. This field is typically empty but may contain information if `primary_line` is too long. |
| urbanization | string (urbanization) <= 200 characters
Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See [USPS documentation](https://pe.usps.com/text/pub28/28api_008.htm#:~:text=I51.,-4%20Urbanizations&text=In%20Puerto%20Rico%2C%20identical%20street,placed%20before%20the%20urbanization%20name.)
for clarification. |
| last\_line | string
Combination of the following applicable `components`:
* City (`city`)
* State (`state`)
* ZIP code (`zip_code`)
* ZIP+4 (`zip_code_plus_4`) |
| score | number or null \[ 0 .. 100 \]
Default: null
A numerical score between 0 and 100 that represents the likelihood the provided name is associated with a physical address. |
| confidence | string
Enum: "high" "medium" "low" ""
Indicates the likelihood the recipient name and address match based on our custom internal calculation. Possible values are:
* `high` — Has a Lob confidence score greater than 70.
* `medium` — Has a Lob confidence score between 40 and 70.
* `low` — Has a Lob confidence score less than 40.
* `""` — No tracking data exists for this address. |
| object | string
Default: "id\_validation"
Value: "id\_validation"
Value is resource type. |
**default**
Error
post/identity\_validation
production
https://api.lob.com/v1/identity\_validation
### Request samples
* Payload
* CURL
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "recipient": "Larry Lobster", * "primary_line": "210 King St.", * "secondary_line": "", * "city": "San Francisco", * "state": "CA", * "zip_code": "94107" }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "id_validation_8a013f3e", * "recipient": "LARRY LOBSTER", * "primary_line": "210 KING ST.", * "secondary_line": "", * "urbanization": "", * "last_line": "SAN FRANCISCO CA 94107-1728", * "score": 100, * "confidence": "high", * "object": "id_validation" }`
[](https://docs.lob.com/#tag/Intl-Verifications)
Intl Verifications
===================================================================
Address verification for non-US addresses
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Intl-Verifications/Intl-Verifications-Test-Env)
Intl Verifications Test Env
--------------------------------------------------------------------------------------------------------
When verifying international addresses, you'll likely want to test against a wide array of addresses to ensure you're handling responses correctly. With your test API key, requests that use specific values for `primary_line` let you explore the responses to many types of addresses:
| DELIVERABILITY OF SAMPLE RESPONSE | SET `primary_line` TO |
| --- | --- |
| `deliverable` | deliverable |
| `deliverable_missing_info` | deliverable missing info |
| `undeliverable` | undeliverable |
| `no_match` | no match |
See the `test` request & response examples under [Intl Verification Examples](https://docs.lob.com/#operation/intl_verification)
within the "Verify an international address section" in Intl Verifications.
You can rely on the response from these examples generally matching the response you'd see in the live environment with an address of that type (excluding the `recipient` field).
The test API key does not perform any verification, automatic correction, or standardization for addresses. If you wish to try these features out, use our [live demo](https://lob.com/address-verification)
or the free plan (see [our pricing](https://lob.com/pricing/address-verification)
for details).
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Intl-Verifications/operation/bulk_intl_verifications)
Bulk Verify
----------------------------------------------------------------------------------------------
Verify a list of international (except US or US territories) address _with a live API key_. Requests to this endpoint with a test API key will return a dummy response based on the primary line you input.
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonmultipart/form-dataapplication/json
| | |
| --- | --- |
| addresses
required | Array of objects (multiple\_components\_intl) \[ 1 .. 20 \] items |
### Responses
**200**
Returns an array of international verification objects.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| addresses
required | Array of intl\_verification (object) or error (object) |
| errors
required | boolean
Indicates whether any errors occurred during the verification process. |
**default**
Error
post/bulk/intl\_verifications
production
https://api.lob.com/v1/bulk/intl\_verifications
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
Content type
application/jsonmultipart/form-dataapplication/json
Copy
Expand all Collapse all
`{ * "addresses": [ * { * "recipient": "John Doe", * "primary_line": "370 Water St", * "secondary_line": "", * "city": "Summerside", * "state": "Prince Edwards Island", * "postal_code": "C1N 1C4", * "country": "CA" }, * { * "recipient": "Jane Doe", * "primary_line": "UL. DOLSKAYA 1", * "secondary_line": "", * "city": "MOSCOW", * "state": "MOSCOW G", * "postal_code": "115569", * "country": "RU" } ] }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "addresses": [ * { * "id": "intl_ver_c7cb63d68f8d6", * "recipient": null, * "primary_line": "370 WATER ST", * "secondary_line": "", * "last_line": "SUMMERSIDE PE C1N 1C4", * "country": "CA", * "coverage": "SUBBUILDING", * "deliverability": "deliverable", * "status": "LV4", * "components": { * "primary_number": "370", * "street_name": "WATER ST", * "city": "SUMMERSIDE", * "state": "PE", * "postal_code": "C1N 1C4" }, * "object": "intl_verification" } ], * "errors": false }`
[](https://docs.lob.com/#tag/Intl-Verifications/operation/intl_verification)
Single Verify
------------------------------------------------------------------------------------------
Verify an international (except US or US territories) address _with a live API key_. Requests to this endpoint with a test API key will return a dummy response based on the primary line you input.
##### Authorizations:
_basicAuth_
##### header Parameters
| | |
| --- | --- |
| x-lang-output | string
Enum: "native" "match"
* `native` - Translate response to the native language of the country in the request
* `match` - match the response to the language in the request
Default response is in English. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
One of
multiple\_components\_intlsingle\_line\_address\_intl
| | |
| --- | --- |
| primary\_line
required | string (primary\_line) <= 200 characters
The primary delivery line (usually the street address) of the address. |
| country
required | string (country\_extended)
Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AN" "AO" "AQ" "AR" "AT" "AU" "AW" "AZ" "BA" … 202 more
Must be a 2 letter country short-name code (ISO 3166). Does not accept `US`, `AS`, `PR`, `FM`, `GU`, `MH`, `MP`, `PW`, or `VI`. For these addresses, please use the US verification API. Also does not accept `PS`, which is not currently supported. |
| recipient | string or null (recipient) <= 500 characters
The intended recipient, typically a person's or firm's name. |
| secondary\_line | string (secondary\_line) <= 200 characters
The secondary delivery line of the address. This field is typically empty but may contain information if `primary_line` is too long. |
| city | string (city) <= 200 characters
The name of the city. |
| state | string
The name of the state. |
| postal\_code | string (postal\_code) <= 12 characters
The postal code. |
### Responses
**200**
Returns an international verification object.
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| recipient | string or null (recipient) <= 500 characters
The intended recipient, typically a person's or firm's name. |
| primary\_line | string (primary\_line) <= 200 characters
The primary delivery line (usually the street address) of the address. |
| secondary\_line | string (secondary\_line) <= 200 characters
The secondary delivery line of the address. This field is typically empty but may contain information if `primary_line` is too long. |
| id | string (intl\_ver\_id) ^intl\_ver\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `intl_ver_`. |
| last\_line | string
Combination of the following applicable `components`:
* `city`
* `state`
* `zip_code`
* `zip_code_plus_4` |
| country | string (country\_short)
The country of the address. Will be returned as a 2 letter country short-name code (ISO 3166). |
| coverage | string
Enum: "SUBBUILDING" "HOUSENUMBER/BUILDING" "STREET" "LOCALITY" "SPARSE"
The coverage level for the country. This represents the maximum level of accuracy an input address can be verified to.
* `SUBBUILDING` - Coverage down to unit numbers. For example, in an apartment or a large building
* `HOUSENUMBER/BUILDING` - Coverage down to house number. For example, the address where a house or building may be located
* `STREET` - Coverage down to street. This means that we can verify that an street exists in a city, state, country
* `LOCALITY` - Coverage down to city, state, or village or province. This means that we can verify that a city, village, province, or state exists in a country. Countries differ in how they define what is a province, state, city, village, etc. This attempts to group eveyrthing together.
* `SPARSE` - Some addresses for this country exist in our databases |
| deliverability | string
Enum: "deliverable" "deliverable\_missing\_info" "undeliverable" "no\_match"
Summarizes the deliverability of the `intl_verification` object. Possible values are:
* `deliverable` — The address is deliverable.
* `deliverable_missing_info` — The address is missing some information, but is most likely deliverable.
* `undeliverable` — The address is most likely not deliverable. Some components of the address (such as city or postal code) may have been found.
* `no_match` — This address is not deliverable. No matching street could be found within the city or postal code. |
| status | string
Enum: "LV4" "LV3" "LV2" "LV1" "LF4" "LF3" "LF2" "LF1" "LM4" "LM3" "LM2" "LU1"
The status level for the country. This represents the maximum level of accuracy an input address can be verified to.
* `LV4` - Verified. The input data is correct. All input data was able to match in databases.
* `LV3` - Verified. The input data is correct. All input data was able to match in databases _after_ some or all elements were standarized. The input data may also be using outdated city, state, or country names.
* `LV2` - Verified. The input data is correct although some input data is unverifiable due to incomplete data.
* `LV1` - Verified. The input data is acceptable but in an attempt to standarize user input, errors were introduced.
* `LF4` - Fixed. The input data is matched and fixed. (Example: Brighon, UK -> Brighton, UK)
* `LF3` - Fixed. The input data is matched and fixed but some elements such as Subbuilding number and house number cannot be checked.
* `LF2` - Fixed. The input data is matched but some elements such as Street cannot be checked.
* `LF1` - Fixed. The input data is acceptable but in an attempt to standarize user input, errors were introduced.
* `LM4` - Missing Info. The input data cannot be corrected completely.
* `LM3` - Missing Info. The input data cannot be corrected completely and there were multiple matches found in databases.
* `LM2` - Missing Info. The input data cannot be corrected completely and only some elements were found.
* `LU1` - Unverified. The input data cannot be corrected or matched. |
| components | object (intl\_components)
A nested object containing a breakdown of each component of an address. |
| object | string
Default: "intl\_verification"
Value: "intl\_verification"
Value is resource type. |
**default**
Error
post/intl\_verifications
production
https://api.lob.com/v1/intl\_verifications
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Example
basicfull\_payloadsingle\_linetestbasic
Copy
`{ * "recipient": "Harry Zhang", * "primary_line": "370 Water St", * "secondary_line": "", * "city": "Summerside", * "state": "Prince Edward Island", * "postal code": "C1N 1C4", * "country": "CA" }`
### Response samples
* 200
* default
Content type
application/json
Example
fulltestfull
Copy
Expand all Collapse all
`{ * "id": "intl_ver_c7cb63d68f8d6", * "recipient": null, * "primary_line": "370 WATER ST", * "secondary_line": "", * "last_line": "SUMMERSIDE PE C1N 1C4", * "country": "CA", * "coverage": "SUBBUILDING", * "deliverability": "deliverable", * "status": "LV4", * "components": { * "primary_number": "370", * "street_name": "WATER ST", * "city": "SUMMERSIDE", * "state": "PE", * "postal_code": "C1N 1C4" }, * "object": "intl_verification" }`
[](https://docs.lob.com/#tag/Webhooks)
Webhooks
===============================================
Webhooks are an easy way to get notifications on events happening asynchronously within Lob's architecture. For example, when a postcard gets a "Processed For Delivery" tracking event, an event object of type `postcard.processed_for_delivery` will be created. If you are subscribed to that event type in that Environment (Test vs. Live), Lob will send that event to any URLs you've specified via an HTTP POST request. In Live mode, you can only have as many webhooks as allotted in your current [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions)
. There is no limit in Test mode. You can view and create [webhooks](https://dashboard.lob.com/#/webhooks)
on the Lob Dashboard, as well as view your [events](https://dashboard.lob.com/#/events)
. See our [Webhooks Integration Guide](https://help.lob.com/print-and-mail/getting-data-and-results/using-webhooks)
for more details on how to integrate. Please see the full list of event types available for subscription here.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Events)
Events
===========================================
When various notable things happen within the Lob architecture, Events will be created. To get these events sent to your server automatically when they occur, you can set up [Webhooks](https://docs.lob.com/#tag/Webhooks)
.
### Postcards
| EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
| --- | --- | --- |
| `postcard.created` | `false` | A postcard is successfully created (Lob returns a 200 status code). |
| `postcard.rejected` | `false` | A postcard was not successfully created (Usually happens when one or more postcards fail the creation step during a batch request) |
| `postcard.rendered_pdf` | `false` | A postcard's PDF proof is successfully rendered. |
| `postcard.rendered_thumbnails` | `false` | A postcard's thumbnails are successfully rendered. |
| `postcard.deleted` | `false` | A postcard is successfully canceled. |
| `postcard.mailed` | `true` | A postcard receives a "Mailed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
. |
| `postcard.in_transit` | `true` | A postcard receives an "In Transit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.in_local_area` | `true` | A postcard receives an "In Local Area" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.processed_for_delivery` | `true` | A postcard receives a "Processed for Delivery" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.delivered` | `false` | A postcard receives a "Delivered" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.failed` | `false` | A postcard receives a "Failed" [rendering error](https://help.lob.com/print-and-mail/designing-mail-creatives/creative-formatting/rendering-errors)
or [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.re-routed` | `true` | A postcard receives a "Re-Routed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.returned_to_sender` | `true` | A postcard receives a "Returned to Sender" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.international_exit` | `true` | A postcard receives a "International Exit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `postcard.viewed` | `false` | A postcard QR code or URL was scanned or viewed by the recipient. |
| `postcard.informed_delivery.email_sent` | `true` | An informed delivery email was sent to the recipient. |
| `postcard.informed_delivery.email_opened` | `true` | An informed delivery email was opened by the recipient. |
| `postcard.informed_delivery.email_clicked_through` | `true` | The link in an informed delivery email was clicked on. |
### Self Mailers
| EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
| --- | --- | --- |
| `self_mailer.created` | `false` | A self\_mailer is successfully created (Lob returns a 200 status code). |
| `self_mailer.rejected` | `false` | A self\_mailer was not successfully created (Usually happens when one or more self\_mailers fail the creation step during a batch request) |
| `self_mailer.rendered_pdf` | `false` | A self\_mailer's PDF proof is successfully rendered. |
| `self_mailer.rendered_thumbnails` | `false` | A self\_mailer's thumbnails are successfully rendered. |
| `self_mailer.deleted` | `false` | A self\_mailer is successfully canceled. |
| `self_mailer.mailed` | `true` | A self\_mailer receives a "Mailed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
. |
| `self_mailer.in_transit` | `true` | A self\_mailer receives an "In Transit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.in_local_area` | `true` | A self\_mailer receives an "In Local Area" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.processed_for_delivery` | `true` | A self\_mailer receives a "Processed for Delivery" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.delivered` | `true` | A self\_mailer receives an "Delivered" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.failed` | `false` | A self\_mailer receives an "Failed" [rendering error](https://help.lob.com/print-and-mail/designing-mail-creatives/creative-formatting/rendering-errors)
or [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.re-routed` | `true` | A self\_mailer receives a "Re-Routed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.returned_to_sender` | `true` | A self\_mailer receives a "Returned to Sender" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.international_exit` | `true` | A self\_mailer receives an "International Exit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `self_mailer.viewed` | `false` | A self\_mailer's QR code or URL was scanned or viewed by the recipient. |
| `self_mailer.informed_delivery.email_sent` | `true` | An informed delivery email was sent to the recipient. |
| `self_mailer.informed_delivery.email_opened` | `true` | An informed delivery email was opened by the recipient. |
| `self_mailer.informed_delivery.email_clicked_through` | `true` | The link in an informed delivery email was clicked on. |
### Letters
| EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
| --- | --- | --- |
| `letter.created` | `false` | A letter is successfully created (Lob returns a 200 status code). |
| `letter.rejected` | `false` | A letter was not successfully created (Usually happens when one or more letters fail the creation step during a batch request) |
| `letter.rendered_pdf` | `false` | A letter's PDF proof is successfully rendered. |
| `letter.rendered_thumbnails` | `false` | A letter's thumbnails are successfully rendered. |
| `letter.deleted` | `false` | A letter is successfully canceled. |
| `letter.mailed` | `true` | A letter receives a "Mailed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
. |
| `letter.in_transit` | `true` | A letter receives an "In Transit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.in_local_area` | `true` | A letter receives an "In Local Area" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.processed_for_delivery` | `true` | A letter receives a "Processed for Delivery" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.delivered` | `true` | A letter receives a "Delivered" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.failed` | `false` | A letter receives a "Failed" [rendering error](https://help.lob.com/print-and-mail/designing-mail-creatives/creative-formatting/rendering-errors)
or [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.re-routed` | `true` | A letter receives a "Re-Routed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.returned_to_sender` | `true` | A letter receives a "Returned to Sender" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.international_exit` | `true` | A letter receives a "International Exit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.viewed` | `false` | A letter's QR code or URL was scanned or viewed by the recipient. |
| `letter.certified.mailed` | `true` | A certified letter receives a "Mailed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
. |
| `letter.certified.in_transit` | `true` | A certified letter receives an "In Transit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.certified.in_local_area` | `true` | A certified letter receives an "In Transit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.certified.processed_for_delivery` | `true` | A certified letter receives a "Processed for Delivery" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.certified.re-routed` | `true` | A certified letter receives a "Re-Routed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.certified.returned_to_sender` | `true` | A certified letter receives a "Returned to Sender" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.certified.delivered` | `true` | A certified letter receives a "Delivered" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.certified.pickup_available` | `true` | A certified letter receives a "Pickup Available" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.certified.issue` | `true` | A certified letter receives an "Issue" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.return_envelope.created` | `false` | A return envelope is created (occurs simultaneously with letter creation). |
| `letter.return_envelope.in_transit` | `true` | A return envelope receives an "In Transit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.return_envelope.in_local_area` | `true` | A return envelope receives an "In Local Area" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.return_envelope.processed_for_delivery` | `true` | A return envelope receives a "Processed for Delivery" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.return_envelope.re-routed` | `true` | A return envelope receives a "Re-Routed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.return_envelope.returned_to_sender` | `true` | A return envelope receives a "Returned to Sender" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `letter.informed_delivery.email_sent` | `true` | An informed delivery email was sent to the recipient. |
| `letter.informed_delivery.email_opened` | `true` | An informed delivery email was opened by the recipient. |
| `letter.informed_delivery.email_clicked_through` | `true` | The link in an informed delivery email was clicked on. |
### Checks
| EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
| --- | --- | --- |
| `check.created` | `false` | A check is successfully created (Lob returns a 200 status code). |
| `check.rejected` | `false` | A check was not successfully created (Usually happens when one or more checks fail the creation step during a batch request) |
| `check.rendered_pdf` | `false` | A check's PDF proof is successfully rendered. |
| `check.rendered_thumbnails` | `false` | A check's thumbnails are successfully rendered. |
| `check.deleted` | `false` | A check is successfully canceled. |
| `check.mailed` | `true` | A check receives a "Mailed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions)
. |
| `check.in_transit` | `true` | A check receives an "In Transit" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `check.in_local_area` | `true` | A check receives an "In Local Area" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `check.processed_for_delivery` | `true` | A check receives a "Processed for Delivery" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `check.delivered` | `true` | A check receives a "Delivered" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `check.failed` | `false` | A check receives a "Failed" [rendering error](https://help.lob.com/print-and-mail/designing-mail-creatives/creative-formatting/rendering-errors)
or [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `check.re-routed` | `true` | A check receives a "Re-Routed" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `check.returned_to_sender` | `true` | A check receives a "Returned to Sender" [tracking event](https://docs.lob.com/#operation/tracking_event)
. |
| `check.informed_delivery.email_sent` | `true` | An informed delivery email was sent to the recipient. |
| `check.informed_delivery.email_opened` | `true` | An informed delivery email was opened by the recipient. |
| `check.informed_delivery.email_clicked_through` | `true` | The link in an informed delivery email was clicked on. |
### Addresses
| EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
| --- | --- | --- |
| `address.created` | `false` | An address is successfully created (Lob returns a 200 status code). |
| `address.deleted` | `false` | An address is successfully deleted. |
### Bank Accounts
| EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
| --- | --- | --- |
| `bank_account.created` | `false` | A bank account is successfully created (Lob returns a 200 status code). |
| `bank_account.deleted` | `false` | A bank account is successfully deleted. |
| `bank_account.verified` | `false` | A bank account is successfully verified. |
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Events/operation/event)
Events Webhook
-------------------------------------------------------------------
Information about an event
##### Authorizations:
_basicAuth_
### Responses
**200**
Returns an `event` object to the specified server.
##### Response Schema: application/json
| | |
| --- | --- |
| id
required | string^evt\_\[a-zA-Z0-9\_\]+$
Unique identifier prefixed with `evt_`. |
| body
required | object
The body of the associated resource as they were at the time of the event, i.e. the [postcard object](https://docs.lob.com/#operation/postcard_retrieve)
, [the letter object](https://docs.lob.com/#operation/letter_retrieve)
, [the check object](https://docs.lob.com/#operation/check_retrieve)
, [the address object](https://docs.lob.com/#operation/address_retrieve)
, or [the bank account object](https://docs.lob.com/#operation/bank_account_retrieve)
. For `.deleted` events, the body matches the response for the corresponding delete endpoint for that resource (e.g. the [postcard delete response](https://docs.lob.com/#operation/postcard_delete)
). |
| reference\_id
required | string
Unique identifier of the related resource for the event. |
| event\_type
required | object (event\_type) |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| object
required | string
Default: "event"
Value: "event"
Value is resource type. |
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`{ * "event_type": { * "resource": "postcards", * "enabled_for_test": true, * "id": "postcard.created", * "object": "event_type" }, * "reference_id": "psc_d2d10a2e9cba991c", * "id": "evt_d95ff8ffd2b5cfb4", * "date_created": "2016-12-04T22:50:08.180Z", * "body": { * "id": "psc_d2d10a2e9cba991c", * "description": "Test Postcard", * "metadata": { }, * "to": { * "id": "adr_8e783523dd7f0e70", * "description": "Test Recipient Address", * "name": "Harry Zhang", * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "123 TEST ST", * "address_line2": "UNIT 1", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2016-12-04T10:51:51.844Z", * "date_modified": "2016-12-04T10:51:51.844Z", * "object": "address" }, * "from": { * "id": "adr_d2e26faf793ed422", * "description": "Test Sender Address", * "name": "Harry Zhang", * "company": "LOB", * "phone": null, * "email": null, * "address_line1": "123 TEST ST", * "address_line2": "UNIT 1", * "address_city": "SAN FRANCISCO", * "address_state": "CA", * "address_zip": "94107", * "address_country": "UNITED STATES", * "metadata": { }, * "date_created": "2016-12-04T10:51:51.845Z", * "date_modified": "2016-12-04T10:51:51.845Z", * "object": "address" }, * "url": "[https://lob-assets.com/postcards/psc_d2d10a2e9cba991c.pdf?expires=1540372221&signature=dNE8OtbDymujUxBIMYle4H1cv1aZNFk](https://lob-assets.com/postcards/psc_d2d10a2e9cba991c.pdf?expires=1540372221&signature=dNE8OtbDymujUxBIMYle4H1cv1aZNFk) ", * "front_template_id": null, * "back_template_id": null, * "carrier": "USPS", * "tracking_events": [ ], * "thumbnails": [ * { * "small": "[https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_small_1.png?expires=1540372221&signature=McmqScxPgbe7yQY5X31U3vhU8VUlfA1](https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_small_1.png?expires=1540372221&signature=McmqScxPgbe7yQY5X31U3vhU8VUlfA1) ", * "medium": "[https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_medium_1.png?expires=1540372221&signature=VBClptOuCcj9Ybay6gE5aetT5j3C7KS](https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_medium_1.png?expires=1540372221&signature=VBClptOuCcj9Ybay6gE5aetT5j3C7KS) ", * "large": "[https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_large_1.png?expires=1540372221&signature=RAHpIwoYKYM17f0bbaoOiamCkjpzYfH](https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_large_1.png?expires=1540372221&signature=RAHpIwoYKYM17f0bbaoOiamCkjpzYfH) " }, * { * "small": "[https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_small_1.png?expires=1540372221&signature=5biHoaCmkphQaGJymOZxmTF0hHdiH4N](https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_small_1.png?expires=1540372221&signature=5biHoaCmkphQaGJymOZxmTF0hHdiH4N) ", * "medium": "[https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_medium_1.png?expires=1540372221&signature=1ApGx0kn5EO4qQKGJzCe6zEPnQpzpRY](https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_medium_1.png?expires=1540372221&signature=1ApGx0kn5EO4qQKGJzCe6zEPnQpzpRY) ", * "large": "[https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_large_1.png?expires=1540372221&signature=z80p90RBak6T26IAfg5yg7a6qKF53a8](https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_large_1.png?expires=1540372221&signature=z80p90RBak6T26IAfg5yg7a6qKF53a8) " } ], * "merge_variables": null, * "mail_type": "usps_first_class", * "size": "4x6", * "expected_delivery_date": "2016-12-09", * "date_created": "2016-12-04T10:51:51.843Z", * "date_modified": "2016-12-04T10:51:51.843Z", * "send_date": "2016-12-04T10:56:51.843Z", * "object": "postcard" }, * "object": "event" }`
[](https://docs.lob.com/#tag/Tracking-Events)
Tracking Events
=============================================================
As mailpieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events.
### Certified Tracking Event Details
Letters sent with USPS Certified Mail are fully tracked by USPS, and therefore their [tracking events](https://docs.lob.com/#operation/tracking_event)
have an additional `details` object with more detailed information about the tracking event. The following table shows the potential values for the fields in the `details` object mapped to the tracking event `name`.
| NAME | EVENT | DESCRIPTION | ACTION REQUIRED |
| --- | --- | --- | --- |
| Mailed | `package_accepted` | Package has been accepted into the carrier network for delivery. | `false` |
| In Transit | `package_arrived` | Package has arrived at an intermediate location in the carrier network. | `false` |
| In Transit | `package_departed` | Package has departed from an intermediate location in the carrier network. | `false` |
| In Transit | `package_processing` | Package is processing at an intermediate location in the carrier network. | `false` |
| In Transit | `package_processed` | Package has been processed at an intermediate location. | `false` |
| In Local Area | `package_in_local_area` | Package is at a location near the end destination. | `false` |
| Processed For Delivery | `delivery_scheduled` | Package is scheduled for delivery. | `false` |
| Processed For Delivery | `out_for_delivery` | Package is out for delivery. | `false` |
| Pickup Available | `pickup_available` | Package is available for pickup at carrier location. | `true` |
| Delivered | `delivered` | Package has been delivered. | `false` |
| Re-Routed | `package_forwarded` | Package has been forwarded. | `false` |
| Returned to Sender | `returned_to_sender` | Package is to be returned to sender. | `false` |
| Issue | `address_issue` | Address information is incorrect. Contact carrier to ensure delivery. | `true` |
| Issue | `contact_carrier` | Contact the carrier for more information. | `true` |
| Issue | `delayed` | Delivery of package is delayed. | `false` |
| Issue | `delivery_attempted` | Delivery of package has been attempted. Contact carrier to ensure delivery. | `true` |
| Issue | `delivery_rescheduled` | Delivery of package has been rescheduled. | `false` |
| Issue | `location_inaccessible` | Delivery location inaccessible to carrier. Contact carrier to ensure delivery. | `true` |
| Issue | `notice_left` | Carrier left notice during attempted delivery. Follow carrier instructions on notice. | `true` |
| Issue | `package_damaged` | Package has been damaged. Contact carrier for more details. | `true` |
| Issue | `package_disposed` | Package has been disposed. | `false` |
| Issue | `package_held` | Package held at carrier location. Contact carrier for more details. | `true` |
| Issue | `package_lost` | Package has been lost. Contact carrier for more details. | `true` |
| Issue | `package_unclaimed` | Package is unclaimed. | `true` |
| Issue | `package_undeliverable` | Package is not able to be delivered. | `true` |
| Issue | `reschedule_delivery` | Contact carrier to reschedule delivery. | `true` |
| Issue | `other` | Unrecognized carrier status. | `false` |
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Tracking-Events/operation/tracking_event)
Tracking Events Webhook
----------------------------------------------------------------------------------------------
Information about tracking events
##### Authorizations:
_basicAuth_
### Responses
**200**
Returns a `tracking_event` object to the specified server.
##### Response Schema: application/json
One of
tracking\_event\_normaltracking\_event\_certified
| | |
| --- | --- |
| id
required | string (evnt\_id) ^evnt\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `evnt_`. |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "tracking\_event"
Value: "tracking\_event"
Value is resource type. |
| type
required | string
Value: "normal"
non-Certified postcards, self mailers, letters, checks and snap packs |
| name
required | string
Enum: "Mailed" "In Transit" "In Local Area" "Processed for Delivery" "Delivered" "Re-Routed" "Returned to Sender" "International Exit"
Name of tracking event (for normal postcards, self mailers, letters, checks and snap packs):
* `Mailed` - The mailpiece has been handed off to and accepted by USPS and is en route. [More about Mailed.](https://help.lob.com/print-and-mail/getting-data-and-results/tracking-your-mail#mailed-tracking-events-4)
Note this data is only available in Enterprise editions of Lob. [Contact Sales](https://lob.com/support/contact#contact)
if you want access to this feature.
* `In Transit` - The mailpiece is being processed at the entry/origin facility.
* `In Local Area` - The mailpiece is being processed at the destination facility.
* `Processed for Delivery` - The mailpiece has been greenlit for delivery at the recipient's nearest postal facility. The mailpiece should reach the mailbox within 1 business day of this tracking event.
* `Delivered` - The mail piece has been delivered to the recipient’s address. The final scan is generated when the mail carrier's GPS unit leaves the delivery area.
* `Re-Routed` - The mailpiece is re-routed due to recipient change of address, address errors, or USPS relabeling of barcode/ID tag area.
* `Returned to Sender` - The mailpiece is being returned to sender due to barcode, ID tag area, or address errors.
* `International Exit` - The mail piece has been processed to ship to a destination abroad. This is typically the last scan a US-originated international mail piece will receive from the USPS.
[More about tracking](https://help.lob.com/print-and-mail/getting-data-and-results/tracking-your-mail#mailed-tracking-events-4) |
| time | string
A timestamp in ISO 8601 format of the date USPS registered the event. |
| details | object or null
Value: null
Will be `null` for `type=normal` events |
| location | string or null
The zip code in which the scan event occurred. Null for `Mailed` events. |
### Response samples
* 200
Content type
application/json
Example
normalcertifiednormal
Copy
`{ * "id": "evnt_9e84094c9368cfb", * "type": "normal", * "name": "In Local Area", * "details": null, * "location": "72231", * "time": "2016-06-30T15:51:41.000Z", * "date_created": "2016-06-30T17:41:59.771Z", * "date_modified": "2016-06-30T17:41:59.771Z", * "object": "tracking_event" }`
[](https://docs.lob.com/#tag/Billing-Groups)
Billing Groups
===========================================================
The Billing Groups API allows you to create and view labels that can be attached to certain consumption-based usages of Letters, Checks, Postcards and Self-Mailers to customize your bill. Please check each resource API section to learn more about how to access the Billing Groups API.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Billing-Groups/operation/billing_group_retrieve)
Retrieve
--------------------------------------------------------------------------------------
Retrieves the details of an existing billing\_group. You need only supply the unique billing\_group identifier that was returned upon billing\_group creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| bg\_id
required | string (bg\_id) ^bg\_\[a-zA-Z0-9\]+$
id of the billing\_group |
### Responses
**200**
Returns a billing\_group object.
##### Response Schema: application/json
| | |
| --- | --- |
| description | string (bg\_description) <= 255 characters
Description of the billing group. |
| name | string (name) <= 255 characters
Name of the billing group. |
| id | string (bg\_id) ^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object | string
Default: "billing\_group"
Value: "billing\_group"
Value is resource type. |
**default**
Error
get/billing\_groups/{bg\_id}
production
https://api.lob.com/v1/billing\_groups/{bg\_id}
### Request samples
* Shell
* RUBY
* GO
Copy
curl https://api.lob.com/v1/billing\_groups/bg\_4bb02b527a72667d0 \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "bg_c94e83ca2cd5121", * "name": "Marketing Dept", * "description": "Usage group used for the Marketing Dept resource sends", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "billing_group" }`
[](https://docs.lob.com/#tag/Billing-Groups/operation/billing_group_update)
Update
----------------------------------------------------------------------------------
Updates all editable attributes of the billing\_group with the given id.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| bg\_id
required | string (bg\_id) ^bg\_\[a-zA-Z0-9\]+$
id of the billing\_group |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| description | string (bg\_description) <= 255 characters
Description of the billing group. |
| name | string (name) <= 255 characters
Name of the billing group. |
### Responses
**200**
Returns a billing group object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| description | string (bg\_description) <= 255 characters
Description of the billing group. |
| name | string (name) <= 255 characters
Name of the billing group. |
| id | string (bg\_id) ^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object | string
Default: "billing\_group"
Value: "billing\_group"
Value is resource type. |
**default**
Error
post/billing\_groups/{bg\_id}
production
https://api.lob.com/v1/billing\_groups/{bg\_id}
### Request samples
* Payload
* Shell
* RUBY
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "name": "Marketing Dept", * "description": "Usage group used for the Marketing Dept resource sends" }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "bg_c94e83ca2cd5121", * "name": "Marketing Dept", * "description": "Usage group used for the Marketing Dept resource sends", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "billing_group" }`
[](https://docs.lob.com/#tag/Billing-Groups/operation/billing_groups_list)
List
-------------------------------------------------------------------------------
Returns a list of your billing\_groups. The billing\_groups are returned sorted by creation date, with the most recently created billing\_groups appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| offset | integer
Default: 0
An integer that designates the offset at which to begin returning results. Defaults to 0. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| date\_modified | object (date\_filter)
Filter by date modified. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| sort\_by | object or object
Sorts items by ascending or descending dates. Use either `date_created` or `date_modified`, not both. |
### Responses
**200**
Returns a list of billing\_groups.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (billing\_group)
list of billing\_groups |
**default**
Error
get/billing\_groups
production
https://api.lob.com/v1/billing\_groups
### Request samples
* Shell
* RUBY
* GO
Copy
curl -X GET "https://api.lob.com/v1/billing\_groups?limit=2" \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "bg_d5a5a89da9106f8", * "description": "Test billing_group", * "metadata": { }, * "date_created": "2019-07-27T23:49:01.511Z", * "date_modified": "2019-07-27T23:49:01.511Z", * "object": "billing_group" }, * { * "id": "bg_59b2150ae120887", * "description": "Test billing_group", * "metadata": { }, * "date_created": "2019-03-29T10:22:34.642Z", * "date_modified": "2019-03-29T10:22:34.642Z", * "object": "billing_group" } ], * "object": "list", * "next_url": null, * "prev_url": null, * "count": 2 }`
[](https://docs.lob.com/#tag/Billing-Groups/operation/billing_group_create)
Create
----------------------------------------------------------------------------------
Creates a new billing\_group with the provided properties.
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| name
required | string (name) <= 255 characters
Name of the billing group. |
| description | string (bg\_description) <= 255 characters
Description of the billing group. |
### Responses
**200**
Returns a billing group object
| | |
| --- | --- |Response Headers
| ratelimit-limit | integer
Example: 150
The rate limit for a given endpoint. |
| ratelimit-remaining | integer
Example: 100
The number of requests remaining in the current window. |
| ratelimit-reset | integer
Example: 1528749846
The time at which the rate limit window resets in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time) |
##### Response Schema: application/json
| | |
| --- | --- |
| description | string (bg\_description) <= 255 characters
Description of the billing group. |
| name | string (name) <= 255 characters
Name of the billing group. |
| id | string (bg\_id) ^bg\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bg_`. |
| date\_created | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object | string
Default: "billing\_group"
Value: "billing\_group"
Value is resource type. |
**default**
Error
post/billing\_groups
production
https://api.lob.com/v1/billing\_groups
### Request samples
* Payload
* Shell
* RUBY
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "name": "Marketing Dept", * "description": "Usage group used for the Marketing Dept resource sends" }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "bg_c94e83ca2cd5121", * "name": "Marketing Dept", * "description": "Usage group used for the Marketing Dept resource sends", * "date_created": "2017-11-07T22:56:10.962Z", * "date_modified": "2017-11-07T22:56:10.962Z", * "object": "billing_group" }`
[](https://docs.lob.com/#tag/Buckslips)
Buckslips
=================================================
The Buckslips endpoint allows you to easily create buckslips that can later be used as add-ons for Letters Campaigns. Note that a Letter Campaign with Buckslip add-on requires a minimum send quantity of 5,000 letters. The API provides endpoints for creating buckslips, retrieving individual buckslips, creating buckslip orders, and retrieving a list of buckslips.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Buckslips/operation/buckslips_list)
List
---------------------------------------------------------------------
Returns a list of your buckslips. The buckslips are returned sorted by creation date, with the most recently created buckslips appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
### Responses
**200**
Returns a list of buckslip objects
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (buckslip)
list of buckslips |
**default**
Error
get/buckslips
production
https://api.lob.com/v1/buckslips
### Request samples
* CURL
Copy
curl -X GET "https://api.lob.com/v1/buckslips?limit=2" \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "bck_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": null, * "url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "8.75x3.75", * "has_front": true, * "has_back": true, * "auto_reorder": false, * "reorder_quantity": null, * "threshold_amount": 0, * "raw_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " } ], * "available_quantity": 0, * "allocated_quantity": 0, * "onhand_quantity": 0, * "pending_quantity": 0, * "projected_quantity": 0, * "buckslip_orders": [ ], * "stock": "text", * "weight": "80#", * "finish": "gloss", * "status": "rendered", * "mode": "test", * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "buckslip" } ], * "object": "list", * "previous_url": null, * "next_url": null, * "count": 1 }`
[](https://docs.lob.com/#tag/Buckslips/operation/buckslip_create)
Create
------------------------------------------------------------------------
Creates a new buckslip given information
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| front
required | remote\_file\_url (string) or local\_file\_path (string)
A PDF template for the front of the buckslip |
| description | string or null (buckslip\_description) <= 255 characters
Description of the buckslip. |
| size | string
Default: "8.75x3.75"
Value: "8.75x3.75"
The size of the buckslip |
| back | remote\_file\_url (string) or local\_file\_path (string)
A PDF template for the back of the buckslip |
### Responses
**200**
Buckslip created successfully
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "buckslip"
Value: "buckslip"
Value is resource type. |
| description
required | string or null (buckslip\_description) <= 255 characters
Description of the buckslip. |
| id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bck_`. |
| auto\_reorder
required | boolean
Default: false
True if the buckslips should be auto-reordered. |
| reorder\_quantity
required | integer or null
The number of buckslips to be reordered. |
| threshold\_amount
required | integer
Default: 0
The threshold amount of the buckslip |
| url
required | string \[ 1 .. 2083 \] characters
The signed link for the buckslip. |
| raw\_url
required | string \[ 1 .. 2083 \] characters
The raw URL of the buckslip. |
| front\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the front template. |
| back\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the back template. |
| thumbnails
required | Array of objects (thumbnail) |
| available\_quantity
required | number
Default: 0
The available quantity of buckslips. |
| allocated\_quantity
required | number
Default: 0
The allocated quantity of buckslips. |
| onhand\_quantity
required | number
Default: 0
The onhand quantity of buckslips. |
| pending\_quantity
required | number
Default: 0
The pending quantity of buckslips. |
| projected\_quantity
required | number
Default: 0
The sum of pending and onhand quantities of buckslips. |
| buckslip\_orders
required | Array of objects (buckslip\_order) \>= 0 items
An array of buckslip orders that are associated with the buckslip. |
| stock
required | string (The stock of the buckslip.)
Enum: "text" "cover" |
| weight
required | string (The weight of the buckslip.)
Value: "80#" |
| finish
required | string (The finish of the buckslip.)
Enum: "gloss" "matte" |
| status
required | string (The status of the buckslip.)
Enum: "processed" "rendered" "failed" |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| size | string
Default: "8.75x3.75"
Value: "8.75x3.75"
The size of the buckslip |
**default**
Error
post/buckslips
production
https://api.lob.com/v1/buckslips
### Request samples
* Payload
* CURL
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Test buckslip", * "front": "[https://s3-us-west-2.amazonaws.com/public.lob.com/assets/buckslip.pdf](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/buckslip.pdf) ", * "back": "[https://s3-us-west-2.amazonaws.com/public.lob.com/assets/buckslip.pdf](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/buckslip.pdf) " }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "bck_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": "Test buckslip", * "url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "8.75x3.755", * "auto_reorder": false, * "reorder_quantity": null, * "threshold_amount": 0, * "raw_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 0, * "allocated_quantity": 0, * "onhand_quantity": 0, * "pending_quantity": 0, * "projected_quantity": 0, * "buckslip_orders": [ ], * "stock": "text", * "weight": "80#", * "finish": "gloss", * "status": "rendered", * "mode": "test", * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "buckslip" }`
[](https://docs.lob.com/#tag/Buckslips/operation/buckslip_retrieve)
Retrieve
----------------------------------------------------------------------------
Retrieves the details of an existing buckslip. You need only supply the unique customer identifier that was returned upon buckslip creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| buckslip\_id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
id of the buckslip |
### Responses
**200**
Returns a buckslip object
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "buckslip"
Value: "buckslip"
Value is resource type. |
| description
required | string or null (buckslip\_description) <= 255 characters
Description of the buckslip. |
| id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bck_`. |
| auto\_reorder
required | boolean
Default: false
True if the buckslips should be auto-reordered. |
| reorder\_quantity
required | integer or null
The number of buckslips to be reordered. |
| threshold\_amount
required | integer
Default: 0
The threshold amount of the buckslip |
| url
required | string \[ 1 .. 2083 \] characters
The signed link for the buckslip. |
| raw\_url
required | string \[ 1 .. 2083 \] characters
The raw URL of the buckslip. |
| front\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the front template. |
| back\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the back template. |
| thumbnails
required | Array of objects (thumbnail) |
| available\_quantity
required | number
Default: 0
The available quantity of buckslips. |
| allocated\_quantity
required | number
Default: 0
The allocated quantity of buckslips. |
| onhand\_quantity
required | number
Default: 0
The onhand quantity of buckslips. |
| pending\_quantity
required | number
Default: 0
The pending quantity of buckslips. |
| projected\_quantity
required | number
Default: 0
The sum of pending and onhand quantities of buckslips. |
| buckslip\_orders
required | Array of objects (buckslip\_order) \>= 0 items
An array of buckslip orders that are associated with the buckslip. |
| stock
required | string (The stock of the buckslip.)
Enum: "text" "cover" |
| weight
required | string (The weight of the buckslip.)
Value: "80#" |
| finish
required | string (The finish of the buckslip.)
Enum: "gloss" "matte" |
| status
required | string (The status of the buckslip.)
Enum: "processed" "rendered" "failed" |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| size | string
Default: "8.75x3.75"
Value: "8.75x3.75"
The size of the buckslip |
**default**
Error
get/buckslips/{buckslip\_id}
production
https://api.lob.com/v1/buckslips/{buckslip\_id}
### Request samples
* CURL
Copy
curl https://api.lob.com/v1/buckslips/bck\_7a6d73c5c8457fc \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "bck_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": "Test buckslip", * "url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "8.75x3.755", * "auto_reorder": false, * "reorder_quantity": null, * "threshold_amount": 0, * "raw_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 0, * "allocated_quantity": 0, * "onhand_quantity": 0, * "pending_quantity": 0, * "projected_quantity": 0, * "buckslip_orders": [ ], * "stock": "text", * "weight": "80#", * "finish": "gloss", * "status": "rendered", * "mode": "test", * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "buckslip" }`
[](https://docs.lob.com/#tag/Buckslips/operation/buckslip_update)
Update
------------------------------------------------------------------------
Update the details of an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| buckslip\_id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
id of the buckslip |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| description | string or null (buckslip\_description) <= 255 characters
Description of the buckslip. |
| auto\_reorder | boolean
Allows for auto reordering |
| reorder\_quantity | number \[ 5000 .. 10000000 \]
The quantity of items to be reordered (only required when auto\_reorder is true). |
### Responses
**200**
Returns a buckslip object
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "buckslip"
Value: "buckslip"
Value is resource type. |
| description
required | string or null (buckslip\_description) <= 255 characters
Description of the buckslip. |
| id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bck_`. |
| auto\_reorder
required | boolean
Default: false
True if the buckslips should be auto-reordered. |
| reorder\_quantity
required | integer or null
The number of buckslips to be reordered. |
| threshold\_amount
required | integer
Default: 0
The threshold amount of the buckslip |
| url
required | string \[ 1 .. 2083 \] characters
The signed link for the buckslip. |
| raw\_url
required | string \[ 1 .. 2083 \] characters
The raw URL of the buckslip. |
| front\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the front template. |
| back\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the back template. |
| thumbnails
required | Array of objects (thumbnail) |
| available\_quantity
required | number
Default: 0
The available quantity of buckslips. |
| allocated\_quantity
required | number
Default: 0
The allocated quantity of buckslips. |
| onhand\_quantity
required | number
Default: 0
The onhand quantity of buckslips. |
| pending\_quantity
required | number
Default: 0
The pending quantity of buckslips. |
| projected\_quantity
required | number
Default: 0
The sum of pending and onhand quantities of buckslips. |
| buckslip\_orders
required | Array of objects (buckslip\_order) \>= 0 items
An array of buckslip orders that are associated with the buckslip. |
| stock
required | string (The stock of the buckslip.)
Enum: "text" "cover" |
| weight
required | string (The weight of the buckslip.)
Value: "80#" |
| finish
required | string (The finish of the buckslip.)
Enum: "gloss" "matte" |
| status
required | string (The status of the buckslip.)
Enum: "processed" "rendered" "failed" |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| size | string
Default: "8.75x3.75"
Value: "8.75x3.75"
The size of the buckslip |
**default**
Error
patch/buckslips/{buckslip\_id}
production
https://api.lob.com/v1/buckslips/{buckslip\_id}
### Request samples
* Payload
* CURL
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Test buckslip", * "auto_reorder": true }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "bck_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": "Test buckslip", * "url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "8.75x3.755", * "auto_reorder": false, * "reorder_quantity": null, * "threshold_amount": 0, * "raw_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/buckslips/bck_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 0, * "allocated_quantity": 0, * "onhand_quantity": 0, * "pending_quantity": 0, * "projected_quantity": 0, * "buckslip_orders": [ ], * "stock": "text", * "weight": "80#", * "finish": "gloss", * "status": "rendered", * "mode": "test", * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "buckslip" }`
[](https://docs.lob.com/#tag/Buckslips/operation/buckslip_delete)
Delete
------------------------------------------------------------------------
Delete an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| buckslip\_id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
id of the buckslip |
### Responses
**200**
Deleted the buckslip
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bck_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/buckslips/{buckslip\_id}
production
https://api.lob.com/v1/buckslips/{buckslip\_id}
### Request samples
* CURL
Copy
curl -X DELETE https://api.lob.com/v1/buckslips/bck\_7a6d73c5c8457fc \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "buckslip_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/Buckslip-Orders)
Buckslip Orders
=============================================================
The Buckslip Orders endpoint allows you to easily create buckslip orders for existing buckslips. The API provides endpoints for creating buckslip orders and listing buckslip orders for a given buckslip.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Buckslip-Orders/operation/buckslip_orders_retrieve)
Retrieve
-----------------------------------------------------------------------------------------
Retrieves the buckslip orders associated with the given buckslip id.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| buckslip\_id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
The ID of the buckslip to which the buckslip orders belong. |
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| offset | integer
Default: 0
An integer that designates the offset at which to begin returning results. Defaults to 0. |
### Responses
**200**
Returns the buckslip orders associated with the given buckslip id
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (buckslip\_order)
List of buckslip orders |
**default**
Error
get/buckslips/{buckslip\_id}/orders
production
https://api.lob.com/v1/buckslips/{buckslip\_id}/orders
### Request samples
* CURL
Copy
curl https://api.lob.com/v1/buckslips/bck\_6afffd19045076c/orders/ \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "bo_e0f8a0562a06bea7f", * "buckslip_id": "bck_6afffd19045076c", * "status": "available", * "quantity_ordered": 5000, * "unit_price": 0.75, * "cancelled_reason": "No longer needed", * "availability_date": "2021-10-12T21:41:48.326Z", * "expected_availability_date": "2021-11-04T21:03:18.871Z", * "date_created": "2021-10-07T21:03:18.871Z", * "date_modified": "2021-10-16T01:00:30.144Z", * "object": "buckslip_order" } ], * "object": "list", * "next_url": null, * "previous_url": null, * "count": 1 }`
[](https://docs.lob.com/#tag/Buckslip-Orders/operation/buckslip_order_create)
Create
------------------------------------------------------------------------------------
Creates a new buckslip order given information
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| buckslip\_id
required | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
The ID of the buckslip to which the buckslip orders belong. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| quantity
required | integer \[ 5000 .. 10000000 \]
The quantity of buckslips in the order (minimum 5,000). |
### Responses
**200**
Buckslip order created successfully
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string (object)
Value is resource type. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| id | string (bo\_id) ^bo\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bo_`. |
| buckslip\_id | string (buckslip\_id) ^bck\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `bck_`. |
| status | string
Enum: "pending" "printing" "available" "cancelled" "depleted"
The status of the buckslip order. |
| quantity\_ordered | number
Default: 0
The quantity of buckslips ordered. |
| unit\_price | number
Default: 0
The unit price for the buckslip order. |
| inventory | number
Default: 0
The inventory of the buckslip order. |
| cancelled\_reason | string
The reason for cancellation. |
| availability\_date | string
A timestamp in ISO 8601 format of the date the resource was created. |
| expected\_availability\_date | string
The fixed deadline for the buckslips to be printed. |
**default**
Error
post/buckslips/{buckslip\_id}/orders
production
https://api.lob.com/v1/buckslips/{buckslip\_id}/orders
### Request samples
* Payload
* CURL
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "quantity": 10000 }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "bo_e0f8a0562a06bea7f", * "buckslip_id": "bck_6afffd19045076c", * "status": "available", * "quantity_ordered": 10000, * "unit_price": 0.75, * "cancelled_reason": "No longer needed", * "availability_date": "2021-10-12T21:41:48.326Z", * "expected_availability_date": "2021-11-04T21:03:18.871Z", * "date_created": "2021-10-07T21:03:18.871Z", * "date_modified": "2021-10-16T01:00:30.144Z", * "object": "buckslip_order" }`
[](https://docs.lob.com/#tag/Cards)
Cards
=========================================
The cards endpoint allows you to easily create cards that can later be affixed to Letters. The API provides endpoints for creating cards, retrieving individual cards, creating card orders, and retrieving a list of cards.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Cards/operation/cards_list)
List
-------------------------------------------------------------
Returns a list of your cards. The cards are returned sorted by creation date, with the most recently created addresses appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
### Responses
**200**
Returns a list of card objects
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (card)
list of cards |
**default**
Error
get/cards
production
https://api.lob.com/v1/cards
### Request samples
* CURL
* TYPESCRIPT
* NODE
* PYTHON
* PHP
* CSHARP
* RUBY
* GO
Copy
curl -X GET "https://api.lob.com/v1/cards?limit=2" \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "card_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": null, * "url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "2.125x3.375", * "auto_reorder": false, * "reorder_quantity": null, * "raw_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " } ], * "available_quantity": 10000, * "pending_quantity": 0, * "countries": null, * "status": "rendered", * "mode": "test", * "orientation": "horizontal", * "threshold_amount": 0, * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "card" } ], * "object": "list", * "previous_url": null, * "next_url": null, * "count": 1 }`
[](https://docs.lob.com/#tag/Cards/operation/card_create)
Create
----------------------------------------------------------------
Creates a new card given information
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| front
required | remote\_file\_url (string) or local\_file\_path (string)
A PDF template for the front of the card |
| description | string or null (card\_description) <= 255 characters
Description of the card. |
| size | string
Default: "2.125x3.375"
Enum: "3.375x2.125" "2.125x3.375"
The size of the card |
| back | remote\_file\_url (string) or local\_file\_path (string)
Default: "https://s3.us-west-2.amazonaws.com/public.lob.com/assets/card\_blank\_horizontal.pdf"
A PDF template for the back of the card |
### Responses
**200**
Card created successfully
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "card"
Value: "card"
Value is resource type. |
| description
required | string or null (card\_description) <= 255 characters
Description of the card. |
| id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `card_`. |
| url
required | string \[ 1 .. 2083 \] characters
The signed link for the card. |
| auto\_reorder
required | boolean
Default: false
True if the cards should be auto-reordered. |
| reorder\_quantity
required | integer or null
The number of cards to be reordered. |
| raw\_url
required | string \[ 1 .. 2083 \] characters
The raw URL of the card. |
| front\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the front template. |
| back\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the back template. |
| thumbnails
required | Array of objects (thumbnail) |
| available\_quantity
required | integer
Default: 0
The available quantity of cards. |
| pending\_quantity
required | integer
Default: 0
The pending quantity of cards. |
| status
required | string (The status of the card.)
Enum: "processed" "rendered" |
| orientation
required | string
Default: "horizontal"
Enum: "horizontal" "vertical"
The orientation of the card. |
| threshold\_amount
required | integer
Default: 0
The threshold amount of the card |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| size | string
Default: "2.125x3.375"
Enum: "3.375x2.125" "2.125x3.375"
The size of the card |
**default**
Error
post/cards
production
https://api.lob.com/v1/cards
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* PYTHON
* PHP
* CSHARP
* RUBY
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Test card", * "front": "[https://s3-us-west-2.amazonaws.com/public.lob.com/assets/card_horizontal.pdf](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/card_horizontal.pdf) ", * "back": "[https://s3-us-west-2.amazonaws.com/public.lob.com/assets/card_horizontal.pdf](https://s3-us-west-2.amazonaws.com/public.lob.com/assets/card_horizontal.pdf) ", * "size": "2.125x3.375" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "card_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": "Test card", * "url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "2.125x3.375", * "auto_reorder": false, * "reorder_quantity": null, * "raw_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 10000, * "pending_quantity": 0, * "countries": null, * "status": "rendered", * "mode": "test", * "orientation": "horizontal", * "threshold_amount": 0, * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "card" }`
[](https://docs.lob.com/#tag/Cards/operation/card_retrieve)
Retrieve
--------------------------------------------------------------------
Retrieves the details of an existing card. You need only supply the unique customer identifier that was returned upon card creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| card\_id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
id of the card |
### Responses
**200**
Returns a card object
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "card"
Value: "card"
Value is resource type. |
| description
required | string or null (card\_description) <= 255 characters
Description of the card. |
| id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `card_`. |
| url
required | string \[ 1 .. 2083 \] characters
The signed link for the card. |
| auto\_reorder
required | boolean
Default: false
True if the cards should be auto-reordered. |
| reorder\_quantity
required | integer or null
The number of cards to be reordered. |
| raw\_url
required | string \[ 1 .. 2083 \] characters
The raw URL of the card. |
| front\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the front template. |
| back\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the back template. |
| thumbnails
required | Array of objects (thumbnail) |
| available\_quantity
required | integer
Default: 0
The available quantity of cards. |
| pending\_quantity
required | integer
Default: 0
The pending quantity of cards. |
| status
required | string (The status of the card.)
Enum: "processed" "rendered" |
| orientation
required | string
Default: "horizontal"
Enum: "horizontal" "vertical"
The orientation of the card. |
| threshold\_amount
required | integer
Default: 0
The threshold amount of the card |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| size | string
Default: "2.125x3.375"
Enum: "3.375x2.125" "2.125x3.375"
The size of the card |
**default**
Error
get/cards/{card\_id}
production
https://api.lob.com/v1/cards/{card\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* PYTHON
* PHP
* CSHARP
* RUBY
* GO
Copy
curl https://api.lob.com/v1/cards/card\_7a6d73c5c8457fc \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "card_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": "Test card", * "url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "2.125x3.375", * "auto_reorder": false, * "reorder_quantity": null, * "raw_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 10000, * "pending_quantity": 0, * "countries": null, * "status": "rendered", * "mode": "test", * "orientation": "horizontal", * "threshold_amount": 0, * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "card" }`
[](https://docs.lob.com/#tag/Cards/operation/card_update)
Update
----------------------------------------------------------------
Update the details of an existing card. You need only supply the unique identifier that was returned upon card creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| card\_id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
id of the card |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| description | string or null (card\_description) <= 255 characters
Description of the card. |
| auto\_reorder | boolean
Allows for auto reordering |
| reorder\_quantity | number \[ 10000 .. 10000000 \]
The quantity of items to be reordered (only required when auto\_reorder is true). |
### Responses
**200**
Returns a card object
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string
Default: "card"
Value: "card"
Value is resource type. |
| description
required | string or null (card\_description) <= 255 characters
Description of the card. |
| id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `card_`. |
| url
required | string \[ 1 .. 2083 \] characters
The signed link for the card. |
| auto\_reorder
required | boolean
Default: false
True if the cards should be auto-reordered. |
| reorder\_quantity
required | integer or null
The number of cards to be reordered. |
| raw\_url
required | string \[ 1 .. 2083 \] characters
The raw URL of the card. |
| front\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the front template. |
| back\_original\_url
required | string \[ 1 .. 2083 \] characters
The original URL of the back template. |
| thumbnails
required | Array of objects (thumbnail) |
| available\_quantity
required | integer
Default: 0
The available quantity of cards. |
| pending\_quantity
required | integer
Default: 0
The pending quantity of cards. |
| status
required | string (The status of the card.)
Enum: "processed" "rendered" |
| orientation
required | string
Default: "horizontal"
Enum: "horizontal" "vertical"
The orientation of the card. |
| threshold\_amount
required | integer
Default: 0
The threshold amount of the card |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| size | string
Default: "2.125x3.375"
Enum: "3.375x2.125" "2.125x3.375"
The size of the card |
**default**
Error
post/cards/{card\_id}
production
https://api.lob.com/v1/cards/{card\_id}
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* CSHARP
* PYTHON
* RUBY
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "description": "Test card", * "auto_reorder": true }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "card_7a6d73c5c8457fc", * "account_id": "fa9ea650fc7b31a89f92", * "description": "Test card", * "url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e.pdf?version=v1&expires=1636910992&signature=mnsDH2DAxdkN9VibdlLMxJC86sME5WYDqkNtmvGwdNsAaUWfbnv0rJhJ1mR8Ol4uxQq61j5wYZ0r3s-lBkQfDA) ", * "size": "2.125x3.375", * "auto_reorder": false, * "reorder_quantity": null, * "raw_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "front_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "back_original_url": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_raw.pdf?version=v1&expires=1636910992&signature=-bZo31FMAp2vmNaZKyXn_Qa4APqwtNinw76FrQ7uyQejFZw6VBQQYfoiQ642iXh0H2K5i2aOo8_BAkt3UJdVDw) ", * "thumbnails": [ * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_1.png?version=v1&expires=1636910992&signature=mrv8JDvpZK4I8WUGH0tPdtK-My5oes0Ltj_gL7BDw96SpCTTeZFHkz81SzclyFP9dQRtlsvAsjcuGcTBvCvOCg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_1.png?version=v1&expires=1636910992&signature=VgL_2Ckm_kxKiWGgWtdNoy9HHOn8dGYSVOn7UqyCbwdbVlUtx28TRN4Bo8Iru3n0keKp9He0YhKT1ILotznMDA) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_1.png?version=v1&expires=1636910992&signature=FKSzymA13j-CQ0uk20cGHZTzT3vimzNBYrgp-xifLFg4mMdo1BZALR5O0aF_jVhsX614hKP35ONdYl47TQxXAw) " }, * { * "small": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_small_2.png?version=v1&expires=1636910992&signature=IWsmPa_ULlv2yyqjX564d_YfHHY_M7i9YxDnw-WXDr2jtOFcArmRZQbnHeE9g_rYxnddJbgosuv8-c2utiu7Cg) ", * "medium": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_medium_2.png?version=v1&expires=1636910992&signature=zxK7VKGiTvz5Ywrkaydd0v3GcYf58R7A08J4tNfI7-aiNODDcTF3l0MqY13n9Pyc8RXSdD0XVBY-OpbA1VM-Ag) ", * "large": "[https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw](https://lob-assets.com/cards/card_c51ae96f5cebf3e_thumb_large_2.png?version=v1&expires=1636910992&signature=r0OFUhh315ZwN0raMZdIwJd2oCIEYsz0BABaMxIuO1PKTD0ckGWrhcGdzk2dlWQ6vSvp0CUQ5k1RXGqkIIqkDw) " } ], * "available_quantity": 10000, * "pending_quantity": 0, * "countries": null, * "status": "rendered", * "mode": "test", * "orientation": "horizontal", * "threshold_amount": 0, * "date_created": "2021-03-24T22:51:42.838Z", * "date_modified": "2021-03-24T22:51:42.838Z", * "send_date": "2021-03-24T22:51:42.838Z", * "object": "card" }`
[](https://docs.lob.com/#tag/Cards/operation/card_delete)
Delete
----------------------------------------------------------------
Delete an existing card. You need only supply the unique identifier that was returned upon card creation.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| card\_id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
id of the card |
### Responses
**200**
Deleted the card
##### Response Schema: application/json
| | |
| --- | --- |
| id | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `card_`. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
**default**
Error
delete/cards/{card\_id}
production
https://api.lob.com/v1/cards/{card\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* PYTHON
* PHP
* CSHARP
* RUBY
* GO
Copy
curl -X DELETE https://api.lob.com/v1/cards/card\_7a6d73c5c8457fc \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "card_123456789", * "deleted": true }`
[](https://docs.lob.com/#tag/Card-Orders)
Card Orders
=====================================================
The card orders endpoint allows you to easily create card orders for existing cards. The API provides endpoints for creating card orders and listing card orders for a given card.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Card-Orders/operation/card_orders_retrieve)
Retrieve
---------------------------------------------------------------------------------
Retrieves the card orders associated with the given card id.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| card\_id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
The ID of the card to which the card orders belong. |
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| offset | integer
Default: 0
An integer that designates the offset at which to begin returning results. Defaults to 0. |
### Responses
**200**
Returns the card orders associated with the given card id
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (card\_order)
List of card orders |
**default**
Error
get/cards/{card\_id}/orders
production
https://api.lob.com/v1/cards/{card\_id}/orders
### Request samples
* CURL
* TYPESCRIPT
* NODE
* PYTHON
* PHP
* CSHARP
* RUBY
* GO
Copy
curl https://api.lob.com/v1/cards/card\_6afffd19045076c/orders/ \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "id": "co_e0f8a0562a06bea7f", * "card_id": "card_6afffd19045076c", * "status": "available", * "inventory": 9500, * "quantity_ordered": 10000, * "unit_price": 0.75, * "cancelled_reason": "No longer needed", * "availability_date": "2021-10-12T21:41:48.326Z", * "expected_availability_date": "2021-11-04T21:03:18.871Z", * "date_created": "2021-10-07T21:03:18.871Z", * "date_modified": "2021-10-16T01:00:30.144Z", * "object": "card_order" } ], * "object": "list", * "next_url": null, * "previous_url": null, * "count": 1 }`
[](https://docs.lob.com/#tag/Card-Orders/operation/card_order_create)
Create
----------------------------------------------------------------------------
Creates a new card order given information
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| card\_id
required | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
The ID of the card to which the card orders belong. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| quantity
required | integer \[ 10000 .. 10000000 \]
The quantity of cards in the order (minimum 10,000). |
### Responses
**200**
Card order created successfully
##### Response Schema: application/json
| | |
| --- | --- |
| date\_created
required | string (date\_created)
A timestamp in ISO 8601 format of the date the resource was created. |
| date\_modified
required | string (date\_modified)
A timestamp in ISO 8601 format of the date the resource was last modified. |
| object
required | string (object)
Value is resource type. |
| deleted | boolean (deleted)
Only returned if the resource has been successfully deleted. |
| id | string (co\_id) ^co\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `co_`. |
| card\_id | string (card\_id) ^card\_\[a-zA-Z0-9\]+$
Unique identifier prefixed with `card_`. |
| status | string
Enum: "pending" "printing" "available" "cancelled" "depleted"
The status of the card order. |
| inventory | number
Default: 0
The inventory of the card order. |
| quantity\_ordered | number
Default: 0
The quantity of cards ordered |
| unit\_price | number
Default: 0
The unit price for the card order. |
| cancelled\_reason | string
The reason for cancellation. |
| availability\_date | string
A timestamp in ISO 8601 format of the date the resource was created. |
| expected\_availability\_date | string
The fixed deadline for the cards to be printed. |
**default**
Error
post/cards/{card\_id}/orders
production
https://api.lob.com/v1/cards/{card\_id}/orders
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* PYTHON
* PHP
* CSHARP
* RUBY
* GO
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Copy
`{ * "quantity": 10000 }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "co_e0f8a0562a06bea7f", * "card_id": "card_6afffd19045076c", * "status": "available", * "inventory": 9500, * "quantity_ordered": 10000, * "unit_price": 0.75, * "cancelled_reason": "No longer needed", * "availability_date": "2021-10-12T21:41:48.326Z", * "expected_availability_date": "2021-11-04T21:03:18.871Z", * "date_created": "2021-10-07T21:03:18.871Z", * "date_modified": "2021-10-16T01:00:30.144Z", * "object": "card_order" }`
[](https://docs.lob.com/#tag/QR-Codes)
QR Codes
===============================================
Lob QR codes allow you to generate a QR code that is unique to each mailpiece, thereby allowing each and every customers to receive a personalized link. See the Create endpoint for [Letters](https://docs.lob.com/#tag/Letters/operation/letter_create)
, [Postcards](https://docs.lob.com/#tag/Postcards/operation/postcard_create)
or [Self Mailers](https://docs.lob.com/#tag/Self-Mailers/operation/self_mailer_create)
to learn how to embed a QR code into your mail piece.
Webhooks can be used to integrate Lob QR code scans into your omni channel marketing strategy. See the [Webhooks](https://docs.lob.com/#tag/Webhooks)
section of our documentation to learn how to enable the `letter.viewed`, `postcard.viewed` and `self_mailer.viewed` event notifications for your mail pieces.
Furthermore, our QR code Analytics endpoint can be used to track the impact and engagement rate of your mail sends. Lob can tell you exactly which recipients opened your mailpiece. Our Analytics endpoint allows you to see exactly which recipient scanned a mailpiece, when they scanned it, and more!
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/QR-Codes/operation/qr_codes_list)
List
-------------------------------------------------------------------
Returns a list of your QR codes. The QR codes are returned sorted by scan date, with the most recently scanned QR codes appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| offset | integer
Default: 0
An integer that designates the offset at which to begin returning results. Defaults to 0. |
| include | Array of strings
Request that the response include the total count by specifying `include=["total_count"]`. |
| date\_created | object (date\_filter)
Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. `{ "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" }` where `gt` is >, `lt` is <, `gte` is ≥, and `lte` is ≤. |
| scanned | boolean
Filter list of responses to only include QR codes with at least one scan event. |
| resource\_ids | Array of arrays <= 100 items
Default: \[\]
Filter by the resource ID. |
### Responses
**200**
Returns a list of QR Codes and their analytics.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| scanned\_count | integer
Indicates the number of QR Codes out of `count` that were scanned atleast once. |
| data | Array of objects (qr\_code\_scans)
List of QR code analytics |
get/qr\_code\_analytics
production
https://api.lob.com/v1/qr\_code\_analytics
### Request samples
* Shell
Copy
curl -X GET "https://api.lob.com/v1/qr\_code\_analytics?limit=2&scanned=true" \\
-u :
### Response samples
* 200
Content type
application/json
Copy
Expand all Collapse all
`{ * "data": [ * { * "resource_id": "ltr_d5a5a89da9106f8", * "date_created": "2019-07-27T23:49:01.511Z", * "number_of_scans": 2, * "scans": [ * { * "ip_location": "127.0.0.1", * "scan_date": "2022-07-27T23:49:01.511Z" }, * { * "ip_location": "127.0.0.1", * "scan_date": "2022-07-29T23:45:00.436Z" } ] }, * { * "resource_id": "psc_d5a5a89da9106f8", * "date_created": "2022-09-27T23:49:01.511Z", * "number_of_scans": 1, * "scans": [ * { * "ip_location": "127.0.0.1", * "scan_date": "2022-09-27T23:49:01.511Z" } ] } ], * "object": "list", * "count": 2, * "scanned_count": 2, * "total_count": 2 }`
[](https://docs.lob.com/#tag/URL-Shortener)
URL Shortener
=========================================================
Lob's URL shortener allows you to generate unique short links, either with Lob's own domain or your own custom domains. Each custom link enables Lob to track mail individually and provide customers the relevant tracking data in their dashboard.
Webhooks can be used to integrate Lob's URL Shortener scans into your omni channel marketing stratergy. See the [Webhooks](https://docs.lob.com/#tag/Webhooks)
section of our documentation to learn how to enable the `letter.viewed`, `postcard.viewed` and `self_mailer.viewed` event notifications for your mail pieces.
Furthermore, you can use our Retrieve endpoints to track the impact and engagement rate of links created.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/URL-Shortener/operation/domain_get)
Retrieve a domain
----------------------------------------------------------------------------------
Retrieve details for a single domain.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| domain\_id
required | string
Unique identifier for a domain. |
### Responses
**200**
Returns domain related details.
##### Response Schema: application/json
| | |
| --- | --- |
| id | string
Unique identifier for a domain. |
| domain | string
The registered domain/hostname. |
| error\_redirect\_link | string
URL to redirect customers if a short link is broken or inactive. |
| status | string
Enum: "configured" "not\_configured"
The configuration status of the domain. |
| created\_at | string
The date and time the domain was created. |
| updated\_at | string
The date and time the domain was last updated. |
**default**
Error
get/domains/{domain\_id}
production
https://api.lob.com/v1/domains/{domain\_id}
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/domains/{domain\_id}" \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "string", * "domain": "string", * "error_redirect_link": "string", * "status": "configured", * "created_at": "string", * "updated_at": "string" }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/domain_delete)
Delete a Domain
-----------------------------------------------------------------------------------
Delete a registered domain. This operation can only be performed if all associated links with the domain are deleted.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| domain\_id
required | string
Unique identifier for a domain. |
### Responses
**200**
Returns the deleted link object.
##### Response Schema: application/json
| | |
| --- | --- |
| id | string
Unique identifier for a domain. |
| deleted | boolean
Only returned if the domain was successfully deleted. |
**default**
Error
delete/domains/{domain\_id}
production
https://api.lob.com/v1/domains/{domain\_id}
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "string", * "deleted": true }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/domain_create)
Create Domain
---------------------------------------------------------------------------------
Add a new custom domain that can be used to create custom links.
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| domain
required | string (domain)
The registered domain/hostname. |
| error\_redirect\_link | string (error\_redirect\_link)
URL to redirect customers if a short link is broken or inactive. |
### Responses
**200**
Returns a domain object with details.
##### Response Schema: application/json
| | |
| --- | --- |
| id | string
Unique identifier for a domain. |
| domain | string
The registered domain/hostname. |
| error\_redirect\_link | string
URL to redirect customers if a short link is broken or inactive. |
| status | string
Enum: "configured" "not\_configured"
The configuration status of the domain. |
| created\_at | string
The date and time the domain was created. |
| updated\_at | string
The date and time the domain was last updated. |
**default**
Error
post/domains
production
https://api.lob.com/v1/domains
### Request samples
* Payload
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Example
basictestbasic
Copy
`{ * "domain": "lob.st" }`
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "string", * "domain": "string", * "error_redirect_link": "string", * "status": "configured", * "created_at": "string", * "updated_at": "string" }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/domain_list)
List all domains
----------------------------------------------------------------------------------
Retrieve a list of all created domains.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| status | string
Enum: "configured" "not\_configured"
Filter domains by their configuration status. |
### Responses
**200**
Returns a list of all domains.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (domain\_response)
List of domains. |
**default**
Error
get/domains
production
https://api.lob.com/v1/domains
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/domains?limit=2" \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "object": "string", * "next_url": "string", * "previous_url": "string", * "count": 0, * "total_count": 0, * "data": [ * { * "id": "string", * "domain": "string", * "error_redirect_link": "string", * "status": "configured", * "created_at": "string", * "updated_at": "string" } ] }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/links_get)
Retrieve a link
-------------------------------------------------------------------------------
Retrieves a single shortened link.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| link\_id
required | string
Unique identifier for a link. |
### Responses
**200**
Returns a single link.
##### Response Schema: application/json
| | |
| --- | --- |
| id | string
Unique identifier prefixed with `lnk_`. |
| title | string
The title of the URL. |
| domain\_id | string
A unique identifier for the registered domain. |
| redirect\_link | string (redirect\_link)
The original target URL. |
| short\_link | string
The shortened URL for the associated original URL. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| created\_at | string
The date and time the link was created. |
| updated\_at | string
The date and time the link was last updated. |
**default**
Error
get/links/{link\_id}
production
https://api.lob.com/v1/links/{link\_id}
### Request samples
* CURL
Copy
curl -X GET "https://api.lob.com/v1/links/" \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "string", * "title": "string", * "domain_id": "string", * "redirect_link": "string", * "short_link": "string", * "metadata": { * "property1": "string", * "property2": "string" }, * "created_at": "string", * "updated_at": "string" }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/link_update)
Update a Link
-------------------------------------------------------------------------------
Update any of the properties of a shortened link.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| link\_id
required | string
Unique identifier for a link. |
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| redirect\_link
required | string (redirect\_link)
The original target URL. |
| title | string
The title of the URL. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
### Responses
**200**
Returns the updated link.
##### Response Schema: application/json
| | |
| --- | --- |
| id | string
Unique identifier prefixed with `lnk_`. |
| title | string
The title of the URL. |
| domain\_id | string
A unique identifier for the registered domain. |
| redirect\_link | string (redirect\_link)
The original target URL. |
| short\_link | string
The shortened URL for the associated original URL. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| created\_at | string
The date and time the link was created. |
| updated\_at | string
The date and time the link was last updated. |
**default**
Error
patch/links/{link\_id}
production
https://api.lob.com/v1/links/{link\_id}
### Request samples
* Payload
* CURL
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Example
basictestbasic
Copy
`{ * "resource_id": "ltr_133" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "string", * "title": "string", * "domain_id": "string", * "redirect_link": "string", * "short_link": "string", * "metadata": { * "property1": "string", * "property2": "string" }, * "created_at": "string", * "updated_at": "string" }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/links_delete)
Delete Link
------------------------------------------------------------------------------
Delete the shortened link.
##### Authorizations:
_basicAuth_
##### path Parameters
| | |
| --- | --- |
| link\_id
required | string
Unique identifier for a link. |
### Responses
**200**
Returns the deleted short link object
##### Response Schema: application/json
| | |
| --- | --- |
| id | string
Unique identifier for a link. |
| deleted | boolean
Only returned if the link was successfully deleted. |
**default**
Error
delete/links/{link\_id}
production
https://api.lob.com/v1/links/{link\_id}
### Response samples
* 200
* default
Content type
application/json
Copy
`{ * "id": "string", * "deleted": true }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/link_create)
Create Link
-----------------------------------------------------------------------------
Given a long URL, shorten your URL either by using a custom domain or Lob's own short domain.
##### Authorizations:
_basicAuth_
##### Request Body schema:
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
| | |
| --- | --- |
| redirect\_link
required | string (redirect\_link)
The original target URL. |
| title | string
The title of the URL. |
| domain | string
Default: "lob.st"
The registered domain to be used for the short URL. |
| slug | string
The unique path for the shortened URL, if empty a unique path will be used. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
### Responses
**200**
Returns a successfully created link.
##### Response Schema: application/json
| | |
| --- | --- |
| id | string
Unique identifier prefixed with `lnk_`. |
| title | string
The title of the URL. |
| domain\_id | string
A unique identifier for the registered domain. |
| redirect\_link | string (redirect\_link)
The original target URL. |
| short\_link | string
The shortened URL for the associated original URL. |
| metadata | object (metadata) <= 500 characters \[^"\\\\\]{0,500}
Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. i.e. '{"customer\_id" : "NEWYORK2015"}' Nested objects are not supported. See [Metadata](https://docs.lob.com/#section/Metadata)
for more information. |
| created\_at | string
The date and time the link was created. |
| updated\_at | string
The date and time the link was last updated. |
**default**
Error
post/links
production
https://api.lob.com/v1/links
### Request samples
* Payload
* CURL
Content type
application/jsonapplication/x-www-form-urlencodedmultipart/form-dataapplication/json
Example
basictestbasic
Copy
`{ * "redirect_link": "[https://www.lob.com](https://www.lob.com/) ", * "slug": "a1b2c3" }`
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "id": "string", * "title": "string", * "domain_id": "string", * "redirect_link": "string", * "short_link": "string", * "metadata": { * "property1": "string", * "property2": "string" }, * "created_at": "string", * "updated_at": "string" }`
[](https://docs.lob.com/#tag/URL-Shortener/operation/links_list)
List all links
-------------------------------------------------------------------------------
Retrieves a list of shortened links. The list is sorted by creation date, with the most recently created appearing first.
##### Authorizations:
_basicAuth_
##### query Parameters
| | |
| --- | --- |
| limit | integer \[ 1 .. 100 \]
Default: 10
Example: limit=10
How many results to return. |
| before/after | object or object
`before` and `after` are both optional but only one of them can be in the query at a time. |
| campaign\_id | string or null (campaign\_id) ^(cmp\|camp)\_\[a-zA-Z0-9\]+$
Filters resources created by the provided campaign id, prefixed with `cmp_`. In the case of snap packs, booklets, and letters with size `us_legal`, however, the campaign id is prefixed with `camp_` instead of `cmp_`. |
| domain\_id | string^(dom)\_\[a-zA-Z0-9\]+$
Filters links by the provided domain id. |
### Responses
**200**
Returns the deleted link object.
##### Response Schema: application/json
| | |
| --- | --- |
| object | string (object)
Value is resource type. |
| next\_url | string or null
Url of next page of items in list. |
| previous\_url | string or null
Url of previous page of items in list. |
| count | integer (count)
number of resources in a set |
| total\_count | integer
Indicates the total number of records. Provided when the request specifies an "include" query parameter |
| data | Array of objects (link\_response)
List of links |
**default**
Error
get/links
production
https://api.lob.com/v1/links
### Request samples
* CURL
* TYPESCRIPT
* NODE
* RUBY
* PYTHON
* PHP
* JAVA
* ELIXIR
* CSHARP
* GO
Copy
curl -X GET "https://api.lob.com/v1/links?limit=2" \\
-u :
### Response samples
* 200
* default
Content type
application/json
Copy
Expand all Collapse all
`{ * "object": "string", * "next_url": "string", * "previous_url": "string", * "count": 0, * "total_count": 0, * "data": [ * { * "id": "string", * "title": "string", * "domain_id": "string", * "redirect_link": "string", * "short_link": "string", * "metadata": { * "property1": "string", * "property2": "string" }, * "created_at": "string", * "updated_at": "string" } ] }`
[](https://docs.lob.com/#tag/Beta-Program)
Beta Program
=======================================================
At Lob, we pride ourselves on building high quality platform capabilities rapidly and iteratively, so we can constantly be delivering additional value to our customers. When evaluating a new product or feature from Lob, you may see that it has been released in Beta.
Typically, something in Beta means that the feature is early in its lifecycle here at Lob. While we fully stand behind the quality of everything we release in Beta, we do anticipate receiving a higher level of customer feedback on Beta features, as well as a faster pace of changes from our engineering team in response to that feedback.
By participating in a Lob Beta program, you will have the opportunity to get early access to a new product capability, as well as having a unique opportunity to influence the product's direction with your feedback.
You should also anticipate that features in Beta may have functional or design limitations, and might change rapidly as we receive customer feedback and make improvements. In particular, new APIs in Beta may also go through more frequent versioning and version deprecation cycles than our more mature APIs.
If you are participating in a Beta program and want to provide feedback, please feel free to [contact us](https://lob.com/support#contact)
!
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Errors)
Errors
===========================================
Lob uses RESTful HTTP response codes to indicate success or failure of an API request - read below for more information. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end.
| ATTRIBUTE | DESCRIPTION |
| --- | --- |
| `code` | A consistent machine-keyable string identifying the error |
| `status_code` | A conventional HTTP status code |
| `message` | A human-readable, subject-to-change message with more details about the error |
### HTTP Status Code Summary
| STATUS\_CODE | CODE | MESSAGE |
| --- | --- | --- |
| `200` | SUCCESS | Successful API request |
| `401` | UNAUTHORIZED | Authorization error with your API key or account |
| `403` | FORBIDDEN | Forbidden error with your API key or account |
| `404` | NOT FOUND | The requested item does not exist |
| `422` | BAD REQUEST | The query or body parameters did not pass validation |
| `429` | TOO MANY REQUESTS | Too many requests have been sent with an API key in a given amount of time |
| `500` | SERVER ERROR | An internal server error occurred, please contact support@lob.com |
### Error Codes - Generic
| STATUS\_CODE | CODE | MESSAGE |
| --- | --- | --- |
| `422` | BAD\_REQUEST | An invalid request was made. See error message for details. |
| `409/422` | CONFLICT | This operation would leave data in a conflicted state. |
| `403` | FEATURE\_LIMIT\_REACHED | The account has reached its resource limit and requires upgrading to add more. |
| `500` | INTERNAL\_SERVER\_ERROR | An error has occured on Lob's servers. Please try request again. |
| `422` | INVALID | An invalid request was made. See error message for details. |
| `422` | NOT\_DELETABLE | An attempt was made to delete a resource, but the resource cannot be deleted. |
| `404` | NOT\_FOUND | The requested resource was not found. |
| `408` | REQUEST\_TIMEOUT | The request took too long. Please try again. |
| `503` | SERVICE\_UNAVAILABLE | The Lob servers are temporarily unavailable. Please try again. |
| `404` | UNRECOGNIZED\_ENDPOINT | The requested endpoint doesn't exist. |
| `422` | UNSUPPORTED\_LOB\_VERSION | An unsupported Lob API version was requested. |
### Error Codes - Authentication
| STATUS\_CODE | CODE | MESSAGE |
| --- | --- | --- |
| `401` | EMAIL\_REQUIRED | Account must have a verified email address before creating live resources. |
| `401` | UNAUTHORIZED | The request isn't authorized. |
| `401` | UNAUTHORIZED\_TOKEN | Token isn't authorized. |
| `401/403` | INVALID\_API\_KEY | The API key is invalid. |
| `403` | PUBLISHABLE\_KEY\_NOT\_ALLOWED | The requested operation needs a secret key, not a publishable key. See \[API Keys\](#tag/API-Keys) for more information. |
| `429` | RATE\_LIMIT\_EXCEEDED | Requests were sent too quickly and must be slowed down. |
### Error Codes - Advanced
| STATUS\_CODE | CODE | MESSAGE |
| --- | --- | --- |
| `401` | PAYMENT\_METHOD\_UNVERIFIED | You must have a verified bank account or credit card to submit live requests. |
| `404` | DELETED\_BANK\_ACCOUNT | Checks cannot be created with a deleted bank account. |
| `422` | ADDRESS\_LENGTH\_EXCEEDS\_LIMIT | The sum of to.address\_line1 and to.address\_line2 cannot surpass 50 characters. |
| `422` | BANK\_ACCOUNT\_ALREADY\_VERIFIED | The bank account has already been verified. |
| `422` | BANK\_ERROR | There's an issue with the bank account. |
| `403` | BILLING\_ADDRESS\_REQUIRED | In order to create a live mail piece, your account needs to set up a billing address. |
| `422` | CUSTOM\_ENVELOPE\_INVENTORY\_DEPLETED | Custom envelope inventory is depleted, and more will need to be ordered. |
| `422` | FAILED\_DELIVERABILITY\_STRICTNESS | The to address doesn't meet strictness requirements. See [Account Settings](https://dashboard.lob.com/#/settings/account)
to configure strictness. |
| `422` | FILE\_PAGES\_BELOW\_MIN | Not enough pages. |
| `422` | FILE\_PAGES\_EXCEED\_MAX | Too many pages. |
| `422` | FILE\_SIZE\_EXCEEDS\_LIMIT | The file size is too large. See description for details. |
| `422` | FOREIGN\_RETURN\_ADDRESS | The 'from' address must be a US address. |
| `422` | INCONSISTENT\_PAGE\_DIMENSIONS | All pages of the input file must have the same dimensions. |
| `422` | INVALID\_BANK\_ACCOUNT | The provided bank routing number is invalid. |
| `422` | INVALID\_BANK\_ACCOUNT\_VERIFICATION | Verification amounts do not match. |
| `422` | INVALID\_CHECK\_INTERNATIONAL | Checks cannot be sent internationally. |
| `422` | INVALID\_COUNTRY\_COVID | The postal service in the specified country is currently unable to process the request due to COVID-19 restrictions. |
| `422` | INVALID\_FILE | The file is invalid. |
| `422` | INVALID\_FILE\_DIMENSIONS | File dimensions are incorrect for the selected mail type. |
| `422` | INVALID\_FILE\_DOWNLOAD\_TIME | File download from remote server took too long. |
| `422` | INVALID\_FILE\_URL | The file URL when creating a resource is invalid. |
| `422` | INVALID\_IMAGE\_DPI | DPI must be at least 300. |
| `422` | INVALID\_INTERNATIONAL\_FEATURE | The specified product cannot be sent to the destination. |
| `422` | INVALID\_PERFORATION\_RETURN\_ENVELOPE | Both \`return\_envelope\` and \`perforation\` must be used together. |
| `422` | INVALID\_TEMPLATE\_HTML | The provided HTML is invalid. |
| `422` | MAIL\_USE\_TYPE\_CAN\_NOT\_BE\_NULL | \`use\_type\` must be one of "marketing" or "operational". Alternatively, an admin can set the account default use type in Account Settings. |
| `422` | MERGE\_VARIABLE\_REQUIRED | A required merge variable is missing. |
| `422` | MERGE\_VARIABLE\_WHITESPACE | Merge variable names cannot contain whitespace. |
| `422` | PDF\_ENCRYPTED | An encrypted PDF was provided. |
| `422` | SPECIAL\_CHARACTERS\_RESTRICTED | Cannot use special characters for merge variable names. |
| `422` | UNEMBEDDED\_FONTS | The provided PDF contains non-standard unembedded fonts. See description for details. |
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Rate-Limiting)
Rate Limiting
=========================================================
To prevent misuse, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits. By default, all accounts and their corresponding Test and Live API Keys have a rate limit of 150 requests per 5 seconds per endpoint. The `POST /v1/us_verifications` and `POST /v1/us_autocompletions` endpoints have a limit of 300 requests per 5 seconds for all accounts.
When your application exceeds the rate limit for a given API endpoint, the Lob API will return an HTTP 429 "Too Many Requests" response code instead of the variety of codes you would find across the other API endpoints.
**HTTP Headers**
HTTP headers are returned on each request to a rate limited endpoint. Ensure that you inspect these headers during your requests as they provide relevant data on how many more requests your application is allowed to make for the endpoint you just utilized.
While the headers are documented here in titlecase, HTTP headers are case insensitive and certain libraries may transform them to lowercase. Please inspect your headers carefully to see how they will be represented in your chosen development scenario.
| | |
| --- | --- |
| X-Rate-Limit-Limit: | the rate limit ceiling for a given request |
| X-Rate-Limit-Remaining: | the number of requests remaining in this window |
| X-Rate-Limit-Reset: | the time at which the rate limit window resets (in [UTC epoch seconds](https://en.wikipedia.org/wiki/Unix_time)
) |
### Example HTTP Headers
X-Rate-Limit-Limit:150
X-Rate-Limit-Remaining:100
X-Rate-Limit-Reset:1528749846
### Example Response
If you hit the rate limit on a given endpoint, this is the body of the HTTP 429 message that you will see:
`javascript { "error": { "message": "Rate limit exceeded. Please wait 5 seconds and try your request again.", "code": "rate_limit_exceeded", "status_code": 429 } }`
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Requests-and-Responses)
Requests and Responses
===========================================================================
[](https://docs.lob.com/#tag/Requests-and-Responses/Asset-URLs)
Asset URLs
--------------------------------------------------------------------------
All asset URLs returned by the Lob API (postcards, letters, thumbnails, etc) are signed links served over HTTPS. All links returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Requests-and-Responses/Query-Parameters)
Query Parameters
--------------------------------------------------------------------------------------
Query parameters which consist of lists of strings require that all elements of the list be double-quoted, as per query filter standards.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Requests-and-Responses/Idempotent-Requests)
Idempotent Requests
--------------------------------------------------------------------------------------------
Lob supports idempotency for safely retrying `POST` requests to create postcards, self mailers, letters, and checks without accidentally creating duplicates.
For example, if a request to create a check fails due to a network error, you can safely retry the same request with the same idempotency key and guarantee that only one check will ultimately be created and sent. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.
To perform an idempotent `POST` request to one of the mailpiece product endpoints, provide an additional `Idempotency-Key` header or an `idempotency_key` query parameter to the request. If multiple idempotency keys are provided, the request will fail. How you create unique keys is up to you, but we suggest using random values, such as V4 UUIDs. Idempotency keys are intended to prevent issues over a short periods of time, therefore keys expire after 24 hours. Keys are unique by mode (Test vs. Live) as well as by resource (postcard vs. letter, etc.).
By default, all `GET` and `DELETE` requests are idempotent by nature, so they do not require an additional idempotency key.
For more help integrating idempotency keys, refer to our [implementation guide](https://help.lob.com/print-and-mail/building-a-mail-strategy/managing-mail-settings#idempotent-requests-12)
.
**Headers**
| | |
| --- | --- |
| Idempotency-Key: | optional
A string of no longer than 256 characters that uniquely identifies this resource. |
**Query Parameters**
| | |
| --- | --- |
| idempotency-key: | optional
A string of no longer than 256 characters that uniquely identifies this resource. |
### Example Request
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-H "Idempotency-Key: 026e7634-24d7-486c-a0bb-4a17fd0eebc5" \
-d "to=adr_bae820679f3f536b" \
-d "from=adr_210a8d4b0b76d77b" \
--data-urlencode "front=Front HTML for {{name}}" \
--data-urlencode "back=Back HTML" \
-d "merge_variables[name]=Harry"
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Requests-and-Responses/Metadata)
Metadata
----------------------------------------------------------------------
When creating any Lob object, you can include a metadata object with up to 20 key-value pairs of custom data. You can use metadata to store information like `metadata[customer_id] = "987654"` or `metadata[campaign] = "NEWYORK2015"`. This is especially useful for filtering and matching to internal systems.
Each metadata key must be less than 40 characters long and values must be less than 500 characters. Metadata does not support nested objects.
### Example Create Request with Metadata
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-d "description=Demo Postcard job" \
-d "metadata[campaign]=NEWYORK2015" \
-d "to=adr_bae820679f3f536b" \
-d "from=adr_210a8d4b0b76d77b" \
--data-urlencode "front=Front HTML for {{name}}" \
--data-urlencode "back=Back HTML" \
-d "merge_variables[name]=Harry"
### Example List Request with Metadata Filter
curl -g "https://api.lob.com/v1/postcards?metadata[campaign]=NEWYORK2015&limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Requests-and-Responses/Request-Body)
Request Body
------------------------------------------------------------------------------
When manually sending a POST HTTP request directly to the Lob API, without the use of a library, you may represent the body as either a Form URL Encoded request, a JSON document, or a Multipart Form Data request.
However, if you're using one of our [SDKs](https://docs.lob.com/#tag/SDKs-and-Tools)
, the generation of the request bodies is done for you automatically and you don't need to worry about the format.
For fields that are intended to accept only string values, submitting JSON objects in string format (stringified JSON objects) is not supported. Our system automatically parses and validates incoming data according to their expected types. As a result, providing a stringified JSON object in a field designated for string input can cause parsing errors or lead to unexpected validation results.
### Form URL Encoded
This request body encoding is accompanied with the `Content-Type: application/x-www-form-urlencoded` header. The content is an example of what the [Verify a US address](https://docs.lob.com/#operation/us_verification)
endpoint accepts. An example of a request body encoded in this format follows.
primary_line=210 King Street&city=San Francisco&state=CA&zip_code=94107
### JSON
This request body encoding is accompanied with the `Content-Type: application/json` header. The content is an example of what the [Verify a US address endpoint](https://docs.lob.com/#operation/us_verification)
accepts. An example of a request body encoded in this format follows.
{
"primary_line": "210 King Street",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107"
}
### Multipart Form Data
This request body encoding is accompanied with the `Content-Type: multipart/form-data` header. This is the only format that can be used for uploading a file to the API. The content is an example of what the [Create a check](https://docs.lob.com/#operation/check_create)
endpoint accepts. An example of a request body encoded in this format follows.
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="description"
Demo Letter
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="to"
adr_bae820679f3f536b
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="from"
adr_210a8d4b0b76d77b
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="file"; filename="file.pdf"
Content-Type: application/pdf
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="color"
true
--------------------------7015ebe79c0a5f8c--
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Test-and-Live-Environments)
Test and Live Environments
===================================================================================
To make the API as explorable as possible, accounts have test and live environment API keys. You're not charged any fees in the test environment, so we encourage you to use it to try out services, perform quality assurance, and run automated testing. Objects―addresses, letters, checks, etc―in one environment cannot be manipulated by objects in the other.
In general, a payment method (either credit card or ACH account) must be added to your account to make live API requests. However, a payment method is not required for the first 300 live requests per month to the `/v1/us_verifications` endpoint. After the first 300 requests, you will begin receiving errors with status code `403`.
Requests made in the test environment always validate request arguments, simulate live environment behavior, and enforce rate limits. _They never print, mail nor, for verification services, verify addresses._ The US & International verification services trigger behavior with specific argument values, and, if you plan on using those, we recommend reading [US Verification Test Environment](https://docs.lob.com/#tag/US-Verifications-Test-Environment)
and [Intl Verification Test Environment](https://docs.lob.com/#tag/Intl-Verifications-Test-Environment)
.
To switch between environments, use the appropriate key for that environment when performing a request. You can find each environment's API key in your dashboard under Settings; test API keys are always prefixed with `test_` and production API keys with `live_`.
[back to top](https://docs.lob.com/#)
[](https://docs.lob.com/#tag/Versioning-and-Changelog)
Versioning and Changelog
===============================================================================
### API Versioning
When backwards-incompatible changes are made to the API, a new dated version is released. The latest available version of the API is version **2020-02-11**. All versions prior to, and inclusive of, 2019-02-11 have been sunsetted. You can view your version and upgrade to the latest version in your [Dashboard Settings](https://dashboard.lob.com/settings/api-keys)
. You will only need to specify a version if you would like to test a newer version of the API without doing a full upgrade. The API will return an error if a version older than your current one is passed in.
### Example Request
curl https://api.lob.com/v1/addresses \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-H "Lob-Version: 2020-02-11"
### Specification Versioning
You might be wondering why our API and specification use different versioning schemes. Lob's API predates our specification and follows the [Stripe versioning](https://stripe.com/blog/api-versioning)
approach. This works well to manage backwards-incompatible changes to our API.
For our API specification (used to create this documentation), we've chosen [semantic versioning](https://semver.org/)
. This versioning reflects the backward-compatible changes that do not require a versioning of Lob's API.
Lob's API specification will be used to generate artifacts like documentation, client SDKs, and other developer tooling. Semantic versioning of our specification will inform how we version those artifacts like SDKs. It is helpful to know the version of a specification used to produce an artifact in order reference the specification release notes.
### Changelog
We are in the process of renovating our changelog, and will link it here shortly.
---