Lob Documentation - curl

Introduction

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. Keep reading below for more information on each specific Service. For Frequently Asked Questions and other help, please visit our help center.

API endpoint

https://api.lob.com/

Summary of Resource URL Patterns

/v1/addresses
/v1/addresses/{id}
/v1/us_verifications
/v1/intl_verifications
/v1/postcards
/v1/postcards/{id}
/v1/letters
/v1/letters/{id}
/v1/checks
/v1/checks/{id}
/v1/bank_accounts
/v1/bank_accounts/{id}
/v1/bank_accounts/{id}/verify
/v1/areas
/v1/areas/{id}
/v1/routes/{zip_code}
/v1/routes
/v1/countries
/v1/states

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.

All API requests must be made over HTTPS, or they will fail.

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

Versioning

When backwards-incompatible changes are made to the API, a new dated version is released. The latest version of the API is version 2017-05-17. 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. See API Changelog for a full list of breaking changes.

Example Request


curl https://api.lob.com/v1/addresses \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -H "Lob-Version: 2017-05-17"

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.

Attributes

message:	A human-readable message with more details about the error
status_code:	A conventional HTTP status code

HTTP Status Code Summary

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	Some sort of error with the provided inputs
429 - Too Many Requests	The user has sent too many requests in a given amout of time
500 - Server Error	Something is wrong on Lob's end

Rate Limiting

Rate limiting is primarily considered on both a user-by-user basis and an endpoint-by-endpoint basis. If an endpoint allows for 15 requests per rate limit window, then it allows you to make 15 requests per API key. This is similar to the way many other APIs enforce rate limits.

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 and Response Codes

HTTP headers are returned on each request to a rate limited endpoint. Ensure that you inspect these headers during your requests. They provide relevant data on how many more requests your application is allowed to make for the endpoint you just utilized.

rate-limit-limit:	the rate limit ceiling for a given request
rate-limit-window:	the window of time for this cycle (in seconds)
rate-limit-remaining:	the number of requests remaining in this window

Example HTTP Headers

      
rate-limit-limit:250
rate-limit-remaining:78
rate-limit-window:60

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:

        
{
  "error": {
    "message": "Rate limit exceeded. Please wait 60 seconds and try your request again.",
    "status_code": 429
  }
}

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

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_78c304d54912c502" \
  -d "from=adr_61a0865c8c573139" \
  --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 "data[name]=Harry"

Example List Request with Metadata Filter


curl -g "https://api.lob.com/v1/postcards?metadata[campaign]=NEWYORK2015&limit=2&offset=0" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

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.

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 "data[name]=Harry"

Asset URLs

All asset URLs returned by the Lob API (postcards, letters, thumbnails, etc) are signed S3 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.

Libraries

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

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.

The address object

Fields

id:	string Unique identifier prefixed with `adr_`.
description:	string or null
name:	string or null
company:	string or null
phone:	string or null
email:	string or null
address_line1:	string
address_line2:	string or null
address_city:	string or null
address_state:	string or null Will be returned as a 2 letter state short-name code if `address_country` is `US`, otherwise will be returned as the full string.
address_zip:	string or null
address_country:	string Will be returned as the full country name.
metadata:	object
date_created:	string A timestamp in ISO 8601 format of the date the address was created.
date_modified:	string A timestamp in ISO 8601 format of the date the address was last modified.
object:	string Value is `address`.

Example Response


{
  "id": "adr_d3489cd64c791ab5",
  "description": "Harry - Home",
  "name": "Harry Zhang",
  "company": "Lob",
  "phone": "5555555555",
  "email": "[email protected]",
  "address_line1": "123 Test Street",
  "address_line2": "Unit 199",
  "address_city": "Mountain View",
  "address_state": "CA",
  "address_zip": "94085",
  "address_country": "United States",
  "metadata": {},
  "date_created": "2015-04-27T18:52:44.725Z",
  "date_modified": "2015-04-27T18:52:44.725Z",
  "object": "address"
}

Create an address

Creates a new address object

Arguments

description:	optional
name:	optional Either `name` or `company` is required, you may also add both. The total string for `name` must be no longer than 50 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address.
company:	optional Either `name` or `company` is required, you may also add both. The total string for `company` must be no longer than 200 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 The total string must be no longer than 200 characters.
address_line2:	optional The total string must be no longer than 200 characters.
address_country:	optional Must be a 2 letter country short-name code (ISO 3166). Defaults to `US`.
address_city:	optional Required if `address_country` is `US`, otherwise optional. The total string must be no longer than 200 characters.
address_state:	optional Required and must be a 2 letter state short-name code if `address_country` is `US`, otherwise optional and the total string can not be any longer than 200 characters.
address_zip:	optional Required and must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234` if `address_country` is `US`, otherwise optional and the total string can not be any longer than 40 characters.
phone:	optional The total string must be no longer than 40 characters.
email:	optional The total string must be no longer than 100 characters.
metadata:	optional Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. See Metadata for more information.

Returns

Returns an address object upon successful creation.

Example Definition

POST https://api.lob.com/v1/addresses

Example Request


curl https://api.lob.com/v1/addresses \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Harry - Home" \
  -d "name=Harry Zhang" \
  -d "company=Lob" \
  -d "[email protected]" \
  -d "phone=5555555555" \
  -d "address_line1=123 Test Street" \
  -d "address_line2=Unit 199" \
  -d "address_city=Mountain View" \
  -d "address_state=CA" \
  -d "address_zip=94085" \
  -d "address_country=US"

Example Response


{
  "id": "adr_d3489cd64c791ab5",
  "description": "Harry - Home",
  "name": "Harry Zhang",
  "company": "Lob",
  "phone": "5555555555",
  "email": "[email protected]",
  "address_line1": "123 Test Street",
  "address_line2": "Unit 199",
  "address_city": "Mountain View",
  "address_state": "CA",
  "address_zip": "94085",
  "address_country": "United States",
  "metadata": {},
  "date_created": "2015-04-27T18:52:44.725Z",
  "date_modified": "2015-04-27T18:52:44.725Z",
  "object": "address"
}

Retrieve an address

Retrieves the details of an existing address. You need only supply the unique customer identifier that was returned upon address creation.

Arguments

id:	required The identifier of the address to be retrieved.

Returns

Returns an address object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/addresses/{id}

Example Request


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

Example Response


{
  "id": "adr_fa85158b26c3eb7c",
  "description": null,
  "metadata": {},
  "name": "Harry Zhang",
  "phone": "5555555555",
  "email": "[email protected]",
  "company": null,
  "address_line1": "345 UPDATE STREET",
  "address_line2": "Unit 199",
  "address_city": "Mountain View",
  "address_state": "CA",
  "address_zip": "94085",
  "address_country": "United States",
  "date_created": "2013-07-20T05:52:30.000Z",
  "date_modified": "2013-12-05T20:45:37.000Z",
  "object": "address"
}

Delete an address

Permanently deletes a customer. It cannot be undone.

Arguments

id:	required The identifier of the address to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

DELETE https://api.lob.com/v1/addresses/{id}

Example Request


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

Example Response


{
  "id": "adr_43769b47aed248c2",
  "deleted": true
}

List all addresses

Returns a list of your addresses. The addresses are returned sorted by creation date, with the most recently created addresses appearing first.

Arguments

offset:	optional Return requested # of items starting with the value, default=0, must be an integer
limit:	optional How many results to return, default=10, max 100, must be an integer
include:	optional Request that the response include the total count by specifying include[]=total_count
metadata:	optional Filter by metadata key-value pair, e.g. `metadata[customer_id]=987654`
date_created:	optional 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 ≤

Returns

A dictionary with a data property that contains an array of up to limit addresses, starting at index offset. Each entry in the array is a separate address object. If no more addresses are available, the resulting array will be empty.

Example Definition

GET https://api.lob.com/v1/addresses

Example Request


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

Example Response


{
  "data": [
    {
      "id": "adr_b8fb5acf3a2b55db",
      "description": null,
      "metadata": {},
      "name": "TestAddress",
      "phone": null,
      "email": "[email protected]",
      "company": null,
      "address_line1": "123 Test Street",
      "address_line2": "Unit 199",
      "address_city": "Mountain View",
      "address_state": "CA",
      "address_zip": "94085",
      "address_country": "United States",
      "date_created": "2015-04-25T01:07:10.374Z",
      "date_modified": "2015-04-25T01:07:10.374Z",
      "object": "address"
    },
    {
      "id": "adr_a6e74e875bbafb92",
      "description": null,
      "metadata": {},
      "name": "TestAddress",
      "phone": null,
      "email": "[email protected]",
      "company": null,
      "address_line1": "123 Test Street",
      "address_line2": "Unit 199",
      "address_city": "Mountain View",
      "address_state": "CA",
      "address_zip": "94085",
      "address_country": "United States",
      "date_created": "2015-04-25T01:06:39.459Z",
      "date_modified": "2015-04-25T01:06:39.459Z",
      "object": "address"
    }
  ],
  "count": 2,
  "object": "list"
}

US Verifications

The US Verification API allows you to validate and standardize your addresses based on USPS's Coding Accuracy Support System (CASS). It will return a US verification object based on provided inputs.

The US verification object

Fields

id:

string

Unique identifier prefixed with us_ver_.

recipient:

string

The intended recipient, typically a person's or firm's name.

primary_line:

string

The primary delivery line (usually the street address) of the address. Combination of the following applicable components:

Primary Number (primary_number)
Street Predirection (street_predirection)
Street Name (street_name)
Street Suffix (street_suffix)
Street Postdirection (street_postdirection)
Secondary Designator (secondary_designator)
Secondary Number (secondary_number)
PMB Designator (pmb_designator)
PMB Number (pmb_number)

secondary_line:

string

The secondary delivery line of the address. This field is typically empty but may contain information if primary_line is too long.

urbanization:

string

Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city.

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

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_extra_secondary — The address is deliverable by removing the provided secondary unit designator. This information may be incorrect or unnecessary.
deliverable_missing_secondary — The address is deliverable to the building's default address but is missing a secondary unit designator and/or number. There is a chance the mail will not reach the intended recipient.
undeliverable — The address is not deliverable according to the USPS, but parts of the address are valid (such as the street and ZIP code).
no_match — This address is not deliverable. No matching street could be found within the city or ZIP code.

components:

object

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

primary_number:

string

The numeric or alphanumeric part of an address preceding the street name. Often the house, building, or PO Box number.

street_predirection:

string

Geographic direction preceding a street name (N, E, S, W, NE, SE, NW, SW).

street_name:

string

The name of the street.

street_suffix:

string

The standard USPS abbreviation for the street suffix (ST, AVE, BLVD, etc).

street_postdirection:

string

Geographic direction following a street name (N, E, S, W, NE, SE, NW, SW).

secondary_designator:

string

The standard USPS abbreviation describing the components[secondary_number] (STE, APT, BLDG, etc).

secondary_number:

string

Number of the apartment/unit/etc.

pmb_designator:

string

Designator of a CMRA-authorized private mailbox.

pmb_number:

string

Number of a CMRA-authorized private mailbox.

extra_secondary_information:

string

An extra (often unnecessary) secondary designator and/or number provided with the input address.

city:

string

The name of the city.

state:

string

The state as a two-letter abbreviation.

zip_code:

string

The 5-digit ZIP code.

zip_code_plus_4:

string

The 4-digit ZIP add-on code.

zip_code_type:

string

A description of the ZIP code type. For more detailed information about each ZIP code type, see the appendix. Will be one of standard, military, unique, po_box, or an empty string.

delivery_point_barcode:

string

A 12-digit identifier that uniquely identifies a delivery point (location where mail can be sent and received). It consists of the 5-digit ZIP code (zip_code), 4-digit ZIP+4 add-on (zip_code_plus_4), 2-digit delivery point, and 1-digit delivery point check digit.

record_type:

string

A description of the type of address. Populated if a DPV match is made (deliverability_analysis[dpv_confirmation] is Y, S, or D). For more detailed information about each record type, see the appendix. Will be one of street, highrise, firm, po_box, rural_route, general_delivery, or an empty string.

default_building_address:

boolean

Designates whether or not the address is the default address for a building containing multiple delivery points.

county:

string

County name of the address.

county_fips:

string

A 5-digit FIPS county code which uniquely identifies components[county]. It consists of a 2-digit state code and a 3-digit county code.

carrier_route:

string

A 4-character code assigned to a mail delivery route within a ZIP code.

carrier_route_type:

string

The type of components[carrier_route]. For more detailed information about each carrier route type, see the appendix. Possible values are:

city_delivery — City delivery (starts with "C")
rural_route — Rural route (starts with "R")
highway_contract — Highway contract route (starts with "H")
po_box — P.O. Box route (starts with "B")
general_delivery — General delivery (starts with "G")

deliverability_analysis:

object

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

dpv_confirmation:

string

Result of Delivery Point Validation (DPV), which determines whether or not the address is deliverable by the USPS. Possible values are:

Y — The address is deliverable by the USPS.
S — The address is deliverable by removing the provided secondary unit designator. This information may be incorrect or unnecessary.
D — The address is deliverable to the building's default address but is missing a secondary unit des ignator and/or number. There is a chance the mail will not reach the intended recipient.
N — The address is not deliverable according to the USPS, but parts of the address are valid (such as the street and ZIP code).
empty string — This address is not deliverable. No matching street could be found within the city or ZIP code.

dpv_cmra:

string

Indicates whether or not the address is CMRA-authorized. Possible values are:

Y — Address is CMRA-authorized
N — Address is not CMRA-authorized.
empty string — A DPV match is not made (deliverability_analysis[dpv_confirmation] is N or an empty string)

dpv_vacant:

string

Indicates that an address was once deliverable, but has become vacant and is no longer receiving deliveries. Possible values are:

Y — Address is vacant
N — Address is not vacant
empty string — A DPV match is not made (deliverability_analysis[dpv_confirmation] is N or an empty string)

dpv_footnotes:

array

An array of 2-character strings that gives more insight into how deliverability_analysis[dpv_confirmation] was determined. Will always include at least 1 string, and can include up to 3. For possible values and details, see the appendix.

ews_match:

boolean

Indicates whether or not an address has been flagged in the Early Warning System (EWS), meaning the address is under development and not yet ready to receive mail. However, it should become available in a few months.

lacs_indicator:

string

Indicates whether the address was matched and converted by LACS^Link. LACS^Link corrects outdated addresses into their modern counterparts. Possible values are:

Y — New address produced with a matching record in LACS^Link.
N — New address could not be produced because no match was found in LACS^Link.
empty string — LACS^Link was not attempted.

lacs_return_code:

string

A code indicating how deliverability_analysis[lacs_indicator] was determined. Possible values are:

A — A new address was produced because a match was found in LACS^Link.
92 — A LACS^Link record was matched after dropping secondary information.
14 — A match was found in LACS^Link, but could not be converted to a deliverable address.
00 — A match was not found in LACS^Link, and no new address was produced.
empty string — LACS^Link was not attempted.

suite_return_code:

string

Indicates whether the address was matched and corrected by Suite^Link. Suite^Link attempts to provide secondary information businesses. Possible values are:

A — A Suite^Link match was found and secondary information was added.
00 — A Suite^Link match could not be found and no secondary information was added.
empty string — Suite^Link lookup was not attempted.

object:

string

Value is us_verification.

Example Response


{
  "id": "us_ver_c7cb63d68f8d6",
  "recipient": "LOB.COM",
  "primary_line": "185 BERRY ST STE 6600",
  "secondary_line": "",
  "urbanization": "",
  "last_line": "SAN FRANCISCO CA 94107-1728",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "185",
    "street_predirection": "",
    "street_name": "BERRY",
    "street_suffix": "ST",
    "street_postdirection": "",
    "secondary_designator": "STE",
    "secondary_number": "6600",
    "pmb_designator": "",
    "pmb_number": "",
    "extra_secondary_information": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip_code": "94107",
    "zip_code_plus_4": "1728",
    "zip_code_type": "standard",
    "delivery_point_barcode": "941071728506",
    "record_type": "highrise",
    "default_building_address": false,
    "county": "SAN FRANCISCO",
    "county_fips": "06075",
    "carrier_route": "C001",
    "carrier_route_type": "city_delivery"
  },
  "deliverability_analysis": {
    "dpv_confirmation": "Y",
    "dpv_cmra": "N",
    "dpv_vacant": "N",
    "dpv_footnotes": [
      "AA",
      "BB"
    ],
    "ews_match": false,
    "lacs_indicator": "",
    "lacs_return_code": "",
    "suite_return_code": ""
  },
  "object": "us_verification"
}

Verify a US address

Verify a domestic address. Only requests with live API keys will use valid CASS data to generate a response. Properly formatted requests with test API keys will return the generic dummy response on the right, regardless of inputs.

Arguments

recipient:	optional The intended recipient, typically a person's or firm's name.
primary_line:	required
secondary_line:	optional
urbanization:	optional Only used for addresses in Puerto Rico.
zip_code:	optional Required if no `city` and `state` are passed. Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234` or `12345 1234`.
city:	optional `city` and `state` are required if no `zip_code` is passed.
state:	optional `city` and `state` are required if no `zip_code` is passed.

Returns

A US verification object with detailed information about the corrected address.

Example Definition

POST https://api.lob.com/v1/us_verifications

Example Request


curl https://api.lob.com/v1/us_verifications \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "primary_line=185 Berry Street" \
  -d "city=San Francisco" \
  -d "state=CA" \
  -d "zip_code=94107"

Example Response


{
  "id": "us_ver_c7cb63d68f8d6",
  "recipient": "LOB.COM",
  "primary_line": "185 BERRY ST STE 6600",
  "secondary_line": "",
  "urbanization": "",
  "last_line": "SAN FRANCISCO CA 94107-1728",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "185",
    "street_predirection": "",
    "street_name": "BERRY",
    "street_suffix": "ST",
    "street_postdirection": "",
    "secondary_designator": "STE",
    "secondary_number": "6600",
    "pmb_designator": "",
    "pmb_number": "",
    "extra_secondary_information": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip_code": "94107",
    "zip_code_plus_4": "1728",
    "zip_code_type": "standard",
    "delivery_point_barcode": "941071728506",
    "record_type": "highrise",
    "default_building_address": false,
    "county": "SAN FRANCISCO",
    "county_fips": "06075",
    "carrier_route": "C001",
    "carrier_route_type": "city_delivery"
  },
  "deliverability_analysis": {
    "dpv_confirmation": "Y",
    "dpv_cmra": "N",
    "dpv_vacant": "N",
    "dpv_footnotes": [
      "AA",
      "BB"
    ],
    "ews_match": false,
    "lacs_indicator": "",
    "lacs_return_code": "",
    "suite_return_code": ""
  },
  "object": "us_verification"
}

International Verifications

Address verification for international (non-US) addresses.

Verify an international address

Verify an international address. Requests to this endpoint with a test API key will return a 403 error.

Arguments

name:	optional
address_line1:	optional
address_line2:	optional
address_city:	optional
address_state:	optional
address_zip:	optional
address_country:	required Must be a 2 letter country short-name code (ISO 3166). Does not accept `US`, `PR`, `FM`, `GU`, `MH`, `MP`, `PW`, or `VI`. For these addresses, please use the US verification API.

Returns

Returns the validated address object. If there is only a partial match and more information is required (e.g. Apt#, etc), a message string with more information will also be returned.

Example Definition

POST https://api.lob.com/v1/intl_verifications

Example Request


curl https://api.lob.com/v1/intl_verifications \
  -u : \
  -d "address_line1=370 Water St" \
  -d "address_city=Summerside" \
  -d "address_state=Prince Edward Island" \
  -d "address_zip=C1N 1C4" \
  -d "address_country=CA"

Example Response


{
  "address": {
    "address_line1": "370 WATER ST",
    "address_line2": "",
    "address_city": "SUMMERSIDE",
    "address_state": "PE",
    "address_zip": "C1N 1C4",
    "address_country": "CA",
    "object": "address"
  }
}

Postcards

The postcards endpoint allows you to easily print and mail postcards. The postcard front must be supplied as a PDF, image, or an HTML string. The back can be a PDF, image, HTML string, or it can be automatically generated by supplying a custom message. The API provides endpoints for creating postcards, retrieving individual postcards, and retrieving a list of postcards.

The postcard object

Fields

id:	string Unique identifier prefixed with `psc_`.
description:	string or null
metadata:	object
to:	an address object
from:	an address object or null
message:	string or null
url:	string A signed S3 link to the rendered postcard.
front_template_id:	string or null The unique ID of the HTML template used for the front of the postcard.
back_template_id:	string or null The unique ID of the HTML template used for the back of the postcard.
front_template_version_id:	string or null The unique ID of the specific version of the HTML template used for the front of the postcard.
back_template_version_id:	string or null The unique ID of the specific version of the HTML template used for the back of the postcard.
carrier:	string Value is `USPS`.
tracking_events:	array An array of tracking_event objects. Will not be populated for postcards created in test mode.
thumbnails:	array Signed S3 links to different sized thumbnails of each postcard page.
size:	string Value is `4x6`, `6x9`, or `6x11`.
mail_type:	string Value is `usps_first_class`.
expected_delivery_date:	string A date in ISO 8601 format of the postcard's expected delivery date.
date_created:	string A timestamp in ISO 8601 format of the date the postcard was created.
date_modified:	string A timestamp in ISO 8601 format of the date the postcard was last modified.
send_date:	string Only returned if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. A timestamp in ISO 8601 format of the date the postcard was scheduled to begin processing. `send_date` will either be equal to or later than `date_created`. If the `send_date` of a postcard has passed, it can no longer be canceled. To activate this feature, please contact support.
object:	string Value is `postcard`.

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_fa533435bce2d94d",
    "description": null,
    "metadata": {},
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.808Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_0654fd1038e46eac",
    "description": null,
    "metadata": {},
    "name": "Ami Wang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Avenue",
    "address_line2": null,
    "address_city": "Seattle",
    "address_state": "WA",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.821Z",
    "deleted": true,
    "object": "address"
  },
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "front_template_id": null,
  "back_template_id": null,
  "front_template_version_id": null,
  "back_template_version_id": null,
  "carrier": "USPS",
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    },
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "size": "4x6",
  "mail_type": "usps_first_class",
  "expected_delivery_date": "2015-05-06",
  "date_created": "2015-04-27T19:01:11.355Z",
  "date_modified": "2015-04-27T19:01:11.427Z",
  "send_date": "2015-04-27T19:01:11.355Z",
  "object": "postcard"
}

Create a postcard

Create a new postcard.

Arguments

description:	optional
to:	required Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.
from:	optional Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.
front:	required The artwork to use as the front of your postcard. This can be passed as an HTML string, a saved HTML template ID, or a remote URL or direct upload of a PDF, PNG, or JPEG file. PDF, PNG, and JPEGs 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`. For HTML examples, please see Postcard Examples Appendix.
back:	optional Either `message` or `back` is required, choose one. The artwork to use as the back of your postcard. This can be passed as an HTML string, a saved HTML template ID, or a remote URL or direct upload of a PDF, PNG, or JPEG file. PDF, PNG, and JPEGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to the specified `size`. Be sure to leave room for address and postage information by following the templates provided here: 4x6 template, 6x9 template, 6x11 template. For HTML examples, please see Postcard Examples Appendix.
data:	optional Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: `{{variable_name}}`.
message:	optional Either `message` or `back` is required, choose one. Max of 350 characters to be included on the back of postcard. If included, we will generate the back based off to, from, and message arguments.
size:	optional Specifies the size of the postcard. Must be either `4x6`, `6x9`, or `6x11`. Defaults to `4x6`. Only `4x6` postcards can be sent to international destinations.
mail_type:	optional A string designating the mail postage type. Defaults to `usps_first_class`. To activate other options, please contact support.
send_date:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. `send_date` accepts a timestamp in ISO-8601 format which specifies a date up to 90 days in the future to send the postcard for processing. To activate this feature, please contact support.
metadata:	optional Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. See Metadata for more information.

Returns

Returns a postcard object upon successful creation.

Example Definition

POST https://api.lob.com/v1/postcards

Example Request with HTML strings


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Postcard job" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=123 Test Street" \
  -d "to[address_city]=Mountain View" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94041" \
  -d "to[address_country]=US" \
  -d "from[name]=Harry Zhang" \
  -d "from[address_line1]=123 Test Avenue" \
  -d "from[address_city]=Seattle" \
  -d "from[address_state]=WA" \
  -d "from[address_zip]=94041" \
  -d "from[address_country]=US" \
  --data-urlencode "front=<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>" \
  --data-urlencode "back=<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>" \
  -d "data[name]=Harry"

Example Request with saved HTML templates


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Postcard job" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=123 Test Street" \
  -d "to[address_city]=Mountain View" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94041" \
  -d "to[address_country]=US" \
  -d "from[name]=Harry Zhang" \
  -d "from[address_line1]=123 Test Avenue" \
  -d "from[address_city]=Seattle" \
  -d "from[address_state]=WA" \
  -d "from[address_zip]=94041" \
  -d "from[address_country]=US" \
  -d "front=tmpl_b846a20859ae11a" \
  -d "back=tmpl_01b0d396a10c268" \
  -d "data[name]=Harry"

Example Request with Remote Files


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Postcard job" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=123 Test Street" \
  -d "to[address_city]=Mountain View" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94041" \
  -d "to[address_country]=US" \
  -d "from[name]=Ami Wang" \
  -d "from[address_line1]=123 Test Avenue" \
  -d "from[address_city]=Seattle" \
  -d "from[address_state]=WA" \
  -d "from[address_zip]=94041" \
  -d "from[address_country]=US" \
  --data-urlencode "front=https://lob.com/postcardfront.pdf" \
  --data-urlencode "back=https://lob.com/postcardback.pdf"

Example Request with Local Files


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -F "description=Demo Postcard job" \
  -F "to[name]=Harry Zhang" \
  -F "to[address_line1]=123 Test Street" \
  -F "to[address_city]=Mountain View" \
  -F "to[address_state]=CA" \
  -F "to[address_zip]=94041" \
  -F "to[address_country]=US" \
  -F "from[name]=Ami Wang" \
  -F "from[address_line1]=123 Test Avenue" \
  -F "from[address_city]=Seattle" \
  -F "from[address_state]=WA" \
  -F "from[address_zip]=94041" \
  -F "from[address_country]=US" \
  -F "front=@path/to/your/front.pdf" \
  -F "back=@path/to/your/back.pdf"

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_fa533435bce2d94d",
    "description": null,
    "metadata": {},
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.808Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_0654fd1038e46eac",
    "description": null,
    "metadata": {},
    "name": "Ami Wang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Avenue",
    "address_line2": null,
    "address_city": "Seattle",
    "address_state": "WA",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.821Z",
    "deleted": true,
    "object": "address"
  },
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "front_template_id": null,
  "back_template_id": null,
  "front_template_version_id": null,
  "back_template_version_id": null,
  "carrier": "USPS",
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    },
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "size": "4x6",
  "mail_type": "usps_first_class",
  "expected_delivery_date": "2015-05-06",
  "date_created": "2015-04-27T19:01:11.355Z",
  "date_modified": "2015-04-27T19:01:11.427Z",
  "send_date": "2015-04-27T19:01:11.355Z",
  "object": "postcard"
}

Retrieve a postcard

Retrieves the postcard with a given ID. You need only supply the unique postcard ID that was returned upon postcard creation.

Arguments

id:	required The identifier of the postcard to be retrieved.

Returns

Returns a postcard object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/postcards/{id}

Example Request


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

Example Response


{
  "id": "psc_5c002b86ce47537a",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_8f1e724f58792fce",
    "description": null,
    "metadata": {},
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2013-07-20T06:01:30.000Z",
    "date_modified": "2013-07-20T06:01:30.000Z",
    "object": "address"
  },
  "from": null,
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_5c002b86ce47537a.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "carrier": "USPS",
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_5c002b86ce47537a_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_5c002b86ce47537a_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_5c002b86ce47537a_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    },
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_5c002b86ce47537a_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_5c002b86ce47537a_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_5c002b86ce47537a_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "size": "4x6",
  "mail_type": "usps_first_class",
  "date_created": "2013-07-20T06:01:30.000Z",
  "date_modified": "2013-07-20T06:01:30.000Z",
  "send_date": "2013-07-20T06:01:30.000Z",
  "expected_delivery_date": "2013-07-30",
  "object": "postcard"
}

List all postcards

Returns a list of postcards. The returned postcards are sorted by creation date, with the most recently created postcards appearing first.

Arguments

offset:	optional Return requested # of items starting with the value, default=0, must be an integer
limit:	optional How many results to return, default=10, max 100, must be an integer
include:	optional Request that the response include the total count by specifying include[]=total_count.
metadata:	optional Filter by metadata key-value pair, e.g. `metadata[customer_id]=987654`
date_created:	optional 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 ≤
size:	optional The postcard sizes to be returned. Must be a non-empty string array of sizes. Acceptable values are `4x6`, `6x9`, and `6x11`.
scheduled:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Set `scheduled` to `true` to only return orders (past or future) that were scheduled. Set `scheduled` to `false` to only return orders that were not scheduled. To activate this feature, please contact support.
send_date:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Filter by postcards' `send_date` instead of by `date_created`. Accepts ISO-8601 dates or datetimes, e.g. `{ gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' }` where `gt` is ›, `lt` is ‹, `gte` is ≥, and `lte` is ≤. To activate this feature, please contact support.
sort_by:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Sorts postcards by `send_date` in a desired order. `sort_by` accepts an object with the key being `send_date` and the value being either `asc` or `desc`. To activate this feature, please contact support.

Returns

A dictionary with a data property that contains an array of up to limit postcards, starting at index offset. Each entry in the array is a separate postcard object. If no more postcards are available, the resulting array will be empty.

Example Definition

GET https://api.lob.com/v1/postcards

Example Request


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

Example Response


{
  "data": [
    {
      "id": "psc_2a379c909c5d6341",
      "description": "Demo Postcard Job",
      "metadata": {},
      "to": {
        "id": "adr_ca878b465496f4d4",
        "description": null,
        "metadata": {},
        "name": "Harry Zhang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "CA",
        "address_zip": "94041",
        "address_country": "United States",
        "date_created": "2015-04-27T19:02:19.713Z",
        "date_modified": "2015-04-27T19:02:19.728Z",
        "deleted": true,
        "object": "address"
      },
      "from": null,
      "message": null,
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_2a379c909c5d6341.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_2a379c909c5d6341_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_2a379c909c5d6341_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_2a379c909c5d6341_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        },
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_2a379c909c5d6341_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_2a379c909c5d6341_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_2a379c909c5d6341_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        }
      ],
      "size": "4x6",
      "mail_type": "usps_first_class",
      "date_created": "2015-04-27T19:02:21.594Z",
      "date_modified": "2015-04-27T19:02:23.177Z",
      "send_date": "2015-04-27T19:02:21.594Z",
      "expected_delivery_date": "2015-04-27",
      "object": "postcard"
    },
    {
      "id": "psc_66a94c0e4b004efd",
      "description": "Demo Postcard Job",
      "metadata": {},
      "to": {
        "id": "adr_2f69b2be7198ef2e",
        "description": null,
        "metadata": {},
        "name": "Harry Zhang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "CA",
        "address_zip": "94041",
        "address_country": "United States",
        "date_created": "2015-04-27T19:01:48.047Z",
        "date_modified": "2015-04-27T19:01:48.074Z",
        "deleted": true,
        "object": "address"
      },
      "from": null,
      "message": null,
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_66a94c0e4b004efd.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_66a94c0e4b004efd_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_66a94c0e4b004efd_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_66a94c0e4b004efd_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        },
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_66a94c0e4b004efd_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_66a94c0e4b004efd_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_66a94c0e4b004efd_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        }
      ],
      "size": "4x6",
      "mail_type": "usps_first_class",
      "date_created": "2015-04-27T19:01:49.810Z",
      "date_modified": "2015-04-27T19:02:29.950Z",
      "send_date": "2015-04-27T19:01:49.810Z",
      "expected_delivery_date": "2015-04-27",
      "object": "postcard"
    }
  ],
  "count": 2,
  "object": "list"
}

Letters

The letters endpoint allows you to easily print and mail letters. The letter file must be supplied as a PDF or an HTML string. The API provides endpoints for creating letters, retrieving individual letters, and retrieving a list of letters.

The letter object

Fields

id:	string Unique identifier prefixed with `ltr_`.
description:	string or null
metadata:	object
to:	an address object
from:	an address object
color:	boolean
double_sided:	boolean
address_placement:	string Value is `top_first_page` or `insert_blank_page`.
return_envelope:	boolean
perforated_page:	integer or null
extra_service:	string or null Value is `certified` or `registered`.
mail_type:	string Value is `usps_first_class`.
url:	string A signed S3 link to the rendered letter.
template_id:	string or null The unique ID of the HTML template used for the letter.
template_version_id:	string or null The unique ID of the specific version of the HTML template used for the letter.
carrier:	string Value is `USPS`.
tracking_number:	string or null If the letter is being sent as `certified` or `registered`, a tracking number will appear here when it becomes available. Will not be populated for letters created in test mode.
tracking_events:	array An array of tracking_event objects. Will not be populated when `extra_service` is `certified` or `registered`, a `tracking_number` will be returned instead. Will not be populated for letters created in test mode.
thumbnails:	array Signed S3 links to different sized thumbnails of each letter page.
expected_delivery_date:	string A date in ISO 8601 format of the letter's expected delivery date.
date_created:	string A timestamp in ISO 8601 format of the date the letter was created.
date_modified:	string A timestamp in ISO 8601 format of the date the letter was last modified.
send_date:	string Only returned if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. A timestamp in ISO 8601 format of the date the letter was scheduled to begin processing. `send_date` will either be equal to or later than `date_created`. If the `send_date` of a letter has passed, it can no longer be canceled. To activate this feature, please contact support.
object:	string Value is `letter`.

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_8bad937e10c42730",
    "description": null,
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-04-27T21:06:05.013Z",
    "date_modified": "2015-04-27T21:06:05.013Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_76e48bf412848b2a",
    "description": null,
    "name": "Ami Wang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Avenue",
    "address_line2": null,
    "address_city": "Seattle",
    "address_state": "WA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-04-27T21:06:05.038Z",
    "date_modified": "2015-04-27T21:06:05.038Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "extra_service": null,
  "mail_type": "usps_first_class",
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "template_id": null,
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "expected_delivery_date": "2015-05-05",
  "date_created": "2015-04-27T21:06:06.824Z",
  "date_modified": "2015-04-27T21:06:06.824Z",
  "send_date": "2015-04-27T21:06:06.824Z",
  "object": "letter"
}

Create a letter

Create a new letter.

Arguments

description:	optional
to:	required Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.
from:	required Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.
color:	required Boolean. Set this key to true to if you would like to print in color. Set to false if you would like to print in black and white.
file:	required Can be an HTML string, a saved HTML template ID, or an 8.5"x11" PDF (uploaded file or URL). For design specifications, please see our PDF and HTML templates. 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. See pricing for extra costs incurred. 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.
data:	optional Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: `{{variable_name}}`.
double_sided:	optional Boolean that defaults to true. Use false to force single-sided printing.
address_placement:	optional Specifies the location of the address information that will show through the double-window envelope. Options are `top_first_page` and `insert_blank_page`. Defaults to `top_first_page`, meaning we will print address information at the top of your provided first page. To see how this will impact your letter design, view our letter template. If you pass `insert_blank_page`, a blank address page will be inserted at the beginning of your file and you will be charged for the extra page.
return_envelope:	optional Boolean. Set this key to true and specify the `perforated_page` if you would like to include a return envelope with your letter. See pricing for extra costs incurred.
perforated_page:	optional Required if `return_envelope` is true. Number of the page that should be perforated for use with `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.
mail_type:	optional A string designating the mail postage type. Defaults to `usps_first_class`. To activate other options, please contact support.
extra_service:	optional Add an extra service to your letter. Options are `certified` or `registered`. Certified provides tracking and delivery confirmation for domestic destinations. Registered provides tracking and confirmation for international addresses. See pricing for extra costs incurred.
send_date:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. `send_date` accepts a timestamp in ISO-8601 format which specifies a date up to 90 days in the future to send the letter for processing. To activate this feature, please contact support.
metadata:	optional Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. See Metadata for more information.

Returns

Returns a letter object upon successful creation.

Example Definition

POST https://api.lob.com/v1/letters

Example Request with an HTML string


  curl https://api.lob.com/v1/letters \
    -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
    -d "description=Demo Letter" \
    -d "to[name]=Harry Zhang" \
    -d "to[address_line1]=123 Test Street" \
    -d "to[address_city]=Mountain View" \
    -d "to[address_state]=CA" \
    -d "to[address_zip]=94041" \
    -d "to[address_country]=US" \
    -d "from[name]=Ami Wang" \
    -d "from[address_line1]=123 Test Avenue" \
    -d "from[address_city]=Seattle" \
    -d "from[address_state]=WA" \
    -d "from[address_zip]=94041" \
    -d "from[address_country]=US" \
    --data-urlencode "file=<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>" \
    -d "data[name]=Harry" \
    -d "color=true"

Example Request with a saved HTML template


  curl https://api.lob.com/v1/letters \
    -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
    -d "description=Demo Letter" \
    -d "to[name]=Harry Zhang" \
    -d "to[address_line1]=123 Test Street" \
    -d "to[address_city]=Mountain View" \
    -d "to[address_state]=CA" \
    -d "to[address_zip]=94041" \
    -d "to[address_country]=US" \
    -d "from[name]=Ami Wang" \
    -d "from[address_line1]=123 Test Avenue" \
    -d "from[address_city]=Seattle" \
    -d "from[address_state]=WA" \
    -d "from[address_zip]=94041" \
    -d "from[address_country]=US" \
    -d "file=tmpl_cf5068f529da670" \
    -d "data[name]=Harry" \
    -d "color=true"

Example Request with Remote File


curl https://api.lob.com/v1/letters \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Letter" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=123 Test Street" \
  -d "to[address_city]=Mountain View" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94041" \
  -d "to[address_country]=US" \
  -d "from[name]=Ami Wang" \
  -d "from[address_line1]=123 Test Avenue" \
  -d "from[address_city]=Seattle" \
  -d "from[address_state]=WA" \
  -d "from[address_zip]=94041" \
  -d "from[address_country]=US" \
  --data-urlencode "file=https://s3-us-west-2.amazonaws.com/lob-assets/letter-goblue.pdf" \
  -d "color=true"

Example Request with Local File


curl https://api.lob.com/v1/letters \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -F "description=Demo Letter" \
  -F "to[name]=Harry Zhang" \
  -F "to[address_line1]=123 Test Street" \
  -F "to[address_city]=Mountain View" \
  -F "to[address_state]=CA" \
  -F "to[address_zip]=94041" \
  -F "to[address_country]=US" \
  -F "from[name]=Ami Wang" \
  -F "from[address_line1]=123 Test Avenue" \
  -F "from[address_city]=Seattle" \
  -F "from[address_state]=WA" \
  -F "from[address_zip]=94041" \
  -F "from[address_country]=US" \
  -F "file=@path/to/your/letter.pdf" \
  -F "color=true"

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_8bad937e10c42730",
    "description": null,
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-04-27T21:06:05.013Z",
    "date_modified": "2015-04-27T21:06:05.013Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_76e48bf412848b2a",
    "description": null,
    "name": "Ami Wang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Avenue",
    "address_line2": null,
    "address_city": "Seattle",
    "address_state": "WA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-04-27T21:06:05.038Z",
    "date_modified": "2015-04-27T21:06:05.038Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "extra_service": null,
  "mail_type": "usps_first_class",
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "template_id": null,
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "expected_delivery_date": "2015-05-05",
  "date_created": "2015-04-27T21:06:06.824Z",
  "date_modified": "2015-04-27T21:06:06.824Z",
  "send_date": "2015-04-27T21:06:06.824Z",
  "object": "letter"
}

Retrieve a letter

Retrieves the letter with a given ID. You need only supply the unique letter ID that was returned upon letter creation.

Arguments

id:	required The identifier of the letter to be retrieved.

Returns

Returns a letter object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/letters/{id}

Example Request


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

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_8bad937e10c42730",
    "description": null,
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-04-27T21:06:05.013Z",
    "date_modified": "2015-04-27T21:06:05.013Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_76e48bf412848b2a",
    "description": null,
    "name": "Ami Wang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Avenue",
    "address_line2": null,
    "address_city": "Seattle",
    "address_state": "WA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-04-27T21:06:05.038Z",
    "date_modified": "2015-04-27T21:06:05.038Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "extra_service": null,
  "mail_type": "usps_first_class",
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_4868c3b754655f90_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "expected_delivery_date": "2015-05-05",
  "date_created": "2015-04-27T21:06:06.824Z",
  "date_modified": "2015-04-27T21:06:06.824Z",
  "send_date": "2015-04-27T21:06:06.824Z",
  "object": "letter"
}

List all letters

Returns a list of letters. The letters are returned sorted by creation date, with the most recently created letters appearing first.

Arguments

offset:	optional Return requested # of items starting with the value, default=0, must be an integer
limit:	optional How many results to return, default=10, max 100, must be an integer
include:	optional Request that the response include the total count by specifying include[]=total_count.
metadata:	optional Filter by metadata key-value pair, e.g. `metadata[customer_id]=987654`
date_created:	optional 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 ≤
scheduled:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Set `scheduled` to `true` to only return orders (past or future) that were scheduled. Set `scheduled` to `false` to only return orders that were not scheduled. To activate this feature, please contact support.
send_date:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Filter by postcards' `send_date` instead of by `date_created`. Accepts ISO-8601 dates or datetimes, e.g. `{ gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' }` where `gt` is ›, `lt` is ‹, `gte` is ≥, and `lte` is ≤. To activate this feature, please contact support.
sort_by:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Sorts postcards by `send_date` in a desired order. `sort_by` accepts an object with the key being `send_date` and the value being either `asc` or `desc`. To activate this feature, please contact support.

Returns

A object with a data property that contains an array of up to limit letters, starting at index offset. Each entry in the array is a separate letter object. If no more letters are available, the resulting array will be empty.

Example Definition

GET https://api.lob.com/v1/letters

Example Request


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

Example Response


{
  "data": [
    {
      "id": "ltr_b6bfe21858208b46",
      "description": "Demo Letter",
      "metadata": {},
      "to": {
        "id": "adr_d1a4f3b35e673847",
        "description": null,
        "name": "Harry Zhang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "CA",
        "address_zip": "94041",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2015-04-27T21:21:27.733Z",
        "date_modified": "2015-04-27T21:21:27.733Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_53b1305608e0a99e",
        "description": null,
        "name": "Ami Wang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Avenue",
        "address_line2": null,
        "address_city": "Seattle",
        "address_state": "WA",
        "address_zip": "94041",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2015-04-27T21:21:27.794Z",
        "date_modified": "2015-04-27T21:21:27.794Z",
        "deleted": true,
        "object": "address"
      },
      "color": true,
      "double_sided": true,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "extra_service": null,
      "mail_type": "usps_first_class",
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_b6bfe21858208b46.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_b6bfe21858208b46_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_b6bfe21858208b46_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_b6bfe21858208b46_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        }
      ],
      "expected_delivery_date": "2015-05-05",
      "date_created": "2015-04-27T21:21:29.948Z",
      "date_modified": "2015-04-27T21:21:33.243Z",
      "send_date": "2015-04-27T21:21:29.948Z",
      "object": "letter"
    },
    {
      "id": "ltr_8ea22b5354337084",
      "description": "Demo Letter 2",
      "metadata": {},
      "to": {
        "id": "adr_7a595d3e436e6237",
        "description": null,
        "name": "Harry Zhang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "CA",
        "address_zip": "94041",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2015-04-27T21:15:54.145Z",
        "date_modified": "2015-04-27T21:15:54.145Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_51b2a083f9091da3",
        "description": null,
        "name": "Ami Wang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Avenue",
        "address_line2": null,
        "address_city": "Seattle",
        "address_state": "WA",
        "address_zip": "94041",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2015-04-27T21:15:54.151Z",
        "date_modified": "2015-04-27T21:15:54.151Z",
        "deleted": true,
        "object": "address"
      },
      "color": true,
      "double_sided": true,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "extra_service": null,
      "mail_type": "usps_first_class",
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_8ea22b5354337084.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_8ea22b5354337084_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_8ea22b5354337084_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/ltr_8ea22b5354337084_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        }
      ],
      "expected_delivery_date": "2015-05-05",
      "date_created": "2015-04-27T21:15:55.902Z",
      "date_modified": "2015-04-27T21:17:26.066Z",
      "send_date": "2015-04-27T21:15:55.902Z",
      "object": "letter"
    }
  ],
  "count": 2,
  "object": "list"
}

Checks

Checks allow you to send payments via physical checks. The API allows you to create and send checks. You can retrieve individual checks as well as a list of all your checks.

The check object

Fields

id:	string Unique identifier prefixed with `chk_`.
description:	string or null
metadata:	object
check_number:	integer
memo:	string or null
amount:	decimal
message:	string or null
url:	string A signed S3 link to the rendered check.
check_bottom_template_id:	string or null The unique ID of the HTML template used for the check bottom.
attachment_template_id:	string or null The unique ID of the HTML template used for the attachment.
check_bottom_template_version_id:	string or null The unique ID of the specific version of the HTML template used for the check bottom.
attachment_template_version_id:	string or null The unique ID of the specific version of the HTML template used for the attachment.
to:	an address object
from:	an address object
bank_account:	a bank account object
carrier:	string Value is `USPS` normally and `UPS` when `mail_type` is `ups_next_day_air`.
tracking_number:	string or null If the check is being sent as `ups_next_day_air`, a tracking number will appear here when it becomes available. Will not be populated for checks created in test mode.
tracking_events:	array An array of tracking_event objects. Will not be populated when `mail_type` is `ups_next_day_air`, a `tracking_number` will be returned instead. Will not be populated for checks created in test mode.
thumbnails:	array Signed S3 links to different sized thumbnails of each check page.
expected_delivery_date:	string A date in ISO 8601 format of the check's expected delivery date.
mail_type:	string Value is `usps_first_class` or `ups_next_day_air`.
date_created:	string A timestamp in ISO 8601 format of the date the check was created.
date_modified:	string A timestamp in ISO 8601 format of the date the check was last modified.
send_date:	string Only returned if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. A timestamp in ISO 8601 format of the date the check was scheduled to begin processing. `send_date` will either be equal to or later than `date_created`. If the `send_date` of a check has passed, it can no longer be canceled. To activate this feature, please contact support.
object:	string Value is `check`.

Example Response


{
  "id": "chk_534f10783683daa0",
  "description": "Demo Check",
  "metadata": {},
  "check_number": 10062,
  "memo": "rent",
  "amount": 22.50,
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "check_bottom_template_id": null,
  "attachment_template_id": null,
  "check_bottom_template_version_id": null,
  "attachment_template_version_id": null,
  "to": {
    "id": "adr_f3fa41cd6cb2a875",
    "description": null,
    "name": "Harry Zhang",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-11-06T19:33:47.916Z",
    "date_modified": "2015-11-06T19:33:47.916Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_eae4448bb64c07f0",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 TEST STREET.",
    "address_line2": "APT 155",
    "address_city": "SUNNYVALE",
    "address_state": "CA",
    "address_zip": "94085",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2013-10-06T01:03:56.000Z",
    "date_modified": "2013-10-06T01:03:56.000Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=LZYvWt8grRdKyiijyok9Gv52jUA%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=X1r1Om96m53mUcudK%2FkxwWk2TBU%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=omhZpV4oQMAzVPtrRhaFUIh6PuE%3D"
    }
  ],
  "expected_delivery_date": "2015-11-17",
  "mail_type": "usps_first_class",
  "date_created": "2015-11-06T19:33:48.143Z",
  "date_modified": "2015-11-06T19:33:48.143Z",
  "send_date": "2015-11-06T19:33:48.143Z",
  "object": "check"
}

Create a check

Create a new check.

Arguments

description:	optional
to:	required Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.
from:	required Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.
bank_account:	required Must be a bank account ID. Only verified bank accounts may be used.
amount:	required The payment amount to be sent in dollars. Must be less than `1000000`.
memo:	optional Max of 40 characters to be included on the memo line of the check.
check_number:	optional Checks will default starting at 10000 and increment accordingly.
logo:	optional This can be a URL or local file. The image must be a square, have color model of RGB or CMYK, be at least 100px X 100px, and have a transparent background. The accepted file types are PNG and JPEG. If supplied, the logo is printed in grayscale and placed in the upper-left corner of the check.
message:	optional Either `message` or `check_bottom`, choose one. Max of 400 characters to be included at the bottom of the check page.
check_bottom:	optional Either `message` or `check_bottom`, choose one. The artwork to use on the bottom of the check page. This can be passed as an HTML string, a saved HTML template ID, or a remote URL or direct upload of a 1 page PDF, PNG, or JPEG file. PDF, PNG, and JPEGs 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. You must follow this template.
attachment:	optional A document to include with the check. This can be passed as an HTML string, a saved HTML template ID, or a remote URL or direct upload of a PDF, PNG, or JPEG file. All pages of PDF, PNG, and JPEGs 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. 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.
data:	optional Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: `{{variable_name}}`.
mail_type:	optional A string designating the mail postage type. Options are `usps_first_class` or `ups_next_day_air`. Defaults to `usps_first_class`. Passing `ups_next_day_air` will create an overnight check, which is guaranteed to reach its recipient by the next business day if the API request is sent in before 10AM PT. `ups_next_day_air` can only be sent to US destinations with non-PO Box addresses. See pricing for extra costs incurred for `ups_next_day_air`.
send_date:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. `send_date` accepts a timestamp in ISO-8601 format which specifies a date up to 90 days in the future to send the check for processing. To activate this feature, please contact support.
metadata:	optional Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. See Metadata for more information.

Returns

Returns a check object upon successful creation.

Example Definition

POST https://api.lob.com/v1/checks

Example Request with HTML string


curl https://api.lob.com/v1/checks \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Check" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=123 Test Street" \
  -d "to[address_city]=Mountain View" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94041" \
  -d "to[address_country]=US" \
  -d "from=adr_eae4448bb64c07f0" \
  -d "bank_account=bank_8cad8df5354d33f" \
  -d "amount=22.50" \
  -d "memo=rent" \
  --data-urlencode "logo=https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png" \
  --data-urlencode "check_bottom=<h1 style='padding-top:4in;'>Demo Check for {{name}}</h1>" \
  -d "data[name]=Harry"

Example Request with saved HTML template


curl https://api.lob.com/v1/checks \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Check" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=123 Test Street" \
  -d "to[address_city]=Mountain View" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94041" \
  -d "to[address_country]=US" \
  -d "from=adr_eae4448bb64c07f0" \
  -d "bank_account=bank_8cad8df5354d33f" \
  -d "amount=22.50" \
  -d "memo=rent" \
  -d "logo=https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png" \
  -d "check_bottom=tmpl_23668b406d5afef" \
  -d "data[name]=Harry"

Example Request with Remote Files


curl https://api.lob.com/v1/checks \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Check" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=123 Test Street" \
  -d "to[address_city]=Mountain View" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94041" \
  -d "to[address_country]=US" \
  -d "from=adr_eae4448bb64c07f0" \
  -d "bank_account=bank_8cad8df5354d33f" \
  -d "amount=22.50" \
  -d "memo=rent" \
  --data-urlencode "logo=https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png" \
  --data-urlencode "check_bottom=https://s3-us-west-2.amazonaws.com/lob-assets/check-file-example.pdf"

Example Request with Local Files


curl https://api.lob.com/v1/checks \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -F "description=Demo Check" \
  -F "to[name]=Harry Zhang" \
  -F "to[address_line1]=123 Test Street" \
  -F "to[address_city]=Mountain View" \
  -F "to[address_state]=CA" \
  -F "to[address_zip]=94041" \
  -F "to[address_country]=US" \
  -F "from=adr_eae4448bb64c07f0" \
  -F "bank_account=bank_8cad8df5354d33f" \
  -F "amount=22.50" \
  -F "memo=rent" \
  -F "logo=@path/to/your/logo.png" \
  -F "check_bottom=@path/to/your/file.pdf"

Example Response


{
  "id": "chk_534f10783683daa0",
  "description": "Demo Check",
  "metadata": {},
  "check_number": 10062,
  "memo": "rent",
  "amount": 22.50,
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "check_bottom_template_id": null,
  "attachment_template_id": null,
  "check_bottom_template_version_id": null,
  "attachment_template_version_id": null,
  "to": {
    "id": "adr_f3fa41cd6cb2a875",
    "description": null,
    "name": "Harry Zhang",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-11-06T19:33:47.916Z",
    "date_modified": "2015-11-06T19:33:47.916Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_eae4448bb64c07f0",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 TEST STREET.",
    "address_line2": "APT 155",
    "address_city": "SUNNYVALE",
    "address_state": "CA",
    "address_zip": "94085",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2013-10-06T01:03:56.000Z",
    "date_modified": "2013-10-06T01:03:56.000Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=LZYvWt8grRdKyiijyok9Gv52jUA%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=X1r1Om96m53mUcudK%2FkxwWk2TBU%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=omhZpV4oQMAzVPtrRhaFUIh6PuE%3D"
    }
  ],
  "expected_delivery_date": "2015-11-17",
  "mail_type": "usps_first_class",
  "date_created": "2015-11-06T19:33:48.143Z",
  "date_modified": "2015-11-06T19:33:48.143Z",
  "send_date": "2015-11-06T19:33:48.143Z",
  "object": "check"
}

Retrieve a check

Retrieves the check with a given ID. You need only supply the unique ID that was returned upon check creation.

Arguments

id:	required The identifier of the check to be retrieved.

Returns

Returns a check object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/checks/{id}

Example Request


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

Example Response


{
  "id": "chk_534f10783683daa0",
  "description": "Demo Check",
  "metadata": {},
  "check_number": 10062,
  "memo": "rent",
  "amount": 22.50,
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "to": {
    "id": "adr_f3fa41cd6cb2a875",
    "description": null,
    "name": "Harry Zhang",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "CA",
    "address_zip": "94041",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2015-11-06T19:33:47.916Z",
    "date_modified": "2015-11-06T19:33:47.916Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_eae4448bb64c07f0",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 TEST STREET.",
    "address_line2": "APT 155",
    "address_city": "SUNNYVALE",
    "address_state": "CA",
    "address_zip": "94085",
    "address_country": "United States",
    "metadata": {},
    "date_created": "2013-10-06T01:03:56.000Z",
    "date_modified": "2013-10-06T01:03:56.000Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=LZYvWt8grRdKyiijyok9Gv52jUA%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=X1r1Om96m53mUcudK%2FkxwWk2TBU%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=omhZpV4oQMAzVPtrRhaFUIh6PuE%3D"
    }
  ],
  "expected_delivery_date": "2015-11-17",
  "mail_type": "usps_first_class",
  "date_created": "2015-11-06T19:33:48.143Z",
  "date_modified": "2015-11-06T19:33:48.143Z",
  "send_date": "2015-11-06T19:33:48.143Z",
  "object": "check"
}

List all checks

Returns a list of checks. The returned checks are sorted by creation date, with the most recently created checks appearing first.

Arguments

offset:	optional Return requested # of items starting with the value, default=0, must be an integer
limit:	optional How many results to return, default=10, max 100, must be an integer
include:	optional Request that the response include the total count by specifying include[]=total_count.
metadata:	optional Filter by metadata key-value pair, e.g. `metadata[customer_id]=987654`
scheduled:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Set `scheduled` to `true` to only return orders (past or future) that were scheduled. Set `scheduled` to `false` to only return orders that were not scheduled. To activate this feature, please contact support.
date_created:	optional 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 ≤
send_date:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Filter by postcards' `send_date` instead of by `date_created`. Accepts ISO-8601 dates or datetimes, e.g. `{ gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' }` where `gt` is ›, `lt` is ‹, `gte` is ≥, and `lte` is ≤. To activate this feature, please contact support.
sort_by:	optional Only accepted if you are on a Growth Plan or higher and opted into the Scheduled Sends feature. Sorts postcards by `send_date` in a desired order. `sort_by` accepts an object with the key being `send_date` and the value being either `asc` or `desc`. To activate this feature, please contact support.

Returns

A dictionary with a data property that contains an array of up to limit checks, starting at index offset. Each entry in the array is a separate check object. If no more checks are available, the resulting array will be empty.

Example Definition

GET https://api.lob.com/v1/checks

Example Request


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

Example Response


{
  "data": [
    {
      "id": "chk_fa2d38a6f0ce638e",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 10006,
      "memo": "rent",
      "amount": 2200,
      "message": null,
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_fa2d38a6f0ce638e.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=IPjMermP%2FKwQRRh4x9Z5411Sdik%3D",
      "to": {
        "id": "adr_1673bbd26e2f9b3a",
        "description": null,
        "name": "Harry Zhang",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "CA",
        "address_zip": "94041",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2015-11-09T19:41:52.359Z",
        "date_modified": "2015-11-09T19:41:52.359Z",
        "object": "address"
      },
      "from": {
        "id": "adr_eae4448bb64c07f0",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "123 TEST STREET.",
        "address_line2": "APT 155",
        "address_city": "SUNNYVALE",
        "address_state": "CA",
        "address_zip": "94085",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2013-10-06T01:03:56.000Z",
        "date_modified": "2013-10-06T01:03:56.000Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_8cad8df5354d33f",
        "description": "Test Bank Account",
        "metadata": {},
        "routing_number": "322271627",
        "account_number": "123456789",
        "signatory": "John Doe",
        "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
        "verified": true,
        "account_type": "company",
        "date_created": "2015-11-06T19:24:24.440Z",
        "date_modified": "2015-11-06T19:41:28.312Z",
        "object": "bank_account"
      },
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_fa2d38a6f0ce638e_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=xpZkX2fjPboPoECBEp0gcvDBj3Y%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_fa2d38a6f0ce638e_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=XCEgCdh57KOKfi4pq5gKkPhes2k%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_fa2d38a6f0ce638e_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=Po2e8jzmTMAIoHQaz1MJfYEUE08%3D"
        }
      ],
      "expected_delivery_date": "2015-11-18",
      "mail_type": "usps_first_class",
      "date_created": "2015-11-09T19:41:52.570Z",
      "date_modified": "2015-11-09T19:41:58.722Z",
      "send_date": "2015-11-09T19:41:52.570Z",
      "object": "check"
    },
    {
      "id": "chk_213657231f256688",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 10005,
      "memo": "rent",
      "amount": 2200,
      "message": null,
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_213657231f256688.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=zFqvjvUQtyy8oda5f6iSS%2BiwKMU%3D",
      "to": {
        "id": "adr_9e96cb17341fe076",
        "description": null,
        "name": "Harry Zhang",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "CA",
        "address_zip": "94041",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2015-11-09T19:41:50.670Z",
        "date_modified": "2015-11-09T19:41:50.670Z",
        "object": "address"
      },
      "from": {
        "id": "adr_eae4448bb64c07f0",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "123 TEST STREET.",
        "address_line2": "APT 155",
        "address_city": "SUNNYVALE",
        "address_state": "CA",
        "address_zip": "94085",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2013-10-06T01:03:56.000Z",
        "date_modified": "2013-10-06T01:03:56.000Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_8cad8df5354d33f",
        "description": "Test Bank Account",
        "metadata": {},
        "routing_number": "322271627",
        "account_number": "123456789",
        "signatory": "John Doe",
        "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
        "verified": true,
        "account_type": "company",
        "date_created": "2015-11-06T19:24:24.440Z",
        "date_modified": "2015-11-06T19:41:28.312Z",
        "object": "bank_account"
      },
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_213657231f256688_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=ni0kKsP8SAXo6IbthJMvxOyHSLw%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_213657231f256688_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=tzK2zG2Es%2F32KN8BE1sha%2F9YViA%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_213657231f256688_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=UDR0%2Bx%2FGk4R%2FEsUJG2g%2BDfijTtM%3D"
        }
      ],
      "expected_delivery_date": "2015-11-18",
      "mail_type": "usps_first_class",
      "date_created": "2015-11-09T19:41:50.874Z",
      "date_modified": "2015-11-09T19:41:57.145Z",
      "send_date": "2015-11-09T19:41:50.874Z",
      "object": "check"
    }
  ],
  "count": 2,
  "object": "list"
}

Bank Accounts

Bank Accounts allow you to store your bank account securely in our system. The API allows you to create and delete your accounts. You can retrieve individual accounts as well as a list of all your accounts.

The bank account object

Fields

id:	string Unique identifier prefixed with `bank_`.
description:	string or null
metadata:	object
routing_number:	string
account_number:	string
account_type:	string Value is `company` or `individual`.
signatory:	string
signature_url:	string or null A signed S3 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
date_created:	string A timestamp in ISO 8601 format of the date the bank account was created.
date_modified:	string A timestamp in ISO 8601 format of the date the bank account was last modified.
object:	string Value is `bank_account`.

Example Response


{
  "id": "bank_8cad8df5354d33f",
  "description": "Test Bank Account",
  "metadata": {},
  "routing_number": "322271627",
  "account_number": "123456789",
  "account_type": "company",
  "signatory": "John Doe",
  "signature_url": null,
  "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
  "verified": false,
  "date_created": "2015-11-06T19:24:24.440Z",
  "date_modified": "2015-11-06T19:24:24.440Z",
  "object": "bank_account"
}

Create a bank account

Create a new bank account. 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".

Arguments

description:	optional
routing_number:	required The bank's routing number
account_number:	required The account number at the bank
account_type:	required The type of entity that holds the account. Must be either `company` or `individual`.
signatory:	required The signatory associated with your account. This name will be printed on checks created with the bank account. If you prefer to use a custom signature image on your checks instead, please create your bank account from the Dashboard.
metadata:	optional Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. See Metadata for more information.

Returns

Returns a bank object upon successful creation.

Example Definition

POST https://api.lob.com/v1/bank_accounts

Example Request


curl https://api.lob.com/v1/bank_accounts \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Test Bank Account" \
  -d "routing_number=322271627" \
  -d "account_number=123456789" \
  -d "signatory=John Doe" \
  -d "account_type=company"

Example Response


{
  "id": "bank_8cad8df5354d33f",
  "description": "Test Bank Account",
  "metadata": {},
  "routing_number": "322271627",
  "account_number": "123456789",
  "account_type": "company",
  "signatory": "John Doe",
  "signature_url": null,
  "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
  "verified": false,
  "date_created": "2015-11-06T19:24:24.440Z",
  "date_modified": "2015-11-06T19:24:24.440Z",
  "object": "bank_account"
}

Retrieve a bank account

Retrieves the bank account with a given ID. You need only supply the unique ID that was returned upon bank account creation.

Arguments

id:	required The identifier of the bank account to be retrieved.

Returns

Returns a bank account object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/bank_accounts/{id}

Example Request


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

Example Response


{
  "id": "bank_8cad8df5354d33f",
  "description": "Test Bank Account",
  "metadata": {},
  "routing_number": "322271627",
  "account_number": "123456789",
  "signatory": "John Doe",
  "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
  "verified": false,
  "account_type": "company",
  "date_created": "2015-11-06T19:24:24.440Z",
  "date_modified": "2015-11-06T19:24:24.440Z",
  "object": "bank_account"
}

Delete a bank account

Permanently deletes a bank account. It cannot be undone.

Arguments

id:	required The identifier of the bank account to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

DELETE https://api.lob.com/v1/bank_accounts/{id}

Example Request


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

Example Response


{
  "id": "bank_3e64d9904356b20",
  "deleted": true
}

Verify a bank account

Verify a bank account in order to create a check.

Arguments

amounts:

required

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 - use any two integers between 1 and 100

Returns

Returns a bank account object upon successful verification.

Example Definition

POST https://api.lob.com/v1/bank_accounts/{id}/verify

Example Request


curl https://api.lob.com/v1/bank_accounts/bank_dfceb4a2a05b57e/verify \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "amounts[]=25" \
  -d "amounts[]=63"

Example Response


{
  "id": "bank_dfceb4a2a05b57e",
  "description": null,
  "metadata": {},
  "routing_number": "123456789",
  "account_number": "123456789",
  "signatory": Leore Avidar,
  "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
  "verified": true,
  "account_type": "company",
  "date_created": "2013-10-06T01:03:56.000Z",
  "date_modified": "2013-10-06T01:03:56.000Z",
  "object": "bank_account"
}

List all bank accounts

Returns a list of bank accounts. The bank accounts are returned sorted by creation date, with the most recently created bank account appearing first.

Arguments

offset:	optional Return requested # of items starting with the value, default=0, must be an integer
limit:	optional How many results to return, default=10, max 100, must be an integer
include:	optional Request that the response include the total count by specifying include[]=total_count.
metadata:	optional Filter by metadata key-value pair, e.g. `metadata[customer_id]=987654`
date_created:	optional 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 ≤

Returns

A dictionary with a data property that contains an array of up to limit bank accounts, starting at index offset. Each entry in the array is a separate bank account object. If no more bank accounts are available, the resulting array will be empty.

Example Definition

GET https://api.lob.com/v1/bank_accounts

Example Request


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

Example Response


{
  "data": [
    {
      "id": "bank_c97ccce34e5a800",
      "description": "Test Bank Account 1",
      "metadata": {},
      "routing_number": "322271627",
      "account_number": "123456789",
      "signatory": "John Doe",
      "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
      "verified": false,
      "account_type": "company",
      "date_created": "2015-11-06T19:29:46.077Z",
      "date_modified": "2015-11-06T19:29:46.077Z",
      "object": "bank_account"
    },
    {
      "id": "bank_248262b88971545",
      "description": "Test Bank Account 2",
      "metadata": {},
      "routing_number": "322271627",
      "account_number": "123456789",
      "signatory": "John Doe",
      "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
      "verified": false,
      "account_type": "company",
      "date_created": "2015-11-06T19:24:24.440Z",
      "date_modified": "2015-11-06T19:24:24.440Z",
      "object": "bank_account"
    }
  ],
  "count": 2,
  "object": "list"
}

Areas

Easily send collateral to an entire zip code or specific delivery routes

The area object

Fields

id:	string Unique identifier prefixed with `area_`.
description:	string or null
metadata:	object
price:	decimal Price of the area mailing based on the number of addresses.
url:	string A signed S3 link to the rendered area mail.
target_type:	string Value is `all` or `residential`.
addresses:	integer Number of addresses included in the area mailing based on the `routes` chosen and `target_type`
zip_codes:	array An array of objects with the property `routes`, which is an array of route objects.
thumbnails:	array Signed S3 links to different sized thumbnails of each area mail page.
expected_delivery_date:	string A date in ISO 8601 format of the area mail's expected delivery date.
trackings:	array or null An array of objects with `tracking_number` and `carrier` properties. Each object represents a package that can be tracked using the specified `tracking_number` via the respective carrier's online tool. These objects will appear here as they become available. Will not be populated for areas created in test mode.
date_created:	string A timestamp in ISO 8601 format of the date the area mail was created.
date_modified:	string A timestamp in ISO 8601 format of the date the area mail was last modified.
object:	string Value is `area`.

Example Response


{
  "id": "area_de75bb527080d5f",
  "description": "Test Area",
  "metadata": {},
  "price": "954.57",
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "target_type": "all",
  "addresses": 2031,
  "zip_codes": [
    {
      "zip_code": "94107",
      "routes": [
        {
          "route": "C031",
          "residential": 496,
          "business": 187,
          "object": "route"
        }
      ],
      "object": "zip_code"
    },
    {
      "zip_code": "94158",
      "routes": [
        {
          "route": "C001",
          "residential": 1323,
          "business": 25,
          "object": "route"
        }
      ],
      "object": "zip_code"
    }
  ],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    },
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "expected_delivery_date": "2015-05-07",
  "trackings": [],
  "date_created": "2015-04-27T21:58:31.159Z",
  "date_modified": "2015-04-27T21:58:31.159Z",
  "object": "area"
}

Create an area mailing

Create a new mailing for a specific zip or delivery routes

Arguments

description:	optional
routes:	required Must enter a zip code or delivery route. This can be an array of zip codes or delivery routes.
target_type:	optional A string designating the target recipients. Options are `all` and `residential`. Defaults to `all`.
front:	required A 6.25"x11.25" image that will be the front of the postcard. This can be a URL, local file, or an HTML string. Supported file types are PDF, PNG, and JPEG. For HTML examples, please see Area Examples Appendix.
back:	required A 6.25"x11.25" image that will be the back of the postcard. Follow this template when creating your artwork. This can be a URL, local file, or an HTML string. Supported file types are PDF, PNG, and JPEG. For HTML examples, please see Area Examples Appendix.
data:	optional Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: `{{variable_name}}`.
metadata:	optional Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters `"` and `\`. Nested objects are not supported. See Metadata for more information.

Returns

Returns an area object upon successful creation.

Example Definition

POST https://api.lob.com/v1/areas

Example Request with HTML Front


curl https://api.lob.com/v1/areas \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Test Area" \
  --data-urlencode "front=<h1>Demo Area Mail for {{city}}</h1>" \
  --data-urlencode "back=https://lob.com/areaback.pdf" \
  -d "data[city]=Oakland" \
  -d "routes=94158-C001" \
  -d "routes=94107-C031" \
  -d "target_type=all"

Example Request with Remote Files


curl https://api.lob.com/v1/areas \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Test Area" \
  --data-urlencode "front=https://lob.com/areafront.pdf" \
  --data-urlencode "back=https://lob.com/areaback.pdf" \
  -d "routes=94158-C001" \
  -d "routes=94107-C031" \
  -d "target_type=all"

Example Request with Local Files


curl https://api.lob.com/v1/areas \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -F "description=Test Area" \
  -F "front=@path/to/your/front.pdf" \
  -F "back=@path/to/your/back.pdf" \
  -F "routes=94158-C001" \
  -F "routes=94107-C031" \
  -F "target_type=all"

Example Response


{
  "id": "area_de75bb527080d5f",
  "description": "Test Area",
  "metadata": {},
  "price": "954.57",
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "target_type": "all",
  "addresses": 2031,
  "zip_codes": [
    {
      "zip_code": "94107",
      "routes": [
        {
          "route": "C031",
          "residential": 496,
          "business": 187,
          "object": "route"
        }
      ],
      "object": "zip_code"
    },
    {
      "zip_code": "94158",
      "routes": [
        {
          "route": "C001",
          "residential": 1323,
          "business": 25,
          "object": "route"
        }
      ],
      "object": "zip_code"
    }
  ],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    },
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "expected_delivery_date": "2015-05-07",
  "trackings": [],
  "date_created": "2015-04-27T21:58:31.159Z",
  "date_modified": "2015-04-27T21:58:31.159Z",
  "object": "area"
}

Retrieve an area mailing

Retrieves the area mailing with a given ID. You need only supply the unique ID that was returned upon area mail creation.

Arguments

id:	required The identifier of the area mail to be retrieved.

Returns

Returns an area mail object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/areas/{id}

Example Request


curl https://api.lob.com/v1/areas/area_de75bb527080d5f \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Example Response


{
  "id": "area_de75bb527080d5f",
  "description": "Test Area",
  "metadata": {},
  "price": "954.57",
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "target_type": "all",
  "addresses": 2031,
  "zip_codes": [
    {
      "zip_code": "94107",
      "routes": [
        {
          "route": "C031",
          "residential": 496,
          "business": 187,
          "object": "route"
        }
      ],
      "object": "zip_code"
    },
    {
      "zip_code": "94158",
      "routes": [
        {
          "route": "C001",
          "residential": 1323,
          "business": 25,
          "object": "route"
        }
      ],
      "object": "zip_code"
    }
  ],
  "thumbnails": [
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    },
    {
      "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_de75bb527080d5f_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
    }
  ],
  "expected_delivery_date": "2015-05-07",
  "trackings": [],
  "date_created": "2015-04-27T21:58:31.159Z",
  "date_modified": "2015-04-27T21:58:31.159Z",
  "object": "area"
}

List all area mailings

Returns a list of area mailings. The area mailings are returned sorted by creation date, with the most recently created area mail appearing first.

Arguments

offset:	optional Return requested # of items starting with the value, default=0, must be an integer
limit:	optional How many results to return, default=10, max 100, must be an integer
include:	optional Request that the response include the total count by specifying include[]=total_count
metadata:	optional Filter by metadata key-value pair, e.g. `metadata[customer_id]=987654`
date_created:	optional 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 ≤

Returns

A dictionary with a data property that contains an array of up to limit area mailings, starting at index offset. Each entry in the array is a separate area object. If no more area mailings are available, the resulting array will be empty.

Example Definition

GET https://api.lob.com/v1/areas

Example Request


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

Example Response


{
  "data": [
    {
      "id": "area_ae5edeae8e958a0",
      "description": "Test Area 2",
      "metadata": {},
      "price": "760.72",
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_ae5edeae8e958a0.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "target_type": "residential",
      "addresses": 1323,
      "zip_codes": [
        {
          "zip_code": "94158",
          "routes": [
            {
              "route": "C001",
              "residential": 1323,
              "business": 0,
              "object": "route"
            }
          ],
          "object": "zip_code"
        }
      ],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_ae5edeae8e958a0_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_ae5edeae8e958a0_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_ae5edeae8e958a0_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        },
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_ae5edeae8e958a0_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_ae5edeae8e958a0_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_ae5edeae8e958a0_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        }
      ],
      "expected_delivery_date": "2015-05-07",
      "trackings": [],
      "date_created": "2015-04-27T22:03:01.274Z",
      "date_modified": "2015-04-27T22:03:01.274Z",
      "object": "area"
    },
    {
      "id": "area_2a2b99030e7282f",
      "description": "Test Area",
      "metadata": {},
      "price": "954.57",
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_2a2b99030e7282f.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
      "target_type": "all",
      "addresses": 2031,
      "zip_codes": [
        {
          "zip_code": "94107",
          "routes": [
            {
              "route": "C031",
              "residential": 496,
              "business": 187,
              "object": "route"
            }
          ],
          "object": "zip_code"
        },
        {
          "zip_code": "94158",
          "routes": [
            {
              "route": "C001",
              "residential": 1323,
              "business": 25,
              "object": "route"
            }
          ],
          "object": "zip_code"
        }
      ],
      "thumbnails": [
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_2a2b99030e7282f_thumb_small_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_2a2b99030e7282f_thumb_medium_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_2a2b99030e7282f_thumb_large_1.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        },
        {
          "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_2a2b99030e7282f_thumb_small_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_2a2b99030e7282f_thumb_medium_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
          "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/area_2a2b99030e7282f_thumb_large_2.png?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D"
        }
      ],
      "expected_delivery_date": "2015-05-07",
      "trackings": [],
      "date_created": "2015-04-27T22:01:03.045Z",
      "date_modified": "2015-04-27T22:00:55.824Z",
      "object": "area"
    }
  ],
  "count": 2,
  "object": "list"
}

Routes

The routes endpoint provides detailed information about postal routes, including the number of deliverable addresses and demographic data. This endpoint can be used in conjunction with the Area Mail API to find suitable delivery routes. Note that not all routes have complete demographics data due to inconsistencies in census data.

The route object

Fields

route:	string 1 letter and 3 numbers designating the carrier route.
residential:	integer An integer representing the number of residential addresses in the route.
business:	integer An integer representing the number of business addresses in the route.
median_income:	integer or null An integer representing the median income in dollars of residents in the route (based on 2010 census data). Not returned when nested within area responses.
age_20_24:	integer or null An integer representing the number of residents between ages 20 and 24 in the route (based on 2010 census data). Not returned when nested within area responses.
age_25_34:	integer or null An integer representing the number of residents between ages 25 and 34 in the route (based on 2010 census data). Not returned when nested within area responses.
age_35_44:	integer or null An integer representing the number of residents between ages 35 and 44 in the route (based on 2010 census data). Not returned when nested within area responses.
age_45_54:	integer or null An integer representing the number of residents between ages 45 and 54 in the route (based on 2010 census data). Not returned when nested within area responses.
age_55_64:	integer or null An integer representing the number of residents between ages 55 and 64 in the route (based on 2010 census data). Not returned when nested within area responses.
age_65_74:	integer or null An integer representing the number of residents between ages 65 and 74 in the route (based on 2010 census data). Not returned when nested within area responses.
age_75_84:	integer or null An integer representing the number of residents between ages 75 and 84 in the route (based on 2010 census data). Not returned when nested within area responses.
age_lt_19:	integer or null An integer representing the number of residents younger than 19 in the route (based on 2010 census data). Not returned when nested within area responses.
age_gt_85:	integer or null An integer representing the number of residents older than 85 in the route (based on 2010 census data). Not returned when nested within area responses.
median_age:	integer or null An integer representing the median age of residents in the route (based on 2010 census data). Not returned when nested within area responses.
avg_household_size:	decimal or null A decimal representing the average household size of the route (based on 2010 census data). Not returned when nested within area responses.
object:	string Value is `route`.

Example Response

      
{
  "route": "C002",
  "residential": 1133,
  "business": 26,
  "median_income": 106369,
  "age_20_24": 731,
  "age_25_34": 3205,
  "age_35_44": 1634,
  "age_45_54": 722,
  "age_55_64": 488,
  "age_65_74": 297,
  "age_75_84": 109,
  "age_lt_19": 37,
  "age_gt_85": 708,
  "median_age": 33,
  "avg_household_size": 1.8,
  "object": "route"
}

Retrieve routes for a zip code

Retrieves the delivery routes for the zip code or zip-route requested.

Arguments

zip_code:

required

The zip code or specific zip-route to be retrieved.

Returns

Returns an array of route objects.

Example Definition

GET https://api.lob.com/v1/routes/{zip_code}

Example Request


curl -X GET "https://api.lob.com/v1/routes/94158-C002" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Example Response


{
  "zip_code": "94158",
  "routes": [
    {
      "route": "C002",
      "residential": 1133,
      "business": 26,
      "median_income": 106369,
      "age_20_24": 731,
      "age_25_34": 3205,
      "age_35_44": 1634,
      "age_45_54": 722,
      "age_55_64": 488,
      "age_65_74": 297,
      "age_75_84": 109,
      "age_lt_19": 37,
      "age_gt_85": 708,
      "median_age": 33,
      "avg_household_size": 1.8,
      "object": "route"
    }
  ]
}

List all routes

Filters by the zip codes or zip-routes requested.

Arguments

zip_codes:

required

The zip codes or zip-routes to filter by.

Returns

A dictionary with a data property that contains an array of route objects for all zip codes and routes requested.

Example Definition

GET https://api.lob.com/v1/routes

Example Request


curl -X GET "https://api.lob.com/v1/routes?zip_codes=48168-C016&zip_codes=94158" \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:

Example Response


{
  "data": [
    {
      "zip_code": "48168",
      "routes": [
        {
          "route": "C016",
          "residential": 385,
          "business": 1,
          "median_income": 163863,
          "age_20_24": 188,
          "age_25_34": 256,
          "age_35_44": 869,
          "age_45_54": 1291,
          "age_55_64": 853,
          "age_65_74": 453,
          "age_75_84": 193,
          "age_lt_19": 32,
          "age_gt_85": 1933,
          "median_age": 42,
          "avg_household_size": 2.9,
          "object": "route"
        }
      ]
    },
    {
      "zip_code": "94158",
      "routes": [
        {
          "route": "C002",
          "residential": 1133,
          "business": 26,
          "median_income": 106369,
          "age_20_24": 731,
          "age_25_34": 3205,
          "age_35_44": 1634,
          "age_45_54": 722,
          "age_55_64": 488,
          "age_65_74": 297,
          "age_75_84": 109,
          "age_lt_19": 37,
          "age_gt_85": 708,
          "median_age": 33,
          "avg_household_size": 1.8,
          "object": "route"
        },
        {
          "route": "C003",
          "residential": 1276,
          "business": 89,
          "median_income": 109656,
          "age_20_24": 620,
          "age_25_34": 2736,
          "age_35_44": 1411,
          "age_45_54": 626,
          "age_55_64": 418,
          "age_65_74": 253,
          "age_75_84": 92,
          "age_lt_19": 32,
          "age_gt_85": 605,
          "median_age": 34,
          "avg_household_size": 1.8,
          "object": "route"
        }
      ]
    }
  ],
  "object": "list"
}

Countries

A list of ISO 3166 country codes and names to use for forms and dropdowns.

List all countries

Returns a list of all currently supported countries with their full and short names.

Returns

A dictionary with a data property that contains an array of all countries.

Example Definition

GET https://api.lob.com/v1/countries

Example Request


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

Example Response


{
  "object": "list",
  "data": [
      {
          "id": "1",
          "name": "United States",
          "short_name": "US",
          "object": "country"
      },
      {
          "id": "2",
          "name": "Andorra",
          "short_name": "AD",
          "object": "country"
      },
      {
          "id": "3",
          "name": "United Arab Emirates",
          "short_name": "AE",
          "object": "country"
      },
      {
          "id": "4",
          "name": "Afghanistan",
          "short_name": "AF",
          "object": "country"
      },
      {...}
      ]
}

States

A list of standard US state codes and names to use for forms and dropdowns.

List all states

Returns a list of all US states with their full and short names.

Returns

A dictionary with a data property that contains an array of all states.

Example Definition

GET https://api.lob.com/v1/states

Example Request


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

Example Response


{
  "object": "list",
  "data": [
      {
          "id": "1",
          "name": "Alabama",
          "short_name": "AL",
          "object": "state"
      },
      {
          "id": "2",
          "name": "Alaska",
          "short_name": "AK",
          "object": "state"
      },
  {...}
   ]
}

Changelog

2017-05-17

discontinues the /v1/verify endpoint - please use /v1/us_verifications or /v1/intl_verifications instead

2016-06-30

unnest tracking object from postcard, letter, and check response objects

2016-05-02

adds address_placement parameter to letters that defaults to top_first_page, template is no longer allowed

2016-03-21

removes tracking numbers that do not provide any consumer-facing tracking information
removes link from tracking responses
requires account_type when creating a bank account

2016-01-19

renames the count parameter to limit for all list endpoints
removes the next_url and previous_url from list responses

2015-12-22

adds size parameter to postcards that defaults to 4x6, setting is no longer allowed

2015-11-23

remove price from letters
remove pages from letters
remove price from postcards
renamed file parameter to check_bottom for checks

2015-11-06

remove bank_address from bank_accounts
remove account_address from bank_accounts and add from to checks
remove price from checks

2015-10-21

use the new HTML renderer for all products

2015-06-25

remove the status field from all endpoints

2015-04-11

errors on all endpoints are now single objects instead of arrays
full_bleed is no longer allowed for postcards, objects, and area mails - all products are now full_bleed by default
template is no longer allowed for postcards - all postcards must adhere to the template
name is no longer allowed for area mails, bank accounts, checks, jobs, objects, and postcards - it has been replaced by description
setting ID's 100 and 101 are no longer supported for objects - please use the Simple Letter Service instead
service is no longer supported for jobs
all boolean parameters now return true/false instead of 1/0
double_sided is no longer allowed for objects - all products are default double sided if more than one page is allowed
template is no longer allowed for objects

2014-12-18

removed concept of packaging
signatory is now a required field when creating a bank account
bank_code is no longer an allowed field when creating a bank account
service_id parameter replaced by service parameter in /jobs
setting_id parameter replaced by setting parameter in /objects

The tracking event object

Fields

id:	string Unique identifier prefixed with `evnt_`.
name:	string A string representing what scan event occurred. Possible values are `In Transit`, `In Local Area`, `Processed for Delivery`, `Re-routed`, and `Returned to Sender`. See here for more detailed descriptions of each type of scan event.
location:	string The zip code in which the scan event occurred.
time:	string A timestamp in ISO 8601 format of the date USPS registered the scan event.
date_created:	string A timestamp in ISO 8601 format of the date the tracking event was created.
date_modified:	string A timestamp in ISO 8601 format of the date the tracking event was last modified.
object:	string Value is `tracking_event`.

Example Response

      
{
  "id": "evnt_9e84094c9368cfb",
  "name": "In Local Area",
  "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"
}

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.

The event object

Fields

id:	string Unique identifier prefixed with `evt_`.
body:	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.
reference_id:	string Unique identifier of the related resource for the event.
event_type:	an event type object
date_created:	string A timestamp in ISO 8601 format of the date the event was created.
object:	string Value is `event`.

Example Response


{
  "id": "evt_d95ff8ffd2b5cfb4",
  "body": {
    "id": "psc_d2d10a2e9cba991c",
    "description": "Test Postcard",
    "metadata": {},
    "to": {
      "id": "adr_8e783523dd7f0e70",
      "description": "Test Address",
      "name": "Harry Zhang",
      "address_line1": "123 Test St",
      "address_line2": "Unit 1",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_zip": "94107",
      "address_country": "United States",
      "metadata": {},
      "date_created": "2016-12-04T10:51:51.844Z",
      "date_modified": "2016-12-04T10:51:51.844Z",
      "object": "address"
    },
    "from": {
      "id": "adr_d2e26faf793ed422",
      "description": "Test Address",
      "name": "Harry Zhang",
      "address_line1": "123 Test St",
      "address_line2": "Unit 1",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_zip": "94107",
      "address_country": "United States",
      "metadata": {},
      "date_created": "2016-12-04T10:51:51.845Z",
      "date_modified": "2016-12-04T10:51:51.845Z",
      "object": "address"
    },
    "message": null,
    "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_d2d10a2e9cba991c.pdf?AWSAccessKeyId=AKIAJCFUUY3W2HE7FMBQ&Expires=1483483808&Signature=ZGATcDqwKpeXy%2BWxVg%2B6G2H%2FHNA%3D",
    "carrier": "USPS",
    "tracking_events": [],
    "thumbnails": [
      {
        "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_d2d10a2e9cba991c_thumb_small_1.png?AWSAccessKeyId=AKIAJCFUUY3W2HE7FMBQ&Expires=1483483808&Signature=JN7y64Yig29jX%2FyqbXoteDk4Ocg%3D",
        "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_d2d10a2e9cba991c_thumb_medium_1.png?AWSAccessKeyId=AKIAJCFUUY3W2HE7FMBQ&Expires=1483483808&Signature=U6XL3D77WY%2FeiXV7SUer6%2FV9E3E%3D",
        "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_d2d10a2e9cba991c_thumb_large_1.png?AWSAccessKeyId=AKIAJCFUUY3W2HE7FMBQ&Expires=1483483808&Signature=tteV85IY%2FK5bfR62O0t47QSslv8%3D"
      },
      {
        "small": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_d2d10a2e9cba991c_thumb_small_2.png?AWSAccessKeyId=AKIAJCFUUY3W2HE7FMBQ&Expires=1483483808&Signature=xcTPeTp5Vs0KtEHXLZvuSfdEwho%3D",
        "medium": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_d2d10a2e9cba991c_thumb_medium_2.png?AWSAccessKeyId=AKIAJCFUUY3W2HE7FMBQ&Expires=1483483808&Signature=oiYNgnPotPziX9%2Flq8OhTk9DyUo%3D",
        "large": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_d2d10a2e9cba991c_thumb_large_2.png?AWSAccessKeyId=AKIAJCFUUY3W2HE7FMBQ&Expires=1483483808&Signature=qC7iaCJFRpwHEU567Z5vB89Iv6Q%3D"
      }
    ],
    "size": "4x6",
    "expected_delivery_date": "2016-12-09",
    "date_created": "2016-12-04T10:51:51.843Z",
    "date_modified": "2016-12-04T10:51:51.843Z",
    "object": "postcard"
  },
  "reference_id": "psc_d2d10a2e9cba991c",
  "event_type": {
    "id": "postcard.created",
    "enabled_for_test": true,
    "resource": "postcards",
    "object": "event_type"
  },
  "date_created": "2016-12-04T22:50:08.180Z",
  "object": "event"
}

The event type object

Fields

id:	string Unique identifier, full list of possible values can be found here.
enabled_for_test:	boolean Value is `true` if the event type is enabled in both the test and live environments and `false` if it is only enabled in the live environment.
resource:	string Value is `postcards`, `letters`, `checks`, `addresses`, or `bank accounts`.
object:	string Value is `event_type`.

Example Response


{
  "id": "postcard.created",
  "enabled_for_test": true,
  "resource": "postcards",
  "object": "event_type"
}

All event types

These are all the event types Lob currently creates and are available for subscription.

Postcards

Event Type	When Event Type Occurs
`postcard.created`	Occurs when a postcard is successfully created (Lob returns a 200 status code).
`postcard.rendered_pdf`	Occurs when a postcard's PDF proof is successfully rendered.
`postcard.rendered_thumbnails`	Occurs when a postcard's thumbnails are successfully rendered.
`postcard.in_transit`	Occurs when a postcard receives an "In Transit" tracking event. Only created in the Live Environment.
`postcard.in_local_area`	Occurs when a postcard receives an "In Local Area" tracking event. Only created in the Live Environment.
`postcard.processed_for_delivery`	Occurs when a postcard receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
`postcard.re-routed`	Occurs when a postcard receives a "Re-routed" tracking event. Only created in the Live Environment.
`postcard.returned_to_sender`	Occurs when a postcard receives a "Returned to Sender" tracking event. Only created in the Live Environment.

Letters

Event Type	When Event Type Occurs
`letter.created`	Occurs when a letter is successfully created (Lob returns a 200 status code).
`letter.rendered_pdf`	Occurs when a letter's PDF proof is successfully rendered.
`letter.rendered_thumbnails`	Occurs when a letter's thumbnails are successfully rendered.
`letter.in_transit`	Occurs when a letter receives an "In Transit" tracking event. Only created in the Live Environment.
`letter.in_local_area`	Occurs when a letter receives an "In Local Area" tracking event. Only created in the Live Environment.
`letter.processed_for_delivery`	Occurs when a letter receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
`letter.re-routed`	Occurs when a letter receives a "Re-routed" tracking event. Only created in the Live Environment.
`letter.returned_to_sender`	Occurs when a letter receives a "Returned to Sender" tracking event. Only created in the Live Environment.

Checks

Event Type	When Event Type Occurs
`check.created`	Occurs when a check is successfully created (Lob returns a 200 status code).
`check.rendered_pdf`	Occurs when a check's PDF proof is successfully rendered.
`check.rendered_thumbnails`	Occurs when a check's thumbnails are successfully rendered.
`check.in_transit`	Occurs when a check receives an "In Transit" tracking event. Only created in the Live Environment.
`check.in_local_area`	Occurs when a check receives an "In Local Area" tracking event. Only created in the Live Environment.
`check.processed_for_delivery`	Occurs when a check receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
`check.re-routed`	Occurs when a check receives a "Re-routed" tracking event. Only created in the Live Environment.
`check.returned_to_sender`	Occurs when a check receives a "Returned to Sender" tracking event. Only created in the Live Environment.

Addresses

Event Type	When Event Type Occurs
`address.created`	Occurs when an address is successfully created (Lob returns a 200 status code).
`address.deleted`	Occurs when an address is successfully deleted.

Bank Accounts

Event Type	When Event Type Occurs
`bank_account.created`	Occurs when a bank account is successfully created (Lob returns a 200 status code).
`bank_account.deleted`	Occurs when a bank account is successfully deleted.
`bank_account.verified`	Occurs when a bank account is successfully verified.

HTML Examples

Use the following HTML examples as starting points for creating custom Postcards, Letters, Area Mailings, 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.

Postcard 4x6 Front Example

An example of a 4x6 postcard front. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample 4x6 Postcard Front</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 6.25in;
    height: 4.25in;
    margin: 0;
    padding: 0;
    /* If using an image, the background image should have dimensions of 1875x1275 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/beach.jpg);
    background-size: 6.25in 4.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 5.875in;
    height: 3.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  .text {
    margin: 10px;
    font-family: 'Open Sans';
    font-weight: 400;
    font-size: 40px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
  <div id="safe-area">
    <!-- All text should appear within the safe area. -->
    <div class="text">
      The frosted white box is the safe area. Do not put text outside this box.
    </div>
  </div>
</body>

</html>

Postcard 4x6 Back Example

An example of a 4x6 postcard back. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample 4x6 Postcard Back</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 6.25in;
    height: 4.25in;
    margin: 0;
    padding: 0;
    /* If using an image, the background image should have dimensions of 1875x1275 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/beach.jpg);
    background-size: 6.25in 4.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 5.875in;
    height: 3.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  #ink-free {
    position: absolute;
    width: 3.5in;
    height: 2.7in;
    right: -0.1875in;
    bottom: -0.1875in;
    background-color: white;
  }

  .text {
    margin: 10px;
    width: 200px;
    font-family: 'Open Sans';
    font-weight: 400;
    font-size: 20px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
  <div id="safe-area">
    <!-- All text should appear within the safe area. -->
    <div class="text">
      The frosted white box denotes the safe area to place text. The solid white box denotes the ink-free area which must be left blank. If you are using the data argument, you can add variables like this: {{variable_name}}.
    </div>
    <div id="ink-free">
      <!-- Do not place any artwork or text in the ink free area. Address and postage will be automatically printed here. Delete this div before submitting your postcard! -->
    </div>
  </div>
</body>

</html>

Postcard 6x9 Front Example

An example of a 6x9 postcard front. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample 6x9 Postcard Front</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 9.25in;
    height: 6.25in;
    margin: 0;
    padding: 0;
    /* If using an image, the background image should have dimensions of 2775x1875 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/desert.jpg);
    background-size: 9.25in 6.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 8.875in;
    height: 5.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  .text {
    margin: 10px;
    font-family: 'Open Sans';
    font-weight: 400;
    font-size: 40px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
  <div id="safe-area">
    <!-- All text should appear within the safe area. -->
    <div class="text">
      The frosted white box is the safe area. Do not put text outside this box.
    </div>
  </div>
</body>

</html>

Postcard 6x9 Back Example

An example of a 6x9 postcard back. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample 6x9 Postcard Back</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 9.25in;
    height: 6.25in;
    margin: 0;
    padding: 0;
    /* If using an image, the background image should have dimensions of 2775x1875 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/desert.jpg);
    background-size: 9.25in 6.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 8.875in;
    height: 5.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  #ink-free {
    position: absolute;
    width: 4in;
    height: 2.375in;
    right: .1in;
    bottom: .05in;
    background-color: white;
  }

  .text {
    margin: 10px;
    font-family: 'Open Sans';
    font-weight: 400;
    font-size: 40px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
<div id="safe-area">
  <!-- All text should appear within the safe area. -->
  <div class="text">
    The frosted white box denotes the safe area to place text. The solid white box denotes the ink-free area which must be left blank. If you are using the data argument, you can add variables like this: {{variable_name}}.
  </div>
  <div id="ink-free">
    <!-- Do not place any artwork or text in the ink free area. Address and postage will be automatically printed here. Delete this div before submitting your postcard! -->
  </div>
</div>
</body>

</html>

Postcard 6x11 Front Example

An example of a 6x11 postcard front. Make sure to set size to 6x11 when creating a postcard with this example. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample 6x11 Postcard Front</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 11.25in;
    height: 6.25in;
    margin: 0;
    padding: 0;
    /* If using an image, the background image should have dimensions of 3375x1875 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/jungle.jpg);
    background-size: 11.25in 6.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 10.875in;
    height: 5.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  .text {
    margin: 10px;
    font-family: 'Open Sans';
    font-weight: 400;
    font-size: 60px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
  <div id="safe-area">
    <!-- All text should appear within the safe area. -->
    <div class="text">
      The frosted white box is the safe area. Do not put text outside this box.
    </div>
  </div>
</body>

</html>

Postcard 6x11 Back Example

An example of a 6x11 postcard back. Make sure to set size to 6x11 when creating a postcard with this example. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample 6x11 Postcard Back</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width:11.25in;
    height:6.25in;
    margin:0;
    padding:0;
    /* If using an image, the background image should have dimensions of 3375x1875 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/jungle.jpg);
    background-size: 11.25in 6.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 10.875in;
    height: 5.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  #ink-free {
    position: absolute;
    width: 4in;
    height: 2.375in;
    right: .1in;
    bottom: .05in;
    background-color: white;
  }

  .text {
    margin: 10px;
    font-family: 'Open Sans';
    font-weight: 400;
    width: 600px;
    font-size: 28px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
  <div id="safe-area">
    <!-- All text should appear within the safe area. -->
    <div class="text">
      The frosted white box denotes the safe area to place text. The solid white box denotes the ink-free area which must be left blank. If you are using the data argument, you can add variables like this: {{variable_name}}.
    </div>

    <div id="ink-free">
      <!-- Do not place any artwork or text in the ink free area. Address and postage will be automatically printed here. Delete this div before submitting your postcard! -->
    </div>
  </div>
</body>

</html>

Letter Example

An example of a two page letter where space is reserved to print the recipient and return addresses. Letters will default to this behavior. If you choose to pass your letters as address_placement = insert_blank_page, you should remove the elements in the HTML representing the address information. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample Letter</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 8.5in;
    height: 11in;
    margin: 0;
    padding: 0;
  }

  .page {
    page-break-after: always;
    position: relative;
    width: 8.5in;
    height: 11in;
  }

  .page-content {
    position: absolute;
    width: 8.125in;
    height: 10.625in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(0,0,0,0.2);
  }

  .text {
    position: relative;
    left: 20px;
    top: 20px;
    width: 6in;
    font-family: 'Open Sans';
    font-size: 30px;
  }

  #return-address-window {
    position: absolute;
    left: .625in;
    top: .5in;
    width: 3.25in;
    height: .875in;
    background-color: rgba(255,0,0,0.5);
  }

  #return-address-text {
    position: absolute;
    left: .07in;
    top: .34in;
    width: 2.05in;
    height: .44in;
    background-color: white;
    font-size: .11in;
  }

  #return-logo {
    position: absolute;
    left: .07in;
    top: .02in;
    width: 2.05in;
    height: .3in;
    background-color: white;
  }

  #recipient-address-window {
    position: absolute;
    left: .625in;
    top: 1.75in;
    width: 4in;
    height: 1in;
    background-color: rgba(255,0,0,0.5);
  }

  #recipient-address-text {
    position: absolute;
    left: .07in;
    top: .05in;
    width: 2.92in;
    height: .9in;
    background-color: white;
  }

</style>
</head>

<body>
  <div class="page">
    <div class="page-content">
      <div class="text" style="top: 3in">
        The grey box is the safe area. Do not put text outside this box. If you are using the data argument, you can add variables like this: {{variable_name}}.
      </div>
    </div>
    <div id="return-address-window">
      <div id="return-logo">
        Room for company logo.
      </div>
      <div id="return-address-text">
        The Return Address will be printed here. The red area will be visible through the envelope window.
      </div>
    </div>
    <div id="recipient-address-window">
      <div id="recipient-address-text">
        The Recipient's Address will be printed here. The red area will be visible through the envelope window.
      </div>
    </div>
  </div>
  <div class="page">
    <div class="page-content">
      <div class="text">
        This is a second page.
      </div>
    </div>
  </div>
</body>

</html>

Check Example

An example of an HTML check_bottom to customize the area below the check. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample Check</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 8.5in;
    height: 11in;
    margin: 0;
    padding: 0;
  }

  .text {
    position: relative;
    left: 20px;
    top: 20px;
    width: 6in;
    font-family: 'Open Sans';
    font-size: 30px;
  }

  #ink-free-area {
    position: absolute;
    left: 0;
    top: 0;
    width: 8.5in;
    height: 3.625in;
    background-color: rgba(255,0,0,0.5);
  }

  #page-content {
    position: relative;
    width: 8.125in;
    height: 7.1875in;
    left: 0.1875in;
    top: 3.625in;
    background-color: rgba(0,0,0,0.2);
  }
</style>
</head>

<body>
  <div id="ink-free-area">
    <div class="text">
      Leave this red area completely blank. This is where the check will be printed and perforated.
    </div>
  </div>
  <div id="page-content">
    <div class="text">
      The grey box is the safe area. Do not put text outside this box. If you are using the data argument, you can add variables like this: {{variable_name}}.
    </div>
  </div>
</body>

</html>

Area Mail Front Example

An example of an Area Mail front. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample Area Mail Front</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 11.25in;
    height: 6.25in;
    margin: 0;
    padding: 0;
    /* If using an image, the background image should have dimensions of 3375x1875 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/jungle.jpg);
    background-size: 11.25in 6.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 10.875in;
    height: 5.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  .text {
    margin: 10px;
    font-family: 'Open Sans';
    font-weight: 400;
    font-size: 60px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
  <div id="safe-area">
    <!-- All text should appear within the safe area. -->
    <div class="text">
      The white box is the safe area. Do not put text outside this box.
    </div>
  </div>
</body>

</html>

Area Mail Back Example

An example of an Area Mail back. You can view the rendered example in your browser here.


<html>
<head>
<meta charset="UTF-8">
<link href="https://fonts.googleapis.com/css?family=Open+Sans" rel="stylesheet" type="text/css">
<title>Lob.com Sample Area Mail Back</title>
<style>
  *, *:before, *:after {
    -webkit-box-sizing: border-box;
    -moz-box-sizing: border-box;
    box-sizing: border-box;
  }

  body {
    width: 11.25in;
    height: 6.25in;
    margin: 0;
    padding: 0;
    /* If using an image, the background image should have dimensions of 3375x1875 pixels. */
    background-image: url(https://s3-us-west-2.amazonaws.com/lob-assets/jungle.jpg);
    background-size: 11.25in 6.25in;
    background-repeat: no-repeat;
  }

  #safe-area {
    position: absolute;
    width: 10.875in;
    height: 5.875in;
    left: 0.1875in;
    top: 0.1875in;
    background-color: rgba(255,255,255,0.5);
  }

  #postage-ink-free {
    position: absolute;
    width: 3.4in;
    height: 1.05in;
    left: 7.57in;
    top: .28in;
    background-color: white;
  }

  .text {
    margin: 10px;
    font-family: 'Open Sans';
    font-weight: 400;
    width: 600px;
    font-size: 28px;
    color: white;
    text-shadow: 2px 2px black;
  }
</style>
</head>

<body>
  <div id="safe-area">
    <!-- All text should appear within the safe area. -->
    <div class="text">
      The frosted white box denotes the safe area to place text. The solid white box denotes the ink-free area which must be left blank. If you are using the data argument, you can add variables like this: {{variable_name}}.
    </div>
  </div>

  <div id="postage-ink-free">
    <!-- Do not place any artwork or text in the ink free area, it is reserved for postage -->
  </div>
</body>

</html>

Image Prepping

Currently we support the following file types for all endpoints:

PDF
PNG
JPEG

Templates

You can find pre-made templates that already adhere to all of these guidelines here:

Postcards
Letters
Checks
Area Mail

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.

Prepping PDFs

To ensure that you are producing PDF's correctly please follow the guidelines below:

Make sure all fonts are embedded.
Generated PDF's need to be be PDF/A compliant.

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.

US Verification Details

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]`

`standard`	The default address type. Used when none of the other types apply.
`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.
`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.
`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.
`R1`	The address matched to a CMRA and private mailbox information is present.
`RR`	The address matched to a CMRA and private mailbox information is not present.

Postcards

Letters

Checks

Area Mail

Address Verification

Documentation

Guides

Integrations

Introduction

API endpoint

Summary of Resource URL Patterns

Authentication

Example Request

Versioning

Example Request

Errors

Attributes

HTTP Status Code Summary

Rate Limiting

HTTP Headers and Response Codes

Example HTTP Headers

Example Response

Webhooks

Metadata

Example Create Request with Metadata

Example List Request with Metadata Filter

HTML Templates

Example Create Request using HTML Templates

Asset URLs

Libraries

Addresses

The address object

Fields

Example Response

Create an address

Arguments

Returns

Example Definition

Example Request

Example Response

Retrieve an address

Arguments

Returns

Example Definition

Example Request

Example Response

Delete an address

Arguments

Returns

Example Definition

Example Request

Example Response

List all addresses

Arguments

Returns

Example Definition

Example Request

Example Response

US Verifications

The US verification object

Fields

Example Response

Verify a US address

Arguments

Returns

Example Definition

Example Request

Example Response

International Verifications

Verify an international address

Arguments

Returns

Example Definition

Example Request

Example Response

Postcards

The postcard object

Fields

Example Response

Create a postcard