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/verify
  • /v1/postcards
  • /v1/postcards/{id}
  • /v1/letters
  • /v1/letters/{id}
  • /v1/checks
  • /v1/checks/{id}
  • /v1/bank_accounts
  • /v1/bank_accounts/{id}
  • /v1/bank_accounts/{id}/verify
  • /v1/areas
  • /v1/areas/{id}
  • /v1/routes/{zip_code}
  • /v1/routes
  • /v1/countries
  • /v1/states

Authentication

In order to properly authenticate with the API, you must send your API key in the header of each request. You should include it via HTTP Basic Authentication, providing the key as the username and leaving the password blank.

Your API keys are listed in your Settings on your Dashboard.

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 2016-06-30. 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: 2016-06-30"

Errors

Lob uses RESTful HTTP response codes to indicate success or failure of an API request - read below for more information. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end.

Attributes

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

HTTP Status Code Summary

200 - Success Successful API request
401 - Unauthorized Authorization error with your API key or account
403 - Forbidden Forbidden error with your API key or account
404 - Not Found The requested item does not exist
422 - Bad Request Some sort of error with the provided inputs
429 - Too Many Requests The user has sent too many requests in a given amout of time
500 - Server Error Something is wrong on Lob's end

Rate Limiting

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

When your application exceeds the rate limit for a given API endpoint, the Lob API will return an HTTP 429 "Too Many Requests" response code instead of the variety of codes you would find across the other API endpoints.

HTTP Headers and Response Codes

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

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

Example HTTP Headers

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

Example Response

If you hit the rate limit on a given endpoint, this is the body of the HTTP 429 message that you will see:

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

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


curl https://api.lob.com/v1/postcards \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "description=Demo Postcard job" \
  -d "metadata[campaign]=NEWYORK2015" \
  -d "to=adr_78c304d54912c502" \
  -d "from=adr_61a0865c8c573139" \
  --data-urlencode "front=<html style='margin: 130px; font-size: 50;'>Front HTML for {{name}}</html>" \
  --data-urlencode "back=<html style='margin: 130px; font-size: 50;'>Back HTML</html>" \
  -d "data[name]=Harry"

Example List Request with Metadata Filter


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

Asset URLs

All asset URLs returned by the Lob API (postcards, letters, thumbnails, etc) are signed S3 links served over HTTPS. All links returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated.

Libraries

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

Addresses

To add an address to your address book, you create a new address object. You can retrieve and delete individual addresses as well as get a list of addresses. Addresses are identified by a unique random ID.

The address object

Arguments

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 the full state name.

address_zip: string or null
address_country: string

Will be returned as the full country name.

metadata: object
date_created: string

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

date_modified: string

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

object: string

Value is address.

Example Response


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

Create an address

Creates a new address object

Arguments

description: optional
name: optional

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

company: optional

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

address_line1: required

The total string must be no longer than 200 characters.

address_line2: optional

The total string must be no longer than 200 characters.

address_country: optional

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

address_city: optional

Required if address_country is US, otherwise optional. The total string must be no longer than 200 characters.

address_state: optional

Required and must be a 2 letter state short-name code if address_country is US, otherwise optional and the total string can not be any longer than 200 characters.

address_zip: optional

Required and must follow the ZIP format of 12345 or ZIP+4 format of 12345-1234 if address_country is US, otherwise optional and the total string can not be any longer than 40 characters.

phone: optional

The total string must be no longer than 40 characters.

email: optional

The total string must be no longer than 100 characters.

metadata: optional

Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns an address object upon successful creation.

Example Definition

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

Example Request


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

Example Response


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

Retrieve an address

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

Arguments

id: required

The identifier of the address to be retrieved.

Returns

Returns an address object if a valid identifier was provided.

Example Definition

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

Example Request


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

Example Response


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

Delete an address

Permanently deletes a customer. It cannot be undone.

Arguments

id: required

The identifier of the address to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request


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

Example Response


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

List all addresses

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

Arguments

limit: optional

How many results to return, default=10, max 100, must be an integer

offset: optional

Return requested # of items starting with the value, default=0, must be an integer

include: optional

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

metadata: optional

Filter by metadata key-value pair, e.g. metadata[customer_id]=987654

date_created: optional

Filter by ISO-8601 date or datetime, e.g. { gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Address Verification

Address verification allows you to validate your address to increase accuracy to ensure deliveries. It will return the validated address object and additional details as necessary.

Verify an address

Validates a given address.

Arguments

name: optional
address_line1: optional
address_line2: optional
address_city: optional
address_state: optional
address_zip: optional
address_country: optional

Must be a 2 letter country short-name code (ISO 3166)

Returns

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

Example Definition

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

Example Request


curl https://api.lob.com/v1/verify \
  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
  -d "address_line1=185 Berry Street" \
  -d "address_city=San Francisco" \
  -d "address_state=CA" \
  -d "address_zip=94107"

Example Response


{
  "address": {
    "address_line1": "185 BERRY ST",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-5705",
    "address_country": "US",
    "object": "address"
  },
  "message": "Default address: The address you entered was found but more information is needed (such as an apartment, suite, or box number) to match to a specific address."
}

Postcards

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

The postcard object

Arguments

id: string

Unique identifier prefixed with psc_.

description: string or null
metadata: object
to: an address object
from: an address object or null
message: string or null
url: string

A signed S3 link to the rendered postcard.

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.

expected_delivery_date: string

A date in ISO 8601 format of the postcard's expected delivery date.

date_created: string

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

date_modified: string

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

object: string

Value is postcard.

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_fa533435bce2d94d",
    "description": null,
    "metadata": {},
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "California",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.808Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_0654fd1038e46eac",
    "description": null,
    "metadata": {},
    "name": "Ami Wang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Avenue",
    "address_line2": null,
    "address_city": "Seattle",
    "address_state": "Washington",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.821Z",
    "deleted": true,
    "object": "address"
  },
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "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",
  "expected_delivery_date": "2015-05-06",
  "date_created": "2015-04-27T19:01:11.355Z",
  "date_modified": "2015-04-27T19:01:11.427Z",
  "object": "postcard"
}

Create a postcard

Create a new postcard.

Arguments

description: optional
to: required

Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID

from: optional

Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID

front: required

A 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" image to use as the front of the postcard. This can be a URL, local file, or an HTML string. Supported file types are PDF, PNG, and JPEG. For HTML examples, please see Postcard Examples Appendix.

back: optional

Either message or back is required, choose one. A 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" image to use as the back of the postcard, supplied as a URL, local file, or HTML string. This allows you to customize your back design, but we will still insert the recipient address for you. Follow the templates provided here: 4x6 template, 6x9 template, 6x11 template. For HTML examples, please see Postcard Examples Appendix.

data: optional

Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: {{variable_name}}.

message: optional

Either message or back is required, choose one. Max of 350 characters to be included on the back of postcard. If included, we will generate the back based off to, from, and message arguments.

size: optional

Specifies the size of the postcard. Must be either 4x6, 6x9, or 6x11. Defaults to 4x6. Only 4x6 postcards can be sent to international destinations.

metadata: optional

Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a postcard object upon successful creation.

Example Definition

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

Example Request with HTML


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

Example Request with Remote Files


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

Example Request with Local Files


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

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_fa533435bce2d94d",
    "description": null,
    "metadata": {},
    "name": "Harry Zhang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "California",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.808Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_0654fd1038e46eac",
    "description": null,
    "metadata": {},
    "name": "Ami Wang",
    "phone": null,
    "email": null,
    "company": null,
    "address_line1": "123 Test Avenue",
    "address_line2": null,
    "address_city": "Seattle",
    "address_state": "Washington",
    "address_zip": "94041",
    "address_country": "United States",
    "date_created": "2015-04-27T19:01:08.685Z",
    "date_modified": "2015-04-27T19:01:08.821Z",
    "deleted": true,
    "object": "address"
  },
  "message": null,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/psc_14c1b66f31264c34.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "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",
  "expected_delivery_date": "2015-05-06",
  "date_created": "2015-04-27T19:01:11.355Z",
  "date_modified": "2015-04-27T19:01:11.427Z",
  "object": "postcard"
}

Retrieve a postcard

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

Arguments

id: required

The identifier of the postcard to be retrieved.

Returns

Returns a postcard object if a valid identifier was provided.

Example Definition

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

Example Request


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

Example Response


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

List all postcards

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

Arguments

limit: optional

How many results to return, default=10, max 100, must be an integer

offset: optional

Return requested # of items starting with the value, default=0, must be an integer

include: optional

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

metadata: optional

Filter by metadata key-value pair, e.g. metadata[customer_id]=987654

date_created: optional

Filter by ISO-8601 date or datetime, e.g. { gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Letters

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

The letter object

Arguments

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.

url: string

A signed S3 link to the rendered letter.

carrier: string

Value is USPS.

tracking_number: string or null

If the letter is being sent as certified or registered, a tracking number will appear here when it becomes available. Will not be populated for letters created in test mode.

tracking_events: array

An array of tracking_event objects. Will not be populated when extra_service is certified or registered, a tracking_number will be returned instead. Will not be populated for letters created in test mode.

thumbnails: array

Signed S3 links to different sized thumbnails of each letter page.

expected_delivery_date: string

A date in ISO 8601 format of the letter's expected delivery date.

date_created: string

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

date_modified: string

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

object: string

Value is letter.

Example Response


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

Create a letter

Create a new letter.

Arguments

description: optional
to: required

Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.

from: required

Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.

color: required

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

file: required

File can be an HTML string or an 8.5"x11" PDF (uploaded file or URL). For design specifications, please see our PDF and HTML templates. For domestic destinations, the file limit is 60 pages single-sided or 120 pages double-sided. For international destinations, the file limit is 6 pages single-sided or 12 pages double-sided. PDFs that surpass the file limit will error, while HTML that renders more pages than the file limit will be trimmed. See pricing for extra costs incurred.

data: optional

Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: {{variable_name}}.

double_sided: optional

Boolean that defaults to true. Use false to force single-sided printing.

address_placement: optional

Specifies the location of the address information that will show through the double-window envelope. Options are top_first_page and insert_blank_page. Defaults to top_first_page, meaning we will print address information at the top of your provided first page. To see how this will impact your letter design, view our letter template. If you pass insert_blank_page, a blank address page will be inserted at the beginning of your file and you will be charged for the extra page.

return_envelope: optional

Boolean. Set this key to true and specify the perforated_page if you would like to include a return envelope with your letter. See pricing for extra costs incurred.

perforated_page: optional

Required if return_envelope is true. Number of the page that should be perforated for use with return_envelope. Must be greater than or equal to 1. To see how perforation will impact your letter design, view our perforation guide.

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.

metadata: optional

Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a letter object upon successful creation.

Example Definition

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

Example Request with HTML


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

Example Request with Remote File


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

Example Request with Local File


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

Example Response


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

Retrieve a letter

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

Arguments

id: required

The identifier of the letter to be retrieved.

Returns

Returns a letter object if a valid identifier was provided.

Example Definition

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

Example Request


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

Example Response


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

List all letters

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

Arguments

limit: optional

How many results to return, default=10, max 100, must be an integer

offset: optional

Return requested # of items starting with the value, default=0, must be an integer

include: optional

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

metadata: optional

Filter by metadata key-value pair, e.g. metadata[customer_id]=987654

date_created: optional

Filter by ISO-8601 date or datetime, e.g. { gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Checks

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

The check object

Arguments

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.

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

If the check is being sent as ups_next_day_air, a tracking number will appear here when it becomes available. Will not be populated for checks created in test mode.

tracking_events: array

An array of tracking_event objects. Will not be populated when mail_type is ups_next_day_air, a tracking_number will be returned instead. Will not be populated for checks created in test mode.

thumbnails: array

Signed S3 links to different sized thumbnails of each check page.

expected_delivery_date: string

A date in ISO 8601 format of the check's expected delivery date.

mail_type: string

Value is usps_first_class or ups_next_day_air.

date_created: string

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

date_modified: string

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

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

Create a check

Create a new check.

Arguments

description: optional
to: required

Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.

from: required

Must either be an address ID or an object with correct address parameters. If an object is used, an address will be created for you and returned with an ID.

bank_account: required

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

amount: required

The payment amount to be sent in dollars. Must be less than 1000000.

memo: optional

Max of 40 characters to be included on the memo line of the check.

check_number: optional

Checks will default starting at 10000 and increment accordingly.

logo: optional

This can be a URL or local file. The image must be a square, have color model of RGB or CMYK, be at least 100px X 100px, and have a transparent background. The accepted file types are PNG and JPEG. If supplied, the logo is printed in grayscale and placed in the upper-left corner of the check.

message: optional

Either message or check_bottom, choose one. Max of 400 characters to be included at the bottom of the check page.

check_bottom: optional

Either message or file, choose one. This can be a local file or a URL to a 1 page 8.5"x11" PDF, PNG, or JPEG, or an HTML string. This will be printed on the bottom of the check page in black & white. You must follow this template.

attachment: optional

A document to include with the check. This can be a local file or a URL to an 8.5"x11" PDF, PNG, or JPEG, or an HTML string. This will be printed double-sided in black & white and will be included in the envelope after the check page. If a PDF is provided, it must be 6 pages or fewer. If HTML is provided that renders to more than 6 pages, it will be trimmed. Please follow these design guidelines. See pricing for extra costs incurred.

data: optional

Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: {{variable_name}}.

mail_type: optional

A string designating the mail postage type. Options are usps_first_class or ups_next_day_air. Defaults to usps_first_class. See pricing for extra costs incurred for ups_next_day_air.

metadata: optional

Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a check object upon successful creation.

Example Definition

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

Example Request with HTML


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

Example Request with Remote Files


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

Example Request with Local Files


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

Example Response


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

Retrieve a check

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

Arguments

id: required

The identifier of the check to be retrieved.

Returns

Returns a check object if a valid identifier was provided.

Example Definition

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

Example Request


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

Example Response


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

List all checks

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

Arguments

limit: optional

How many results to return, default=10, max 100, must be an integer

offset: optional

Return requested # of items starting with the value, default=0, must be an integer

include: optional

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

metadata: optional

Filter by metadata key-value pair, e.g. metadata[customer_id]=987654

date_created: optional

Filter by ISO-8601 date or datetime, e.g. { gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

to: optional

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Bank Accounts

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

The bank account object

Arguments

id: string

Unique identifier prefixed with bank_.

description: string or null
metadata: object
routing_number: string
account_number: string
account_type: string

Value is company or individual.

signatory: string
signature_url: string or null

A signed S3 link to the signature image.

bank_name: string

The name of the bank based on the provided routing number, e.g. JPMORGAN CHASE BANK.

verified: boolean
date_created: string

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

date_modified: string

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

object: string

Value is bank_account.

Example Response


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

Create a bank account

Create a new bank account. Bank accounts created in live mode will need to be verified via micro deposits before being able to send live checks. The deposits will appear in the bank account in 2-3 business days and have the description "VERIFICATION".

Arguments

description: optional
routing_number: required

The bank's routing number

account_number: required

The account number at the bank

account_type: required

The type of entity that holds the account. Must be either company or individual.

signatory: required

The signatory associated with your account. This name will be printed on checks created with the bank account. If you prefer to use a custom signature image on your checks instead, please create your bank account from the Dashboard.

metadata: optional

Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a bank object upon successful creation.

Example Definition

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

Example Request


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

Example Response


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

Retrieve a bank account

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

Arguments

id: required

The identifier of the bank account to be retrieved.

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Delete a bank account

Permanently deletes a bank account. It cannot be undone.

Arguments

id: required

The identifier of the bank account to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request


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

Example Response


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

Verify a bank account

Verify a bank account in order to create a check.

Arguments

amounts: required

In live mode, an array containing the two micro deposits (in cents) placed in the bank account. In test mode, no micro deposits will be placed - use any two integers between 1 and 100

Returns

Returns a bank account object upon successful verification.

Example Definition

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

Example Request


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

Example Response


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

List all bank accounts

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

Arguments

limit: optional

How many results to return, default=10, max 100, must be an integer

offset: optional

Return requested # of items starting with the value, default=0, must be an integer

include: optional

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

metadata: optional

Filter by metadata key-value pair, e.g. metadata[customer_id]=987654

date_created: optional

Filter by ISO-8601 date or datetime, e.g. { gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Areas

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

The area object

Arguments

id: string

Unique identifier prefixed with area_.

description: string or null
metadata: object
price: decimal

Price of the area mailing based on the number of addresses.

url: string

A signed S3 link to the rendered area mail.

target_type: string

Value is all or residential.

addresses: integer

Number of addresses included in the area mailing based on the routes chosen and target_type

zip_codes: array

An array of objects with the property routes, which is an array of route objects.

thumbnails: array

Signed S3 links to different sized thumbnails of each area mail page.

expected_delivery_date: string

A date in ISO 8601 format of the area mail's expected delivery date.

trackings: array or null

An array of objects with tracking_number and carrier properties. Each object represents a package that can be tracked using the specified tracking_number via the respective carrier's online tool. These objects will appear here as they become available. Will not be populated for areas created in test mode.

date_created: string

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

date_modified: string

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

object: string

Value is area.

Example Response


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

Create an area mailing

Create a new mailing for a specific zip or delivery routes

Arguments

description: optional
routes: required

Must enter a zip code or delivery route. This can be an array of zip codes or delivery routes.

target_type: optional

A string designating the target recipients. Options are all and residential. Defaults to all.

front: required

A 6.25"x11.25" image that will be the front of the postcard. This can be a URL, local file, or an HTML string. Supported file types are PDF, PNG, and JPEG. For HTML examples, please see Area Examples Appendix.

back: required

A 6.25"x11.25" image that will be the back of the postcard. Follow this template when creating your artwork. This can be a URL, local file, or an HTML string. Supported file types are PDF, PNG, and JPEG. For HTML examples, please see Area Examples Appendix.

data: optional

Must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. For parameters that accept HTML strings, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML like so: {{variable_name}}.

metadata: optional

Must be an object with up to 20 key-value pairs. Keys must at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns an area object upon successful creation.

Example Definition

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

Example Request with HTML Front


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

Example Request with Remote Files


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

Example Request with Local Files


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

Example Response


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

Retrieve an area mailing

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

Arguments

id: required

The identifier of the area mail to be retrieved.

Returns

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

Example Definition

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

Example Request


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

Example Response


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

List all area mailings

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

Arguments

limit: optional

How many results to return, default=10, max 100, must be an integer

offset: optional

Return requested # of items starting with the value, default=0, must be an integer

include: optional

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

metadata: optional

Filter by metadata key-value pair, e.g. metadata[customer_id]=987654

date_created: optional

Filter by ISO-8601 date or datetime, e.g. { gt: '2012-01-01', lt: '2012-01-31T12:34:56Z' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

A dictionary with a data property that contains an array of up to <code>limit</code> area mailings, starting at index <code>offset</code>. 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

Arguments

route: string

1 letter and 3 numbers designating the carrier route.

residential: integer

An integer representing the number of residential addresses in the route.

business: integer

An integer representing the number of business addresses in the route.

median_income: integer or null

An integer representing the median income in dollars of residents in the route (based on 2010 census data). Not returned when nested within area responses.

age_20_24: integer or null

An integer representing the number of residents between ages 20 and 24 in the route (based on 2010 census data). Not returned when nested within area responses.

age_25_34: integer or null

An integer representing the number of residents between ages 25 and 34 in the route (based on 2010 census data). Not returned when nested within area responses.

age_35_44: integer or null

An integer representing the number of residents between ages 35 and 44 in the route (based on 2010 census data). Not returned when nested within area responses.

age_45_54: integer or null

An integer representing the number of residents between ages 45 and 54 in the route (based on 2010 census data). Not returned when nested within area responses.

age_55_64: integer or null

An integer representing the number of residents between ages 55 and 64 in the route (based on 2010 census data). Not returned when nested within area responses.

age_65_74: integer or null

An integer representing the number of residents between ages 65 and 74 in the route (based on 2010 census data). Not returned when nested within area responses.

age_75_84: integer or null

An integer representing the number of residents between ages 75 and 84 in the route (based on 2010 census data). Not returned when nested within area responses.

age_lt_19: integer or null

An integer representing the number of residents younger than 19 in the route (based on 2010 census data). Not returned when nested within area responses.

age_gt_85: integer or null

An integer representing the number of residents older than 85 in the route (based on 2010 census data). Not returned when nested within area responses.

median_age: integer or null

An integer representing the median age of residents in the route (based on 2010 census data). Not returned when nested within area responses.

avg_household_size: decimal or null

A decimal representing the average household size of the route (based on 2010 census data). Not returned when nested within area responses.

object: string

Value is route.

Example Response

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

Retrieve routes for a zip code

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

Arguments

zip_code: required

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

Returns

Returns an array of route objects.

Example Definition

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

Example Request


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

Example Response


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

List all routes

Filters by the zip codes or zip-routes requested.

Arguments

zip_codes: required

The zip codes or zip-routes to filter by.

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Countries

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

List all countries

Returns a list of all currently supported countries. You can use these when submitting addresses, jobs, and verification requests.

Returns

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

Example Definition

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

Example Request


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

Example Response


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

States

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

List all states

Returns a list of all US states. You can use these when submitting addresses, jobs, and verification requests.

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Changelog

2016-06-30

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

2016-05-02

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

2016-03-21

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

2016-01-19

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

2015-12-22

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

2015-11-23

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

2015-11-06

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

2015-10-21

  • use the new HTML renderer for all products

2015-06-25

  • remove the status field from all endpoints

2015-04-11

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

2014-12-18

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

The tracking event object

Arguments

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

HTML Examples

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

Please follow the standards used in these templates, such as:

  • For any linked assets, you must use a performant file hosting provider with no rate limits such as Amazon S3.
  • Use inline styles or an internal stylesheet, do not link to external stylesheets.
  • Link to images that are 300DPI and sized at the final desired size on the physical mailing. For example, for a photo that is desired to be 1in x 1in on the final postcard, the image asset should be sized at 1in x 1in at 300DPI (which equates to 300px by 300px).
  • The sum of all linked assets should not exceed 5MB in file size.

Because different browsers have varying user-agent styles, the HTML you see in your browser will not always look identical to what is produced through the API. It is strongly recommended that you test all HTML requests by reviewing the final PDF files in your Test Environment, as these are the files that will be printed.

Postcard 4x6 Front Example

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


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

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

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

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

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

</html>

Postcard 4x6 Back Example

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


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

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

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

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

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

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

</html>

Postcard 6x9 Front Example

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


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

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

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

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

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

</html>

Postcard 6x9 Back Example

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


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

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

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

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

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

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

</html>

Postcard 6x11 Front Example

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


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

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

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

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

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

</html>

Postcard 6x11 Back Example

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


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

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

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

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

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

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

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

</html>

Letter Example

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


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

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

  .page {
    page-break-after: always;
  }

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

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

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

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

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

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

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

</style>
</head>

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

</html>

Check Example

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


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

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

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

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

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

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

</html>

Area Mail Front Example

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


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

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

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

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

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

</html>

Area Mail Back Example

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


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

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

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

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

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

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

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

</html>

Image Prepping

Currently we support the following file types for all endpoints:

  • PDF
  • PNG
  • JPEG

Templates

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

Prepping All Images

The following guidelines apply to image types:

  • Images should be 300 dpi or higher - PNG/JPEG files with less than 300 dpi will be rejected
  • Your artwork should include a 1/8" border around the final trim size. This means your final file size will be a total of 0.25" larger than your expected printed piece (ie, a 4"x6" postcard should be submitted as 4.25"x6.25")
  • Include a safe zone – make sure no critical elements are within 1/8" from the edge of the final size.

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