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.

API endpoint

https://api.lob.com/

Summary of Resource URL Patterns

  • /v1/addresses
  • /v1/addresses/{ADDRESS_ID}
  • /v1/verify
  • /v1/postcards
  • /v1/postcards/{POSTCARD_ID}
  • /v1/letters
  • /v1/letters/{LETTER_ID}
  • /v1/checks
  • /v1/checks/{CHECK_ID}
  • /v1/bank_accounts
  • /v1/bank_accounts/{BANK_ACCOUNTS_ID}
  • /v1/jobs
  • /v1/jobs/{JOB_ID}
  • /v1/objects
  • /v1/objects/{OBJECT_ID}
  • /v1/settings
  • /v1/settings/{SETTING_ID}
  • /v1/countries
  • /v1/states

Authentication

In order to use the API you must you send your API key in the request. Your API keys are listed in your Settings on your Dashboard. No password is required.

Example Request

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

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.

Versioning

When backwards-incompatible changes are made to the API, a new dated version is released. The latest version of the API is version 2015-04-11. 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.

Example Request

    
    curl https://api.lob.com/v1/addresses \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
      -H "Lob-Version: 2015-04-11"
    
    

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
404 - Not Found The requested item does not exist
422 - Bad Request Some sort of error with the provided inputs
500 - Server Error Something is wrong on Lob's end

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 -X GET "https://api.lob.com/v1/postcards?metadata[campaign]=NEWYORK2015&count=2&offset=0" \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
    
    

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

Must be no longer than 50 characters

company:
optional
email:
optional
phone:
optional

Recommended to include as sometimes mail carriers require phone number to ensure delivery (PO Boxes required)

address_line1:
required
address_line2:
optional
address_city:
required

Optional in some countries

address_state:
required

Optional in some countries

address_zip:
required

Optional in some countries

address_country:
required

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

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

Returns

Returns a 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/{ADDRESS_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.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request

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

Example Response

    
    {
      "message": "Success! Address has been deleted"
    }
    
    

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

count:
optional

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

include:
optional

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

metadata:
optional

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

Example Definition

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

Example Request

    
    curl -X GET "https://api.lob.com/v1/addresses/?count=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,
      "next_url": "https://api.lob.com/v1/addresses?count=2&offset=3",
      "previous_url": null,
      "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 an address given.

Arguments

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

Returns

If address is valid, returns the address object (some data can be missing and will still return an address) and a message if any additional information is needed (ie. Apt#, etc.) for an exact match.

Example Definition

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

Example Request

    
    curl https://api.lob.com/v1/verify \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
      -d "address_line1=220 William T Morrissey Boulevard" \
      -d "address_city=Boston" \
      -d "address_state=MA" \
      -d "address_zip=02125"
    
    

Example Response

    
    {
      "address": {
          "address_line1": "220 WILLIAM T MORRISSEY BLVD",
          "address_line2": "",
          "address_city": "BOSTON",
          "address_state": "MA",
          "address_zip": "02125-3314",
          "address_country": "US",
          "object": "address"
      }
    }
    
    

Postcards

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

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.

message:
required (either message or back, 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.

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:
required (either message or back, 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.

setting:
optional

When providing a front or back in PDF, PNG or JPEG, the setting is auto-detected based on the dimensions of the file. When supplying a front or back in HTML, use the setting 1001 for 4x6 (default) or setting 1002 for 6x11.

data:
optional

When providing a front or back as an HTML string, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML: {{variable_name}}.

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

Returns

Returns a postcard object upon successful creation.

Example Definition

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

Example Request with HTML Front

    
    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=https://lob.com/postcardback.pdf" \
      -d "data[name]=Harry"
    
    

Example Request with Remote File

    
    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 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,
      "status": "processed",
      "price": "0.70",
      "url": "http://assets.lob.com/psc_14c1b66f31264c34.pdf",
      "tracking": {
        "id": "trk_5b4ac787b7f956ea",
        "tracking_number": "901397106123456",
        "carrier": "USPS",
        "link": null,
        "events": [],
        "object": "tracking"
      },
      "thumbnails": [
        {
          "small": "http://assets.lob.com/psc_14c1b66f31264c34_thumb_small_1.png",
          "medium": "http://assets.lob.com/psc_14c1b66f31264c34_thumb_medium_1.png",
          "large": "http://assets.lob.com/psc_14c1b66f31264c34_thumb_large_1.png"
        },
        {
          "small": "http://assets.lob.com/psc_14c1b66f31264c34_thumb_small_2.png",
          "medium": "http://assets.lob.com/psc_14c1b66f31264c34_thumb_medium_2.png",
          "large": "http://assets.lob.com/psc_14c1b66f31264c34_thumb_large_2.png"
        }
      ],
      "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/{POSTCARD_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,
      "status": "processed",
      "price": "0.70",
      "url": "http://assets.lob.com/psc_5c002b86ce47537a.pdf",
      "tracking": {
        "id": "trck_64ec00ef2a050b3",
        "tracking_number": "No Tracking Available",
        "carrier": "USPS",
        "link": null,
        "events": [],
        "object": "tracking"
      },
      "thumbnails": [
        {
          "small": "http://assets.lob.com/psc_5c002b86ce47537a_thumb_small_1.png",
          "medium": "http://assets.lob.com/psc_5c002b86ce47537a_thumb_medium_1.png",
          "large": "http://assets.lob.com/psc_5c002b86ce47537a_thumb_large_1.png"
        },
        {
          "small": "http://assets.lob.com/psc_5c002b86ce47537a_thumb_small_2.png",
          "medium": "http://assets.lob.com/psc_5c002b86ce47537a_thumb_medium_2.png",
          "large": "http://assets.lob.com/psc_5c002b86ce47537a_thumb_large_2.png"
        }
      ],
      "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 postcards are returned sorted by creation date, with the most recently created postcards appearing first.

Arguments

count:
optional

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

offset:
optional

Return requested # of items starting 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[campaign]=NEWYORK2015.

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?count=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,
          "status": "processed",
          "price": "0.70",
          "url": "http://assets.lob.com/psc_2a379c909c5d6341.pdf",
          "tracking": {
            "id": "trk_3b1b5ade5ba278fb",
            "tracking_number": "901397106123456",
            "carrier": "USPS",
            "link": null,
            "events": [],
            "object": "tracking"
          },
          "thumbnails": [
            {
              "small": "http://assets.lob.com/psc_2a379c909c5d6341_thumb_small_1.png",
              "medium": "http://assets.lob.com/psc_2a379c909c5d6341_thumb_medium_1.png",
              "large": "http://assets.lob.com/psc_2a379c909c5d6341_thumb_large_1.png"
            },
            {
              "small": "http://assets.lob.com/psc_2a379c909c5d6341_thumb_small_2.png",
              "medium": "http://assets.lob.com/psc_2a379c909c5d6341_thumb_medium_2.png",
              "large": "http://assets.lob.com/psc_2a379c909c5d6341_thumb_large_2.png"
            }
          ],
          "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,
          "status": "processed",
          "price": "0.70",
          "url": "http://assets.lob.com/psc_66a94c0e4b004efd.pdf",
          "tracking": {
            "id": "trk_1617040b36c71c87",
            "tracking_number": "901397106123456",
            "carrier": "USPS",
            "link": null,
            "events": [],
            "object": "tracking"
          },
          "thumbnails": [
            {
              "small": "http://assets.lob.com/psc_66a94c0e4b004efd_thumb_small_1.png",
              "medium": "http://assets.lob.com/psc_66a94c0e4b004efd_thumb_medium_1.png",
              "large": "http://assets.lob.com/psc_66a94c0e4b004efd_thumb_large_1.png"
            },
            {
              "small": "http://assets.lob.com/psc_66a94c0e4b004efd_thumb_small_2.png",
              "medium": "http://assets.lob.com/psc_66a94c0e4b004efd_thumb_medium_2.png",
              "large": "http://assets.lob.com/psc_66a94c0e4b004efd_thumb_large_2.png"
            }
          ],
          "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,
      "next_url": "https://api.lob.com/v1/postcards?count=2&offset=2",
      "previous_url": null,
      "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.

file:
required

File can be an HTML string or an 8.5"x11" PDF (uploaded file or URL). The first page of your file must follow the Lob address template unless specified otherwise by using the template parameter. For HTML examples, please see Letter Examples Appendix.

data:
optional

When providing a file as an HTML string, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML: {{variable_name}}.

color:
required

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

extra_service:
optional

Add an extra service to your letter. Options are "certified" or "registered". Certified provides tracking and delivery confirmation for domestic destinations, and is an additional $5.00. Registered provides tracking and confirmation for international addresses, and is an additional $16.50.

double_sided:
optional

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

template:
optional

Boolean that defaults to true. When set to false, this specifies that your letter does not follow the Lob address template. In this case, a blank address page will be inserted at the beginning of your file and you will be charged for the extra page.

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

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,
      "pages": 1,
      "template": true,
      "price": 1.15,
      "status": "processed",
      "url": "http://assets.lob.com/ltr_4868c3b754655f90.pdf",
      "tracking": {
        "events": [],
        "object": "tracking"
      },
      "extra_service": null,
      "thumbnails": [
        {
          "small": "http://assets.lob.com/ltr_4868c3b754655f90_thumb_small_1.png",
          "medium": "http://assets.lob.com/ltr_4868c3b754655f90_thumb_medium_1.png",
          "large": "http://assets.lob.com/ltr_4868c3b754655f90_thumb_large_1.png"
        }
      ],
      "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/{LETTER_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,
      "pages": 1,
      "template": true,
      "price": 1.15,
      "status": "processed",
      "url": "http://assets.lob.com/ltr_4868c3b754655f90.pdf",
      "tracking": {
        "events": [],
        "object": "tracking"
      },
      "extra_service": null,
      "thumbnails": [
        {
          "small": "http://assets.lob.com/ltr_4868c3b754655f90_thumb_small_1.png",
          "medium": "http://assets.lob.com/ltr_4868c3b754655f90_thumb_medium_1.png",
          "large": "http://assets.lob.com/ltr_4868c3b754655f90_thumb_large_1.png"
        }
      ],
      "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

count:
optional

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

offset:
optional

Return requested # of items starting 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[campaign]=NEWYORK2015.

Returns

A dictionary 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?count=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,
          "pages": 1,
          "template": true,
          "price": "1.15",
          "status": "processed",
          "url": "http://assets.lob.com/ltr_b6bfe21858208b46.pdf",
          "tracking": {
            "events": [],
            "object": "tracking"
          },
          "extra_service": null,
          "thumbnails": [
            {
              "small": "http://assets.lob.com/ltr_b6bfe21858208b46_thumb_small_1.png",
              "medium": "http://assets.lob.com/ltr_b6bfe21858208b46_thumb_medium_1.png",
              "large": "http://assets.lob.com/ltr_b6bfe21858208b46_thumb_large_1.png"
            }
          ],
          "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,
          "pages": 1,
          "template": true,
          "price": "1.15",
          "status": "processed",
          "url": "http://assets.lob.com/ltr_8ea22b5354337084.pdf",
          "tracking": {
            "events": [],
            "object": "tracking"
          },
          "extra_service": null,
          "thumbnails": [
            {
              "small": "http://assets.lob.com/ltr_8ea22b5354337084_thumb_small_1.png",
              "medium": "http://assets.lob.com/ltr_8ea22b5354337084_thumb_medium_1.png",
              "large": "http://assets.lob.com/ltr_8ea22b5354337084_thumb_large_1.png"
            }
          ],
          "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,
      "next_url": "https://api.lob.com/v1/letters?count=2&offset=2",
      "previous_url": null,
      "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
check_number:
optional

Checks will default starting at 10000 and increment accordingly.

bank_account:
required

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

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

amount:
required

The payment amount to be sent

memo:
optional

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

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 file, choose one)

Max of 400 characters to be included at the bottom of the check page.

file:
optional (either message or file, choose one)

This can be a URL or local file 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.

data:
optional

When providing a file as an HTML string, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML: {{variable_name}}.

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

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 "bank_account=bank_dfceb4a2a05b57e" \
      -d "amount=2200" \
      -d "memo=rent" \
      --data-urlencode "logo=https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png" \
      --data-urlencode "file=<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 "bank_account=bank_dfceb4a2a05b57e" \
      -d "amount=2200" \
      -d "memo=rent" \
      --data-urlencode "logo=https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png" \
      --data-urlencode "file=https://s3-us-west-2.amazonaws.com/lob-assets/check-file-example.pdf"
    
    

Example Response

    
    {
      "id": "chk_be06e868f1aa19dd",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 10000,
      "memo": "rent",
      "amount": "2200.00",
      "message": null,
      "price": "1.50",
      "status": "processed",
      "url": "http://assets.lob.com/chk_be06e868f1aa19dd.pdf",
      "to": {
        "id": "adr_968cb67283a9ad19",
        "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:32:40.136Z",
        "date_modified": "2015-04-27T21:32:40.136Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_dfceb4a2a05b57e",
        "description": null,
        "metadata": {},
        "routing_number": "123456789",
        "account_number": "123456789",
        "signatory": Leore Avidar,
        "bank_address": {
          "id": "adr_7634570f6d91feef",
          "description": null,
          "name": "CHASE BANK",
          "phone": null,
          "email": null,
          "company": null,
          "address_line1": "55 EDMONDS",
          "address_line2": null,
          "address_city": "PALO ALTO",
          "address_state": "California",
          "address_zip": "90081",
          "address_country": "United States",
          "metadata": {},
          "date_created": "2013-10-06T01:03:56.000Z",
          "date_modified": "2013-10-06T01:03:56.000Z",
          "object": "address"
        },
        "account_address": {
          "id": "adr_eae4448bb64c07f0",
          "description": null,
          "name": "LEORE AVIDAR",
          "phone": null,
          "email": null,
          "company": 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"
        },
        "verified": true,
        "date_created": "2013-10-06T01:03:56.000Z",
        "date_modified": "2015-04-27T21:32:05.889Z",
        "object": "bank_account"
      },
      "tracking": {
        "id": "trk_92041ad623316709",
        "tracking_number": "901519773123456",
        "carrier": "USPS",
        "link": null,
        "events": [],
        "object": "tracking"
      },
      "thumbnails": [
        {
          "small": "http://assets.lob.com/chk_be06e868f1aa19dd_thumb_small_1.png",
          "medium": "http://assets.lob.com/chk_be06e868f1aa19dd_thumb_medium_1.png",
          "large": "http://assets.lob.com/chk_be06e868f1aa19dd_thumb_large_1.png"
        }
      ],
      "expected_delivery_date": "2015-05-05",
      "date_created": "2015-04-27T21:32:40.674Z",
      "date_modified": "2015-04-27T21:32:40.674Z",
      "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/{CHECK_ID}

Example Request

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

Example Response

    
    {
      "id": "chk_232aa33fcada28ca",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 10000,
      "memo": "rent",
      "amount": "2200.00",
      "message": null,
      "price": "1.50",
      "status": "processed",
      "url": "http://assets.lob.com/chk_232aa33fcada28ca.pdf",
      "to": {
        "id": "adr_968cb67283a9ad19",
        "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:32:40.136Z",
        "date_modified": "2015-04-27T21:32:40.136Z",
        "deleted": true,
        "object": "address"
      },
      "bank_account": {
        "id": "bank_dfceb4a2a05b57e",
        "description": null,
        "metadata": {},
        "routing_number": "123456789",
        "account_number": "123456789",
        "signatory": Leore Avidar,
        "bank_address": {
          "id": "adr_7634570f6d91feef",
          "description": null,
          "name": "CHASE BANK",
          "phone": null,
          "email": null,
          "company": null,
          "address_line1": "55 EDMONDS",
          "address_line2": null,
          "address_city": "PALO ALTO",
          "address_state": "California",
          "address_zip": "90081",
          "address_country": "United States",
          "metadata": {},
          "date_created": "2013-10-06T01:03:56.000Z",
          "date_modified": "2013-10-06T01:03:56.000Z",
          "object": "address"
        },
        "account_address": {
          "id": "adr_eae4448bb64c07f0",
          "description": null,
          "name": "LEORE AVIDAR",
          "phone": null,
          "email": null,
          "company": 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"
        },
        "verified": true,
        "date_created": "2013-10-06T01:03:56.000Z",
        "date_modified": "2015-04-27T21:32:05.889Z",
        "object": "bank_account"
      },
      "tracking": {
        "id": "trk_92041ad623316709",
        "tracking_number": "901519773123456",
        "carrier": "USPS",
        "link": null,
        "events": [],
        "object": "tracking"
      },
      "thumbnails": [
        {
          "small": "http://assets.lob.com/chk_232aa33fcada28ca_thumb_small_1.png",
          "medium": "http://assets.lob.com/chk_232aa33fcada28ca_thumb_medium_1.png",
          "large": "http://assets.lob.com/chk_232aa33fcada28ca_thumb_large_1.png"
        }
      ],
      "expected_delivery_date": "2015-05-05",
      "date_created": "2015-04-27T21:32:40.674Z",
      "date_modified": "2015-04-27T21:32:40.674Z",
      "object": "check"
    }
    
    

List all checks

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

Arguments

count:
optional

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

offset:
optional

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

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

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?count=2&offset=0" \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
    
    

Example Response

    
    {
      "data": [
        {
          "id": "chk_9164867519921920",
          "description": "Demo Check",
          "metadata": {},
          "check_number": 362348,
          "memo": "rent",
          "amount": "2200.00",
          "message": null,
          "price": "1.50",
          "status": "processed",
          "url": "http://assets.lob.com/chk_9164867519921920.pdf",
          "to": {
            "id": "adr_60d1b21e9e4fe69f",
            "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:33:51.428Z",
            "date_modified": "2015-04-27T21:33:51.428Z",
            "deleted": true,
            "object": "address"
          },
          "bank_account": {
            "id": "bank_3e64d9904356b20",
            "description": null,
            "metadata": {},
            "routing_number": "123456789",
            "account_number": "123456789",
            "signatory": Leore Avidar,
            "bank_address": {
              "id": "adr_0e418aa8d1eb41fb",
              "description": null,
              "name": "CHASE BANK",
              "phone": null,
              "email": null,
              "company": null,
              "address_line1": "55 EDMONDS",
              "address_line2": null,
              "address_city": "PALO ALTO",
              "address_state": "California",
              "address_zip": "90081",
              "address_country": "United States",
              "metadata": {},
              "date_created": "2013-10-06T00:52:26.000Z",
              "date_modified": "2013-10-06T00:52:26.000Z",
              "object": "address"
            },
            "account_address": {
              "id": "adr_e52f199b76590ed7",
              "description": null,
              "name": "LEORE AVIDAR",
              "phone": null,
              "email": null,
              "company": 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-06T00:52:26.000Z",
              "date_modified": "2013-10-06T00:52:26.000Z",
              "object": "address"
            },
            "verified": true,
            "date_created": "2013-10-06T00:52:26.000Z",
            "date_modified": "2015-04-17T23:27:45.608Z",
            "object": "bank_account"
          },
          "tracking": {
            "id": "trk_b75b209cb8b399d8",
            "tracking_number": "901519773123456",
            "carrier": "USPS",
            "link": null,
            "events": [],
            "object": "tracking"
          },
          "thumbnails": [
            {
              "small": "http://assets.lob.com/chk_9164867519921920_thumb_small_1.png",
              "medium": "http://assets.lob.com/chk_9164867519921920_thumb_medium_1.png",
              "large": "http://assets.lob.com/chk_9164867519921920_thumb_large_1.png"
            }
          ],
          "expected_delivery_date": "2015-05-05",
          "date_created": "2015-04-27T21:33:51.494Z",
          "date_modified": "2015-04-27T21:32:03.821Z",
          "object": "check"
        },
        {
          "id": "chk_c1b37993c0d1a580",
          "description": "Demo Check",
          "metadata": {},
          "check_number": 362347,
          "memo": "rent",
          "amount": "2200.00",
          "message": null,
          "price": "1.50",
          "status": "processed",
          "url": "http://assets.lob.com/chk_c1b37993c0d1a580.pdf",
          "to": {
              "id": "adr_def141c015342567",
              "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:33:29.654Z",
              "date_modified": "2015-04-27T21:33:29.654Z",
              "deleted": true,
              "object": "address"
          },
          "bank_account": {
            "id": "bank_3e64d9904356b20",
            "description": null,
            "metadata": {},
            "routing_number": "123456789",
            "account_number": "123456789",
            "signatory": Leore Avidar,
            "bank_address": {
              "id": "adr_0e418aa8d1eb41fb",
              "description": null,
              "name": "CHASE BANK",
              "phone": null,
              "email": null,
              "company": null,
              "address_line1": "55 EDMONDS",
              "address_line2": null,
              "address_city": "PALO ALTO",
              "address_state": "California",
              "address_zip": "90081",
              "address_country": "United States",
              "metadata": {},
              "date_created": "2013-10-06T00:52:26.000Z",
              "date_modified": "2013-10-06T00:52:26.000Z",
              "object": "address"
            },
            "account_address": {
              "id": "adr_e52f199b76590ed7",
              "description": null,
              "name": "LEORE AVIDAR",
              "phone": null,
              "email": null,
              "company": 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-06T00:52:26.000Z",
              "date_modified": "2013-10-06T00:52:26.000Z",
              "object": "address"
            },
            "verified": true,
            "date_created": "2013-10-06T00:52:26.000Z",
            "date_modified": "2015-04-17T23:27:45.608Z",
            "object": "bank_account"
          },
          "tracking": {
            "id": "trk_b2ff9f048b14e1a6",
            "tracking_number": "901519773123456",
            "carrier": "USPS",
            "link": null,
            "events": [],
            "object": "tracking"
          },
          "thumbnails": [
            {
              "small": "http://assets.lob.com/chk_c1b37993c0d1a580_thumb_small_1.png",
              "medium": "http://assets.lob.com/chk_c1b37993c0d1a580_thumb_medium_1.png",
              "large": "http://assets.lob.com/chk_c1b37993c0d1a580_thumb_large_1.png"
            }
          ],
          "expected_delivery_date": "2015-05-05",
          "date_created": "2015-04-27T21:33:29.876Z",
          "date_modified": "2015-04-27T21:32:53.364Z",
          "object": "check"
        }
      ],
      "count": 2,
      "next_url": "https://api.lob.com/v1/checks?count=2&offset=2",
      "previous_url": null,
      "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

bank_address:
required

The bank branch address. 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

account_address:
required

The address associated with your account. 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

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 be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

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 "routing_number=322271627" \
      -d "account_number=123456789" \
      -d "signatory=John Doe" \
      -d "bank_address[name]=Chase Bank" \
      -d "bank_address[address_line1]=55 Edmonds" \
      -d "bank_address[address_city]=Palo Alto" \
      -d "bank_address[address_state]=CA" \
      -d "bank_address[address_zip]=90081" \
      -d "bank_address[address_country]=US" \
      -d "account_address[name]=Leore Avidar" \
      -d "account_address[address_line1]=123 Test Street" \
      -d "account_address[address_line2]=Apt 155" \
      -d "account_address[address_city]=Sunnyvale" \
      -d "account_address[address_state]=CA" \
      -d "account_address[address_zip]=94085" \
      -d "account_address[address_country]=US"
    
    

Example Response

    
    {
      "id": "bank_b76799ef24eb242",
      "description": null,
      "metadata": {},
      "routing_number": "322271627",
      "account_number": "123456789",
      "signatory": "John Doe",
      "bank_address": {
        "id": "adr_0bbce1e2fc44b8cb",
        "description": null,
        "name": "Chase Bank",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "55 Edmonds",
        "address_line2": null,
        "address_city": "Palo Alto",
        "address_state": "California",
        "address_zip": "90081",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2015-04-27T21:24:18.808Z",
        "date_modified": "2015-04-27T21:24:19.290Z",
        "object": "address"
      },
      "account_address": {
        "id": "adr_93e6f29f958dc48b",
        "description": null,
        "name": "Leore Avidar",
        "phone": null,
        "email": null,
        "company": 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": "2015-04-27T21:24:18.808Z",
        "date_modified": "2015-04-27T21:24:19.288Z",
        "object": "address"
      },
      "verified": false,
      "date_created": "2015-04-27T21:24:19.366Z",
      "date_modified": "2015-04-27T21:24:19.366Z",
      "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/{ACCOUNT_ID}

Example Request

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

Example Response

    
    {
      "id": "bank_dfceb4a2a05b57e",
      "description": null,
      "metadata": {},
      "routing_number": "123456789",
      "account_number": "123456789",
      "signatory": Leore Avidar,
      "bank_address": {
        "id": "adr_7634570f6d91feef",
        "description": null,
        "name": "CHASE BANK",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "55 EDMONDS",
        "address_line2": null,
        "address_city": "PALO ALTO",
        "address_state": "California",
        "address_zip": "90081",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2013-10-06T01:03:56.000Z",
        "date_modified": "2013-10-06T01:03:56.000Z",
        "object": "address"
      },
      "account_address": {
        "id": "adr_eae4448bb64c07f0",
        "description": null,
        "name": "LEORE AVIDAR",
        "phone": null,
        "email": null,
        "company": 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"
      },
      "verified": false,
      "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

count:
optional

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

offset:
optional

Return requested # of items starting 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.

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?count=2&offset=0" \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
    
    

Example Response

    
    {
      "data": [
        {
          "id": "bank_77e218868fd6c3d",
          "description": null,
          "metadata": {},
          "routing_number": "122100024",
          "account_number": "123456789",
          "signatory": "John Doe",
          "bank_address": {
            "id": "adr_6b9721c822356ac0",
            "description": null,
            "name": "Bank Address",
            "phone": null,
            "email": null,
            "company": null,
            "address_line1": "123 Test Street",
            "address_line2": null,
            "address_city": "San Francisco",
            "address_state": "California",
            "address_zip": "94107",
            "address_country": "United States",
            "metadata": {},
            "date_created": "2015-04-27T21:26:28.367Z",
            "date_modified": "2015-04-27T21:26:28.469Z",
            "object": "address"
          },
          "account_address": {
            "id": "adr_40d98ab76db566ee",
            "description": null,
            "name": "Account Address",
            "phone": null,
            "email": null,
            "company": null,
            "address_line1": "123 Test Street",
            "address_line2": null,
            "address_city": "San Francisco",
            "address_state": "California",
            "address_zip": "94107",
            "address_country": "United States",
            "metadata": {},
            "date_created": "2015-04-27T21:26:28.367Z",
            "date_modified": "2015-04-27T21:26:28.466Z",
            "object": "address"
          },
          "verified": true,
          "date_created": "2015-04-27T21:26:28.486Z",
          "date_modified": "2015-04-27T21:26:04.526Z",
          "object": "bank_account"
        },
        {
          "id": "bank_a60db70b5175f73",
          "description": null,
          "metadata": {},
          "routing_number": "122100024",
          "account_number": "123456789",
          "signatory": "John Doe",
          "bank_address": {
            "id": "adr_6eeab3a75072bf0b",
            "description": null,
            "name": "Bank Address",
            "phone": null,
            "email": null,
            "company": null,
            "address_line1": "123 Test Street",
            "address_line2": null,
            "address_city": "San Francisco",
            "address_state": "California",
            "address_zip": "94107",
            "address_country": "United States",
            "metadata": {},
            "date_created": "2015-04-27T21:25:54.108Z",
            "date_modified": "2015-04-27T21:25:54.182Z",
            "object": "address"
          },
          "account_address": {
            "id": "adr_8dfe31f2e175019b",
            "description": null,
            "name": "Account Address",
            "phone": null,
            "email": null,
            "company": null,
            "address_line1": "123 Test Street",
            "address_line2": null,
            "address_city": "San Francisco",
            "address_state": "California",
            "address_zip": "94107",
            "address_country": "United States",
            "metadata": {},
            "date_created": "2015-04-27T21:25:54.108Z",
            "date_modified": "2015-04-27T21:25:54.146Z",
            "object": "address"
          },
          "verified": true,
          "date_created": "2015-04-27T21:25:54.188Z",
          "date_modified": "2015-04-27T21:25:54.836Z",
          "object": "bank_account"
        }
      ],
      "count": 2,
      "next_url": "https://api.lob.com/v1/bank_accounts?count=2&offset=2",
      "previous_url": null,
      "object": "list"
    }
    
    

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/{BANK_ACCOUNT_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_address": {
        "id": "adr_7634570f6d91feef",
        "description": null,
        "name": "CHASE BANK",
        "phone": null,
        "email": null,
        "company": null,
        "address_line1": "55 EDMONDS",
        "address_line2": null,
        "address_city": "PALO ALTO",
        "address_state": "California",
        "address_zip": "90081",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2013-10-06T01:03:56.000Z",
        "date_modified": "2013-10-06T01:03:56.000Z",
        "object": "address"
      },
      "account_address": {
        "id": "adr_eae4448bb64c07f0",
        "description": null,
        "name": "LEORE AVIDAR",
        "phone": null,
        "email": null,
        "company": 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"
      },
      "verified": true,
      "date_created": "2013-10-06T01:03:56.000Z",
      "date_modified": "2013-10-06T01:03:56.000Z",
      "object": "bank_account"
    }
    
    

Delete a bank account

Permanently deletes a bank account. It cannot be undone.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request

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

Example Response

    
    {
      "message": "Success! Bank account has been deleted"
    }
    
    

Jobs

Jobs allows you to send your actual print jobs that will be processed and mailed. You can retrieve individual jobs as well as a list of all your jobs.

Create a single object job

Create a new job for a single object.

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

object1:
required

Must be an object ID or an object with object parameters. Jobs can have more than one object: each additional object after object1 should be named object2, object3, ..., object{n}. If an object is used, the object will be created for you.

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

Returns

Returns a job object upon successful creation.

Example Definition

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

Example Request

    
    curl https://api.lob.com/v1/jobs \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
      -d "description=test photo job" \
      -d "to=adr_43769b47aed248c2" \
      -d "from=adr_7f9ece71fbca3796" \
      -d "object1=obj_325b20a1e0ea3c7a"
    
    

Example Response

    
    {
      "id": "job_9838b3682695a731",
      "description": "test photo job",
      "metadata": {},
      "to": {
        "id": "adr_43769b47aed248c2",
        "description": null,
        "name": "Harry Zhang",
        "phone": "5555555555",
        "email": "harry@lob.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",
        "metadata": {},
        "date_created": "2013-07-20T05:53:25.000Z",
        "date_modified": "2015-04-08T15:19:08.268Z",
        "object": "address"
      },
      "from": {
        "id": "adr_7f9ece71fbca3796",
        "description": null,
        "name": "Harry Zhang",
        "phone": "5555555555",
        "email": "harry@lob.com",
        "company": null,
        "address_line1": "123 Test Avenue",
        "address_line2": "Unit 401",
        "address_city": "Seattle",
        "address_state": "Washington",
        "address_zip": "98122",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2013-07-20T05:55:19.000Z",
        "date_modified": "2013-07-20T05:55:19.000Z",
        "object": "address"
      },
      "objects": [
        {
          "id": "obj_325b20a1e0ea3c7a",
          "description": "jellyfish photo",
          "quantity": 1,
          "pages": 1,
          "metadata": {},
          "setting": {
            "id": "500",
            "type": "photos",
            "description": "4x6 gloss photo",
            "paper": "gloss photo paper",
            "width": "6.000",
            "length": "4.000",
            "color": "color",
            "notes": null,
            "object": "setting"
          },
          "url": "http://assets.lob.com/obj_325b20a1e0ea3c7a.pdf",
          "thumbnails": [
            {
              "small": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_small_1.png",
              "medium": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_medium_1.png",
              "large": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_large_1.png"
            }
          ],
          "date_created": "2015-04-24T20:30:30.907Z",
          "date_modified": "2015-04-24T20:30:53.579Z",
          "object": "object"
        }
      ],
      "price": "1.15",
      "tracking": {
        "id": "trk_f8387dba17150a90",
        "tracking_number": "897714123456789",
        "carrier": "USPS",
        "link": null,
        "events": [],
        "object": "tracking"
      },
      "status": "processed",
      "date_created": "2015-04-24T21:12:19.235Z",
      "date_modified": "2015-04-24T21:12:19.305Z",
      "expected_delivery_date": "2015-05-04",
      "object": "job"
    }
    
    

Create a multi object job

Create a new job for a multiple objects. Multiple object jobs are only supported for Photos (Settings 500-504) and Posters (Settings 304-307).

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

object1:
required

Must be an object ID or an object with object parameters. Jobs can have more than one object: each additional object after object1 should be named object2, object3, ..., object{n}. If an object is used, the object will be created for you.

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

Returns

Returns a job object upon successful creation.

Example Definition

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

Example Request

    
    curl https://api.lob.com/v1/jobs \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
      -d "description=multi object photo job" \
      -d "to=adr_43769b47aed248c2" \
      -d "from=adr_7f9ece71fbca3796" \
      -d "object1=obj_325b20a1e0ea3c7a" \
      -d "object2=obj_8a7e27cc02ef916b"
    
    

Example Response

    
    {
      "id": "job_f6e2b621179a1d61",
      "description": "multi object photo job",
      "metadata": {},
      "to": {
        "id": "adr_43769b47aed248c2",
        "description": null,
        "name": "Harry Zhang",
        "phone": "5555555555",
        "email": "harry@lob.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",
        "metadata": {},
        "date_created": "2013-07-20T05:53:25.000Z",
        "date_modified": "2015-04-08T15:19:08.268Z",
        "object": "address"
      },
      "from": {
        "id": "adr_7f9ece71fbca3796",
        "description": null,
        "name": "Harry Zhang",
        "phone": "5555555555",
        "email": "harry@lob.com",
        "company": null,
        "address_line1": "123 Test Avenue",
        "address_line2": "Unit 401",
        "address_city": "Seattle",
        "address_state": "Washington",
        "address_zip": "98122",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2013-07-20T05:55:19.000Z",
        "date_modified": "2013-07-20T05:55:19.000Z",
        "object": "address"
      },
      "objects": [
        {
          "id": "obj_325b20a1e0ea3c7a",
          "description": "jellyfish photo",
          "metadata": {},
          "quantity": 1,
          "pages": 1,
          "setting": {
            "id": "500",
            "type": "photos",
            "description": "4x6 gloss photo",
            "paper": "gloss photo paper",
            "width": "6.000",
            "length": "4.000",
            "color": "color",
            "notes": null,
            "object": "setting"
          },
          "url": "http://assets.lob.com/obj_325b20a1e0ea3c7a.pdf",
          "thumbnails": [
            {
              "small": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_small_1.png",
              "medium": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_medium_1.png",
              "large": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_large_1.png"
            }
          ],
          "date_created": "2015-04-24T20:30:30.907Z",
          "date_modified": "2015-04-24T20:30:53.579Z",
          "object": "object"
        },
        {
          "id": "obj_8a7e27cc02ef916b",
          "description": "jellyfish photo",
          "metadata": {},
          "quantity": 1,
          "pages": 1,
          "setting": {
            "id": "500",
            "type": "photos",
            "description": "4x6 gloss photo",
            "paper": "gloss photo paper",
            "width": "6.000",
            "length": "4.000",
            "color": "color",
            "notes": null,
            "object": "setting"
          },
          "url": "http://assets.lob.com/obj_8a7e27cc02ef916b.pdf",
          "thumbnails": [
            {
              "small": "http://assets.lob.com/obj_8a7e27cc02ef916b_thumb_small_1.png",
              "medium": "http://assets.lob.com/obj_8a7e27cc02ef916b_thumb_medium_1.png",
              "large": "http://assets.lob.com/obj_8a7e27cc02ef916b_thumb_large_1.png"
            }
          ],
          "date_created": "2015-04-24T20:41:31.862Z",
          "date_modified": "2015-04-24T20:42:33.093Z",
          "object": "object"
        }
      ],
      "price": "1.61",
      "tracking": {
        "id": "trk_535060da76943992",
        "tracking_number": "897714123456789",
        "carrier": "USPS",
        "link": null,
        "events": [],
        "object": "tracking"
      },
      "status": "processed",
      "date_created": "2015-04-24T21:23:44.933Z",
      "date_modified": "2015-04-24T21:23:44.977Z",
      "expected_delivery_date": "2015-05-04",
      "object": "job"
    }
    
    

Retrieve a job

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

Arguments

id:
required

The identifier of the job to be retrieved.

Returns

Returns a job object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/jobs/{JOB_ID}

Example Request

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

Example Response

    
    {
      "id": "job_9838b3682695a731",
      "description": "test photo job",
      "metadata": {},
      "to": {
        "id": "adr_43769b47aed248c2",
        "description": null,
        "name": "Harry Zhang",
        "phone": "5555555555",
        "email": "harry@lob.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",
        "metadata": {},
        "date_created": "2013-07-20T05:53:25.000Z",
        "date_modified": "2015-04-08T15:19:08.268Z",
        "object": "address"
      },
      "from": {
        "id": "adr_7f9ece71fbca3796",
        "description": null,
        "name": "Harry Zhang",
        "phone": "5555555555",
        "email": "harry@lob.com",
        "company": null,
        "address_line1": "123 Test Avenue",
        "address_line2": "Unit 401",
        "address_city": "Seattle",
        "address_state": "Washington",
        "address_zip": "98122",
        "address_country": "United States",
        "metadata": {},
        "date_created": "2013-07-20T05:55:19.000Z",
        "date_modified": "2013-07-20T05:55:19.000Z",
        "object": "address"
      },
      "objects": [
        {
          "id": "obj_325b20a1e0ea3c7a",
          "description": "jellyfish photo",
          "metadata": {},
          "quantity": 1,
          "pages": 1,
          "setting": {
            "id": "500",
            "type": "photos",
            "description": "4x6 gloss photo",
            "paper": "gloss photo paper",
            "width": "6.000",
            "length": "4.000",
            "color": "color",
            "notes": null,
            "object": "setting"
          },
          "url": "http://assets.lob.com/obj_325b20a1e0ea3c7a.pdf",
          "thumbnails": [
            {
              "small": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_small_1.png",
              "medium": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_medium_1.png",
              "large": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_large_1.png"
            }
          ],
          "date_created": "2015-04-24T20:30:30.907Z",
          "date_modified": "2015-04-24T20:30:53.579Z",
          "object": "object"
        }
      ],
      "price": "1.15",
      "tracking": {
        "id": "trk_f8387dba17150a90",
        "tracking_number": "897714123456789",
        "carrier": "USPS",
        "link": null,
        "events": [],
        "object": "tracking"
      },
      "status": "processed",
      "date_created": "2015-04-24T21:12:19.235Z",
      "date_modified": "2015-04-24T21:12:19.305Z",
      "expected_delivery_date": "2015-05-04",
      "object": "job"
    }
    
    

List all jobs

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

Arguments

count:
optional

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

offset:
optional

Return requested # of items starting 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[campaign]=NEWYORK2015.

Returns

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

Example Definition

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

Example Request

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

Example Response

    
    {
      "data": [
        {
          "id": "job_bcdce6030faed7c4",
          "description": "test photo job",
          "metadata": {},
          "to": {
            "id": "adr_43769b47aed248c2",
            "description": null,
            "metadata": {},
            "name": "Harry Zhang",
            "phone": "5555555555",
            "email": "harry@lob.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": "2013-07-20T05:53:25.000Z",
            "date_modified": "2015-04-08T15:19:08.268Z",
            "deleted": true,
            "object": "address"
          },
          "from": {
            "id": "adr_7f9ece71fbca3796",
            "description": null,
            "metadata": {},
            "name": "Harry Zhang",
            "phone": "5555555555",
            "email": "harry@lob.com",
            "company": null,
            "address_line1": "123 Test Avenue",
            "address_line2": "Unit 401",
            "address_city": "Seattle",
            "address_state": "Washington",
            "address_zip": "98122",
            "address_country": "United States",
            "date_created": "2013-07-20T05:55:19.000Z",
            "date_modified": "2013-07-20T05:55:19.000Z",
            "object": "address"
          },
          "objects": [
            {
              "id": "obj_325b20a1e0ea3c7a",
              "description": "jellyfish photo",
              "metadata": {},
              "quantity": 1,
              "pages": 1,
              "setting": {
                "id": "500",
                "type": "photos",
                "description": "4x6 gloss photo",
                "paper": "gloss photo paper",
                "width": "6.000",
                "length": "4.000",
                "color": "color",
                "notes": null,
                "object": "setting"
              },
              "url": "http://assets.lob.com/obj_325b20a1e0ea3c7a.pdf",
              "thumbnails": [
                {
                  "small": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_small_1.png",
                  "medium": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_medium_1.png",
                  "large": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_large_1.png"
                }
              ],
              "date_created": "2015-04-24T20:30:30.907Z",
              "date_modified": "2015-04-24T20:30:53.579Z",
              "object": "object"
            }
          ],
          "price": "1.15",
          "tracking": {
            "id": "trk_3df17b77237a3cff",
            "tracking_number": "897714123456789",
            "carrier": "USPS",
            "link": null,
            "events": [],
            "object": "tracking"
        },
          "status": "processed",
          "date_created": "2015-04-28T16:46:41.915Z",
          "date_modified": "2015-04-28T16:46:42.000Z",
          "expected_delivery_date": "2015-05-06",
          "object": "job"
        },
        {
          "id": "job_ccfab3d02a9c270f",
          "description": "test photo job",
          "metadata": {},
          "to": {
            "id": "adr_43769b47aed248c2",
            "description": null,
            "metadata": {},
            "name": "Harry Zhang",
            "phone": "5555555555",
            "email": "harry@lob.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": "2013-07-20T05:53:25.000Z",
            "date_modified": "2015-04-08T15:19:08.268Z",
            "deleted": true,
            "object": "address"
          },
          "from": {
            "id": "adr_7f9ece71fbca3796",
            "description": null,
            "metadata": {},
            "name": "Harry Zhang",
            "phone": "5555555555",
            "email": "harry@lob.com",
            "company": null,
            "address_line1": "123 Test Avenue",
            "address_line2": "Unit 401",
            "address_city": "Seattle",
            "address_state": "Washington",
            "address_zip": "98122",
            "address_country": "United States",
            "date_created": "2013-07-20T05:55:19.000Z",
            "date_modified": "2013-07-20T05:55:19.000Z",
            "object": "address"
          },
          "objects": [
            {
              "id": "obj_325b20a1e0ea3c7a",
              "description": "jellyfish photo",
              "metadata": {},
              "quantity": 1,
              "pages": 1,
              "setting": {
                "id": "500",
                "type": "photos",
                "description": "4x6 gloss photo",
                "paper": "gloss photo paper",
                "width": "6.000",
                "length": "4.000",
                "color": "color",
                "notes": null,
                "object": "setting"
              },
              "url": "http://assets.lob.com/obj_325b20a1e0ea3c7a.pdf",
              "thumbnails": [
                {
                  "small": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_small_1.png",
                  "medium": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_medium_1.png",
                  "large": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_large_1.png"
                }
              ],
              "date_created": "2015-04-24T20:30:30.907Z",
              "date_modified": "2015-04-24T20:30:53.579Z",
              "object": "object"
            }
          ],
          "price": "1.15",
          "tracking": {
            "id": "trk_91e1a2dd6cbc8275",
            "tracking_number": "897714123456789",
            "carrier": "USPS",
            "link": null,
            "events": [],
            "object": "tracking"
          },
          "status": "processed",
          "date_created": "2015-04-28T16:46:40.108Z",
          "date_modified": "2015-04-28T16:46:40.203Z",
          "expected_delivery_date": "2015-05-06",
          "object": "job"
        }
      ],
      "count": 2,
      "next_url": "https://api.lob.com/v1/jobs?count=2&offset=2",
      "previous_url": null,
      "object": "list"
    }
    
    

Objects

Objects are the files used in your print job. They allow you to store files and print settings associated with the document. The API allows you to create and delete your objects. You can retrieve individual objects as well as a list of all your objects.

Create an object

Creates an new object.

Arguments

description:
optional
file:
required

This can be a URL, local file, or HTML string. Supported file types are PDF, PNG, and JPEG. For HTML examples for letters (settings 100 and 101), please see Letter Examples Appendix.

data:
optional

When providing a file as an HTML string, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML: {{variable_name}}.

setting:
required

Must be a supported ID.

quantity:
optional

Default is 1

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

Returns

Returns an object object upon successful creation.

Example Definition

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

Example Request with HTML

    
    curl https://api.lob.com/v1/objects \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
      -d "description=jellyfish photo" \
      --data-urlencode "file=<html>HTML here for {{name}}</html>" \
      -d "data[name]=Harry" \
      -d "setting=500"
    
    

Example Request with Remote File

    
    curl https://api.lob.com/v1/objects \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
      -d "description=jellyfish photo" \
      --data-urlencode "file=https://s3-us-west-2.amazonaws.com/lob-assets/lob-jelly-photo.jpg" \
      -d "setting=500"
    
    

Example Request with Local File

    
    curl https://api.lob.com/v1/objects \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
      -F "description=jellyfish photo" \
      -F "file=@/path/to/your/file/lob-jelly-photo.jpg" \
      -F "setting=500"
    
    

Example Response

    
    {
      "id": "obj_325b20a1e0ea3c7a",
      "description": "jellyfish photo",
      "metadata": {},
      "quantity": 1,
      "pages": 1,
      "setting": {
        "id": "500",
        "type": "photos",
        "description": "4x6 gloss photo",
        "paper": "gloss photo paper",
        "width": "6.000",
        "length": "4.000",
        "color": "color",
        "notes": null,
        "object": "setting"
      },
      "url": "http://assets.lob.com/obj_325b20a1e0ea3c7a.pdf",
      "thumbnails": [
        {
          "small": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_small_1.png",
          "medium": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_medium_1.png",
          "large": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_large_1.png"
        }
      ],
      "date_created": "2015-04-24T20:30:30.907Z",
      "date_modified": "2015-04-24T20:30:30.907Z",
      "object": "object"
    }
    
    

Retrieve an object

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

Arguments

id:
required

The identifier of the object to be retrieved.

Returns

Returns an object object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/objects/{OBJECT_ID}

Example Request

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

Example Response

    
    {
      "id": "obj_325b20a1e0ea3c7a",
      "description": "jellyfish photo",
      "metadata": {},
      "quantity": 1,
      "pages": 1,
      "setting": {
        "id": "500",
        "type": "photos",
        "description": "4x6 gloss photo",
        "paper": "gloss photo paper",
        "width": "6.000",
        "length": "4.000",
        "color": "color",
        "notes": null,
        "object": "setting"
      },
      "url": "http://assets.lob.com/obj_325b20a1e0ea3c7a.pdf",
      "thumbnails": [
        {
          "small": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_small_1.png",
          "medium": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_medium_1.png",
          "large": "http://assets.lob.com/obj_325b20a1e0ea3c7a_thumb_large_1.png"
        }
      ],
      "date_created": "2015-04-24T20:30:30.907Z",
      "date_modified": "2015-04-24T20:30:30.907Z",
      "object": "object"
    }
    
    

Delete an object

Permanently deletes an object. It cannot be undone.

Returns

Returns a message that the deletion has been successful.

Example Definition

DELETE https://api.lob.com/v1/objects/{OBJECT_ID}

Example Request

    
    curl -X DELETE https://api.lob.com/v1/objects/obj_4241a46e01b4f892 \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
    
    

Example Response

    
    {
      "message": "Success! Object has been deleted"
    }
    
    

List all objects

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

Arguments

count:
optional

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

offset:
optional

Return requested # of items starting 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[campaign]=NEWYORK2015.

Returns

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

Example Definition

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

Example Request

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

Example Response

    
    {
      "data": [
        {
          "id": "obj_8a7e27cc02ef916b",
          "description": "jellyfish photo",
          "metadata": {},
          "quantity": 1,
          "pages": 1,
          "setting": {
            "id": "500",
            "type": "photos",
            "description": "4x6 gloss photo",
            "paper": "gloss photo paper",
            "width": "6.000",
            "length": "4.000",
            "color": "color",
            "notes": null,
            "object": "setting"
          },
          "url": "http://assets.lob.com/obj_8a7e27cc02ef916b.pdf",
          "thumbnails": [
            {
              "small": "http://assets.lob.com/obj_8a7e27cc02ef916b_thumb_small_1.png",
              "medium": "http://assets.lob.com/obj_8a7e27cc02ef916b_thumb_medium_1.png",
              "large": "http://assets.lob.com/obj_8a7e27cc02ef916b_thumb_large_1.png"
            }
          ],
          "date_created": "2015-04-24T20:41:31.862Z",
          "date_modified": "2015-04-24T20:42:33.093Z",
          "object": "object"
        },
        {
          "id": "obj_bc5395df3c517561",
          "description": "GO BLUE",
          "metadata": {},
          "quantity": 1,
          "pages": 1,
          "setting": {
            "id": "200",
            "type": "cards",
            "description": "4x6 color card",
            "paper": "120lb gloss cover",
            "width": "6.000",
            "length": "4.000",
            "color": "color",
            "notes": "includes envelope",
            "object": "setting"
          },
          "url": "http://assets.lob.com/obj_bc5395df3c517561.pdf",
          "thumbnails": [
            {
              "small": "http://assets.lob.com/obj_bc5395df3c517561_thumb_small_1.png",
              "medium": "http://assets.lob.com/obj_bc5395df3c517561_thumb_medium_1.png",
              "large": "http://assets.lob.com/obj_bc5395df3c517561_thumb_large_1.png"
            }
          ],
          "date_created": "2015-04-24T20:41:18.514Z",
          "date_modified": "2015-04-24T20:40:56.100Z",
          "object": "object"
        }
      ],
      "count": 2,
      "next_url": "https://api.lob.com/v1/objects?count=2&offset=3",
      "previous_url": null,
      "object": "list"
    }
    
    

Settings

Settings are predetermined configurations for popular objects (eg. posters, photos, etc.) and contain all the details about that object used for printing. Please ensure that your object matches the size of the setting being used and is at least 300 DPI to ensure a high quality print. A list of all settings is available on the SPS page and if you need a setting not on the list please contact us to request it.

Retrieve a setting

Retrieves the setting with a given ID. You need only supply the unique setting identifier.

Arguments

id:
required

The identifier of the setting to be retrieved.

Returns

Returns a setting object if a valid identifier was provided.

Example Definition

GET https://api.lob.com/v1/settings/{SETTING_ID}

Example Request

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

Example Response

    
    {
      "id": "200",
      "type": "cards",
      "description": "4x6 color card",
      "paper": "120lb gloss cover",
      "width": "6.000",
      "length": "4.000",
      "color": "color",
      "notes": "includes envelope",
      "object": "setting"
    }
    
    

List all settings

Returns a list of all currently supported settings. You can use the IDs for objects to specify a configuration.

Returns

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

Example Definition

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

Example Request

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

Example Response

    
    {
      "data": [
        {
          "id": "200",
          "type": "cards",
          "description": "4x6 color card",
          "paper": "120lb gloss cover",
          "width": "6.000",
          "length": "4.000",
          "color": "color",
          "notes": "includes envelope",
          "object": "setting"
        },
        {
          "id": "201",
          "type": "cards",
          "description": "4x6 premium color card",
          "paper": "18pt premium cougar cardstock",
          "width": "6.000",
          "length": "4.000",
          "color": "color",
          "notes": "includes envelope",
          "object": "setting"
        },
        {
          "id": "203",
          "type": "cards",
          "description": "5x7 folded greeting card",
          "paper": "120lb gloss cover",
          "width": "10.000",
          "length": "7.000",
          "color": "color",
          "notes": "includes envelope",
          "object": "setting"
        },
        {
          "id": "304",
          "type": "posters",
          "description": "8x10 semi-gloss poster",
          "paper": "semi-gloss poster paper",
          "width": "8.000",
          "length": "10.000",
          "color": "color",
          "notes": null,
            "object": "setting"
        },
        {
          "id": "305",
          "type": "posters",
          "description": "11x17 semi-gloss poster",
          "paper": "semi-gloss poster paper",
          "width": "11.000",
          "length": "17.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        },
        {
          "id": "306",
          "type": "posters",
          "description": "18x24 semi-gloss poster",
          "paper": "semi-gloss poster paper",
          "width": "18.000",
          "length": "24.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        },
        {
          "id": "307",
          "type": "posters",
          "description": "24x36 semi-gloss poster",
          "paper": "semi-gloss poster paper",
          "width": "24.000",
          "length": "36.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        },
        {
          "id": "500",
          "type": "photos",
          "description": "4x6 gloss photo",
          "paper": "gloss photo paper",
          "width": "6.000",
          "length": "4.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        },
        {
          "id": "501",
          "type": "photos",
          "description": "5x7 gloss photo",
          "paper": "gloss photo paper",
          "width": "7.000",
          "length": "5.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        },
        {
          "id": "502",
          "type": "photos",
          "description": "8x10 gloss photo",
          "paper": "gloss photo paper",
          "width": "10.000",
          "length": "8.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        },
        {
          "id": "503",
          "type": "photos",
          "description": "4x4 gloss photo",
          "paper": "gloss photo paper",
          "width": "4.000",
          "length": "4.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        },
        {
          "id": "504",
          "type": "photos",
          "description": "8x8 gloss photo",
          "paper": "gloss photo paper",
          "width": "8.000",
          "length": "8.000",
          "color": "color",
          "notes": null,
          "object": "setting"
        }
      ],
      "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
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

When providing a front or back as an HTML string, you can provide optional data variables that will be merged with your HTML. To add a variable, insert double curly braces into your HTML: {{variable_name}}.

routes:
required (either zipcode or routes)

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

target_type:
optional

Defaults to "all". Must enter “all” or “residential”.

metadata:
optional

Must be an object with up to 20 key-value pairs. Keys must be less than 40 characters and values must be less than 500 characters. Nested objects are not supported. See Metadata.

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=Sample SAM" \
      --data-urlencode "front=<h1>Demo Area Mail for {{city}}</h1>" \
      --data-urlencode "back=https://lob.com/areaback.pdf" \
      -d "data[city]=California" \
      -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=Sample SAM" \
      --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 Response

    
    {
      "id": "area_de75bb527080d5f",
      "description": "Sample SAM",
      "metadata": {},
      "status": "processed",
      "price": "954.57",
      "url": "http://assets.lob.com/area_de75bb527080d5f.pdf",
      "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": "http://assets.lob.com/area_de75bb527080d5f_thumb_small_1.png",
          "medium": "http://assets.lob.com/area_de75bb527080d5f_thumb_medium_1.png",
          "large": "http://assets.lob.com/area_de75bb527080d5f_thumb_large_1.png"
        },
        {
          "small": "http://assets.lob.com/area_de75bb527080d5f_thumb_small_2.png",
          "medium": "http://assets.lob.com/area_de75bb527080d5f_thumb_medium_2.png",
          "large": "http://assets.lob.com/area_de75bb527080d5f_thumb_large_2.png"
        }
      ],
      "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

Example Request

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

Example Response

    
    {
      "id": "area_de75bb527080d5f",
      "description": "Sample SAM",
      "metadata": {},
      "status": "processed",
      "price": "954.57",
      "url": "http://assets.lob.com/area_de75bb527080d5f.pdf",
      "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": "http://assets.lob.com/area_de75bb527080d5f_thumb_small_1.png",
          "medium": "http://assets.lob.com/area_de75bb527080d5f_thumb_medium_1.png",
          "large": "http://assets.lob.com/area_de75bb527080d5f_thumb_large_1.png"
        },
        {
          "small": "http://assets.lob.com/area_de75bb527080d5f_thumb_small_2.png",
          "medium": "http://assets.lob.com/area_de75bb527080d5f_thumb_medium_2.png",
          "large": "http://assets.lob.com/area_de75bb527080d5f_thumb_large_2.png"
        }
      ],
      "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

count:
optional

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

offset:
optional

Return requested # of items starting 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[campaign]=NEWYORK2015.

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?count=2&offset=0" \
      -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
    
    

Example Response

    
    {
      "data": [
        {
          "id": "area_ae5edeae8e958a0",
          "description": "Sample SAM 2",
          "metadata": {},
          "status": "processed",
          "price": "760.72",
          "url": "http://assets.lob.com/area_ae5edeae8e958a0.pdf",
          "target_type": "residential",
          "addresses": 1323,
          "zip_codes": [
            {
              "zip_code": "94158",
              "routes": [
                {
                  "route": "C001",
                  "residential": 1323,
                  "business": 0,
                  "object": "route"
                }
              ],
              "object": "zip_code"
            }
          ],
          "thumbnails": [
            {
              "small": "http://assets.lob.com/area_ae5edeae8e958a0_thumb_small_1.png",
              "medium": "http://assets.lob.com/area_ae5edeae8e958a0_thumb_medium_1.png",
              "large": "http://assets.lob.com/area_ae5edeae8e958a0_thumb_large_1.png"
            },
            {
              "small": "http://assets.lob.com/area_ae5edeae8e958a0_thumb_small_2.png",
              "medium": "http://assets.lob.com/area_ae5edeae8e958a0_thumb_medium_2.png",
              "large": "http://assets.lob.com/area_ae5edeae8e958a0_thumb_large_2.png"
            }
          ],
          "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": {},
          "status": "processed",
          "price": "954.57",
          "url": "http://assets.lob.com/area_2a2b99030e7282f.pdf",
          "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": "http://assets.lob.com/area_2a2b99030e7282f_thumb_small_1.png",
              "medium": "http://assets.lob.com/area_2a2b99030e7282f_thumb_medium_1.png",
              "large": "http://assets.lob.com/area_2a2b99030e7282f_thumb_large_1.png"
            },
            {
              "small": "http://assets.lob.com/area_2a2b99030e7282f_thumb_small_2.png",
              "medium": "http://assets.lob.com/area_2a2b99030e7282f_thumb_medium_2.png",
              "large": "http://assets.lob.com/area_2a2b99030e7282f_thumb_large_2.png"
            }
          ],
          "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,
      "next_url": "https://api.lob.com/v1/areas?count=2&offset=2",
      "previous_url": null,
      "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/?zip_codes={ZIP_CODE}

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 3316 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"
          },
      {...}
       ]
    }
    
    

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:

  • Host custom font files as shown here
  • Use inline styles or an internal stylesheet, do not link to external stylesheets
  • Link to images that are 300DPI and then resize them in the HTML to the final desired 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 on the dashboard, as these are the files that will be printed.

Custom Font Example

For HTML, Lob supports common Web Safe fonts. To include your own custom fonts beyond those, please host font files and link them into your HTML as shown in the example on the right. For the most consistent results, please use a performant file hosting provider such as Amazon S3.

    
    @font-face {
      font-family: 'Loved by the King';
      font-style: normal;
      font-weight: 400;
      src: url('https://s3-us-west-2.amazonaws.com/lob-assets/LovedbytheKing.ttf') format('truetype');
    }
    
    .text {
      font-family: 'Loved by the King';
    }
    
    

Postcard 4x6 Front Example

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

    
    <html>
    <head>
    <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;
        width: 200px;
        font-family: sans-serif;
        font-size: 40px;
        font-weight: 700;
        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>
    
    

Postcard 4x6 Back Example

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

    
    <html>
    <head>
    <title>Lob.com Sample 4x6 Postcard Back Template 1</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: 400px;
        font-family: sans-serif;
        font-size: 20px;
        font-weight: 700;
        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 boxes denote 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 use "setting=1002" when creating a postcard with this example. You can view the rendered example in your browser here.

    
    <html>
    <head>
    <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 1875x1275 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;
        width: 200px;
        font-family: sans-serif;
        font-size: 40px;
        font-weight: 700;
        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>
    
    

Postcard 6x11 Back Example

An example of a 6x11 postcard back. Make sure to use "setting=1002" when creating a postcard with this example. You can view the rendered example in your browser here.

    
    <html>
    <head>
    <title>Lob.com Sample 6x11 Postcard Back Template 1</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;
        width: 600px;
        font-family: sans-serif;
        font-size: 28px;
        font-weight: 700;
        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 boxes denote 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 Template = 1 Example

An example of a two page letter where space is reserved to print the recipient and return addresses. You can view the rendered example in your browser here.

    
    <html>
    <head>
    <title>Lob.com Sample Letter Template = 1</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>
    
    

Letter Template = 0 Example

An example of a two page letter. Be sure to include "template=0" in your request if using this example. You can view the rendered example in your browser here.

    
    <html>
    <head>
    <title>Lob.com Sample Letter Template = 0</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;
      }
    </style>
    </head>
    
    <body>
      <div class="page">
        <div class="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>
      </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 file to customize the bottom of the page. You can view the rendered example in your browser here.

    
    <html>
    <head>
    <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: sans-serif;
        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>
    <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;
        width: 200px;
        font-family: sans-serif;
        font-size: 40px;
        font-weight: 700;
        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>
    <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;
        width: 600px;
        font-family: sans-serif;
        font-size: 28px;
        font-weight: 700;
        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.
  • For mailed products like postcards, make sure the address and stamp area should be ink free, stamp area always need to be in the top right.

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 setting in inches) and (length of image in pixels) / (length of setting 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 setting. Images will not be cropped or stretched by the API

SPS Templates

Refer to these Settings and templates when creating Objects:

Item Setting Templates
4x6 Color Card 200 PDF AI
4x6 Premium Color Card 201
5x7 Folded Greeting Card 203 PDF AI
8x10 Semi-gloss Poster 304 PDF AI
11x17 Semi-gloss Poster 305 PDF AI
18x24 Semi-gloss Poster 306 PDF AI
24x36 Semi-gloss Poster 307 PDF AI
5x7 Gloss Photo 501 PDF PSD
8x10 Gloss Photo 502 PDF PSD
4x4 Gloss Photo 503 PDF PSD
8x8 Gloss Photo 504 PDF PSD