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.

Create an address

Creates a new address object

Arguments

description:
optional
name:
optional

Either name or company is required, you may also add both. Must be no longer than 50 characters.

company:
optional

Either name or company is required, you may also add both. Must be no longer than 200 characters.

address_line1:
required
address_line2:
optional
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.

address_state:
optional

Required and must be a 2 letter state short-name code if address_country is US, otherwise optional.

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.

phone:
optional
email:
optional
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",
  "metadata": {},
  "name": "Harry Zhang",
  "phone": "5555555555",
  "email": "harry@lob.com",
  "company": "Lob",
  "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-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 date, e.g. { gt: '2012-01-01', lt: '2012-01-31' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


{
  "data": [
    {
      "id": "adr_b8fb5acf3a2b55db",
      "description": null,
      "metadata": {},
      "name": "TestAddress",
      "phone": null,
      "email": "test@test.com",
      "company": null,
      "address_line1": "123 Test Street",
      "address_line2": "Unit 199",
      "address_city": "Mountain View",
      "address_state": "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.

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" 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" 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 and 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 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",
  "date_created": "2015-04-27T19:01:11.355Z",
  "date_modified": "2015-04-27T19:01:11.427Z",
  "expected_delivery_date": "2015-05-06",
  "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 date, e.g. { gt: '2012-01-01', lt: '2012-01-31' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


{
  "data": [
    {
      "id": "psc_2a379c909c5d6341",
      "description": "Demo Postcard Job",
      "metadata": {},
      "to": {
        "id": "adr_ca878b465496f4d4",
        "description": null,
        "metadata": {},
        "name": "Harry Zhang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "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.

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",
  "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",
  "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 date, e.g. { gt: '2012-01-01', lt: '2012-01-31' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


{
  "data": [
    {
      "id": "ltr_b6bfe21858208b46",
      "description": "Demo Letter",
      "metadata": {},
      "to": {
        "id": "adr_d1a4f3b35e673847",
        "description": null,
        "name": "Harry Zhang",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "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.

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.

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,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "message": null,
  "to": {
    "id": "adr_f3fa41cd6cb2a875",
    "description": null,
    "name": "Harry Zhang",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "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",
  "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": 2200,
  "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_534f10783683daa0.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449430428&Signature=j%2FTzUuHJkrlbAJZGNpCm3xfxgmE%3D",
  "message": null,
  "to": {
    "id": "adr_f3fa41cd6cb2a875",
    "description": null,
    "name": "Harry Zhang",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "123 Test Street",
    "address_line2": null,
    "address_city": "Mountain View",
    "address_state": "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",
  "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 date, e.g. { gt: '2012-01-01', lt: '2012-01-31' } 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 count checks, starting at index offset. Each entry in the array is a separate check object. If no more checks are available, the resulting array will be empty.

Example Definition

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

Example Request


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

Example Response


{
  "data": [
    {
      "id": "chk_fa2d38a6f0ce638e",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 10006,
      "memo": "rent",
      "amount": 2200,
      "message": null,
      "url": "https://s3-us-west-2.amazonaws.com/assets.lob.com/chk_fa2d38a6f0ce638e.pdf?AWSAccessKeyId=AKIAJVT3IPSNH662QU6A&Expires=1449690126&Signature=IPjMermP%2FKwQRRh4x9Z5411Sdik%3D",
      "to": {
        "id": "adr_1673bbd26e2f9b3a",
        "description": null,
        "name": "Harry Zhang",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "123 Test Street",
        "address_line2": null,
        "address_city": "Mountain View",
        "address_state": "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",
      "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",
      "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.

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.

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",
  "signatory": "John Doe",
  "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
  "account_type": "company",
  "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 date, e.g. { gt: '2012-01-01', lt: '2012-01-31' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Areas

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

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 date, e.g. { gt: '2012-01-01', lt: '2012-01-31' } where gt is ›, lt is ‹, gte is ≥, and lte is ≤

Returns

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

Example Definition

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

Example Request


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

Example Response


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

Routes

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

Retrieve 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

Returns an array of route objects.

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

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