API docs by Redocly

Lob (1.20.2)

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):

Use Case guides

SDKs and Tools

Please visit our Github for a list of our supported libraries.



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.

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"].

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 ≤.

object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

Responses

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

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

Request samples 

curl -X GET "https://api.lob.com/v1/addresses?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "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:
One of
Any of
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"
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

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
Any of
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

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.

Request samples

Content type
Example
{
  • "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

Content type
application/json
Example
{
  • "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

Response Schema: application/json
One of
Any of
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

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.

Request samples 

curl https://api.lob.com/v1/addresses/adr_fa85158b26c3eb7c \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
Example
{
  • "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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/addresses/adr_43769b47aed248c2 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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

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

Response Schema: application/json
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...

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.

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.

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.

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.

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.

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.
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.

Request samples 

curl https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
Example
{
  • "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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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 ≤.

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
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.

object or object

Sorts items by ascending or descending dates. Use either date_created or send_date, not both.

Responses

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

Array of objects (postcard)

list of postcards

Request samples 

curl -X GET "https://api.lob.com/v1/postcards?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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:
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

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.

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:

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.

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.

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.

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.

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

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
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...

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.

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.

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.

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.

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.

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.
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.

Request samples

Content type
{
  • "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

Content type
application/json
Example
{
  • "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

Response Schema: application/json
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...

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.

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.

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.

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.

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.

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_.

object or null

An object describing the reason for failure if the resource failed to render.

Request samples 

curl -X GET "https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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 ≤.

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
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.

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

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

Array of objects (self_mailer)

list of self_mailers

Request samples 

curl -X GET "https://api.lob.com/v1/self_mailers?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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:
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

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:

See here for HTML examples.

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.

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.

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.

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.

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

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
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...

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.

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.

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.

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.

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.

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_.

object or null

An object describing the reason for failure if the resource failed to render.

Request samples

Content type
{
  • "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

Content type
application/json
{}

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

Response Schema: application/json
One of
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.

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_.

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.

Array of objects (tracking_event_normal)

An array of tracking events ordered by ascending time.

Array of objects or null (card)

An array of cards associated with a specific letter

Array of objects or null (buckslip)

An array of buckslip(s) associated with a specific letter

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.

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.

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
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.

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.

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...

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.
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.

Request samples 

curl https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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 ≤.

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
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.

object or object

Sorts items by ascending or descending dates. Use either date_created or send_date, not both.

Responses

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

Array of regular (object) or registered (object) or certified (object) (letter)

list of letters

Request samples 

curl -X GET "https://api.lob.com/v1/letters?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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:
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

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.

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.

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.

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
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.

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

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
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.

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_.

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.

Array of objects (tracking_event_normal)

An array of tracking events ordered by ascending time.

Array of objects or null (card)

An array of cards associated with a specific letter

Array of objects or null (buckslip)

An array of buckslip(s) associated with a specific letter

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.

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.

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
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.

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.

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...

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.
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.

Request samples

Content type
{
  • "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

Content type
application/json
{}

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.

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"].

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 ≤.

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
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.

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

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

Array of objects (check)

list of checks

Request samples 

curl -X GET "https://api.lob.com/v1/checks?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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:
One of
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.

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

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.

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.

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.

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

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.

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

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
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.

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...

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.

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.

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.

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.

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.

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.
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.

Request samples

Content type
{
  • "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

Content type
application/json
{}

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

Response Schema: application/json
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.

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...

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.

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.

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.

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.

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.

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.
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.

Request samples 

curl https://api.lob.com/v1/checks/chk_534f10783683daa0 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/checks/chk_534f10783683daa0 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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

Response Schema: application/json
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...

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.

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.

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.

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.

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.

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_.

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.

Request samples 

curl -X GET "https://api.lob.com/v1/snap_packs/ord_0d6a16a3fff6318ac8f8008dc1" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/snap_packs/ord_0d6a16a3fff6318ac8f8008dc1 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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 ≤.

object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

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.

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

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

Array of objects (snap_pack)

list of snap_packs

Request samples 

curl -X GET "https://api.lob.com/v1/snap_packs?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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:
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

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:

See here for HTML examples.

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.

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.

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.

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.

object (qr_code)

Customize and place a QR code on the creative at the required position.

Responses

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
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...

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.

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.

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.

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.

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.

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_.

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.

Request samples

Content type
{
  • "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

Content type
application/json
{}

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

Response Schema: application/json
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_.

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.

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.

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.

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.
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...

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.

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.

Request samples 

curl -X GET "https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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 ≤.

object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

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.

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

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

Array of objects (booklet)

list of booklets

Request samples 

curl -X GET "https://api.lob.com/v1/booklets?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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:
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

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.

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.

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.

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.

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

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
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_.

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.

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.

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.

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.
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...

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.

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.

Request samples

Content type
{
  • "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

Content type
application/json
{}

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:
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

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
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.

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...

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.

Request samples

Content type
{
  • "amounts": [
    • 1,
    • 100
    ]
}

Response samples

Content type
application/json
{
  • "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

Response Schema: application/json
routing_number
required
string = 9 characters
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.

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...

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.

Request samples 

curl https://api.lob.com/v1/bank_accounts/bank_8cad8df5354d33f \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/bank_accounts/bank_3e64d9904356b20 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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 ≤.

object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

Responses

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

Array of objects (bank_account)

list of bank_accounts

Request samples 

curl -X GET "https://api.lob.com/v1/bank_accounts?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{}

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:
routing_number
required
string = 9 characters
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.

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

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
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.

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...

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.

Request samples

Content type
{
  • "description": "Test Bank Account",
  • "routing_number": "322271627",
  • "account_number": "123456789",
  • "signatory": "Jane Doe",
  • "account_type": "individual",
  • "metadata": {
    • "spiffy": "true"
    }
}

Response samples

Content type
application/json
{
  • "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

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.

required
Array of objects (template_version)

An array of all non-deleted version objects associated with the template.

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.

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.

Request samples 

curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "id": "tmpl_c94e83ca2cd5121",
  • "description": "Test Template",
  • "versions": [
    • {
      }
    ],
  • "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:
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

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.

required
Array of objects (template_version)

An array of all non-deleted version objects associated with the template.

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.

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.

Request samples

Content type
{
  • "description": "Updated Example",
  • "published_version": "vrsn_a"
}

Response samples

Content type
application/json
{
  • "id": "tmpl_c94e83ca2cd5121",
  • "description": "Test Template",
  • "versions": [
    • {
      }
    ],
  • "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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/templates/tmpl_df934eeda694203 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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 ≤.

object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

Responses

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

Array of objects (template)

list of templates

Request samples 

curl -X GET "https://api.lob.com/v1/templates?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "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:
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:

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.

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

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.

required
Array of objects (template_version)

An array of all non-deleted version objects associated with the template.

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.

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.

Request samples

Content type
{
  • "description": "demo",
  • "html": "<html>HTML for {{name}}</html>",
  • "metadata": {
    • "spiffy": "true"
    },
  • "engine": "handlebars"
}

Response samples

Content type
application/json
{
  • "id": "tmpl_c94e83ca2cd5121",
  • "description": "Test Template",
  • "versions": [
    • {
      }
    ],
  • "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

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:

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.

Request samples 

curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121/versions/vrsn_534e339882d2282 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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:
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

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:

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.

Request samples

Content type
{
  • "description": "Some description"
}

Response samples

Content type
application/json
{
  • "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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/templates/tmpl_4aa14648113e45b/versions/vrsn_534e339882d2282 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "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.

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"].

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

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

Array of objects (template_version)

list of template versions

Request samples 

curl -X GET "https://api.lob.com/v1/templates/tmpl_ea6e6a1abf01703/versions?limit=2" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "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:
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:

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

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:

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.

Request samples

Content type
{
  • "description": "Some Description",
  • "html": "<html>HTML for {{name}}</html>"
}

Response samples

Content type
application/json
{
  • "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:

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"].

object or object

before and after are both optional but only one of them can be in the query at a time.

Responses

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

Array of objects (campaign)

list of campaigns

Request samples 

curl https://api.lob.com/v1/campaigns \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "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:
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.

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

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.

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.

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.

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.

Request samples

Content type
{
  • "name": "My Demo Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate"
}

Response samples

Content type
application/json
{
  • "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

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.

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.

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.

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.

Request samples 

curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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:
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.

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

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.

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.

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.

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.

Request samples

Content type
{
  • "description": "Test campaign"
}

Response samples

Content type
application/json
{
  • "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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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

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.

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.

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.

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.

Request samples 

curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b/send \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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:
One of
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.

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:

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

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.

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.

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

Response Schema: application/json
One of
resource_type
required
string
Value: "postcard"

Mailpiece type for the creative

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.

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.

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.

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.

Request samples

Content type
{
  • "campaign_id": "cmp_e05ee61ff80764b",
  • "resource_type": "postcard",
  • "description": "Our 4x6 postcard creative",
  • "details": { }
}

Response samples

Content type
application/json
{
  • "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

Response Schema: application/json
One of
resource_type
required
string
Value: "postcard"

Mailpiece type for the creative

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.

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.

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.

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.

Request samples 

curl https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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:
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.

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

Response Schema: application/json
One of
resource_type
required
string
Value: "postcard"

Mailpiece type for the creative

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.

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.

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.

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.

Request samples

Content type
{
  • "description": "Test creative"
}

Response samples

Content type
application/json
{
  • "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

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

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.

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.

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

Request samples 

curl https://api.lob.com/v1/uploads \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
[
  • {
    • "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": {
      },
    • "optionalAddressColumnMapping": {
      },
    • "mergeVariableColumnMapping": {
      },
    • "metadata": {
      }
    }
]

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_.

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.

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.

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

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

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.

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.

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

Request samples

Content type
application/json
{
  • "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": [
      ]
    },
  • "mergeVariableColumnMapping": {
    • "name": "recipient_name",
    • "gift_code": "code",
    • "qr_code_redirect_url": "redirect_url"
    }
}

Response samples

Content type
application/json
{
  • "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

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

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.

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.

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

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9 \
  -u <YOUR API KEY>: \

Response samples

Content type
application/json
{
  • "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.

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.

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.

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

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

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.

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.

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

Request samples

Content type
application/json
{
  • "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": [
      ]
    },
  • "mergeVariableColumnMapping": {
    • "name": "recipient_name",
    • "gift_code": "code",
    • "qr_code_redirect_url": "redirect_url"
    }
}

Response samples

Content type
application/json
{
  • "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

Request samples 

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

Request samples 

curl -X POST https://api.lob.com/v1/uploads/upl_71be866e430b11e9/file \
  -u <YOUR API KEY>: \
  -F file=@<YOUR FILE NAME HERE>

Response samples

Content type
application/json
{
  • "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

Response Schema: application/json
message
required
string (Message)
Default: "Export is processing"
Value: "Export is processing"
exportId
required
string (Export ID)

Request samples

Content type
application/json
{
  • "type": "all"
}

Response samples

Content type
application/json
{
  • "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

Response Schema: application/json
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.

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/report \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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

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_.

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/exports/ex_6a94fe68fd151e0f8 \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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

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

Array of objects (response)

list of Informed Delivery campaigns

Request samples 

curl https://api.lob.com/v1/informed_delivery_campaign \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "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

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).

Request samples 

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

Content type
application/json
{
  • "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

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).

Request samples 

curl https://api.lob.com/v1/informed_delivery_campaign/1200772869 \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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

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).

Request samples 

curl -X PATCH https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \
  -u <YOUR API KEY>: \
  -d '{"status":"approved"}'

Response samples

Content type
application/json
{
  • "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:
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

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
required
Array of us_verification (object) or error (object)
errors
required
boolean

Indicates whether any errors occurred during the verification process.

Request samples

Content type
{
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    • {
      }
    ],
  • "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:
One of
Any of
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

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.

object (us_components)

A nested object containing a breakdown of each component of an address.

object (deliverability_analysis)

A nested object containing a breakdown of the deliverability of an address.

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.

Request samples

Content type
Example
{
  • "primary_line": "210 King Street",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107"
}

Response samples

Content type
application/json
Example
{
  • "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": [
      ],
    • "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:
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

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_.

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.

Request samples

Content type
Example
{
  • "address_prefix": "185 B",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107",
  • "geo_ip_sort": false
}

Response samples

Content type
application/json
Example
{
  • "id": "us_auto_a3ac97bcfbb2460ab20c",
  • "suggestions": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "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:
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

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_.

Array of objects (addresses)

list of addresses

object
string
Default: "us_reverse_geocode_lookup"
Value: "us_reverse_geocode_lookup"

Value is resource type.

Request samples

Content type
{
  • "latitude": 37.7749,
  • "longitude": 122.4194
}

Response samples

Content type
application/json
{
  • "id": "us_reverse_geocode_8a013f3e",
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

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:
zip_code
required
string^\d{5}$

A 5-digit ZIP code.

Responses

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_.

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.

Request samples

Content type
{
  • "zip_code": "94107"
}

Response samples

Content type
application/json
{
  • "id": "us_zip_c7cb63d68f8d6",
  • "cities": [
    • {
      }
    ],
  • "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:
One of
Any of
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

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
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.

Request samples

Content type
{
  • "recipient": "Larry Lobster",
  • "primary_line": "210 King St.",
  • "secondary_line": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107"
}

Response samples

Content type
application/json
{
  • "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:
required
Array of objects (multiple_components_intl) [ 1 .. 20 ] items

Responses

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
required
Array of intl_verification (object) or error (object)
errors
required
boolean

Indicates whether any errors occurred during the verification process.

Request samples

Content type
{
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    • {
      }
    ],
  • "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:
One of
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

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.
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.

Request samples

Content type
Example
{
  • "recipient": "Harry Zhang",
  • "primary_line": "370 Water St",
  • "secondary_line": "",
  • "city": "Summerside",
  • "state": "Prince Edward Island",
  • "postal code": "C1N 1C4",
  • "country": "CA"
}

Response samples

Content type
application/json
Example
{
  • "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

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.

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

Content type
application/json
{}

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

Response Schema: application/json
One of
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

Content type
application/json
Example
{
  • "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

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.

Request samples 

curl https://api.lob.com/v1/billing_groups/bg_4bb02b527a72667d0 \
-u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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:
description
string (bg_description) <= 255 characters

Description of the billing group.

name
string (name) <= 255 characters

Name of the billing group.

Responses

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.

Request samples

Content type
{
  • "name": "Marketing Dept",
  • "description": "Usage group used for the Marketing Dept resource sends"
}

Response samples

Content type
application/json
{
  • "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"].

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 ≤.

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 ≤.

object or object

Sorts items by ascending or descending dates. Use either date_created or date_modified, not both.

Responses

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

Array of objects (billing_group)

list of billing_groups

Request samples 

curl -X GET "https://api.lob.com/v1/billing_groups?limit=2" \
-u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "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:
name
required
string (name) <= 255 characters

Name of the billing group.

description
string (bg_description) <= 255 characters

Description of the billing group.

Responses

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.

Request samples

Content type
{
  • "name": "Marketing Dept",
  • "description": "Usage group used for the Marketing Dept resource sends"
}

Response samples

Content type
application/json
{
  • "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.

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

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

Array of objects (buckslip)

list of buckslips

Request samples 

curl -X GET "https://api.lob.com/v1/buckslips?limit=2" \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{}

Create

Creates a new buckslip given information

Authorizations:
basicAuth
Request Body schema:
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

remote_file_url (string) or local_file_path (string)

A PDF template for the back of the buckslip

Responses

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.

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.

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

Request samples

Content type
{}

Response samples

Content type
application/json
{}

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

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.

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.

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

Request samples 

curl https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{}

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:
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

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.

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.

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

Request samples

Content type
{
  • "description": "Test buckslip",
  • "auto_reorder": true
}

Response samples

Content type
application/json
{}

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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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

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

Array of objects (buckslip_order)

List of buckslip orders

Request samples 

curl https://api.lob.com/v1/buckslips/bck_6afffd19045076c/orders/ \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "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:
quantity
required
integer [ 5000 .. 10000000 ]

The quantity of buckslips in the order (minimum 5,000).

Responses

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.

Request samples

Content type
{
  • "quantity": 10000
}

Response samples

Content type
application/json
{
  • "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.

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

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

Array of objects (card)

list of cards

Request samples 

curl -X GET "https://api.lob.com/v1/cards?limit=2" \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{}

Create

Creates a new card given information

Authorizations:
basicAuth
Request Body schema:
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

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

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.

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

Request samples

Content type
{}

Response samples

Content type
application/json
{}

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

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.

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

Request samples 

curl https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{}

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:
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

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.

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

Request samples

Content type
{
  • "description": "Test card",
  • "auto_reorder": true
}

Response samples

Content type
application/json
{}

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

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.

Request samples 

curl -X DELETE https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "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

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

Array of objects (card_order)

List of card orders

Request samples 

curl https://api.lob.com/v1/cards/card_6afffd19045076c/orders/ \
  -u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "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:
quantity
required
integer [ 10000 .. 10000000 ]

The quantity of cards in the order (minimum 10,000).

Responses

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.

Request samples

Content type
{
  • "quantity": 10000
}

Response samples

Content type
application/json
{
  • "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"].

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

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.

Array of objects (qr_code_scans)

List of QR code analytics

Request samples 

curl -X GET "https://api.lob.com/v1/qr_code_analytics?limit=2&scanned=true" \
-u <YOUR API KEY>:

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "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

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.

Request samples 

curl -X GET "https://api.lob.com/v1/domains/{domain_id}" \
  -u <YOUR_LIVE_API_KEY>:

Response samples

Content type
application/json
{
  • "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

Response Schema: application/json
id
string

Unique identifier for a domain.

deleted
boolean

Only returned if the domain was successfully deleted.

Response samples

Content type
application/json
{
  • "id": "string",
  • "deleted": true
}

Create Domain

Add a new custom domain that can be used to create custom links.

Authorizations:
basicAuth
Request Body schema:
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

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.

Request samples

Content type
Example
{
  • "domain": "lob.st"
}

Response samples

Content type
application/json
{
  • "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.

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

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

Array of objects (domain_response)

List of domains.

Request samples 

curl -X GET "https://api.lob.com/v1/domains?limit=2" \
  -u <YOUR_LIVE_API_KEY>:

Response samples

Content type
application/json
{
  • "object": "string",
  • "next_url": "string",
  • "previous_url": "string",
  • "count": 0,
  • "total_count": 0,
  • "data": [
    • {
      }
    ]
}

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 version of the API is version 2024-01-01. 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: 2024-01-01"

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

View our Changelog here.