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 account settings. No password is required.

Libraries

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

PDF Prepping

Currently we only support PDF files for all endpoints. To ensure that you are producing PDF's correctly please follow the guidelines below:

  • Make sure all fonts are embedded
  • Images should be 300 dpi or higher
  • Generated PDF's need to be be PDF/A compliant.
  • If your product has color to the edge – you must include a bleed 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 0.125” 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.

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.

packaging_id:
optional

Must be a valid packaging ID

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

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.

packaging_id:
optional

Must be a valid packaging ID

service_id:
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
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
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. Only PDF is currently supported

setting_id:
required

Must be an ID supported in the SPS page

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

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. Only PDF is currently supported

setting_id:
required

Must be an ID supported in the SPS page

quantity:
optional

Default is 1

double_sided:
optional

Boolean, use 1 for double-sided

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.

Packagings

A packaging represents the actual application of a specific packaging type to a particular a job. Whenever you are creating a job, you can choose to add a packaging_id that determines the packaging being selected. It contains information about the packaging and price. Please contact us if you have a request for a specific type of packaging that isn't on the list.

List all packagings

Returns a list of all currently supported packagings. You can use the IDs for jobs to specify the packaging of which your print job will be put into.

Returns

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

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

Postcards allow you to send your a print job for an postcard that will be printed and mailed. Postcards have both a front and back and can either be generated via the API or using images. You can retrieve individual postcards as well as a list of all your 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:
optional

Must be a .pdf sized 4"x6", this will be the front of the postcard. This can be a URL or local file. If local file use -F and remember the @ before the name

back:
required (either message or back, choose one)

Must be a .pdf sized 4"x6" and contain the to address. This can be a URL or local file. If local file use -F and remember the @ before the name. This will be the back of the postcard, if not included we will generate the back based off the to, from, and message arguments

full_bleed:
optional

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

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.

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_code:
optional

The bank code that is printed on your checks. Added for extra security. You can usually find this near the bank address on the check.

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

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.

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.