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. There are two different type of print job methods: one for postcards and another for standard print jobs. To send a print job you need to:

  1. Create an address
  2. Create an object - an object is the content you will be printing

Once you have done this you can send this a job to Lob! All printing is processed typically within 2-3 business days then mailed right after.

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.

Versioning

When backwards-incompatible changes are made to the API, a new dated version is released. The current version of the API is 2014-12-18. You can view your current version and upgrade to the newest version in your Settings on your Dashboard. 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.

Libraries

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

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 for Simple Print Services Objects and for Simple Postcard Service.

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
  • If your product has color to the edge – you must include a bleed (1/8" margin on all sides) to ensure it is cut correctly.
    1. Bleeds should be 1/8th” in size. Include full_bleed=1 as a parameter in your API call.
    2. Your file should have an extra 1/8th” around both the horizontal and vertical dimensions.
    3. This means your final file size will be a total of 0.25” larger than the original (ie, 4x6 will be 4.25x6.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: 1200px x 1600px image used to create a 4" x 6" 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

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

name:
optional
to:
required

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

from:
required

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

object1:
required

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

service:
optional

Must be a valid service ID

Returns

Returns a job object upon successful creation.

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

name:
optional
to:
required

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

from:
required

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

object1:
required

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

service:
optional

Must be a valid service ID

Returns

Returns a job object upon successful creation.

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.

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

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.

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

name:
required

Must no longer than 50 characters

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)

Returns

Returns an address object upon successful creation.

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.

Delete an address

Permanently deletes a customer. It cannot be undone.

Returns

Returns a message that the deletion was successful.

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

offset:
optional

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

Returns

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

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 w/remote file

Creates an new object using a remote file.

Arguments

name:
optional
file:
required

This can be a URL or local file. If local file use -F and remember the @ before the name. Supported file types are PDF, PNG, JPEG, and HTML. For HTML examples for letters (settings 100 and 101), please see Letter Examples Appendix.

setting:
required

Must be a supported ID.

quantity:
optional

Default is 1

double_sided:
optional

Boolean, use 1 for double-sided

full_bleed:
optional

Boolean, use 1 for full bleed. This will allow you to add 1/8 inch border around object you submit

template:
optional

Boolean, only applicable with letters (setting 100 and 101). Defaults to 0 which adds a blank page with only the address printed on it. Use 1 to denote that your object adheres to this template and that the extra address page is not necessary.

Returns

Returns an object object upon successful creation.

Create an object w/local file

Creates an new object using a local file.

Arguments

name:
optional
file:
required

This can be a URL or local file. If local file use -F and remember the @ before the name. Supported file types are PDF, PNG, and JPEG

setting:
required

Must be an ID supported in the SPS page

quantity:
optional

Default is 1

double_sided:
optional

Boolean, use 1 for double-sided

template:
optional

Boolean, only applicable with letters (setting 100 and 101). Defaults to 0 which adds a blank page with only the address printed on it. Use 1 to denote that your object adheres to this template and that the extra address page is not necessary.

Returns

Returns an object object upon successful creation.

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.

Delete an object

Permanently deletes an object. It cannot be undone.

Returns

Returns a message that the deletion has been successful.

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

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.

Settings

Settings are predetermined configurations for popular objects (ie. posters, business cards, 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.

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.

Services

A service adds an additional service to a particular job. Whenever you are creating a job, you can choose to add a service ID that determines the service being added. It contains information about the service and price.

List all services

Returns a list of all currently supported services. You can specify what additional services to add to your print job.

Returns

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

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

name:
optional
to:
required

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

from:
required

Must either be an address ID or an array with correct address parameters. If an array 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"x6" or 6"x11" 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"x6" or 6"x11" image to use as the back of the postcard, supplied as a URL, local file, or HTML string. The back must contain the to address unless you are using the template parameter (below). For HTML examples, please see Postcard Examples Appendix.

template:
optional

Boolean, use 1 for template. This will allow you to send the back and customize it yourself, but we will still insert the recipient address for you. Follow the templates provided here: 4x6 template and 6x11 template.

full_bleed:
optional

Boolean, use 1 for full bleed. This will require an addition 1/8 inch border on each side of the object you submit, and require the dimensions to be 4.25"x6.25" or 6.25"x11.25".

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.

Returns

Returns a postcard object upon successful creation.

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.

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

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.

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

name:
optional
check_number:
optional

Checks will default starting at 10000 and increment accordingly.

bank_account:
required

Must be a bank account ID.

to:
required

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

amount:
required

The payment amount to be sent

message:
optional

Max of 400 characters to be included on the top of the check.

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. If local file use -F and remember the @ before the name. 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.

Returns

Returns a check object upon successful creation.

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.

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

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.

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.

Arguments

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 array with correct address parameters. If an array 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 array with correct address parameters. If an array 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.

Returns

Returns a bank object upon successful creation.

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.

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

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.

Delete a bank account

Permanently deletes a bank account. It cannot be undone.

Returns

Returns a message that the deletion was successful.

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

name:
optional
front:
required

Must be a 6.25"x11.25" (or 6"x11" if no bleed) image, this will be the front of the postcard. This can be a URL, local file, or an HTML string. If local file use -F and remember the @ before the path. Supported file types are PDF, PNG, and JPEG. For HTML examples, please see Area Examples Appendix.

back:
required

Must be a 6.25"x11.25" (or 6"x11" if no bleed) image and use template. This can be a URL, local file, or an HTML string. If local file use -F and remember the @ before the path. Supported file types are PDF, PNG, and JPEG. For HTML examples, please see Area Examples Appendix.

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

full_bleed:
optional

Defaults to 1. This allows for 1/8th inch border around object you submit and final size is 6.25"x11.25"

Returns

Returns an area object upon successful creation.

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.

List all area mailings

Returns a list of ara 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

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.

Routes

A list of standard delivery routes and naming based on the zip codes requested.

Retrieve the routes

Retrieves the delivery routes for the zip codes requested.

Arguments

zip_codes:
required

The identifier of the area mail to be retrieved.

Returns

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

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.

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.

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.

SPS Templates

Refer to these Settings and templates when creating Objects:

Item Setting Templates
Black and White Document 100 PDF AI
Color Document 101
4x6 Color Card 201 PDF AI
4x6 Premium Color Card 202
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
Business Card Thick (500 CT) 400 PDF AI
Business Card Standard (250 CT) 402
4x6 Gloss Photo 500 PDF PSD
5x7 Gloss Photo 501 PDF PSD
8x10 Gloss Photo 502 PDF PSD
4x4 Gloss Photo 503 PDF PSD
8x8 Gloss Photo 504 PDF PSD
4.25x11 Standard Door Hangers (100 CT) 800 PDF AI
Glossy Color Flyer (100 CT) 803 PDF AI

Custom Fonts with HTML

Lob does not currently support web fonts in supplied HTML files. To include custom fonts, please host font files and link them into your HTML as shown on the right. For the most consistent results, please use a performant file hosting provider such as Amazon S3.

Postcard HTML Examples

Use the following HTML examples as starting points for creating custom postcard fronts and backs.

Postcard 4x6 Front Full-Bleed

An example of a 4x6 full-bleed postcard front. Make sure to use "full_bleed=1" when creating a postcard with this example. You can view the rendered example in your browser here.

Postcard 4x6 Back Full-Bleed

An example of a 4x6 full-bleed postcard back. Make sure to use "full_bleed=1" when creating a postcard with this example. You can view the rendered example in your browser here.

Postcard 4x6 Back Full-Bleed Template

An example of a 4x6 full-bleed postcard back that conforms to the postcard template. Make sure to use "full_bleed=1" and "template=1" when creating a postcard with this example. You must provide a "to" address in your API request when creating a postcard with this example. You can view the rendered example in your browser here.

Postcard 6x11 Front Full-Bleed

An example of a 6x11 full-bleed postcard front. Make sure to use "setting=1002" and "full_bleed=1" when creating a postcard with this example. You can view the rendered example in your browser here.

Postcard 6x11 Back Full-Bleed

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

Postcard 6x11 Back Full-Bleed Template

An example of a 6x11 full-bleed postcard back that conforms to the postcard template. Make sure to use "setting=1002" and "full_bleed=1" and "template=1" when creating a postcard with this example. You must provide a "to" address in your API request when creating a postcard with this example. You can view the rendered example in your browser here.

Area Mail HTML Examples

Use the following HTML examples as starting points for creating custom Area Mail fronts and backs.

Area Mail Front Full-Bleed

An example of an Area Mail full-bleed front. Make sure to use "full_bleed=1" when creating an Area Mailing with this example. You can view the rendered example in your browser here.

Area Mail Back Full-Bleed

An example of an Area Mail full-bleed back. Make sure to use "full_bleed=1" when creating an Area Mailing with this example. You can view the rendered example in your browser here.

Letter HTML Examples

Use the following HTML examples as starting points for creating custom letter fronts and backs.

Letter Sample Letter Template = 1

An example of a two page letter where space is reserved to print the recipient and return addresses. This is valid for settings 100 and 101. Be sure to use "template=1" in your request. You can view the rendered example in your browser here.

Letter Sample Letter Template = 0

An example of a two page letter. This is valid for settings 100 and 101. You can view the rendered example in your browser here.