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": "harry@lob.com",
  "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=harry@lob.com" \
  -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": "harry@lob.com",
  "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": "harry@lob.com",
  "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": "test@test.com",
      "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": "test@test.com",
      "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 LACSLink. LACSLink corrects outdated addresses into their modern counterparts. Possible values are:

  • Y — New address produced with a matching record in LACSLink.
  • N — New address could not be produced because no match was found in LACSLink.
  • empty string — LACSLink 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 LACSLink.
  • 92 — A LACSLink record was matched after dropping secondary information.
  • 14 — A match was found in LACSLink, but could not be converted to a deliverable address.
  • 00 — A match was not found in LACSLink, and no new address was produced.
  • empty string — LACSLink was not attempted.
suite_return_code:
string

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

  • A — A SuiteLink match was found and secondary information was added.
  • 00 — A SuiteLink match could not be found and no secondary information was added.
  • empty string — SuiteLink 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:

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.