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/us_zip_lookups
  • /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/templates
  • /v1/templates/{id}
  • /v1/templates/{id}/versions
  • /v1/templates/{template_id}/versions/{version_id}

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-11-08. 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-11-08"

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

To prevent mis-use, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits. By default, all accounts and their corresponding Test and Live API Keys have a rate limit of 150 requests per 5 seconds per endpoint.

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:150
rate-limit-remaining:100
rate-limit-window:5
      
    

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

Idempotent Requests

Lob supports idempotency for safely retrying POST requests to create postcards, letters, and checks without accidentally creating duplicates.

For example, if a request to create a check fails due to a network error, you can safely retry the same request with the same idempotency key and guarantee that only one check will ultimately be created and sent. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.

To perform an idempotent POST request to one of the three product endpoints, provide an additional Idempotency-Key header to the request. How you create unique keys is up to you, but we suggest using random values, such as V4 UUIDs. Idempotency keys are intended to prevent issues over a short periods of time, therefore keys expire after 24 hours. Keys are unique by mode (Test vs. Live) as well as by resource (postcard vs. letter vs. check).

By default, all GET and DELETE requests are idempotent by nature, so they do not require an additional idempotency key.

For more help integrating idempotency keys, refer to our implementation guide.

Headers

Idempotency-Key: optional

A string of no longer than 256 characters that uniquely identifies this resource.

Example Request


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -H "Idempotency-Key: 026e7634-24d7-486c-a0bb-4a17fd0eebc5" \
  -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 "merge_variables[name]=Harry"

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.

Cancellation Window

By default, all new accounts have a 5 minute cancellation window for postcards, letters, and checks. Within that timeframe, you can cancel mailings from production, free of charge. Once the window has passed for a postcard, letter, or check, the mailing is no longer cancelable. You can edit your cancellation window by product in your Dashboard Settings. For more details on this feature, check out our Cancellation Guide.

If you schedule a postcard, letter, or check for up to 90 days in the future by supplying the send_date parameter, that will override any cancellation window you may have for that product.

Scheduled Mailings

Postcards, letters, and checks can be scheduled to be sent up to 90 days in advance. You can use this feature to:

  • Create automated drip campaigns (e.g. send a postcard at 15, 30, and 60 days)
  • Schedule recurring sends
  • Plan your mailing schedule ahead of time

Up until the time a mailing is scheduled for, it can also be canceled. If you use this feature in conjunction with a cancellation window, the send_date parameter will always take precedence.

For implementation details, see documentation below for each respective endpoint. For more help, see our Scheduled Mailings Guide.

Example Create Request using Send Date


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Future Postcard" \
  -d "to=adr_78c304d54912c502" \
  -d "from=adr_61a0865c8c573139" \
  -d "front=tmpl_b846a20859ae11a" \
  -d "back=tmpl_01b0d396a10c268" \
  -d "merge_variables[name]=Harry" \
  -d "send_date=2017-11-28"

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 "merge_variables[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 Examples

Use these HTML examples as starting points for creating custom Postcards, Letters, Checks, and Area Mailings.

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.

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.

If you'd like to interact with templates programmatically, check out our Beta Program for API access to the HTML Templates Endpoints.

Example Create Request using HTML Templates


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Postcard job" \
  -d "to=adr_78c304d54912c502" \
  -d "from=adr_61a0865c8c573139" \
  -d "front=tmpl_b846a20859ae11a" \
  -d "back=tmpl_01b0d396a10c268" \
  -d "merge_variables[name]=Harry"

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

Beta Program

Here at Lob, we pride ourselves on building high quality platform capabilities rapidly and iteratively, so we can constantly be delivering additional value to our customers. When evaluating a new product or feature from Lob, you may see that it has been released in Beta.

Typically, something in Beta means that the feature is early in its lifecycle here at Lob. While we fully stand behind the quality of everything we release in Beta, we do anticipate receiving a higher level of customer feedback on Beta features, as well as a faster pace of changes from our engineering team in response to that feedback.

By participating in a Lob Beta program, you will have the opportunity to get early access to a new product capability, as well as having a unique opportunity to influence the product's direction with your feedback.

You should also anticipate that features in Beta may have functional or design limitations, and might change rapidly as we receive customer feedback and make improvements. In particular, new APIs in Beta may also go through more frequent versioning and version deprecation cycles than our more mature APIs.

If you are participating in a Beta program and want to provide feedback, please feel free to contact us!

Current Beta Features

  • API access to HTML Templates: The ability to create and save commonly used HTML postcard, letter and check templates has been available for some time in our Dashboard. We have now exposed our Template API endpoints in Beta, so you can now create, retrieve, and update templates programmatically as well!

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.

deleted: boolean

Only returned if the address has been successfully deleted.

object: string

Value is address.

Example Response


{
  "id": "adr_d3489cd64c791ab5",
  "description": "Harry - Office",
  "name": "HARRY ZHANG",
  "company": "LOB",
  "phone": "5555555555",
  "email": "harry@lob.com",
  "address_line1": "185 BERRY ST STE 6100",
  "address_line2": "",
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107-1741",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2017-09-05T17:47:53.767Z",
  "date_modified": "2017-09-05T17:47:53.767Z",
  "object": "address"
}

Create an address

Creates a new address object. US addresses will be standardized and corrected using our US Verification engine whenever possible. Non-US addresses will be standardized into uppercase only.

Arguments

description: optional

An internal description that identifies this resource.

name: optional

Either name or company is required, you may also add both. The total string for name must be no longer than 40 characters. If both name and company are provided, they will be printed on two separate lines above the rest of the address.

company: optional

Either name or company is required, you may also add both. The total string for company must be no longer than 40 characters. If both name and company are provided, they will be printed on two separate lines above the rest of the address.

address_line1: required

The total string must be no longer than 64 characters for US addresses or 200 characters for international addresses.

address_line2: optional

The total string must be no longer than 64 characters for US addresses or 200 characters for international addresses.

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 or a valid full state name 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.

address_country: optional

Must be a 2 letter country short-name code (ISO 3166). Defaults to US.

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

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must 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 - Office" \
  -d "name=Harry Zhang" \
  -d "company=Lob" \
  -d "email=harry@lob.com" \
  -d "phone=5555555555" \
  -d "address_line1=185 Berry St" \
  -d "address_line2=# 6100" \
  -d "address_city=San Francisco" \
  -d "address_state=CA" \
  -d "address_zip=94107" \
  -d "address_country=US"

Example Response


{
  "id": "adr_d3489cd64c791ab5",
  "description": "Harry - Office",
  "name": "HARRY ZHANG",
  "company": "LOB",
  "phone": "5555555555",
  "email": "harry@lob.com",
  "address_line1": "185 BERRY ST STE 6100",
  "address_line2": "",
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107-1741",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2017-09-05T17:47:53.767Z",
  "date_modified": "2017-09-05T17:47:53.767Z",
  "object": "address"
}

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": "Harry - Office",
  "name": "HARRY ZHANG",
  "company": "LOB",
  "phone": "5555555555",
  "email": "harry@lob.com",
  "address_line1": "185 BERRY ST STE 6100",
  "address_line2": "",
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107-1741",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2017-09-05T17:47:53.767Z",
  "date_modified": "2017-09-05T17:47:53.767Z",
  "object": "address"
}

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

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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_d3489cd64c791ab5",
      "description": "Harry - Office",
      "name": "HARRY ZHANG",
      "company": "LOB",
      "phone": "5555555555",
      "email": "harry@lob.com",
      "address_line1": "185 BERRY ST STE 6100",
      "address_line2": "",
      "address_city": "SAN FRANCISCO",
      "address_state": "CA",
      "address_zip": "94107-1741",
      "address_country": "UNITED STATES",
      "metadata": {},
      "date_created": "2017-09-05T17:47:53.767Z",
      "date_modified": "2017-09-05T17:47:53.767Z",
      "object": "address"
    },
    {
      "id": "adr_b8fb5acf3a2b55db",
      "description": "Leore - Office",
      "name": "LEORE AVIDAR",
      "company": "LOB",
      "phone": "5555555555",
      "email": "leore@lob.com",
      "address_line1": "185 BERRY ST STE 6100",
      "address_line2": "",
      "address_city": "SAN FRANCISCO",
      "address_state": "CA",
      "address_zip": "94107-1741",
      "address_country": "UNITED STATES",
      "metadata": {},
      "date_created": "2017-09-05T17:47:53.767Z",
      "date_modified": "2017-09-05T17:47:53.767Z",
      "object": "address"
    }
  ],
  "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_designator:
string

An extra (often unnecessary) secondary designator provided with the input address.

extra_secondary_number:
string

An extra (often unnecessary) secondary 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.

address_type:
string

Uses USPS's Residential Delivery Indicator (RDI) to identify whether an address is classified as residential or business. Possible values are:

  • residental — The address is residential or a PO Box.
  • commercial — The address is commercial.
  • empty string — Not enough information provided to be determined.
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")
latitude:
decimal or null

A positive or negative decimal indicating the geographic latitude of the address, specifying the north-to-south position of a location. This should be used with longitude to pinpoint locations on a map. Will not be returned for military addresses (state is AA, AE, or AP).

longitude:
decimal or null

A positive or negative decimal indicating the geographic longitude of the address, specifying the east-to-west position of a location. This should be used with latitude to pinpoint locations on a map. Will not be returned for military addresses (state is AA, AE, or AP).

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_designator": "",
    "extra_secondary_number": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip_code": "94107",
    "zip_code_plus_4": "1728",
    "zip_code_type": "standard",
    "delivery_point_barcode": "941071728506",
    "address_type": "commercial",
    "record_type": "highrise",
    "default_building_address": false,
    "county": "SAN FRANCISCO",
    "county_fips": "06075",
    "carrier_route": "C001",
    "carrier_route_type": "city_delivery",
    "latitude": 37.77597542841264,
    "longitude": -122.3929557343685
  },
  "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 provided input with a different deliverability based on the input zip_code.

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.

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.

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.

In test mode, you can pass special values for zip_code to test different deliverability values:

  • 11111: deliverable_missing_secondary
  • 22222: deliverable_extra_secondary
  • 33333: undeliverable
  • 00000: no_match
  • All other values: deliverable

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_designator": "",
    "extra_secondary_number": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip_code": "94107",
    "zip_code_plus_4": "1728",
    "zip_code_type": "standard",
    "delivery_point_barcode": "941071728506",
    "address_type": "commercial",
    "record_type": "highrise",
    "default_building_address": false,
    "county": "SAN FRANCISCO",
    "county_fips": "06075",
    "carrier_route": "C001",
    "carrier_route_type": "city_delivery",
    "latitude": 37.77597542841264,
    "longitude": -122.3929557343685
  },
  "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"
}

US ZIP Lookups

The US ZIP Lookup API allows you to find a list of cities, states, and associated information about a ZIP code. It will return a US ZIP Lookup object based on a provided input ZIP code.

The US ZIP lookup object

Fields

id: string

Unique identifier prefixed with us_zip_.

zip_code: string

The 5-digit ZIP 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.

cities: array

An array of city objects containing valid cities for the zip_code. Multiple cities will be returned if more than one city is associated with the input ZIP code. Each city object contains the following information associated with that city:

city:
string

The name of the city.

state:
string

The state as a two-letter abbreviation.

county:
string

The name of the county that contains this city.

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.

preferred:
boolean

Indicates whether or not the city is the USPS default city (preferred city) of a ZIP code. There is only one preferred city per ZIP code, which will always be in position 0 in the array of cities.

object: string

Value is us_zip_lookup.

Example Response


{
  "id": "us_zip_c7cb63d68f8d6",
  "zip_code": "94107",
  "zip_code_type": "standard",
  "cities": [
    {
      "city": "SAN FRANCISCO",
      "state": "CA",
      "county": "SAN FRANCISCO",
      "county_fips": "06075",
      "preferred": true
    }
  ],
  "object": "us_zip_lookup"
}

Lookup a US ZIP code

Lookup a US ZIP code. Only requests with live API keys will generate a valid response. Properly formatted requests with test API keys will return the generic dummy response on the right, regardless of inputs.

Arguments

zip_code: required

Must be a valid 5-digit US ZIP code.

Returns

A US ZIP Lookup object with detailed information about the input ZIP code.

Example Definition

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

Example Request


curl https://api.lob.com/v1/us_zip_lookups \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "zip_code=94107"

Example Response


{
  "id": "us_zip_c7cb63d68f8d6",
  "zip_code": "94107",
  "zip_code_type": "standard",
  "cities": [
    {
      "city": "SAN FRANCISCO",
      "state": "CA",
      "county": "SAN FRANCISCO",
      "county_fips": "06075",
      "preferred": true
    }
  ],
  "object": "us_zip_lookup"
}

International Verifications

Address verification for international (non-US) addresses.

The International verification object

Fields

id: string

Unique identifier prefixed with intl_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.

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.

last_line: string

Combination of the following applicable components:

  • City (city)
  • State (state)
  • Postal code (postal_code)
country: string

The country of the address. Will be returned as a 2 letter country short-name code (ISO 3166).

deliverability: string

Summarizes the deliverability of the intl_verification object. Possible values are:

  • deliverable — The address is deliverable.
  • deliverable_missing_info — The address is missing some information, but is most likely deliverable.
  • undeliverable — The address is most likely not deliverable. Some components of the address (such as city or postal code) may have been found.
  • no_match — This address is not deliverable. No matching street could be found within the city or postal code.
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_name:
string

The name of the street.

city:
string

The name of the city.

state:
string

The name of the state.

postal_code:
string

The postal code.

object: string

Value is intl_verification.

Example Response


{
  "id": "intl_ver_c7cb63d68f8d6",
  "primary_line": "370 WATER ST",
  "secondary_line": "",
  "last_line": "SUMMERSIDE PE C1N 1C4",
  "country": "CA",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "370",
    "street_name": "WATER ST",
    "city": "SUMMERSIDE",
    "state": "PE",
    "postal_code": "C1N 1C4"
  }
  "object": "intl_verification"
}

Verify an international address

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

Arguments

recipient: optional
primary_line: required
secondary_line: optional
city: optional
state: optional
postal_code: optional
country: required

Must be a 2 letter country short-name code (ISO 3166). Does not accept US, AS, PR, FM, GU, MH, MP, PW, or VI. For these addresses, please use the US verification API.

Returns

Returns the validated address object, along with it's deliverability status.

Example Definition

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

Example Request


curl https://api.lob.com/v1/intl_verifications \
  -u <YOUR_LIVE_API_KEY>: \
  -d "primary_line=370 Water St" \
  -d "city=Summerside" \
  -d "state=Prince Edward Island" \
  -d "postal_code=C1N 1C4" \
  -d "country=CA"

Example Response


{
  "id": "intl_ver_c7cb63d68f8d6",
  "primary_line": "370 WATER ST",
  "secondary_line": "",
  "last_line": "SUMMERSIDE PE C1N 1C4",
  "country": "CA",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "370",
    "street_name": "WATER ST",
    "city": "SUMMERSIDE",
    "state": "PE",
    "postal_code": "C1N 1C4"
  }
  "object": "intl_verification"
}

Postcards

The postcards endpoint allows you to easily print and mail postcards. The API provides endpoints for creating postcards, retrieving individual postcards, canceling postcards, and retrieving a list of postcards.

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
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 based on its send_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

A timestamp in ISO 8601 format of the date the postcard will be dispatched for production. If the send_date of a postcard has passed, it can no longer be canceled. send_date will be the date_created of the postcard plus the cancellation window, if one was applied at the time of the postcard's creation. If a postcard was scheduled using the send_date parameter, that timestamp will be returned here. For billing purposes, mailings will count towards usage in the month of their send_date.

deleted: boolean

Only returned if the postcard has been successfully canceled.

object: string

Value is postcard.

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "url": "https://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": "2017-09-12",
  "date_created": "2017-09-05T17:47:53.967Z",
  "date_modified": "2017-09-05T17:47:53.967Z",
  "send_date": "2017-09-05T17:47:53.967Z",
  "object": "postcard"
}

Create a postcard

Create a new postcard.

Arguments

description: optional

An internal description that identifies this resource.

to: required

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail Strictness Setting, the request will fail. Read more here.

from: optional

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only.

front: required

The artwork to use as the front of your postcard. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to the specified size. See here for HTML examples.

back: required

The artwork to use as the back of your postcard. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to the specified size. Be sure to leave room for address and postage information by following the templates provided here: 4x6 template, 6x9 template, 6x11 template. See here for HTML examples.

merge_variables: optional

For parameters that accept HTML, you can provide optional variables that will be merged with your HTML. To use a variable, insert double curly braces into your HTML like so: {{variable_name}}. merge_variables 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.

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 usps_standard, please contact support.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 90 days in the future to send the postcard off for production. This will override any postcard cancellation window applied to the postcard. Until the send_date has passed, the postcard will be cancelable. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must 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]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from[name]=Leore Avidar" \
  -d "from[address_line1]=185 Berry St" \
  -d "from[address_line2]=# 6100" \
  -d "from[address_city]=San Francisco" \
  -d "from[address_state]=CA" \
  -d "from[address_zip]=94107" \
  -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 "merge_variables[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]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from[name]=Leore Avidar" \
  -d "from[address_line1]=185 Berry St" \
  -d "from[address_line2]=# 6100" \
  -d "from[address_city]=San Francisco" \
  -d "from[address_state]=CA" \
  -d "from[address_zip]=94107" \
  -d "from[address_country]=US" \
  -d "front=tmpl_b846a20859ae11a" \
  -d "back=tmpl_01b0d396a10c268" \
  -d "merge_variables[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]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from[name]=Leore Avidar" \
  -d "from[address_line1]=185 Berry St" \
  -d "from[address_line2]=# 6100" \
  -d "from[address_city]=San Francisco" \
  -d "from[address_state]=CA" \
  -d "from[address_zip]=94107" \
  -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: \
  -d "description=Demo Postcard job" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from[name]=Leore Avidar" \
  -d "from[address_line1]=185 Berry St" \
  -d "from[address_line2]=# 6100" \
  -d "from[address_city]=San Francisco" \
  -d "from[address_state]=CA" \
  -d "from[address_zip]=94107" \
  -d "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_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "url": "https://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": "2017-09-12",
  "date_created": "2017-09-05T17:47:53.967Z",
  "date_modified": "2017-09-05T17:47:53.967Z",
  "send_date": "2017-09-05T17:47:53.967Z",
  "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_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": "LOB",
    "phone": "5555555555",
    "email": "harry@lob.com",
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": 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": "2017-09-05T17:47:53.815Z",
  "date_modified": "2017-09-05T17:47:53.815Z",
  "send_date": "2017-09-05T17:47:53.815Z",
  "expected_delivery_date": "2017-09-12",
  "object": "postcard"
}

Cancel a postcard

Completely removes a postcard from production. This can only be done if the postcard’s send_date has not yet passed. If the postcard is successfully canceled, you will not be charged for it. Read more on postcard cancellation windows and scheduling postcards.

Arguments

id: required

The identifier of the postcard to be canceled.

Returns

Returns a message that the cancellation was successful.

Example Definition

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

Example Request


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

Example Response


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

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

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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 valid sizes. Acceptable values are 4x6, 6x9, and 6x11.

scheduled: optional

Set scheduled to true to only return orders (past or future) where send_date is greater than date_created. Set scheduled to false to only return orders where send_date is equal to date_created.

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

sort_by: optional

Sorts postcards in a desired order. sort_by accepts an object with the key being either date_created or send_date and the value being either asc or desc.

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_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": 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": "2017-09-05T17:47:54.267Z",
      "date_modified": "2017-09-05T17:47:54.267Z",
      "send_date": "2017-09-05T17:47:54.267Z",
      "expected_delivery_date": "2017-09-12",
      "object": "postcard"
    },
    {
      "id": "psc_66a94c0e4b004efd",
      "description": "Demo Postcard Job",
      "metadata": {},
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company":null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": 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": "2017-09-05T17:47:54.182Z",
      "date_modified": "2017-09-05T17:47:54.182Z",
      "send_date": "2017-09-05T17:47:54.182Z",
      "expected_delivery_date": "2017-09-12",
      "object": "postcard"
    }
  ],
  "count": 2,
  "object": "list"
}

Letters

The letters endpoint allows you to easily print and mail letters. The API provides endpoints for creating letters, retrieving individual letters, canceling letters, and retrieving a list of letters.

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 based on its send_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

A timestamp in ISO 8601 format of the date the letter will be dispatched for production. If the send_date of a letter has passed, it can no longer be canceled. send_date will be the date_created of the letter plus the cancellation window, if one was applied at the time of the letter's creation. If a letter was scheduled using the send_date parameter, that timestamp will be returned here. For billing purposes, mailings will count towards usage in the month of their send_date.

deleted: boolean

Only returned if the letter has been successfully canceled.

object: string

Value is letter.

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "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": "2017-09-12",
  "date_created": "2017-09-05T15:54:53.346Z",
  "date_modified": "2017-09-05T15:54:53.346Z",
  "send_date": "2017-09-05T15:54:53.346Z",
  "object": "letter"
}

Create a letter

Create a new letter.

Arguments

description: optional

An internal description that identifies this resource.

to: required

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail Strictness Setting, the request will fail. Read more here.

from: required

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only.

color: required

Set this key to true if you would like to print in color. Set to false if you would like to print in black and white.

file: required

Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML or PDF file. HTML files passed as remote URLs or local file upload have no character limit. All pages of a supplied PDF file must be sized at 8.5"x11", while supplied HTML will be rendered and trimmed to as many 8.5"x11" pages as necessary. For design specifications, please see our PDF and HTML templates. 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.

merge_variables: optional

For parameters that accept HTML, you can provide optional variables that will be merged with your HTML. To use a variable, insert double curly braces into your HTML like so: {{variable_name}}. merge_variables 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.

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 that defaults to false. If you would like to include a return envelope with your letter, set this key to true and specify the perforated_page. See pricing for extra costs incurred.

perforated_page: optional

Required if return_envelope is true. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to 1. The blank page added by address_placement=insert_blank_page will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our perforation guide.

mail_type: optional

A string designating the mail postage type. Defaults to usps_first_class. To activate usps_standard, 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

A timestamp in ISO 8601 format which specifies a date after the current time and up to 90 days in the future to send the letter off for production. This will override any letter cancellation window applied to the letter. Until the send_date has passed, the letter will be cancelable. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must 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]=185 Berry St" \
    -d "to[address_line2]=# 6100" \
    -d "to[address_city]=San Francisco" \
    -d "to[address_state]=CA" \
    -d "to[address_zip]=94107" \
    -d "to[address_country]=US" \
    -d "from[name]=Leore Avidar" \
    -d "from[address_line1]=185 Berry St" \
    -d "from[address_line2]=# 6100" \
    -d "from[address_city]=San Francisco" \
    -d "from[address_state]=CA" \
    -d "from[address_zip]=94107" \
    -d "from[address_country]=US" \
    --data-urlencode "file=<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>" \
    -d "merge_variables[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]=185 Berry St" \
    -d "to[address_line2]=# 6100" \
    -d "to[address_city]=San Francisco" \
    -d "to[address_state]=CA" \
    -d "to[address_zip]=94107" \
    -d "to[address_country]=US" \
    -d "from[name]=Leore Avidar" \
    -d "from[address_line1]=185 Berry St" \
    -d "from[address_line2]=# 6100" \
    -d "from[address_city]=San Francisco" \
    -d "from[address_state]=CA" \
    -d "from[address_zip]=94107" \
    -d "from[address_country]=US" \
    -d "file=tmpl_cf5068f529da670" \
    -d "merge_variables[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]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from[name]=Leore Avidar" \
  -d "from[address_line1]=185 Berry St" \
  -d "from[address_line2]=# 6100" \
  -d "from[address_city]=San Francisco" \
  -d "from[address_state]=CA" \
  -d "from[address_zip]=94107" \
  -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" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from[name]=Leore Avidar" \
  -d "from[address_line1]=185 Berry St" \
  -d "from[address_line2]=# 6100" \
  -d "from[address_city]=San Francisco" \
  -d "from[address_state]=CA" \
  -d "from[address_zip]=94107" \
  -d "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_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "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": "2017-09-12",
  "date_created": "2017-09-05T15:54:53.346Z",
  "date_modified": "2017-09-05T15:54:53.346Z",
  "send_date": "2017-09-05T15:54:53.346Z",
  "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_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "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": "2017-09-12",
  "date_created": "2017-09-05T15:54:53.346Z",
  "date_modified": "2017-09-05T15:54:53.346Z",
  "send_date": "2017-09-05T15:54:53.346Z",
  "object": "letter"
}

Cancel a letter

Completely removes a letter from production. This can only be done if the letter send_date has not yet passed. If the letter is successfully canceled, you will not be charged for it. Read more on letter cancellation windows and scheduling letters.

Arguments

id: required

The identifier of the letter to be canceled.

Returns

Returns a message that the cancellation was successful.

Example Definition

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

Example Request


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

Example Response


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

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

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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

Set scheduled to true to only return orders (past or future) where send_date is greater than date_created. Set scheduled to false to only return orders where send_date is equal to date_created.

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

color: optional

A boolean that represents which letters to return. Set to true to return only color letters or false to return only black & white letters.

sort_by: optional

Sorts letters in a desired order. sort_by accepts an object with the key being either date_created or send_date and the value being either asc or desc.

Returns

A dictionary 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_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "color": true,
      "double_sided": true,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "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": "2017-09-12",
      "date_created": "2017-09-05T15:54:54.416Z",
      "date_modified": "2017-09-05T15:54:54.416Z",
      "send_date": "2017-09-05T15:54:54.416Z",
      "object": "letter"
    },
    {
      "id": "ltr_8ea22b5354337084",
      "description": "Demo Letter 2",
      "metadata": {},
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "color": true,
      "double_sided": true,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "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": "2017-09-12",
      "date_created": "2017-09-05T15:54:53.346Z",
      "date_modified": "2017-09-05T15:54:53.346Z",
      "send_date": "2017-09-05T15:54:53.346Z",
      "object": "letter"
    }
  ],
  "count": 2,
  "object": "list"
}

Checks

Checks allow you to send payments via physical checks. The API provides endpoints for creating checks, retrieving individual checks, canceling checks, and retrieving a list of checks.

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 based on its send_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

A timestamp in ISO 8601 format of the date the check will be dispatched for production. If the send_date of a check has passed, it can no longer be canceled. send_date will be the date_created of the check plus the cancellation window, if one was applied at the time of the check's creation. If a check was scheduled using the send_date parameter, that timestamp will be returned here. For billing purposes, mailings will count towards usage in the month of their send_date.

deleted: boolean

Only returned if the check has been successfully canceled.

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_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "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": "2017-09-12",
  "mail_type": "usps_first_class",
  "date_created": "2017-09-05T17:47:53.896Z",
  "date_modified": "2017-09-05T17:47:53.896Z",
  "send_date": "2017-09-05T17:47:53.896Z",
  "object": "check"
}

Create a check

Create a new check.

Arguments

description: optional

An internal description that identifies this resource.

to: required

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail Strictness Setting, the request will fail. Read more here.

from: required

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only.

bank_account: required

Must be a bank account ID. Only verified bank accounts may be used.

amount: required

A number that specifies 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

An integer that designates the check number. If check_number is not explicitly passed, checks created from a new bank_account will start at 10000 and increment accordingly every time a check is created with that bank_account. If a check_number is ever explicitly passed, that will override any defaults. Afterwards, checks created with that bank_account will increment from there without needing to pass check_number.

logo: optional

This can be a URL or local file to an image to print (in grayscale) in the upper-left corner of your check. The image must have a color model of RGB or CMYK, be a square, be at least 100px X 100px, and have a transparent background. The accepted file types are PNG and JPG.

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. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 8.5"x11" at 300 DPI, while supplied HTML will be rendered and trimmed to fit on a 8.5"x11" page. The check bottom will always be printed in black & white. You must follow this template. See here for HTML examples.

attachment: optional

A document to include with the check. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. All pages of PDF, PNG, and JPGs must be sized at 8.5"x11" at 300 DPI, while supplied HTML will be rendered and trimmed to as many 8.5"x11" pages as necessary. If a PDF is provided, it must be 6 pages or fewer. The attachment will be printed double-sided in black & white and will be included in the envelope after the check page. Please follow these design guidelines. See pricing for extra costs incurred. See here for HTML examples.

merge_variables: optional

For parameters that accept HTML, you can provide optional variables that will be merged with your HTML. To use a variable, insert double curly braces into your HTML like so: {{variable_name}}. merge_variables 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.

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

A timestamp in ISO 8601 format which specifies a date after the current time and up to 90 days in the future to send the check off for production. This will override any check cancellation window applied to the check. Until the send_date has passed, the check will be cancelable. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must 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]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from=adr_b8fb5acf3a2b55db" \
  -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 "merge_variables[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]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from=adr_b8fb5acf3a2b55db" \
  -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 "merge_variables[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]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from=adr_b8fb5acf3a2b55db" \
  -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" \
  -d "to[name]=Harry Zhang" \
  -d "to[address_line1]=185 Berry St" \
  -d "to[address_line2]=# 6100" \
  -d "to[address_city]=San Francisco" \
  -d "to[address_state]=CA" \
  -d "to[address_zip]=94107" \
  -d "to[address_country]=US" \
  -d "from=adr_b8fb5acf3a2b55db" \
  -d "bank_account=bank_8cad8df5354d33f" \
  -d "amount=22.50" \
  -d "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_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "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": "2017-09-12",
  "mail_type": "usps_first_class",
  "date_created": "2017-09-05T17:47:53.896Z",
  "date_modified": "2017-09-05T17:47:53.896Z",
  "send_date": "2017-09-05T17:47:53.896Z",
  "object": "check"
}

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_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "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": "2017-09-12",
  "mail_type": "usps_first_class",
  "date_created": "2017-09-05T17:47:53.896Z",
  "date_modified": "2017-09-05T17:47:53.896Z",
  "send_date": "2017-09-05T17:47:53.896Z",
  "object": "check"
}

Cancel a check

Completely removes a check from production. This can only be done if the check send_date has not yet passed. If the check is successfully canceled, you will not be charged for it. Read more on check cancellation windows and scheduling checks.

Arguments

id: required

The identifier of the check to be canceled.

Returns

Returns a message that the cancellation was successful.

Example Definition

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

Example Request


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

Example Response


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

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

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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

Set scheduled to true to only return orders (past or future) where send_date is greater than date_created. Set scheduled to false to only return orders where send_date is equal to date_created.

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

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

sort_by: optional

Sorts checks in a desired order. sort_by accepts an object with the key being either date_created or send_date and the value being either asc or desc.

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_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.778Z",
        "date_modified": "2017-09-05T17:47:53.778Z",
        "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": "2017-09-12",
      "mail_type": "usps_first_class",
      "date_created": "2017-09-05T17:47:54.128Z",
      "date_modified": "2017-09-05T17:47:54.128Z",
      "send_date": "2017-09-05T17:47:54.128Z",
      "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_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": "",
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_8cad8df5354d33f",
        "description": "Test Bank Account",
        "metadata": {},
        "routing_number": "322271627",
        "account_number": "123456789",
        "signatory": "John Doe",
        "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
        "verified": true,
        "account_type": "company",
        "date_created": "2015-11-06T19:24:24.440Z",
        "date_modified": "2015-11-06T19:41:28.312Z",
        "object": "bank_account"
      },
      "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": "2017-09-12",
      "mail_type": "usps_first_class",
      "date_created": "2017-09-05T17:47:54.078Z",
      "date_modified": "2017-09-05T17:47:54.078Z",
      "send_date": "2017-09-05T17:47:54.078Z",
      "object": "check"
    }
  ],
  "count": 2,
  "object": "list"
}

Bank Accounts

Bank Accounts allow you to store your bank account securely in our system. The API provides endpoints for creating bank accounts, deleting bank accounts, verifying bank accounts, retrieving individual bank accounts, and retrieving a list of bank accounts.

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.

deleted: boolean

Only returned if the bank account has been successfully deleted.

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

An internal description that identifies this resource.

routing_number: required

Must be a valid US routing number.

account_number: required

Must be no longer than 17 characters.

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

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must 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, so any two integers between 1 and 100 will work.

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

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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 postcards to an entire zip code or specific delivery routes. The API provides endpoints for creating area mailings, retrieving individual area mailings, and retrieving a list of area mailings.

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

An internal description that identifies this resource.

routes: required

Must be a string of 1 valid zip code or delivery route or an array of strings of valid zip codes and/or delivery routes. The total number of addresses in your specified routes (combined with your target_type setting) must be greater than 500.

target_type: optional

A string designating the target recipient type which defaults to all. Options are all (residential and business addresses) and residential.

front: required

Accepts an HTML string of under 10,000 characters, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to 6.25"x11.25". See here for HTML examples.

back: required

Follow this template when creating your artwork. Accepts an HTML string of under 10,000 characters, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to 6.25"x11.25". See here for HTML examples.

merge_variables: optional

For parameters that accept HTML, you can provide optional variables that will be merged with your HTML. To use a variable, insert double curly braces into your HTML like so: {{variable_name}}. merge_variables 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.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must 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 "merge_variables[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

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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"
}

Templates Beta

These API endpoints allow you to create, retrieve, update and delete reusable HTML templates for use with the print & mail API.

The template object

Fields

id: string

Unique identifier prefixed with tmpl_.

description: string or null
versions: array

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

published_version: a version object

The template's currently published version.

metadata: object
date_created: string

A timestamp in ISO 8601 format of the date the template was created.

date_modified: string

A timestamp in ISO 8601 format of the date the template was last modified.

deleted: boolean

Only returned if the template has been successfully deleted.

object: string

Value is template.

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Create a template

Creates a new template for use with the print & mail API.

Arguments

description: optional

An internal description that identifies this resource.

html: required

An HTML string of less than 100,000 characters to be used as the published_version of this template. See here for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must 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 template object upon successful creation.

Example Definition

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

Example Request


curl https://api.lob.com/v1/templates \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Test Template" \
  --data-urlencode "html=<html>HTML for {{name}}</html>"

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Retrieve a template

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

Arguments

id: required

The identifier of the template to be retrieved.

Returns

Returns a template object if a valid identifier was provided.

Example Definition

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

Example Request


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

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Update a template

Updates the template with a given ID.

Arguments

description: optional

An internal description that identifies this resource.

published_version: optional

Update the published version of a template. The published version is the one that will be used in any print & mail requests that reference the specified template. Will err if the version attempting to be set as the published_version has been deleted or does not exist.

Returns

Returns the updated template object if a valid identifier was provided.

Example Definition

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

Example Request


curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Updated description" \
  -d "published_version=vrsn_362184d96d9b0c9"

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Delete a template

Permanently deletes a template. Deleting a template also deletes its associated versions. Deleted templates can not be used to create postcard, letter, or check resources.

Arguments

id: required

The identifier of the template to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request


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

Example Response


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

List all templates

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

Arguments

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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 templates, starting at index offset. Each entry in the array is a separate template object. If no more templates are available, the resulting array will be empty.

Example Definition

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

Example Request


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

Example Response


{
  "data": [
    {
      "id": "tmpl_3a15ef6349eb353",
      "description": "Test Template",
      "versions": [
        {
          "id": "vrsn_44cae6231509e8c",
          "description": "Test Template",
          "html": "<html>HTML for {{name}}</html>",
          "date_created": "2017-11-09T04:05:13.116Z",
          "date_modified": "2017-11-09T04:05:13.116Z",
          "object": "version"
        }
      ],
      "published_version": {
        "id": "vrsn_44cae6231509e8c",
        "description": "Test Template",
        "html": "<html>HTML for {{name}}</html>",
        "date_created": "2017-11-09T04:05:13.116Z",
        "date_modified": "2017-11-09T04:05:13.116Z",
        "object": "version"
      },
      "metadata": {},
      "date_created": "2017-11-09T04:05:13.116Z",
      "date_modified": "2017-11-09T04:05:13.116Z",
      "object": "template"
    },
    {
      "id": "tmpl_c94e83ca2cd5121",
      "description": "Updated description",
      "versions": [
        {
          "id": "vrsn_362184d96d9b0c9",
          "description": "Test Template",
          "html": "<html>HTML for {{name}}</html>",
          "date_created": "2017-11-07T22:56:10.962Z",
          "date_modified": "2017-11-07T22:56:10.962Z",
          "object": "version"
        }
      ],
      "published_version": {
        "id": "vrsn_362184d96d9b0c9",
        "description": "Test Template",
        "html": "<html>HTML for {{name}}</html>",
        "date_created": "2017-11-07T22:56:10.962Z",
        "date_modified": "2017-11-07T22:56:10.962Z",
        "object": "version"
      },
      "metadata": {},
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-09T03:42:21.264Z",
      "object": "template"
    }
  ],
  "count": 2,
  "object": "list"
}

Template Versions Beta

These API endpoints allow you to create, retrieve, update and delete versions of reusable HTML templates for use with the print & mail API.

The version object

Fields

id: string

Unique identifier prefixed with vrsn_.

description: string or null
html: string
date_created: string

A timestamp in ISO 8601 format of the date the version was created.

date_modified: string

A timestamp in ISO 8601 format of the date the version was last modified.

deleted: boolean

Only returned if the version has been successfully deleted.

object: string

Value is version.

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Create a version

Create a new version attached to the specified template.

Arguments

description: optional

An internal description that identifies this resource.

html: required

An HTML string of less than 100,000 characters. See here for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details. Newly created versions will not be published until the published_version of the template is updated.

Returns

Returns a version object upon successful creation.

Example Definition

POST https://api.lob.com/v1/templates/{id}/versions

Example Request


curl https://api.lob.com/v1/templates/tmpl_4aa14648113e45b/versions \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Second Version" \
  --data-urlencode "html=<html>Second HTML for {{name}}</html>"

Example Response


{
  "id": "vrsn_534e339882d2282",
  "description": "Second Version",
  "html": "<html>Second HTML for {{name}}</html>",
  "date_created": "2017-11-09T04:49:38.016Z",
  "date_modified": "2017-11-09T04:49:38.016Z",
  "object": "version"
}

Retrieve a version

Retrieves the version with the given template ID and version ID.

Arguments

template_id: required

The identifier of the template the version belongs to.

version_id: required

The identifier of the version to be retrieved.

Returns

Returns a version object if valid identifiers were provided.

Example Definition

GET https://api.lob.com/v1/templates/{template_id}/versions/{version_id}

Example Request


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

Example Response


{
  "id": "vrsn_534e339882d2282",
  "description": "Second Version",
  "html": "<html>Second HTML for {{name}}</html>",
  "date_created": "2017-11-09T04:49:38.016Z",
  "date_modified": "2017-11-09T04:49:38.016Z",
  "object": "version"
}

Update a version

Updates the version with the given template ID and version ID.

Arguments

description: optional

An internal description that identifies this resource.

Returns

Returns a the updated version object if valid identifiers were provided.

Example Definition

POST https://api.lob.com/v1/templates/{template_id}/versions/{version_id}

Example Request


curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121/versions/vrsn_534e339882d2282 \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Updated description"

Example Response


  {
    "id": "vrsn_534e339882d2282",
    "description": "Updated description",
    "html": "<html>Second HTML for {{name}}</html>",
    "date_created": "2017-11-09T04:49:38.016Z",
    "date_modified": "2017-11-09T04:49:38.016Z",
    "object": "version"
  }

Delete a version

Permanently deletes a version. A template's published_version can not be deleted.

Arguments

template_id: required

The identifier of the template the version belongs to.

version_id: required

The identifier of the version to be retrieved.

Returns

Returns a confirmation upon successful deletion.

Example Definition

DELETE https://api.lob.com/v1/templates/{template_id}/versions/{version_id}

Example Request


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

Example Response


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

List all versions

Returns a list of versions. The returned versions all belong to the template of the id passed, and are sorted by creation date with the most recently created appearing first.

Arguments

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

include: optional

Request that the response include the total count by specifying include[]=total_count.

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

Example Definition

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

Example Request


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

Example Response


{
  "data": [
    {
      "id": "vrsn_4d6ff5d868bf630",
      "description": "Second Version",
      "html": "<html>Second HTML for {{name}}</html>",
      "date_created": "2017-11-09T05:09:03.665Z",
      "date_modified": "2017-11-09T05:09:03.665Z",
      "object": "version"
    },
    {
      "id": "vrsn_2a17159c1911919",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-09T05:08:40.004Z",
      "date_modified": "2017-11-09T05:08:40.004Z",
      "object": "version"
    }
  ],
  "count": 2,
  "object": "list"
}

Changelog

2017-11-08

  • split extra_secondary_information into extra_secondary_designator and extra_secondary_number for /v1/us_verifications

2017-10-17

  • remove support for the /v1/states endpoint
  • remove support for the /v1/countries endpoint
  • remove support for the message field from the POST /v1/postcards endpoint

2017-09-08

  • renames input parameters and restructures response object for /v1/intl_verifications

2017-08-14

  • automatically standardizes and corrects US addresses created via POST /v1/addresses. non-US addresses will be standardized into uppercase only.
  • automatically standardizes and corrects inline US addresses used in POST /v1/postcards, POST /v1/letters, and POST /v1/checks. non-US addresses will be standardized into uppercase only.
  • enforce 40 character limit on name and company for all addresses
  • enforce 64 character limit on address_line1 and address_line2 for US addresses

2017-06-16

  • enforce 10,000 character limit on HTML strings
  • rename data parameter for all products to merge_variables

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 Sunsetted

  • 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"
    },
    "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.

Image Prepping

Currently we support the following file types for all endpoints:

  • PDF
  • PNG
  • JPEG

Templates

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

Prepping All Images

The following guidelines apply to image types:

  • Images should be 300 dpi or higher - PNG/JPEG files with less than 300 dpi will be rejected.
  • Your artwork should include a 1/8" border around the final trim size. This means your final file size will be a total of 0.25" larger than your expected printed piece (ie, a 4"x6" postcard should be submitted as 4.25"x6.25"). There is no need to include crop marks in your submitted content.
  • Include a safe zone – make sure no critical elements are within 1/8" from the edge of the final size.
  • Do not include any additional postage marks or indicia.
  • File sizes should be no larger than 5MB.

Prepping PDFs

To ensure that you are producing PDF's correctly please follow the guidelines 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.