Lob (1.20.6)
Lob Developer Experience: lob-openapi@lob.com
URL: https://support.lob.com/
License: MIT
Terms of Service
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.
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.
Authentication
Requests made to the API are protected with HTTP Basic 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. You can find your account's API keys in your Dashboard Settings.
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:
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. 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 for more information.
back to top
Getting Started
1. Get Setup
Create an account at Lob.com
Obtain your API keys in the Lob dashboard settings
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 into your favorite IDE (integrated development environment)
3. Learn more
Try our quick start (TypeScript, Python, PHP, Java or Ruby):
Send your first Postcards
Use Case guides
Mass Deletion Setup
NCOA Restrictions
Override Cancellation Window
Visibility of Address Changes
Ingesting Tracking Events with Webhooksback to top
SDKs and Tools
Please visit our Github for a list of our supported libraries.
Typescript
PHP
Python
Java
Ruby
CSharp
Elixir
Go
Node.js (legacy)
Java (legacy)
PHP (legacy)
Python (Legacy)
Ruby (Legacy)
back to top
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
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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/addresses?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"previous_url": null,
"count": 2
}
Create
Creates a new address given information
Authorizations:
basicAuth
Request Body schema:
application/json
application/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 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
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 for more information.
recipient_moved
boolean or null
Only returned for accounts on certain Print & Mail Editions. Value is true if the address was altered because the recipient filed for a National Change of Address Linkage (NCOALink), 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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Example
full_us
full_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
200default
Content type
application/json
Example
full_us
full_us
Copy
Expand allCollapse 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"
}
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 for more information.
recipient_moved
boolean or null
Only returned for accounts on certain Print & Mail Editions. Value is true if the address was altered because the recipient filed for a National Change of Address Linkage (NCOALink), 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl https://api.lob.com/v1/addresses/adr_fa85158b26c3eb7c \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Example
address_us
address_us
Copy
Expand allCollapse 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"
}
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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/addresses/adr_43769b47aed248c2 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "adr_123456789",
"deleted": true
}
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 to gain access.
For more information, see our NCOALink guide.
back to top
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 within the "Create an Address" section in Addresses
back to top
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.
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 within the "Create an Address" section in Addresses (along with the corresponding request under "Request samples").
back to top
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
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 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 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 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. Depending on your Merge Variable strictness 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 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.
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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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.
fsc
boolean
Default: false
This is in beta. Contact 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Example
basic
basic
Copy
Expand allCollapse 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",
"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,
"object": "postcard"
}
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 and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "psc_123456789",
"deleted": true
}
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 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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/postcards?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"id": "psc_208e45e48d271294",
"description": null,
"metadata": { },
"to": {},
"url": "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": {},
"from": {},
"url": "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": [],
"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
}
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.
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.
Request Body schema:
application/json
application/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, US addresses may also be run through National Change of Address Linkage(NCOALink). Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail strictness setting, the request will fail. Lob Guide: Verification of Mailing 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 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
6x9 template
6x11 template
See here 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 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 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
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 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 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 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. Depending on your Merge Variable strictness 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 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.
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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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.
fsc
boolean
Default: false
This is in beta. Contact 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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse 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",
"width": "2.5",
"top": "2.5",
"right": "2.5",
"pages": "front,back"
},
"fsc": true
}
Response samples
200default
Content type
application/json
Example
basic
basic
Copy
Expand allCollapse 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",
"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,
"object": "postcard"
}
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
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 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 or your account contact to learn more.
thumbnails
Array of objects (thumbnail)
expected_delivery_date
string <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"medium": "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"
},
{
"small": "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",
"large": "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,
"object": "self_mailer"
}
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 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "sfm_123456789",
"deleted": true
}
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 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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/self_mailers?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"id": "sfm_7239rhwqkrfaskas",
"description": "April Campaign",
"metadata": { },
"to": {},
"from": {},
"url": "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": [],
"merge_variables": {},
"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": {},
"from": {},
"url": "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": [],
"merge_variables": {},
"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
}
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.
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.
Request Body schema:
application/json
application/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, US addresses may also be run through National Change of Address Linkage(NCOALink). Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail strictness setting, the request will fail. Lob Guide: Verification of Mailing 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
12x9 bifold template
17.75x9 trifold template
See here 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 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 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 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 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
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 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 or your account contact to learn more.
thumbnails
Array of objects (thumbnail)
expected_delivery_date
string <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse all
{
"description": "Demo Self Mailer job",
"to": "adr_bae820679f3f536b",
"from": "adr_210a8d4b0b76d77b",
"inside": "https://lob.com/selfmailerinside.pdf",
"outside": "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",
"width": "2.5",
"top": "2.5",
"right": "2.5",
"pages": "inside,outside"
},
"fsc": true
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"medium": "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"
},
{
"small": "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",
"large": "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,
"object": "self_mailer"
}
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
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.
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 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. Depending on your Merge Variable strictness 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 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 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 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.
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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"carrier": "USPS",
"tracking_number": null,
"tracking_events": [ ],
"thumbnails": [
{
"small": "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",
"large": "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",
"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",
"front_original_url": "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",
"thumbnails": [],
"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,
"object": "letter"
}
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 and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "ltr_123456789",
"deleted": true
}
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 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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/letters?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"id": "ltr_5ba44b462c79f07c",
"description": "Demo Letter",
"metadata": { },
"to": {},
"from": {},
"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",
"merge_variables": null,
"carrier": "USPS",
"tracking_number": "92071902358909000011275538",
"tracking_events": [],
"thumbnails": [],
"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": {},
"from": {},
"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",
"merge_variables": null,
"carrier": "USPS",
"tracking_number": null,
"tracking_events": [ ],
"thumbnails": [],
"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",
"previous_url": null,
"count": 2
}
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.
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.
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 documentation.
Request Body schema:
application/json
application/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, US addresses may also be run through National Change of Address Linkage(NCOALink). Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail strictness setting, the request will fail. Lob Guide: Verification of Mailing 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 and HTML templates.
If a custom_envelope is used, follow this template.
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 instead of the standard double window envelope.
See pricing 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 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 and flat envelope (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 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 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 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.
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 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 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 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 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
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.
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 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. Depending on your Merge Variable strictness 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 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 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 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.
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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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 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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse 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 style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>",
"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",
"width": "2",
"top": "2",
"right": "2",
"pages": "1-2,4-5"
},
"fsc": true
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"carrier": "USPS",
"tracking_number": null,
"tracking_events": [ ],
"thumbnails": [
{
"small": "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",
"large": "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",
"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",
"front_original_url": "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",
"thumbnails": [],
"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,
"object": "letter"
}
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
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 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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/checks?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"to": {},
"from": {},
"bank_account": {},
"carrier": "USPS",
"tracking_events": [ ],
"thumbnails": [],
"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",
"to": {},
"from": {},
"bank_account": {},
"carrier": "USPS",
"tracking_events": [ ],
"thumbnails": [],
"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",
"previous_url": null,
"count": 2
}
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.
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.
Request Body schema:
application/json
application/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, addresses may also be run through National Change of Address (NCOALink). If an address used does not meet your account’s US Mail Strictness Setting, the request will fail. More about verification of mailing 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 <float> <= 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.
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 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. Depending on your Merge Variable strictness 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 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.
Need more help? Consult our 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.
See pricing for extra costs incurred. Need more help? Consult our 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 for more information.
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
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 <float> 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 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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.
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 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. Depending on your Merge Variable strictness 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 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 <date> (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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse 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",
"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
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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"
},
"carrier": "USPS",
"tracking_events": [ ],
"thumbnails": [
{
"small": "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",
"large": "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",
"deleted": true
}
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 <float> 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 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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.
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 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. Depending on your Merge Variable strictness 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 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 <date> (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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl https://api.lob.com/v1/checks/chk_534f10783683daa0 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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"
},
"carrier": "USPS",
"tracking_events": [ ],
"thumbnails": [
{
"small": "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",
"large": "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",
"deleted": true
}
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 and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/checks/chk_534f10783683daa0 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "chk_123456789",
"deleted": true
}
Snap Packs
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 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/snap_packs/ord_0d6a16a3fff6318ac8f8008dc1" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"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",
"large": "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",
"medium": "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"
}
],
"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"
}
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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/snap_packs/ord_0d6a16a3fff6318ac8f8008dc1 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "ord_0d6a16a3fff6318ac8f8008dc1",
"deleted": true
}
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 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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/snap_packs?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"id": "ord_0d6a16a3fff6318ac8f8008dc1",
"description": "April Campaign",
"to": {},
"from": {},
"url": "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": [],
"merge_variables": {},
"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": {},
"from": {},
"url": "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": [],
"merge_variables": {},
"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
}
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.
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.
Request Body schema:
application/json
application/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, US addresses may also be run through National Change of Address Linkage(NCOALink). Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail strictness setting, the request will fail. Lob Guide: Verification of Mailing 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
See here 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 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 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
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 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse all
{
"description": "Demo Snap Pack Job",
"to": "adr_bae820679f3f536b",
"from": "adr_210a8d4b0b76d77b",
"inside": "https://lob.com/snappackinside.pdf",
"outside": "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"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"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",
"large": "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",
"medium": "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"
}
],
"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"
}
Booklets
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.
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 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. Depending on your Merge Variable strictness 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 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 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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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 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}
Request samples
CURL
Copy
curl -X GET "https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"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",
"large": "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"
}
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}
Request samples
CURL
Copy
curl -X DELETE https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "ord_0d6a16a3fff6318ac8f8008dc1",
"deleted": true
}
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 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
Request samples
CURL
Copy
curl -X GET "https://api.lob.com/v1/booklets?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"id": "ord_0d6a16a3fff6318ac8f8008dc1",
"description": "April Campaign",
"metadata": { },
"to": {},
"from": {},
"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",
"carrier": "USPS",
"tracking_number": null,
"tracking_events": [ ],
"thumbnails": [],
"merge_variables": {},
"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": {},
"from": {},
"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",
"carrier": "USPS",
"tracking_number": null,
"tracking_events": [ ],
"thumbnails": [],
"merge_variables": {},
"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
}
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.
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.
Request Body schema:
application/json
application/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, US addresses may also be run through National Change of Address Linkage(NCOALink). Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail strictness setting, the request will fail. Lob Guide: Verification of Mailing 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 and HTML templates. See pricing 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.
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 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 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. Depending on your Merge Variable strictness 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 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.
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 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 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
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.
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 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. Depending on your Merge Variable strictness 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 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 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 <date> (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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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 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 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
Request samples
PayloadCURL
Content type
application/json
application/json
Copy
Expand allCollapse 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 style='padding-top: 3in; margin: .5in;'>HTML Booklet for {{name}}</html>",
"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",
"width": "2",
"top": "2",
"right": "2",
"pages": "1-2,4-5"
},
"fsc": true,
"size": "8.375x5.375"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"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",
"large": "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"
}
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
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/json
application/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
Response Schema: application/json
routing_number
required
string = 9 characters
Must be a valid US routing number.
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.
date_created
required
string <date-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 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 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.
default Error
post
/bank_accounts/{bank_id}/verify
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse all
{
"amounts": [
1,
100
]
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"id": "bank_8cad8df5354d33f",
"signature_url": "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"
}
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.
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.
date_created
required
string <date-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 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 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.
default Error
get
/bank_accounts/{bank_id}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl https://api.lob.com/v1/bank_accounts/bank_8cad8df5354d33f \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"id": "bank_8cad8df5354d33f",
"signature_url": "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"
}
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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/bank_accounts/bank_3e64d9904356b20 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "bank_123456789",
"deleted": true
}
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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/bank_accounts?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"id": "bank_0e3fb07eba0b35b",
"signature_url": "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",
"previous_url": null,
"count": 2
}
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/json
application/json
routing_number
required
string = 9 characters
Must be a valid US routing number.
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.
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 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
Response Schema: application/json
routing_number
required
string = 9 characters
Must be a valid US routing number.
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.
date_created
required
string <date-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 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 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.
default Error
post
/bank_accounts
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse all
{
"description": "Test Bank Account",
"routing_number": "322271627",
"account_number": "123456789",
"signatory": "Jane Doe",
"account_type": "individual",
"metadata": {
"spiffy": "true"
}
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"id": "bank_8cad8df5354d33f",
"signature_url": "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"
}
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
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.
versions
required
Array of objects (template_version)
An array of all non-deleted version objects 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 for more information.
date_created
string <date-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"id": "tmpl_c94e83ca2cd5121",
"description": "Test Template",
"versions": [
{
"id": "vrsn_362184d96d9b0c9",
"suggest_json_editor": true,
"description": "Test Template",
"engine": "legacy",
"html": "<html>HTML for {{name}}</html>",
"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>HTML for {{name}}</html>",
"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"
}
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/json
application/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
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.
versions
required
Array of objects (template_version)
An array of all non-deleted version objects 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 for more information.
date_created
string <date-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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}
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
{
"description": "Updated Example",
"published_version": "vrsn_a"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"id": "tmpl_c94e83ca2cd5121",
"description": "Test Template",
"versions": [
{
"id": "vrsn_362184d96d9b0c9",
"suggest_json_editor": true,
"description": "Test Template",
"engine": "legacy",
"html": "<html>HTML for {{name}}</html>",
"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>HTML for {{name}}</html>",
"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"
}
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.
deleted
boolean (deleted)
Only returned if the resource has been successfully deleted.
default Error
delete
/templates/{tmpl_id}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/templates/tmpl_df934eeda694203 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"value": {
"id": "tmpl_123456789",
"deleted": true
}
}
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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/templates?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"id": "tmpl_d5a5a89da9106f8",
"description": "Test Template",
"versions": [],
"published_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": [],
"published_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",
"count": 2
}
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. 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/json
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 for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
Postcards - front and back
Self Mailers - inside and outside
Letters - file
Checks - check_bottom and attachment
Cards - 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 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
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.
versions
required
Array of objects (template_version)
An array of all non-deleted version objects 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 for more information.
date_created
string <date-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
Expand allCollapse all
{
"description": "demo",
"html": "<html>HTML for {{name}}</html>",
"metadata": {
"spiffy": "true"
},
"engine": "handlebars"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"id": "tmpl_c94e83ca2cd5121",
"description": "Test Template",
"versions": [
{
"id": "vrsn_362184d96d9b0c9",
"suggest_json_editor": true,
"description": "Test Template",
"engine": "legacy",
"html": "<html>HTML for {{name}}</html>",
"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>HTML for {{name}}</html>",
"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"
}
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
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 for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
Postcards - front and back
Self Mailers - inside and outside
Letters - file
Checks - check_bottom and attachment
Cards - 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121/versions/vrsn_534e339882d2282 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
{
"id": "vrsn_534e339882d2282",
"description": "Second Version",
"html": "<html>Second HTML for {{name}}</html>",
"date_created": "2017-11-09T04:49:38.016Z",
"date_modified": "2017-11-09T04:49:38.016Z",
"object": "version"
}
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/json
application/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
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 for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
Postcards - front and back
Self Mailers - inside and outside
Letters - file
Checks - check_bottom and attachment
Cards - 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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}
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
{
"description": "Some description"
}
Response samples
200default
Content type
application/json
Copy
{
"id": "vrsn_534e339882d2282",
"description": "Second Version",
"html": "<html>Second HTML for {{name}}</html>",
"date_created": "2017-11-09T04:49:38.016Z",
"date_modified": "2017-11-09T04:49:38.016Z",
"object": "version"
}
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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X DELETE https://api.lob.com/v1/templates/tmpl_4aa14648113e45b/versions/vrsn_534e339882d2282 \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"value": {
"id": "vrsn_123456789",
"deleted": true
}
}
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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/templates/tmpl_ea6e6a1abf01703/versions?limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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
}
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/json
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 for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
Postcards - front and back
Self Mailers - inside and outside
Letters - file
Checks - check_bottom and attachment
Cards - 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
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 for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details:
Postcards - front and back
Self Mailers - inside and outside
Letters - file
Checks - check_bottom and attachment
Cards - 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
{
"description": "Some Description",
"html": "<html>HTML for {{name}}</html>"
}
Response samples
200default
Content type
application/json
Copy
{
"id": "vrsn_534e339882d2282",
"description": "Second Version",
"html": "<html>Second HTML for {{name}}</html>",
"date_created": "2017-11-09T04:49:38.016Z",
"date_modified": "2017-11-09T04:49:38.016Z",
"object": "version"
}
Template Design
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. 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 or get started with a pre-designed template from our gallery. In Live mode, you can only have as many templates as allotted in your current Print & Mail Edition. 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.
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
HTML Examples
Use a pre-designed template from our gallery or follow these basic guidelines 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.
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
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
Letters
Checks
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
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
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 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
Manage Mail
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. Upgrade to the appropriate Print & Mail Edition to automatically gain access to this ability. For more details on this feature, check out our Cancellation Guide.
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
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, 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.
This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition 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
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.
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
Request samples
CURLRUBY
Copy
curl https://api.lob.com/v1/campaigns \
-u <YOUR API KEY>:
Response samples
200
Content type
application/json
Copy
Expand allCollapse 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
}
Create
Creates a new campaign with the provided properties. See how to launch your first campaign here.
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/json
application/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.
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 <date-time>
If schedule_type is target_delivery_date, provide a targeted delivery date for mail pieces in this campaign.
send_date
string or null <date-time>
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 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.
Responses
200 Campaign created successfully
Response Schema: application/json
date_created
required
string <date-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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.
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 <date-time>
If schedule_type is target_delivery_date, provide a targeted delivery date for mail pieces in this campaign.
send_date
string or null <date-time>
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 for more information.
default Error
post
/campaigns
Request samples
PayloadCURLRUBY
Content type
application/json
application/json
Copy
{
"name": "My Demo Campaign",
"description": "My Campaign's description",
"schedule_type": "immediate"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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.
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 <date-time>
If schedule_type is target_delivery_date, provide a targeted delivery date for mail pieces in this campaign.
send_date
string or null <date-time>
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 for more information.
default Error
get
/campaigns/{cmp_id}
Request samples
CURLRUBY
Copy
curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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/json
application/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 <date-time>
If schedule_type is target_delivery_date, provide a targeted delivery date for mail pieces in this campaign.
send_date
string <date-time>
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 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.
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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.
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 <date-time>
If schedule_type is target_delivery_date, provide a targeted delivery date for mail pieces in this campaign.
send_date
string or null <date-time>
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 for more information.
default Error
patch
/campaigns/{cmp_id}
Request samples
PayloadCURLPYTHONRUBY
Content type
application/json
application/json
Copy
{
"description": "Test campaign"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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_dates.
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}
Request samples
CURLRUBY
Copy
curl -X DELETE https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
{
"id": "cmp_e05ee61ff80764b",
"deleted": true
}
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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.
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 <date-time>
If schedule_type is target_delivery_date, provide a targeted delivery date for mail pieces in this campaign.
send_date
string or null <date-time>
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 for more information.
default Error
post
/campaigns/{cmp_id}/send
Request samples
CURL
Copy
curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b/send \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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.
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/json
application/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 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
6x9 template
6x11 template
See here 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 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 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_previews 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_previews 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
Request samples
PayloadShellRUBY
Content type
application/json
application/json
Copy
Expand allCollapse all
{
"campaign_id": "cmp_e05ee61ff80764b",
"resource_type": "postcard",
"description": "Our 4x6 postcard creative",
"details": { }
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 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_previews 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_previews 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}
Request samples
CURLRUBY
Copy
curl https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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/json
application/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 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 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_previews 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_previews 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}
Request samples
PayloadCURLPYTHONRUBY
Content type
application/json
application/json
Copy
{
"description": "Test creative"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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.
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 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 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 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 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-time> (Date Created)
A timestamp in ISO 8601 format of the date the upload was created
dateModified
required
string <date-time> (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
Request samples
CURLRUBY
Copy
curl https://api.lob.com/v1/uploads \
-u <YOUR API KEY>:
Response samples
200
Content type
application/json
Copy
Expand allCollapse all
[
{
"id": "upl_71be866e430b11e9",
"accountId": "fa9ea650fc7b31a89f92",
"campaignId": "cmp_1933ad629bae1408",
"mode": "test",
"failuresUrl": "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": []
}
}
]
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 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 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 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 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 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 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 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 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-time> (Date Created)
A timestamp in ISO 8601 format of the date the upload was created
dateModified
required
string <date-time> (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
Request samples
PayloadCURLRUBY
Content type
application/json
Copy
Expand allCollapse 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
201422
Content type
application/json
Copy
Expand allCollapse all
{
"id": "upl_71be866e430b11e9",
"accountId": "fa9ea650fc7b31a89f92",
"campaignId": "cmp_1933ad629bae1408",
"mode": "live",
"failuresUrl": "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": [ ]
}
}
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 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 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 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 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-time> (Date Created)
A timestamp in ISO 8601 format of the date the upload was created
dateModified
required
string <date-time> (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}
Request samples
CURLRUBY
Copy
curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9 \
-u <YOUR API KEY>: \
Response samples
200404422
Content type
application/json
Copy
Expand allCollapse all
{
"id": "upl_71be866e430b11e9",
"accountId": "fa9ea650fc7b31a89f92",
"campaignId": "cmp_1933ad629bae1408",
"mode": "live",
"failuresUrl": "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": [ ]
}
}
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 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 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 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 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 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 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 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 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-time> (Date Created)
A timestamp in ISO 8601 format of the date the upload was created
dateModified
required
string <date-time> (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}
Request samples
PayloadCURLPYTHONRUBY
Content type
application/json
Copy
Expand allCollapse 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
200404422
Content type
application/json
Copy
Expand allCollapse all
{
"id": "upl_71be866e430b11e9",
"accountId": "fa9ea650fc7b31a89f92",
"campaignId": "cmp_1933ad629bae1408",
"mode": "live",
"failuresUrl": "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": [ ]
}
}
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}
Request samples
CURLRUBY
Copy
curl -X DELETE https://api.lob.com/v1/uploads/upl_71be866e430b11e9 \
-u <YOUR API KEY>:
Upload file
Upload an audience file 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 <binary>
Responses
202 Successful Response
422 Validation Error
post
/uploads/{upl_id}/file
Request samples
CURLPYTHON
Copy
curl -X POST https://api.lob.com/v1/uploads/upl_71be866e430b11e9/file \
-u <YOUR API KEY>: \
-F file=@<YOUR FILE NAME HERE>
Response samples
202422
Content type
application/json
Copy
{
"message": "File uploaded successfully",
"filename": "string"
}
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.
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
Request samples
PayloadCURLPYTHONRUBY
Content type
application/json
Copy
{
"type": "all"
}
Response samples
2004XX
Content type
application/json
Copy
{
"message": "Export is processing",
"exportId": "ex_2dafd758ed3da9c43"
}
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
Request samples
CURLPYTHONRUBY
Copy
curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/report \
-u <YOUR API KEY>:
Response samples
200404
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"
}
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 <date-time>
A timestamp in ISO 8601 format of the date the export was created
dateModified
required
string <date-time>
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}
Request samples
CURLPYTHONRUBY
Copy
curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/exports/ex_6a94fe68fd151e0f8 \
-u <YOUR API KEY>:
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"
}
Informed Delivery Campaign
The Informed Delivery campaigns API allows you to create and view Informed Delivery campaigns.
back to top
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
Request samples
CURL
Copy
curl https://api.lob.com/v1/informed_delivery_campaign \
-u <YOUR API KEY>:
Response samples
200
Content type
application/json
Copy
Expand allCollapse 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",
"ride_along_image_s3_link": "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",
"ride_along_image_s3_link": "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
}
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 then you could use any variation of https://lob.com such as https://lob.com/promotions/promo_123
start_date
required
string <date>
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 <date>
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 <date-time>
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 then you could use any variation of https://lob.com such as 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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
Request samples
CURL
Copy
curl --request POST \
--url https://api.lob.com/v1/informed_delivery_campaigns \
-u <YOUR API KEY>: \
--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
200422
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",
"ride_along_image_s3_link": "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
}
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 <date>
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 <date-time>
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 then you could use any variation of https://lob.com such as 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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}
Request samples
CURL
Copy
curl https://api.lob.com/v1/informed_delivery_campaign/1200772869 \
-u <YOUR API KEY>:
Response samples
200404
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",
"ride_along_image_s3_link": "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
}
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 then you could use any variation of https://lob.com such as https://lob.com/promotions/promo_123
start_date
string <date>
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 <date>
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 <date-time>
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 then you could use any variation of https://lob.com such as 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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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}
Request samples
CURL
Copy
curl -X PATCH https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \
-u <YOUR API KEY>: \
-d '{"status":"approved"}'
Response samples
200404422
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",
"ride_along_image_s3_link": "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
}
US Verifications
Validate, automatically correct, and standardize the addresses in your address book based on USPS's Coding Accuracy Support System (CASS).
back to top
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 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 or the free plan (see our pricing for details).
back to top
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/json
application/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
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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARP
Content type
application/json
application/json
Copy
Expand allCollapse 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
200default
Content type
application/json
Copy
Expand allCollapse 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": {},
"deliverability_analysis": {},
"lob_confidence_score": {},
"object": "us_verification"
}
],
"errors": false
}
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 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/json
application/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 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 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
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 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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARP
Content type
application/json
application/json
Example
basic
basic
Copy
{
"primary_line": "210 King Street",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107"
}
Response samples
200default
Content type
application/json
Example
basic
basic
Copy
Expand allCollapse 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"
}
US Verification Types
These are detailed definitions for various fields in the US verification object.
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. 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 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 and private mailbox information is present.
back to top
US Autocompletions
Given partial address information, this endpoint returns up to 10 address suggestions.
back to top
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 within the "Autocomplete a partial address" section in US Autocompletions.
back to top
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.
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/json
application/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
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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Example
basic
basic
Copy
{
"address_prefix": "185 B",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"geo_ip_sort": false
}
Response samples
200default
Content type
application/json
Example
basic
basic
Copy
Expand allCollapse 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"
}
Reverse Geocode Lookups
Find a list of zip codes associated with a valid US location via latitude and longitude.
back to top
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/json
application/json
latitude
required
number or null <float> [ -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 <float> [ -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
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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
{
"latitude": 37.7749,
"longitude": 122.4194
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse all
{
"id": "us_reverse_geocode_8a013f3e",
"addresses": [
{
"components": {},
"location_analysis": {}
},
{
"components": {},
"location_analysis": {}
}
]
}
Zip Lookups
Find a list of cities, states and associated information about a US ZIP code.
back to top
Lookups
Returns information about a ZIP code
Authorizations:
basicAuth
Request Body schema:
application/json
application/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
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.
object
required
string
Default: "us_zip_lookup"
Value: "us_zip_lookup"
Value is resource type.
default Error
post
/us_zip_lookups
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Content type
application/json
application/json
Copy
{
"zip_code": "94107"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
Identity Validation
Validates whether a given name is associated with an address.
back to top
Identity Validation
Validates whether a given name is associated with an address.
Authorizations:
basicAuth
Request Body schema:
application/json
application/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 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 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
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 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 <float> [ 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
Request samples
PayloadCURL
Content type
application/json
application/json
Copy
{
"recipient": "Larry Lobster",
"primary_line": "210 King St.",
"secondary_line": "",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107"
}
Response samples
200default
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"
}
Intl Verifications
Address verification for non-US addresses
back to top
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 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 or the free plan (see our pricing for details).
back to top
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/json
application/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
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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARP
Content type
application/json
application/json
Copy
Expand allCollapse 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
200default
Content type
application/json
Copy
Expand allCollapse 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": {},
"object": "intl_verification"
}
],
"errors": false
}
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/json
application/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
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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARP
Content type
application/json
application/json
Example
basic
basic
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
200default
Content type
application/json
Example
full
full
Copy
Expand allCollapse 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"
}
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. There is no limit in Test mode. You can view and create webhooks on the Lob Dashboard, as well as view your events. See our Webhooks Integration Guide for more details on how to integrate. Please see the full list of event types available for subscription here.
back to top
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.
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. Only enabled for certain Print & Mail Editions.
postcard.in_transit true A postcard receives an "In Transit" tracking event.
postcard.in_local_area true A postcard receives an "In Local Area" tracking event.
postcard.processed_for_delivery true A postcard receives a "Processed for Delivery" tracking event.
postcard.delivered false A postcard receives a "Delivered" tracking event.
postcard.failed false A postcard receives a "Failed" rendering error or tracking event.
postcard.re-routed true A postcard receives a "Re-Routed" tracking event.
postcard.returned_to_sender true A postcard receives a "Returned to Sender" tracking event.
postcard.international_exit true A postcard receives a "International Exit" tracking event.
postcard.viewed false A postcard QR code or URL was scanned or viewed by the recipient.
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. Only enabled for certain Print & Mail Editions.
self_mailer.in_transit true A self_mailer receives an "In Transit" tracking event.
self_mailer.in_local_area true A self_mailer receives an "In Local Area" tracking event.
self_mailer.processed_for_delivery true A self_mailer receives a "Processed for Delivery" tracking event.
self_mailer.delivered true A self_mailer receives an "Delivered" tracking event.
self_mailer.failed false A self_mailer receives an "Failed" rendering error or tracking event.
self_mailer.re-routed true A self_mailer receives a "Re-Routed" tracking event.
self_mailer.returned_to_sender true A self_mailer receives a "Returned to Sender" tracking event.
self_mailer.international_exit true A self_mailer receives an "International Exit" tracking event.
self_mailer.viewed false A self_mailer's QR code or URL was scanned or viewed by the recipient.
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. Only enabled for certain Print & Mail Editions.
letter.in_transit true A letter receives an "In Transit" tracking event.
letter.in_local_area true A letter receives an "In Local Area" tracking event.
letter.processed_for_delivery true A letter receives a "Processed for Delivery" tracking event.
letter.delivered true A letter receives a "Delivered" tracking event.
letter.failed false A letter receives a "Failed" rendering error or tracking event.
letter.re-routed true A letter receives a "Re-Routed" tracking event.
letter.returned_to_sender true A letter receives a "Returned to Sender" tracking event.
letter.international_exit true A letter receives a "International Exit" 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. Only enabled for certain Print & Mail Editions.
letter.certified.in_transit true A certified letter receives an "In Transit" tracking event.
letter.certified.in_local_area true A certified letter receives an "In Transit" tracking event.
letter.certified.processed_for_delivery true A certified letter receives a "Processed for Delivery" tracking event.
letter.certified.re-routed true A certified letter receives a "Re-Routed" tracking event.
letter.certified.returned_to_sender true A certified letter receives a "Returned to Sender" tracking event.
letter.certified.delivered true A certified letter receives a "Delivered" tracking event.
letter.certified.pickup_available true A certified letter receives a "Pickup Available" tracking event.
letter.certified.issue true A certified letter receives an "Issue" 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.
letter.return_envelope.in_local_area true A return envelope receives an "In Local Area" tracking event.
letter.return_envelope.processed_for_delivery true A return envelope receives a "Processed for Delivery" tracking event.
letter.return_envelope.re-routed true A return envelope receives a "Re-Routed" tracking event.
letter.return_envelope.returned_to_sender true A return envelope receives a "Returned to Sender" tracking event.
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. Only enabled for certain Print & Mail Editions.
check.in_transit true A check receives an "In Transit" tracking event.
check.in_local_area true A check receives an "In Local Area" tracking event.
check.processed_for_delivery true A check receives a "Processed for Delivery" tracking event.
check.delivered true A check receives a "Delivered" tracking event.
check.failed false A check receives a "Failed" rendering error or tracking event.
check.re-routed true A check receives a "Re-Routed" tracking event.
check.returned_to_sender true A check receives a "Returned to Sender" tracking event.
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
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, the letter object, the check object, the address object, or the bank account object. For .deleted events, the body matches the response for the corresponding delete endpoint for that resource (e.g. the postcard delete response).
reference_id
required
string
Unique identifier of the related resource for the event.
event_type
required
object (event_type)
date_created
required
string <date-time> (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 allCollapse 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",
"front_template_id": null,
"back_template_id": null,
"carrier": "USPS",
"tracking_events": [ ],
"thumbnails": [
{},
{}
],
"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"
}
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 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
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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. Note this data is only available in Enterprise editions of Lob. Contact Sales 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
time
string <date-time>
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
normal
normal
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"
}
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
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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}
Request samples
ShellRUBYGO
Copy
curl https://api.lob.com/v1/billing_groups/bg_4bb02b527a72667d0 \
-u <YOUR API KEY>:
Response samples
200default
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"
}
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/json
application/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
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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}
Request samples
PayloadShellRUBYGO
Content type
application/json
application/json
Copy
{
"name": "Marketing Dept",
"description": "Usage group used for the Marketing Dept resource sends"
}
Response samples
200default
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"
}
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
Request samples
ShellRUBYGO
Copy
curl -X GET "https://api.lob.com/v1/billing_groups?limit=2" \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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
}
Create
Creates a new billing_group with the provided properties.
Authorizations:
basicAuth
Request Body schema:
application/json
application/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
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
string <date-time> (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
Request samples
PayloadShellRUBYGO
Content type
application/json
application/json
Copy
{
"name": "Marketing Dept",
"description": "Usage group used for the Marketing Dept resource sends"
}
Response samples
200default
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"
}
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
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
Request samples
CURL
Copy
curl -X GET "https://api.lob.com/v1/buckslips?limit=2" \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [],
"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
}
Create
Creates a new buckslip given information
Authorizations:
basicAuth
Request Body schema:
application/json
application/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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <uri> [ 1 .. 2083 ] characters
The signed link for the buckslip.
raw_url
required
string <uri> [ 1 .. 2083 ] characters
The raw URL of the buckslip.
front_original_url
required
string <uri> [ 1 .. 2083 ] characters
The original URL of the front template.
back_original_url
required
string <uri> [ 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
Request samples
PayloadCURL
Content type
application/json
application/json
Copy
{
"description": "Test buckslip",
"front": "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"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [
{
"small": "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",
"large": "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",
"medium": "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"
}
],
"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"
}
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <uri> [ 1 .. 2083 ] characters
The signed link for the buckslip.
raw_url
required
string <uri> [ 1 .. 2083 ] characters
The raw URL of the buckslip.
front_original_url
required
string <uri> [ 1 .. 2083 ] characters
The original URL of the front template.
back_original_url
required
string <uri> [ 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}
Request samples
CURL
Copy
curl https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [
{
"small": "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",
"large": "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",
"medium": "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"
}
],
"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"
}
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/json
application/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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <uri> [ 1 .. 2083 ] characters
The signed link for the buckslip.
raw_url
required
string <uri> [ 1 .. 2083 ] characters
The raw URL of the buckslip.
front_original_url
required
string <uri> [ 1 .. 2083 ] characters
The original URL of the front template.
back_original_url
required
string <uri> [ 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}
Request samples
PayloadCURL
Content type
application/json
application/json
Copy
{
"description": "Test buckslip",
"auto_reorder": true
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [
{
"small": "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",
"large": "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",
"medium": "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"
}
],
"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"
}
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}
Request samples
CURL
Copy
curl -X DELETE https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
{
"id": "buckslip_123456789",
"deleted": true
}
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
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
Request samples
CURL
Copy
curl https://api.lob.com/v1/buckslips/bck_6afffd19045076c/orders/ \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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
}
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/json
application/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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <date-time>
A timestamp in ISO 8601 format of the date the resource was created.
expected_availability_date
string <date-time>
The fixed deadline for the buckslips to be printed.
default Error
post
/buckslips/{buckslip_id}/orders
Request samples
PayloadCURL
Content type
application/json
application/json
Copy
{
"quantity": 10000
}
Response samples
200default
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"
}
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
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
Request samples
CURLTYPESCRIPTNODEPYTHONPHPCSHARPRUBYGO
Copy
curl -X GET "https://api.lob.com/v1/cards?limit=2" \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [],
"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
}
Create
Creates a new card given information
Authorizations:
basicAuth
Request Body schema:
application/json
application/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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <uri> [ 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 <uri> [ 1 .. 2083 ] characters
The raw URL of the card.
front_original_url
required
string <uri> [ 1 .. 2083 ] characters
The original URL of the front template.
back_original_url
required
string <uri> [ 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
Request samples
PayloadCURLTYPESCRIPTNODEPYTHONPHPCSHARPRUBYGO
Content type
application/json
application/json
Copy
{
"description": "Test card",
"front": "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",
"size": "2.125x3.375"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [
{
"small": "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",
"large": "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",
"medium": "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"
}
],
"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"
}
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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <uri> [ 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 <uri> [ 1 .. 2083 ] characters
The raw URL of the card.
front_original_url
required
string <uri> [ 1 .. 2083 ] characters
The original URL of the front template.
back_original_url
required
string <uri> [ 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}
Request samples
CURLTYPESCRIPTNODEPYTHONPHPCSHARPRUBYGO
Copy
curl https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [
{
"small": "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",
"large": "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",
"medium": "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"
}
],
"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"
}
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/json
application/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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <uri> [ 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 <uri> [ 1 .. 2083 ] characters
The raw URL of the card.
front_original_url
required
string <uri> [ 1 .. 2083 ] characters
The original URL of the front template.
back_original_url
required
string <uri> [ 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}
Request samples
PayloadCURLTYPESCRIPTNODECSHARPPYTHONRUBYGO
Content type
application/json
application/json
Copy
{
"description": "Test card",
"auto_reorder": true
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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",
"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",
"front_original_url": "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",
"thumbnails": [
{
"small": "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",
"large": "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",
"medium": "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"
}
],
"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"
}
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}
Request samples
CURLTYPESCRIPTNODEPYTHONPHPCSHARPRUBYGO
Copy
curl -X DELETE https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
{
"id": "card_123456789",
"deleted": true
}
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
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
Request samples
CURLTYPESCRIPTNODEPYTHONPHPCSHARPRUBYGO
Copy
curl https://api.lob.com/v1/cards/card_6afffd19045076c/orders/ \
-u <YOUR API KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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
}
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/json
application/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-time> (date_created)
A timestamp in ISO 8601 format of the date the resource was created.
date_modified
required
string <date-time> (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 <date-time>
A timestamp in ISO 8601 format of the date the resource was created.
expected_availability_date
string <date-time>
The fixed deadline for the cards to be printed.
default Error
post
/cards/{card_id}/orders
Request samples
PayloadCURLTYPESCRIPTNODEPYTHONPHPCSHARPRUBYGO
Content type
application/json
application/json
Copy
{
"quantity": 10000
}
Response samples
200default
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"
}
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, Postcards or Self Mailers 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 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
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
Request samples
Shell
Copy
curl -X GET "https://api.lob.com/v1/qr_code_analytics?limit=2&scanned=true" \
-u <YOUR API KEY>:
Response samples
200
Content type
application/json
Copy
Expand allCollapse all
{
"data": [
{
"resource_id": "ltr_d5a5a89da9106f8",
"date_created": "2019-07-27T23:49:01.511Z",
"number_of_scans": 2,
"scans": []
},
{
"resource_id": "psc_d5a5a89da9106f8",
"date_created": "2022-09-27T23:49:01.511Z",
"number_of_scans": 1,
"scans": []
}
],
"object": "list",
"count": 2,
"scanned_count": 2,
"total_count": 2
}
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 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
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}
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/domains/{domain_id}" \
-u <YOUR_LIVE_API_KEY>:
Response samples
200default
Content type
application/json
Copy
{
"id": "string",
"domain": "string",
"error_redirect_link": "string",
"status": "configured",
"created_at": "string",
"updated_at": "string"
}
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}
Response samples
200default
Content type
application/json
Copy
{
"id": "string",
"deleted": true
}
Create Domain
Add a new custom domain that can be used to create custom links.
Authorizations:
basicAuth
Request Body schema:
application/json
application/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
Request samples
PayloadCURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARP
Content type
application/json
application/json
Example
basic
basic
Copy
{
"domain": "lob.st"
}
Response samples
200default
Content type
application/json
Copy
{
"id": "string",
"domain": "string",
"error_redirect_link": "string",
"status": "configured",
"created_at": "string",
"updated_at": "string"
}
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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/domains?limit=2" \
-u <YOUR_LIVE_API_KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
]
}
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 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}
Request samples
CURL
Copy
curl -X GET "https://api.lob.com/v1/links/<link_id>" \
-u <YOUR_LIVE_API_KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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/json
application/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 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 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}
Request samples
PayloadCURL
Content type
application/json
application/json
Example
basic
basic
Copy
{
"resource_id": "ltr_133"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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}
Response samples
200default
Content type
application/json
Copy
{
"id": "string",
"deleted": true
}
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/json
application/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 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 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
Request samples
PayloadCURL
Content type
application/json
application/json
Example
basic
basic
Copy
{
"redirect_link": "https://www.lob.com",
"slug": "a1b2c3"
}
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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"
}
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
Request samples
CURLTYPESCRIPTNODERUBYPYTHONPHPJAVAELIXIRCSHARPGO
Copy
curl -X GET "https://api.lob.com/v1/links?limit=2" \
-u <YOUR_LIVE_API_KEY>:
Response samples
200default
Content type
application/json
Copy
Expand allCollapse 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": {},
"created_at": "string",
"updated_at": "string"
}
]
}
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!
back to top
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 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
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)
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
Requests and Responses
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
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
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.
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=<html style='margin: 130px; font-size: 50;'>Front HTML for {{name}}</html>" \
--data-urlencode "back=<html style='margin: 130px; font-size: 50;'>Back HTML</html>" \
-d "merge_variables[name]=Harry"
back to top
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=<html style='margin: 130px; font-size: 50;'>Front HTML for {{name}}</html>" \
--data-urlencode "back=<html style='margin: 130px; font-size: 50;'>Back HTML</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
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, 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 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 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 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
<FILE CONTENT>
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="color"
true
--------------------------7015ebe79c0a5f8c--
back to top
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 and Intl Verification 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
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. 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 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. 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.