Introduction

The Lob API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and uses HTTP response codes to indicate any API errors. Keep reading below for more information on each specific service. For frequently asked questions, feedback, and other help, please visit our help center.

API endpoint

https://api.lob.com/

Summary of Resource URL Patterns

  • /v1/addresses
  • /v1/addresses/{id}
  • /v1/us_verifications
  • /v1/us_autocompletions
  • /v1/us_zip_lookups
  • /v1/intl_verifications
  • /v1/postcards
  • /v1/postcards/{id}
  • /v1/letters
  • /v1/letters/{id}
  • /v1/checks
  • /v1/checks/{id}
  • /v1/bank_accounts/{id}/verify
  • /v1/bank_accounts
  • /v1/bank_accounts/{id}
  • /v1/templates
  • /v1/templates/{id}
  • /v1/templates/{id}/versions
  • /v1/templates/{template_id}/versions/{version_id}

Test and Live Environments

To make the API as explorable as possible, accounts have test and live environment API keys. You're not charged any fees in the test environment, so we encourage you to use it to try out services, perform quality assurance, and run automated testing. Objects―addresses, letters, checks, etc―in one environment cannot be manipulated by objects in the other.

In general, a payment method (either credit card or ACH account) must be added to your account to make live API requests. However, a payment method is not required for the first 300 live requests per month to the /v1/us_verifications endpoint. After the first 300 requests, you will begin receiving errors with status code 403.

Requests made in the test environment always validate request arguments, simulate live environment behavior, and enforce rate limits. They never print, mail nor, for verification services, verify addresses. The US verification service triggers behavior with specific argument values, and, if you plan on using that service, we recommend reading US Verification Test Environment.

To switch between environments, use the appropriate key for that environment when performing a request. You can find each environment's API key in your dashboard under Settings; test API keys are always prefixed with test_ and production API keys with live_.

API Keys

Lob authenticates your API requests using your account's API keys. If you do not include your key when making an API request, or use one that is incorrect or outdated, Lob returns an error with a 401 HTTP response code. You can find all API keys in your dashboard under Settings.

There are two types of API keys: secret and publishable.

  • Secret API keys should be kept confidential and only stored on your own servers. Your account's secret API key can perform any API request to Lob without restriction.
  • Publishable API keys are limited to US verifications, international verifications, and US autocomplete requests. While we encourage you to use a secret key for maximum security, you can publish these keys to JavaScript code or in an Android or iPhone app without exposing print and mail services or your secret key. Publishable keys are always prefixed with [environment]_pub.

Every type comes with a pair of keys: one for the testing environment and one for the live environment. We recommend reading Test and Live Environments for more information.

Authentication

Requests made to the API are protected with HTTP Basic authentication. In order to properly authenticate with the API you must use your API key as the username while leaving the password blank. Requests not properly authenticated will return a 401 error code. You can find your account's API keys in your Dashboard Settings.

All API requests must be made over HTTPS, or they will fail.

Example Request

The library will by default refer to the :api_key config when making authenticated requests. If that is not present, it will look for the LOB_API_KEY environment variable.


config :lob_elixir,
  api_key: "test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc"

Versioning

When backwards-incompatible changes are made to the API, a new dated version is released. The latest version of the API is version 2018-06-05. You can view your version and upgrade to the latest version in your Dashboard Settings. You will only need to specify a version if you would like to test a newer version of the API without doing a full upgrade. The API will return an error if a version older than your current one is passed in. See API Changelog for a full list of breaking changes.

Example Request

The library allows users to optionally configure the API version through the :api_version config. If that is not present, it will look for the LOB_API_VERSION environment variable.


config :lob_elixir,
  api_key: "test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc",
  api_version: "2018-06-05"

Errors

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

Attributes

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

HTTP Status Code Summary

200 - Success Successful API request
401 - Unauthorized Authorization error with your API key or account
403 - Forbidden Forbidden error with your API key or account
404 - Not Found The requested item does not exist
422 - Bad Request The query or body parameters did not pass validation
429 - Too Many Requests Too many requests have been sent with an API key in a given amout of time
500 - Server Error An internal server error occurred, please contact support@lob.com

Rate Limiting

To prevent mis-use, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits. By default, all accounts and their corresponding Test and Live API Keys have a rate limit of 150 requests per 5 seconds per endpoint. The POST /v1/us_verifications endpoint has a limit of 300 requests per 5 seconds for all accounts.

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

HTTP Headers and Response Codes

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

x-rate-limit-limit: the rate limit ceiling for a given request
x-rate-limit-remaining: the number of requests remaining in this window
x-rate-limit-reset: the time at which the rate limit window resets (in UTC epoch seconds)

Example HTTP Headers

      
x-rate-limit-limit:150
x-rate-limit-remaining:100
x-rate-limit-reset:1528749846
      
    

Example Response

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

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

Idempotent Requests

Lob supports idempotency for safely retrying POST requests to create postcards, letters, and checks without accidentally creating duplicates.

For example, if a request to create a check fails due to a network error, you can safely retry the same request with the same idempotency key and guarantee that only one check will ultimately be created and sent. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.

To perform an idempotent POST request to one of the three product endpoints, provide an additional Idempotency-Key header to the request. How you create unique keys is up to you, but we suggest using random values, such as V4 UUIDs. Idempotency keys are intended to prevent issues over a short periods of time, therefore keys expire after 24 hours. Keys are unique by mode (Test vs. Live) as well as by resource (postcard vs. letter vs. check).

By default, all GET and DELETE requests are idempotent by nature, so they do not require an additional idempotency key.

For more help integrating idempotency keys, refer to our implementation guide.

Headers

Idempotency-Key: optional

A string of no longer than 256 characters that uniquely identifies this resource.

Example Request


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  to: %{
    name: "Harry Zhang",
    address_line1: "123 Test Street",
    address_city: "Mountain View",
    address_state: "CA",
    address_country: "US",
    address_zip: "94041"
  },
  from: %{
    name: "Ami Wang",
    address_line1: "123 Test Avenue",
    address_city: "Seattle",
    address_state: "WA",
    address_country: "US",
    address_zip: "94041"
  },
  front: "https://lob.com/postcardfront.pdf",
  back: "https://lob.com/postcardback.pdf"
}, %{
  "Idempotency-Key" => "026e7634-24d7-486c-a0bb-4a17fd0eebc5"
})

Webhooks

Webhooks are an easy way to get notifications on events happening asynchronously within Lob's architecture. For example, when a postcard gets a "Processed For Delivery" tracking event, an event object of type postcard.processed_for_delivery will be created. If you are subscribed to that event type in that Environment (Test vs. Live), Lob will send that event to any URLs you've specified via an HTTP POST request. In Live mode, you can only have as many webhooks as allotted in your current Print & Mail Edition. There is no limit in Test mode.

You can view and create webhooks on the Lob Dashboard, as well as view your events. See our Webhooks Integration Guide for more details on how to integrate. Please see the full list of event types available for subscription here.

Cancellation Window

By default, all new accounts have a 5 minute cancellation window for postcards, letters, and checks. Within that timeframe, you can cancel mailings from production, free of charge. Once the window has passed for a postcard, letter, or check, the mailing is no longer cancelable. In addition, certain customers can customize their cancellation windows by product in their Dashboard Settings. Upgrade to the appropriate Print & Mail Edition to automatically gain access to this ability. For more details on this feature, check out our Cancellation Guide.

If you schedule a postcard, letter, or check for up to 90 days in the future by supplying the send_date parameter, that will override any cancellation window you may have for that product.

Scheduled Mailings

Postcards, letters, and checks can be scheduled to be sent up to 90 days in advance. You can use this feature to:

  • Create automated drip campaigns (e.g. send a postcard at 15, 30, and 60 days)
  • Schedule recurring sends
  • Plan your mailing schedule ahead of time

Up until the time a mailing is scheduled for, it can also be canceled. If you use this feature in conjunction with a cancellation window, the send_date parameter will always take precedence.

For implementation details, see documentation below for each respective endpoint. For more help, see our Scheduled Mailings Guide.

This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.

Example Create Request using Send Date


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  metadata: %{
    campaign: "NEWYORK2015"
  },
  to: "adr_78c304d54912c502",
  from: "adr_61a0865c8c573139",
  front: "tmpl_b846a20859ae11a",
  back: "tmpl_01b0d396a10c268",
  merge_variables: %{
    name: "Harry"
  },
  send_date: "2018-12-20"
})

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


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  metadata: %{
    campaign: "NEWYORK2015"
  },
  to: "adr_78c304d54912c502",
  from: "adr_61a0865c8c573139",
  front: "<html style='margin: 130px; font-size: 50;'>Front HTML for {{name}}</html>",
  back: "<html style='margin: 130px; font-size: 50;'>Back HTML</html>",
  merge_variables: %{
    name: "Harry"
  }
})

Example List Request with Metadata Filter


Lob.Postcard.list(%{
  metadata: %{
    campaign: "NEWYORK2015"
  },
  limit: 2,
  offset: 0
})

Asset URLs

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

Libraries

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

Beta Program

Here at Lob, we pride ourselves on building high quality platform capabilities rapidly and iteratively, so we can constantly be delivering additional value to our customers. When evaluating a new product or feature from Lob, you may see that it has been released in Beta.

Typically, something in Beta means that the feature is early in its lifecycle here at Lob. While we fully stand behind the quality of everything we release in Beta, we do anticipate receiving a higher level of customer feedback on Beta features, as well as a faster pace of changes from our engineering team in response to that feedback.

By participating in a Lob Beta program, you will have the opportunity to get early access to a new product capability, as well as having a unique opportunity to influence the product's direction with your feedback.

You should also anticipate that features in Beta may have functional or design limitations, and might change rapidly as we receive customer feedback and make improvements. In particular, new APIs in Beta may also go through more frequent versioning and version deprecation cycles than our more mature APIs.

If you are participating in a Beta program and want to provide feedback, please feel free to contact us!

Current Beta Features

  • API access to HTML Templates: The ability to create and save commonly used HTML postcard, letter and check templates has been available for some time in our Dashboard. We have now exposed our Template API endpoints in Beta, so you can now create, retrieve, and update templates programmatically as well!

HTML Templates

You can save commonly used HTML as templates within Lob to more easily manage them. You can reference your saved templates in postcard, letter, and check requests instead of having to pass a long HTML string on each request. Additionally, you can make changes to your HTML templates and update them independently, without having to touch your API integration. Templates can be created, edited, and viewed on your Dashboard. To use a template in a postcard, letter, or check, see the documentation for each endpoint below. For help using templates, check out our HTML Templates Guide or get started with a pre-designed template from our gallery. In Live mode, you can only have as many templates as allotted in your current Print & Mail Edition. There is no limit in Test mode.

If you'd like to interact with templates programmatically, check out our Beta Program for API access to the HTML Templates Endpoints.

Example Create Request using HTML Templates


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  metadata: %{
    campaign: "NEWYORK2015"
  },
  to: "adr_78c304d54912c502",
  from: "adr_61a0865c8c573139",
  front: "tmpl_b846a20859ae11a",
  back: "tmpl_01b0d396a10c268",
  merge_variables: %{
    name: "Harry"
  }
})

HTML Examples

Use a pre-designed template from our gallery or follow these basic guidelines as starting points for creating custom Postcards, Letters, and Checks.

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

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

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

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"). There is no need to include crop marks in your submitted content.
  • Include a safe zone – make sure no critical elements are within 1/8" from the edge of the final size.
  • Do not include any additional postage marks or indicia.
  • File sizes should be no larger than 5MB.

Prepping PDFs

To ensure that you are producing PDF's correctly please follow the guidelines below:

Prepping PNGs/JPEGs

To ensure that you are producing PNG's/JPEG's correctly please follow the guidelines below:

  • Minimum 300 dpi. The dpi is calculated as (width of image in pixels) / (width of product in inches) and (length of image in pixels) / (length of product in inches). For Example: 1275px x 1875px image used to create a 4.25" x 6.25" postcard has a dpi of 300.
  • Submitted images must have the same length to width ratio as the chosen product. Images will not be cropped or stretched by the API.

Standard PDF Fonts

Ideally, all fonts in provided PDFs should be embedded. Embedding a font in a PDF ensures that the final printed product will look as it was designed. Fonts can vary greatly in size and shape, even within the same family. If the exact font that was used to design the artwork is not used to print, the look and placement of the text is not guaranteed to be the same.

In general, requests that provide PDFs with un-embedded fonts will be rejected. We make an exception for "standard fonts", a set of fonts that we have identified as being common. PDFs that contain un-embedded fonts that are found in the list, and match the accepted font type will be accepted. Otherwise, the request will be rejected.

Font embedding is an essential part of standard PDF workflows. Fonts should be embedded automatically by PDF editing software that are compliant with PDF standards.

Font Name Types
Arial Type 1, TrueType, CID TrueType
Arial,Bold Type 1, TrueType, CID TrueType
Arial,BoldItalic Type 1, TrueType, CID TrueType
Arial,Italic TrueType, CID TrueType
ArialMT TrueType, CID TrueType
Arial-BoldMT TrueType
Arial-BoldItalicMT TrueType
Arial-ItalicMT TrueType
ArialNarrow TrueType
ArialNarrow-Bold TrueType
Calibri TrueType
Calibri-Bold TrueType
Calibri-Italic TrueType
Candara-Bold TrueType
Courier Type 1
Courier-Oblique Type 1
Courier-Bold Type 1
Courier-BoldOblique Type 1
CourierNewPSMT TrueType
CourierNewPS-ItalicMT TrueType
CourierNewPS-BoldMT TrueType
Helvetica Type 1
Helvetica-Bold Type 1
Helvetica-BoldOblique Type 1
Helvetica-Oblique Type 1
LucidaConsole TrueType
MsSansSerif TrueType
MsSansSerif,Bold TrueType
Symbol Type 1, TrueType
Tahoma TrueType
Tahoma-Bold TrueType
Times-Bold Type 1
Times-BoldItalic Type 1
Times-Italic Type 1
Times-Roman Type 1
TimesNewRomanPS-BoldItalicMT TrueType
TimesNewRomanPS-BoldMT TrueType
TimesNewRomanPS-ItalicMT TrueType
TimesNewRomanPSMT TrueType, CID TrueType
TimesNewRomanPSMT,Bold TrueType
TrebuchetMS TrueType
Verdana TrueType
Verdana-Bold TrueType
Verdana,Bold TrueType
Verdana,Italic TrueType
ZapfDingbats Type 1

Addresses

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

The address object

Fields

id: string

Unique identifier prefixed with adr_.

description: string or null
name: string or null
company: string or null
phone: string or null
email: string or null
address_line1: string
address_line2: string or null
address_city: string or null
address_state: string or null

Will be returned as a 2 letter state short-name code if address_country is US, otherwise will be returned as the full string.

address_zip: string or null
address_country: string

Will be returned as the full country name.

metadata: object
date_created: string

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

date_modified: string

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

deleted: boolean

Only returned if the address has been successfully deleted.

object: string

Value is address.

Example Response


{
  "id": "adr_d3489cd64c791ab5",
  "description": "Harry - Office",
  "name": "HARRY ZHANG",
  "company": "LOB",
  "phone": "5555555555",
  "email": "harry@lob.com",
  "address_line1": "185 BERRY ST STE 6100",
  "address_line2": null,
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107-1741",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2017-09-05T17:47:53.767Z",
  "date_modified": "2017-09-05T17:47:53.767Z",
  "object": "address"
}

Create an address

Creates a new address object. US addresses will be standardized and corrected using our US Verification engine whenever possible. Non-US addresses will be standardized into uppercase only. In Live mode, you can only have as many non-deleted addresses as allotted in your current Print & Mail Edition. If you attempt to create an address past your limit, you will receive a 403 error. There is no limit in Test mode.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

name: optional

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

company: optional

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

address_line1: required

Must be no longer than 64 characters for US addresses or 200 characters for international addresses.

address_line2: optional

Must be no longer than 64 characters for US addresses or 200 characters for international addresses.

address_city: optional

Required if address_country is US, otherwise optional. Must be no longer than 200 characters.

address_state: optional

Required and must be a 2 letter state short-name code or a valid full state name if address_country is US, otherwise optional and not any longer than 200 characters.

address_zip: optional

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

address_country: optional

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

phone: optional

Must be no longer than 40 characters.

email: optional

Must be no longer than 100 characters.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns an address object upon successful creation.

Example Definition

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

Example Request


Lob.Address.create(%{
  description: "Harry - Office",
  name: "Harry Zhang",
  company: "Lob",
  email: "harry@lob.com",
  phone: "5555555555",
  address_line1: "185 Berry St",
  address_line2: "# 6100",
  address_city: "San Francisco",
  address_state: "CA",
  address_country: "US",
  address_zip: "94107"
})

Example Response


{
  "id": "adr_d3489cd64c791ab5",
  "description": "Harry - Office",
  "name": "HARRY ZHANG",
  "company": "LOB",
  "phone": "5555555555",
  "email": "harry@lob.com",
  "address_line1": "185 BERRY ST STE 6100",
  "address_line2": null,
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107-1741",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2017-09-05T17:47:53.767Z",
  "date_modified": "2017-09-05T17:47:53.767Z",
  "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.

Path Parameters

id: required

The identifier of the address to be retrieved.

Returns

Returns an address object if a valid identifier was provided.

Example Definition

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

Example Request


Lob.Address.retrieve("adr_fa85158b26c3eb7c")

Example Response


{
  "id": "adr_fa85158b26c3eb7c",
  "description": "Harry - Office",
  "name": "HARRY ZHANG",
  "company": "LOB",
  "phone": "5555555555",
  "email": "harry@lob.com",
  "address_line1": "185 BERRY ST STE 6100",
  "address_line2": null,
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107-1741",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2017-09-05T17:47:53.767Z",
  "date_modified": "2017-09-05T17:47:53.767Z",
  "object": "address"
}

Delete an address

Permanently deletes a customer. It cannot be undone.

Path Parameters

id: required

The identifier of the address to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request


Lob.Address.delete("adr_43769b47aed248c2")

Example Response


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

List all addresses

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

Query Parameters

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

include: optional

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

metadata: optional

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

date_created: optional

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

Returns

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

Example Definition

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

Example Request


Lob.Address.list(%{limit: 2, offset: 1})

Example Response


{
  "data": [
    {
      "id": "adr_d3489cd64c791ab5",
      "description": "Harry - Office",
      "name": "HARRY ZHANG",
      "company": "LOB",
      "phone": "5555555555",
      "email": "harry@lob.com",
      "address_line1": "185 BERRY ST STE 6100",
      "address_line2": null,
      "address_city": "SAN FRANCISCO",
      "address_state": "CA",
      "address_zip": "94107-1741",
      "address_country": "UNITED STATES",
      "metadata": {},
      "date_created": "2017-09-05T17:47:53.767Z",
      "date_modified": "2017-09-05T17:47:53.767Z",
      "object": "address"
    },
    {
      "id": "adr_b8fb5acf3a2b55db",
      "description": "Leore - Office",
      "name": "LEORE AVIDAR",
      "company": "LOB",
      "phone": "5555555555",
      "email": "leore@lob.com",
      "address_line1": "185 BERRY ST STE 6100",
      "address_line2": null,
      "address_city": "SAN FRANCISCO",
      "address_state": "CA",
      "address_zip": "94107-1741",
      "address_country": "UNITED STATES",
      "metadata": {},
      "date_created": "2017-09-05T17:47:53.767Z",
      "date_modified": "2017-09-05T17:47:53.767Z",
      "object": "address"
    }
  ],
  "count": 2,
  "object": "list"
}

US Verifications

The US Verification API allows you to validate, automatically correct, and standardize your addresses based on USPS's Coding Accuracy Support System (CASS). It returns a US verification object based on provided inputs.

The US verification object

Fields

id: string

Unique identifier prefixed with us_ver_.

recipient: string

The intended recipient, typically a person's or firm's name.

primary_line: string

The primary delivery line (usually the street address) of the address. Combination of the following applicable components:

  • Primary Number (primary_number)
  • Street Predirection (street_predirection)
  • Street Name (street_name)
  • Street Suffix (street_suffix)
  • Street Postdirection (street_postdirection)
  • Secondary Designator (secondary_designator)
  • Secondary Number (secondary_number)
  • PMB Designator (pmb_designator)
  • PMB Number (pmb_number)
secondary_line: string

The secondary delivery line of the address. This field is typically empty but may contain information if primary_line is too long.

urbanization: string

Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city.

last_line: string

Combination of the following applicable components:

  • City (city)
  • State (state)
  • ZIP code (zip_code)
  • ZIP+4 (zip_code_plus_4)
deliverability: string

Summarizes the deliverability of the us_verification object. For full details, see the deliverability_analysis field. Possible values are:

  • deliverable — The address is deliverable by the USPS.
  • deliverable_unnecessary_unit — The address is deliverable, but the secondary unit information is unnecessary.
  • deliverable_incorrect_unit — The address is deliverable to the building's default address but the secondary unit provided may not exist. There is a chance the mail will not reach the intended recipient.
  • deliverable_missing_unit — The address is deliverable to the building's default address but is missing secondary unit information. There is a chance the mail will not reach the intended recipient.
  • undeliverable — The address is not deliverable according to the USPS.
components: object

A nested object containing a breakdown of each component of an address.

primary_number:
string

The numeric or alphanumeric part of an address preceding the street name. Often the house, building, or PO Box number.

street_predirection:
string

Geographic direction preceding a street name (N, E, S, W, NE, SE, NW, SW).

street_name:
string

The name of the street.

street_suffix:
string

The standard USPS abbreviation for the street suffix (ST, AVE, BLVD, etc).

street_postdirection:
string

Geographic direction following a street name (N, E, S, W, NE, SE, NW, SW).

secondary_designator:
string

The standard USPS abbreviation describing the components[secondary_number] (STE, APT, BLDG, etc).

secondary_number:
string

Number of the apartment/unit/etc.

pmb_designator:
string

Designator of a CMRA-authorized private mailbox.

pmb_number:
string

Number of a CMRA-authorized private mailbox.

extra_secondary_designator:
string

An extra (often unnecessary) secondary designator provided with the input address.

extra_secondary_number:
string

An extra (often unnecessary) secondary number provided with the input address.

city:
string

The name of the city.

state:
string

The state as a two-letter abbreviation.

zip_code:
string

The 5-digit ZIP code.

zip_code_plus_4:
string

The 4-digit ZIP add-on code.

zip_code_type:
string

A description of the ZIP code type. For more detailed information about each ZIP code type, see the appendix. Will be one of standard, military, unique, po_box, or an empty string.

delivery_point_barcode:
string

A 12-digit identifier that uniquely identifies a delivery point (location where mail can be sent and received). It consists of the 5-digit ZIP code (zip_code), 4-digit ZIP+4 add-on (zip_code_plus_4), 2-digit delivery point, and 1-digit delivery point check digit.

address_type:
string

Uses USPS's Residential Delivery Indicator (RDI) to identify whether an address is classified as residential or business. Possible values are:

  • residential — The address is residential or a PO Box.
  • commercial — The address is commercial.
  • empty string — Not enough information provided to be determined.
record_type:
string

A description of the type of address. Populated if a DPV match is made (deliverability_analysis[dpv_confirmation] is Y, S, or D). For more detailed information about each record type, see the appendix. Will be one of street, highrise, firm, po_box, rural_route, general_delivery, or an empty string.

default_building_address:
boolean

Designates whether or not the address is the default address for a building containing multiple delivery points.

county:
string

County name of the address.

county_fips:
string

A 5-digit FIPS county code which uniquely identifies components[county]. It consists of a 2-digit state code and a 3-digit county code.

carrier_route:
string

A 4-character code assigned to a mail delivery route within a ZIP code.

carrier_route_type:
string

The type of components[carrier_route]. For more detailed information about each carrier route type, see the appendix. Possible values are:

  • city_delivery — City delivery (starts with "C")
  • rural_route — Rural route (starts with "R")
  • highway_contract — Highway contract route (starts with "H")
  • po_box — P.O. Box route (starts with "B")
  • general_delivery — General delivery (starts with "G")
latitude:
decimal or null

A positive or negative decimal indicating the geographic latitude of the address, specifying the north-to-south position of a location. This should be used with longitude to pinpoint locations on a map. Will not be returned for undeliverable addresses or military addresses (state is AA, AE, or AP).

longitude:
decimal or null

A positive or negative decimal indicating the geographic longitude of the address, specifying the east-to-west position of a location. This should be used with latitude to pinpoint locations on a map. Will not be returned for undeliverable addresses or military addresses (state is AA, AE, or AP).

deliverability_analysis: object

A nested object containing a breakdown of the deliverability of an address.

dpv_confirmation:
string

Result of Delivery Point Validation (DPV), which determines whether or not the address is deliverable by the USPS. Possible values are:

  • Y — The address is deliverable by the USPS.
  • S — The address is deliverable by removing the provided secondary unit designator. This information may be incorrect or unnecessary.
  • D — The address is deliverable to the building's default address but is missing a secondary unit designator and/or number. There is a chance the mail will not reach the intended recipient.
  • N — The address is not deliverable according to the USPS, but parts of the address are valid (such as the street and ZIP code).
  • empty string — This address is not deliverable. No matching street could be found within the city or ZIP code.
dpv_cmra:
string

Indicates whether or not the address is CMRA-authorized. Possible values are:

  • Y — Address is CMRA-authorized
  • N — Address is not CMRA-authorized.
  • empty string — A DPV match is not made (deliverability_analysis[dpv_confirmation] is N or an empty string)
dpv_vacant:
string

Indicates that an address was once deliverable, but has become vacant and is no longer receiving deliveries. Possible values are:

  • Y — Address is vacant
  • N — Address is not vacant
  • empty string — A DPV match is not made (deliverability_analysis[dpv_confirmation] is N or an empty string)
dpv_footnotes:
array

An array of 2-character strings that gives more insight into how deliverability_analysis[dpv_confirmation] was determined. Will always include at least 1 string, and can include up to 3. For possible values and details, see the appendix.

ews_match:
boolean

Indicates whether or not an address has been flagged in the Early Warning System (EWS), meaning the address is under development and not yet ready to receive mail. However, it should become available in a few months.

lacs_indicator:
string

Indicates whether the address was matched and converted by LACSLink. LACSLink corrects outdated addresses into their modern counterparts. Possible values are:

  • Y — New address produced with a matching record in LACSLink.
  • N — New address could not be produced because no match was found in LACSLink.
  • empty string — LACSLink was not attempted.
lacs_return_code:
string

A code indicating how deliverability_analysis[lacs_indicator] was determined. Possible values are:

  • A — A new address was produced because a match was found in LACSLink.
  • 92 — A LACSLink record was matched after dropping secondary information.
  • 14 — A match was found in LACSLink, but could not be converted to a deliverable address.
  • 00 — A match was not found in LACSLink, and no new address was produced.
  • empty string — LACSLink was not attempted.
suite_return_code:
string

Indicates whether the address was matched and corrected by SuiteLink. SuiteLink attempts to provide secondary information businesses. Possible values are:

  • A — A SuiteLink match was found and secondary information was added.
  • 00 — A SuiteLink match could not be found and no secondary information was added.
  • empty string — SuiteLink lookup was not attempted.
object: string

Value is us_verification.

Example Response


{
  "id": "us_ver_c7cb63d68f8d6",
  "recipient": "LOB.COM",
  "primary_line": "185 BERRY ST STE 6100",
  "secondary_line": "",
  "urbanization": "",
  "last_line": "SAN FRANCISCO CA 94107-1728",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "185",
    "street_predirection": "",
    "street_name": "BERRY",
    "street_suffix": "ST",
    "street_postdirection": "",
    "secondary_designator": "STE",
    "secondary_number": "6100",
    "pmb_designator": "",
    "pmb_number": "",
    "extra_secondary_designator": "",
    "extra_secondary_number": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip_code": "94107",
    "zip_code_plus_4": "1728",
    "zip_code_type": "standard",
    "delivery_point_barcode": "941071728506",
    "address_type": "commercial",
    "record_type": "highrise",
    "default_building_address": false,
    "county": "SAN FRANCISCO",
    "county_fips": "06075",
    "carrier_route": "C001",
    "carrier_route_type": "city_delivery",
    "latitude": 37.77597542841264,
    "longitude": -122.3929557343685
  },
  "deliverability_analysis": {
    "dpv_confirmation": "Y",
    "dpv_cmra": "N",
    "dpv_vacant": "N",
    "dpv_footnotes": [
      "AA",
      "BB"
    ],
    "ews_match": false,
    "lacs_indicator": "",
    "lacs_return_code": "",
    "suite_return_code": ""
  },
  "object": "us_verification"
}

Verify a US address

Verify a US or US territory address with a live API key. The address can be in components (e.g. primary_line is "185 Berry Street", zip_code is "94107") or as a single string (e.g. "185 Berry Street 94107"), but not as both. Requests using a test API key validate required fields but return empty values unless specific primary_line values are provided. See The US Verifications Test Environment for details.

Query Parameters

case: optional

Casing of the verified address. Possible values are upper and proper for uppercased (e.g. "PO BOX") and proper-cased (e.g. "PO Box"), respectively. Only affects recipient, primary_line, secondary_line, urbanization, and last_line. Default casing is upper.

Payload Parameters

recipient: optional

The intended recipient, typically a person's or firm's name.

primary_line: required
secondary_line: optional
urbanization: optional

Only used for addresses in Puerto Rico.

city: optional

city and state are required if no zip_code is passed.

state: optional

city and state are required if no zip_code is passed.

zip_code: optional

Required if no city and state are passed. If they are not passed, must resemble a US ZIP or ZIP+4 (e.g. 2268, 94107, 941072282, 94107-2282).

OR
address: required

The entire address in one string (e.g. "185 Berry Street 94107"). Does not support a recipient and will error when other payload parameters are provided.

Returns

A US verification object with detailed information about the corrected address.

Example Definition

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

Example Request


Lob.USVerification.verify(%{
  primary_line: "185 Berry Street",
  city: "San Francisco",
  state: "CA",
  zip_code: "94107"
})

Example Response


{
  "id": "us_ver_c7cb63d68f8d6",
  "recipient": "LOB.COM",
  "primary_line": "185 BERRY ST STE 6100",
  "secondary_line": "",
  "urbanization": "",
  "last_line": "SAN FRANCISCO CA 94107-1728",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "185",
    "street_predirection": "",
    "street_name": "BERRY",
    "street_suffix": "ST",
    "street_postdirection": "",
    "secondary_designator": "STE",
    "secondary_number": "6100",
    "pmb_designator": "",
    "pmb_number": "",
    "extra_secondary_designator": "",
    "extra_secondary_number": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip_code": "94107",
    "zip_code_plus_4": "1728",
    "zip_code_type": "standard",
    "delivery_point_barcode": "941071728506",
    "address_type": "commercial",
    "record_type": "highrise",
    "default_building_address": false,
    "county": "SAN FRANCISCO",
    "county_fips": "06075",
    "carrier_route": "C001",
    "carrier_route_type": "city_delivery",
    "latitude": 37.77597542841264,
    "longitude": -122.3929557343685
  },
  "deliverability_analysis": {
    "dpv_confirmation": "Y",
    "dpv_cmra": "N",
    "dpv_vacant": "N",
    "dpv_footnotes": [
      "AA",
      "BB"
    ],
    "ews_match": false,
    "lacs_indicator": "",
    "lacs_return_code": "",
    "suite_return_code": ""
  },
  "object": "us_verification"
}

The US verifications test environment

When verifying US addresses, you'll likely want to test against a wide array of addresses to ensure you're handling responses correctly. With your test API key, requests that use specific values for address or primary_line and an an arbitrary five digit number for zip_code (e.g. "11111") let you explore the responses to many types of addresses:

to get a sample response for set primary_line or address to
Commercial highrise (deliverable) commercial highrise
Residential highrise (deliverable) residential highrise
Residential house (deliverable and also the Full House house) residential house
PO Box (deliverable) po box
Rural route (deliverable) rural route
Puerto Rico address with an urbanization (deliverable) puerto rico
Military address (deliverable) military
Department of state (deliverable) department of state
Generic deliverable deliverable
Missing a suite number missing unit
Suite number doesn't exist incorrect unit
Residential house with a suite number that's unnecessary unnecessary unit
Undeliverable and a block was matched undeliverable block match
Undeliverable and no block was matched undeliverable no match

You can rely on the response from these examples generally matching the response you'd see in the live environment with an address of that type (excluding the recipient field).

The test API key does not perform any verification, automatic correction, or standardization for addresses. If you wish to try these features out, use our live demo or the free plan (see our pricing for details).

Example Request


Lob.USVerification.verify(%{
  primary_line: "po box",
  zip_code: "11111"
})

Example Response


{
  "id": "us_ver_po_box",
  "recipient": "TEST KEYS DO NOT VERIFY ADDRESSES",
  "primary_line": "PO BOX 720114",
  "secondary_line": "",
  "urbanization": "",
  "last_line": "SAN FRANCISCO CA 94172-0114",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "720114",
    "street_predirection": "",
    "street_name": "PO BOX",
    "street_suffix": "",
    "street_postdirection": "",
    "secondary_designator": "",
    "secondary_number": "",
    "pmb_designator": "",
    "pmb_number": "",
    "extra_secondary_designator": "",
    "extra_secondary_number": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip_code": "94172",
    "zip_code_plus_4": "0114",
    "zip_code_type": "po_box",
    "delivery_point_barcode": "941720114146",
    "address_type": "residential",
    "record_type": "po_box",
    "default_building_address": false,
    "county": "SAN FRANCISCO",
    "county_fips": "06075",
    "carrier_route": "B002",
    "carrier_route_type": "po_box",
    "latitude": 37.75971500260575,
    "longitude": -122.69397561170017
  },
  "deliverability_analysis": {
    "dpv_confirmation": "Y",
    "dpv_cmra": "N",
    "dpv_vacant": "N",
    "dpv_footnotes": [
      "AA",
      "BB"
    ],
    "ews_match": false,
    "lacs_indicator": "",
    "lacs_return_code": "",
    "suite_return_code": ""
  },
  "object": "us_verification"
}}

US Autocomplete

The US Autocomplete API takes the beginning of an address (e.g. "185 Berr") and retrieves a list of up to ten suggested addresses that match. It can't suggest addresses when given:

  • A business or location name (e.g. "Lob")
  • A single line address (e.g. "185 Berry Street Suite 6100, San Francisco, CA 94107")
Additionally, the suggested addresses are not guaranteed to be deliverable, each suggested address needs to be verified.

The US autocompletion object

Fields

id: string

Unique identifier prefixed with us_auto_.

suggestions: array

An array of objects representing suggested addresses. The suggested address object is as follows:

primary_line:
string

The primary delivery line (usually the street address) of the address. Street number may not be valid or may be missing a secondary number (e.g. unit or apartment).

city:
string

The name of the city.

state:
string

The state as a two-letter abbreviation.

zip_code:
string

The 5-digit ZIP code.

object: string

Value is us_autocompletion.

Example Response


{
  "id": "us_auto_d4bad6f61ede46498844",
  "suggestions": [
    {
      "primary_line": "185 BERNICE ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94103"
    },
    {
      "primary_line": "185 BERRY ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94107"
    },
    {
      "primary_line": "185 BERGEN ALY",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94109"
    },
    {
      "primary_line": "185 BERNAL HEIGHTS BLVD",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94110"
    },
    {
      "primary_line": "185 BERKSHIRE WAY",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94132"
    },
    {
      "primary_line": "185 BERSIDER DR",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94132"
    },
    {
      "primary_line": "185 BERRY ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94158"
    },
    {
      "primary_line": "185 BERNARD ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94109"
    },
    {
      "primary_line": "185 BERTITA ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94112"
    },
    {
      "primary_line": "185 BERTIE MINOR LN",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94115"
    }
  ],
  "object": "us_autocompletion"
}

Autocomplete a US address

Returns a list of up to ten suggested addresses that match a given address prefix and optional filters. Like US verifications, there is a rate limit of 300 requests per 5 seconds. If you need more please contact support@lob.com.

Payload Parameters

address_prefix: required

Prefix of an address. Only supports street number and name and does not accept non-alphanumeric characters.

city: optional

An optional city to filter suggestions by. Case insensitive and does not match partial cities.

state: optional

An optional two-letter state abbreviation to filter suggestions by. Case insensitive and does not match partial abbreviations.

geo_ip_sort: optional

If true, sort suggestions by proximity to the IP set in the X-Forwarded-For header.

Returns

A US autocompletion object with up to ten suggested addresses.

Example Definition

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

Example Request


Lob.USAutocompletion.autocomplete(%{
  address_prefix: "185 Ber",
  city:           "San Francisco",
  state:          "CA"
})

Example Response


{
  "id": "us_auto_d4bad6f61ede46498844",
  "suggestions": [
    {
      "primary_line": "185 BERNICE ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94103"
    },
    {
      "primary_line": "185 BERRY ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94107"
    },
    {
      "primary_line": "185 BERGEN ALY",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94109"
    },
    {
      "primary_line": "185 BERNAL HEIGHTS BLVD",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94110"
    },
    {
      "primary_line": "185 BERKSHIRE WAY",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94132"
    },
    {
      "primary_line": "185 BERSIDER DR",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94132"
    },
    {
      "primary_line": "185 BERRY ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94158"
    },
    {
      "primary_line": "185 BERNARD ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94109"
    },
    {
      "primary_line": "185 BERTITA ST",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94112"
    },
    {
      "primary_line": "185 BERTIE MINOR LN",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94115"
    }
  ],
  "object": "us_autocompletion"
}

The US autocomplete test environment

Your test API key does not autocomplete US addresses and is used to simulate behavior. With your test API key, requests with specific values for address_prefix return predetermined values. When address_prefix is set to:

  • 0 suggestions - Returns no suggestions
  • [ANY NUMBER] s[uggestion] - Returns a maximum of ten predefined suggested addresses. Each additional letter in suggestion reduces the number of suggestions by one (e.g. 1 su returns 9 suggested addresses). [ANY NUMBER] does not affect the number of suggestions returned.

City and state filters work as expected and filter the list of predetermined suggested addresses.

Example Request


Lob.USAutocompletion.autocomplete(%{
  address_prefix: "1 sugg"
})

Example Response


{
  "id": "us_auto_242ebfa5fb1043f1b52a",
  "suggestions": [
    {
      "primary_line": "1 TELEPHONE RD",
      "city": "OXFORD",
      "state": "AR",
      "zip_code": "72565"
    },
    {
      "primary_line": "1 TELEGA PL",
      "city": "PALMDALE",
      "state": "CA",
      "zip_code": "93550"
    },
    {
      "primary_line": "1 TELEGRAM AVE",
      "city": "ELMONT",
      "state": "NY",
      "zip_code": "11003"
    },
    {
      "primary_line": "1 TELEGRAM AVE",
      "city": "GARDEN CITY",
      "state": "KS",
      "zip_code": "67846"
    },
    {
      "primary_line": "1 TELEGRAPH HILL RD",
      "city": "HOLMDEL",
      "state": "NJ",
      "zip_code": "07733"
    },
    {
      "primary_line": "1 TELEGRAPH HILL RD S",
      "city": "HOLMDEL",
      "state": "NJ",
      "zip_code": "07733"
    },
    {
      "primary_line": "1 TELEGRAPH HILL BLVD",
      "city": "SAN FRANCISCO",
      "state": "CA",
      "zip_code": "94133"
    }
  ],
  "object": "us_autocompletion"
}

US ZIP Lookups

The US ZIP Lookup API allows you to find a list of cities, states, and associated information about a ZIP code. It will return a US ZIP Lookup object based on a provided input ZIP code.

The US ZIP lookup object

Fields

id: string

Unique identifier prefixed with us_zip_.

zip_code: string

The 5-digit ZIP code.

zip_code_type: string

A description of the ZIP code type. For more detailed information about each ZIP code type, see the appendix. Will be one of standard, military, unique, po_box, or an empty string.

cities: array

An array of city objects containing valid cities for the zip_code. Multiple cities will be returned if more than one city is associated with the input ZIP code. Each city object contains the following information associated with that city:

city:
string

The name of the city.

state:
string

The state as a two-letter abbreviation.

county:
string

The name of the county that contains this city.

county_fips:
string

A 5-digit FIPS county code which uniquely identifies components[county]. It consists of a 2-digit state code and a 3-digit county code.

preferred:
boolean

Indicates whether or not the city is the USPS default city (preferred city) of a ZIP code. There is only one preferred city per ZIP code, which will always be in position 0 in the array of cities.

object: string

Value is us_zip_lookup.

Example Response


{
  "id": "us_zip_c7cb63d68f8d6",
  "zip_code": "94107",
  "zip_code_type": "standard",
  "cities": [
    {
      "city": "SAN FRANCISCO",
      "state": "CA",
      "county": "SAN FRANCISCO",
      "county_fips": "06075",
      "preferred": true
    }
  ],
  "object": "us_zip_lookup"
}

Lookup a US ZIP code

Lookup a US ZIP code. Only requests with live API keys will generate a valid response. Properly formatted requests with test API keys will return the generic dummy response on the right, regardless of inputs.

Payload Parameters

zip_code: required

Must be a valid 5-digit US ZIP code.

Returns

A US ZIP Lookup object with detailed information about the input ZIP code.

Example Definition

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

Example Request


Lob.USZipLookup.lookup(%{
  zip_code: "94107"
})

Example Response


{
  "id": "us_zip_c7cb63d68f8d6",
  "zip_code": "94107",
  "zip_code_type": "standard",
  "cities": [
    {
      "city": "SAN FRANCISCO",
      "state": "CA",
      "county": "SAN FRANCISCO",
      "county_fips": "06075",
      "preferred": true
    }
  ],
  "object": "us_zip_lookup"
}

International Verifications

Address verification for international (non-US) addresses.

The International verification object

Fields

id: string

Unique identifier prefixed with intl_ver_.

recipient: string

The intended recipient, typically a person's or firm's name.

primary_line: string

The primary delivery line (usually the street address) of the address.

secondary_line: string

The secondary delivery line of the address. This field is typically empty but may contain information if primary_line is too long.

last_line: string

Combination of the following applicable components:

  • City (city)
  • State (state)
  • Postal code (postal_code)
country: string

The country of the address. Will be returned as a 2 letter country short-name code (ISO 3166).

deliverability: string

Summarizes the deliverability of the intl_verification object. Possible values are:

  • deliverable — The address is deliverable.
  • deliverable_missing_info — The address is missing some information, but is most likely deliverable.
  • undeliverable — The address is most likely not deliverable. Some components of the address (such as city or postal code) may have been found.
  • no_match — This address is not deliverable. No matching street could be found within the city or postal code.
components: object

A nested object containing a breakdown of each component of an address.

primary_number:
string

The numeric or alphanumeric part of an address preceding the street name. Often the house, building, or PO Box number.

street_name:
string

The name of the street.

city:
string

The name of the city.

state:
string

The name of the state.

postal_code:
string

The postal code.

object: string

Value is intl_verification.

Example Response


{
  "id": "intl_ver_c7cb63d68f8d6",
  "recipient": null,
  "primary_line": "370 WATER ST",
  "secondary_line": "",
  "last_line": "SUMMERSIDE PE C1N 1C4",
  "country": "CA",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "370",
    "street_name": "WATER ST",
    "city": "SUMMERSIDE",
    "state": "PE",
    "postal_code": "C1N 1C4"
  },
  "object": "intl_verification"
}

Verify an international address

Verify an international (except US or US territories) address with a live API key. Requests to this endpoint with a test API key will return a 403 error.

Payload Parameters

recipient: optional
primary_line: required
secondary_line: optional
city: optional
state: optional
postal_code: optional
country: required

Must be a 2 letter country short-name code (ISO 3166). Does not accept US, AS, PR, FM, GU, MH, MP, PW, or VI. For these addresses, please use the US verification API.

Returns

Returns the validated address object, along with it's deliverability status.

Example Definition

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

Example Request


Lob.IntlVerification.verify(%{
  primary_line: "370 Water St",
  city: "Summerside",
  state: "Prince Edward Island",
  postal_code: "C1N 1C4",
  country: "CA"
})

Example Response


{
  "id": "intl_ver_c7cb63d68f8d6",
  "recipient": null,
  "primary_line": "370 WATER ST",
  "secondary_line": "",
  "last_line": "SUMMERSIDE PE C1N 1C4",
  "country": "CA",
  "deliverability": "deliverable",
  "components": {
    "primary_number": "370",
    "street_name": "WATER ST",
    "city": "SUMMERSIDE",
    "state": "PE",
    "postal_code": "C1N 1C4"
  },
  "object": "intl_verification"
}

Postcards

The postcards endpoint allows you to easily print and mail postcards. The API provides endpoints for creating postcards, retrieving individual postcards, canceling postcards, and retrieving a list of postcards.

The postcard object

Fields

id: string

Unique identifier prefixed with psc_.

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

A signed link to the rendered postcard.

front_template_id: string or null

The unique ID of the HTML template used for the front of the postcard.

back_template_id: string or null

The unique ID of the HTML template used for the back of the postcard.

front_template_version_id: string or null

The unique ID of the specific version of the HTML template used for the front of the postcard.

back_template_version_id: string or null

The unique ID of the specific version of the HTML template used for the back of the postcard.

carrier: string

Value is USPS.

tracking_events: array

An array of tracking_event objects. Will not be populated for postcards created in test mode.

thumbnails: array

Signed links to different sized thumbnails of each postcard page.

size: string

Value is 4x6, 6x9, or 6x11.

mail_type: string

Value is usps_first_class or usps_standard.

expected_delivery_date: string

A date in ISO 8601 format of the postcard's expected delivery date based on its send_date.

date_created: string

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

date_modified: string

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

send_date: string

A timestamp in ISO 8601 format of the date the postcard will be dispatched for production. If the send_date of a postcard has passed, it can no longer be canceled. send_date will be the date_created of the postcard plus the cancellation window, if one was applied at the time of the postcard's creation. If a postcard was scheduled using the send_date parameter, that timestamp will be returned here. For billing purposes, mailings will count towards usage in the month of their send_date.

deleted: boolean

Only returned if the postcard has been successfully canceled.

object: string

Value is postcard.

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "url": "https://lob-assets.com/postcards/psc_14c1b66f31264c34.pdf?expires=1540372221&signature=laxRaNF2f4snhba42y2jnlBMVlCsOpR",
  "front_template_id": null,
  "back_template_id": null,
  "front_template_version_id": null,
  "back_template_version_id": null,
  "carrier": "USPS",
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_small_1.png?expires=1540372221&signature=ppBe0OaXhqIDAbqjpZWbe97X62aboq8",
      "medium": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_medium_1.png?expires=1540372221&signature=pabTgNdaOor1DTHTDVmQLwZVGimb11q",
      "large": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_large_1.png?expires=1540372221&signature=HJRgDy7zAya1Vo0rbGsrQrjnQxTbaJf"
    },
    {
      "small": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_small_2.png?expires=1540372221&signature=Kpin30JOVaz8DldmbTIy9xusSff0V9G",
      "medium": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_medium_2.png?expires=1540372221&signature=4hl8ImocLv3HM7nQVz49YslueCfN5Oj",
      "large": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_large_2.png?expires=1540372221&signature=m9vFKyKoUBS0kbay2DSchggBBkaY8mq"
    }
  ],
  "size": "4x6",
  "mail_type": "usps_first_class",
  "expected_delivery_date": "2017-09-12",
  "date_created": "2017-09-05T17:47:53.967Z",
  "date_modified": "2017-09-05T17:47:53.967Z",
  "send_date": "2017-09-05T17:47:53.967Z",
  "object": "postcard"
}

Create a postcard

Create a new postcard.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

to: required

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail Strictness Setting, the request will fail. Read more here.

from: optional

Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification.

front: required

The artwork to use as the front of your postcard. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to the specified size. See here for HTML examples.

back: required

The artwork to use as the back of your postcard. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 4.25"x6.25", 6.25"x9.25", or 6.25"x11.25" at 300 DPI, while supplied HTML will be rendered to the specified size. Be sure to leave room for address and postage information by following the templates provided here: 4x6 template, 6x9 template, 6x11 template. See here for HTML examples.

merge_variables: optional

Variables can be defined in your HTML with double curly braces, e.g. {{variable_name}}. Use merge_variables to provide replacements for those variables to create custom content. merge_variables must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Nested objects are not supported. Depending on your Merge Variable Strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string.

size: optional

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

mail_type: optional

A string designating the mail postage type. Options are usps_first_class or usps_standard. Defaults to usps_first_class. usps_standard is a cheaper option which is less predictable and takes longer to deliver. usps_standard cannot be used with 4x6 postcards or for any postcards sent outside of the United States.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 90 days in the future to send the postcard off for production. This will override any postcard cancellation window applied to the postcard. Until the send_date has passed, the postcard will be cancelable. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a postcard object upon successful creation.

Example Definition

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

Example Request with HTML strings


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  front: "<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>",
  back: "<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>",
  merge_variables: %{
    name: "Harry"
  }
})

Example Request with saved HTML templates


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  front: "tmpl_b846a20859ae11a",
  back: "tmpl_01b0d396a10c268",
  merge_variables: %{
    name: "Harry"
  }
})

Example Request with Remote Files


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_country: "US",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_country: "US",
    address_zip: "94107"
  },
  front: "https://lob.com/postcardfront.pdf",
  back: "https://lob.com/postcardback.pdf"
})

Example Request with Local Files


Lob.Postcard.create(%{
  description: "Demo Postcard job",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  front: %{
    local_path: "/path/to/your/front.pdf"
  },
  back: %{
    local_path: "/path/to/your/back.pdf"
  }
})

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "url": "https://lob-assets.com/postcards/psc_14c1b66f31264c34.pdf?expires=1540372221&signature=laxRaNF2f4snhba42y2jnlBMVlCsOpR",
  "front_template_id": null,
  "back_template_id": null,
  "front_template_version_id": null,
  "back_template_version_id": null,
  "carrier": "USPS",
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_small_1.png?expires=1540372221&signature=ppBe0OaXhqIDAbqjpZWbe97X62aboq8",
      "medium": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_medium_1.png?expires=1540372221&signature=pabTgNdaOor1DTHTDVmQLwZVGimb11q",
      "large": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_large_1.png?expires=1540372221&signature=HJRgDy7zAya1Vo0rbGsrQrjnQxTbaJf"
    },
    {
      "small": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_small_2.png?expires=1540372221&signature=Kpin30JOVaz8DldmbTIy9xusSff0V9G",
      "medium": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_medium_2.png?expires=1540372221&signature=4hl8ImocLv3HM7nQVz49YslueCfN5Oj",
      "large": "https://lob-assets.com/postcards/psc_14c1b66f31264c34_thumb_large_2.png?expires=1540372221&signature=m9vFKyKoUBS0kbay2DSchggBBkaY8mq"
    }
  ],
  "size": "4x6",
  "mail_type": "usps_first_class",
  "expected_delivery_date": "2017-09-12",
  "date_created": "2017-09-05T17:47:53.967Z",
  "date_modified": "2017-09-05T17:47:53.967Z",
  "send_date": "2017-09-05T17:47:53.967Z",
  "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.

Path Parameters

id: required

The identifier of the postcard to be retrieved.

Returns

Returns a postcard object if a valid identifier was provided.

Example Definition

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

Example Request


Lob.Postcard.find("psc_5c002b86ce47537a")

Example Response


{
  "id": "psc_5c002b86ce47537a",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": "LOB",
    "phone": "5555555555",
    "email": "harry@lob.com",
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": null,
  "url": "https://lob-assets.com/postcards/psc_5c002b86ce47537a.pdf?expires=1540372221&signature=UN5eVH2fILQbab0ZYHly9Oa6Znb2QlM",
  "carrier": "USPS",
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/postcards/psc_5c002b86ce47537a_thumb_small_1.png?expires=1540372221&signature=xmgnC2r9RQU8eSabJAhKXtgalZD5Mml",
      "medium": "https://lob-assets.com/postcards/psc_5c002b86ce47537a_thumb_medium_1.png?expires=1540372221&signature=Y71Na96hI7Po34b5F6uj26ufR5ayxNm",
      "large": "https://lob-assets.com/postcards/psc_5c002b86ce47537a_thumb_large_1.png?expires=1540372221&signature=2jkqoiT9KbUo7qe70nrRVxmMjYHLtGi"
    },
    {
      "small": "https://lob-assets.com/postcards/psc_5c002b86ce47537a_thumb_small_2.png?expires=1540372221&signature=503MLgiWoaQvkhFZ7b7VD4hSTZ7CVM3",
      "medium": "https://lob-assets.com/postcards/psc_5c002b86ce47537a_thumb_medium_2.png?expires=1540372221&signature=LZFsgcq6aA4qUEz9XSLtptj0JPoxAeG",
      "large": "https://lob-assets.com/postcards/psc_5c002b86ce47537a_thumb_large_2.png?expires=1540372221&signature=3OGjuOdN0mrmBaOeB5BdIG6YLIQNja2"
    }
  ],
  "size": "4x6",
  "mail_type": "usps_first_class",
  "date_created": "2017-09-05T17:47:53.815Z",
  "date_modified": "2017-09-05T17:47:53.815Z",
  "send_date": "2017-09-05T17:47:53.815Z",
  "expected_delivery_date": "2017-09-12",
  "object": "postcard"
}

Cancel a postcard

Completely removes a postcard from production. This can only be done if the postcard’s send_date has not yet passed. If the postcard is successfully canceled, you will not be charged for it. Read more on postcard cancellation windows and scheduling postcards. This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.

Path Parameters

id: required

The identifier of the postcard to be canceled.

Returns

Returns a message that the cancellation was successful.

Example Definition

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

Example Request


Lob.Postcard.destroy("psc_5c002b86ce47537a")

Example Response


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

List all postcards

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

Query Parameters

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

include: optional

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

metadata: optional

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

date_created: optional

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

size: optional

The postcard sizes to be returned. Must be a non-empty string array of valid sizes. Acceptable values are 4x6, 6x9, and 6x11.

scheduled: optional

Set scheduled to true to only return orders (past or future) where send_date is greater than date_created. Set scheduled to false to only return orders where send_date is equal to date_created.

send_date: optional

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

mail_type: optional
sort_by: optional

Sorts postcards in a desired order. sort_by accepts an object with the key being either date_created or send_date and the value being either asc or desc.

Returns

A dictionary with a data property that contains an array of up to limit 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


Lob.Postcard.list(%{limit: 2, offset: 0})

Example Response


{
  "data": [
    {
      "id": "psc_2a379c909c5d6341",
      "description": "Demo Postcard Job",
      "metadata": {},
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": null,
      "url": "https://lob-assets.com/postcards/psc_2a379c909c5d6341.pdf?expires=1540372221&signature=isB0UZSb96jzTiUTGW4br3tqJcRvWUa",
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/postcards/psc_2a379c909c5d6341_thumb_small_1.png?expires=1540372221&signature=S1EuG1bEorWDy4iqRjRuQbmYBamJPa4",
          "medium": "https://lob-assets.com/postcards/psc_2a379c909c5d6341_thumb_medium_1.png?expires=1540372221&signature=89nPFdbIdd8xJ9moSfZdsdMGA7cNiUb",
          "large": "https://lob-assets.com/postcards/psc_2a379c909c5d6341_thumb_large_1.png?expires=1540372221&signature=8yt62EQZhyO2Qd4i0UJKtg5p18BUgMF"
        },
        {
          "small": "https://lob-assets.com/postcards/psc_2a379c909c5d6341_thumb_small_2.png?expires=1540372221&signature=2E1aOxfIzvUseTaSRoWmygjv2jxpDiW",
          "medium": "https://lob-assets.com/postcards/psc_2a379c909c5d6341_thumb_medium_2.png?expires=1540372221&signature=349TIj3liZbAa2LbBCca74aRnMQO7qL",
          "large": "https://lob-assets.com/postcards/psc_2a379c909c5d6341_thumb_large_2.png?expires=1540372221&signature=RLgn8yWZOivdismNsTIP6kBhDP3YZq2"
        }
      ],
      "size": "4x6",
      "mail_type": "usps_first_class",
      "date_created": "2017-09-05T17:47:54.267Z",
      "date_modified": "2017-09-05T17:47:54.267Z",
      "send_date": "2017-09-05T17:47:54.267Z",
      "expected_delivery_date": "2017-09-12",
      "object": "postcard"
    },
    {
      "id": "psc_66a94c0e4b004efd",
      "description": "Demo Postcard Job",
      "metadata": {},
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company":null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": null,
      "url": "https://lob-assets.com/postcards/psc_66a94c0e4b004efd.pdf?expires=1540372221&signature=hdJ2UuJIKXDtbVNHeTRzxnQKOUWqbiz",
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/postcards/psc_66a94c0e4b004efd_thumb_small_1.png?expires=1540372221&signature=IToYikLgZaAmQexqXauTraqgSGdQy4C",
          "medium": "https://lob-assets.com/postcards/psc_66a94c0e4b004efd_thumb_medium_1.png?expires=1540372221&signature=tKta8zpZO1V7xVtZEgDCWQkuNB45myT",
          "large": "https://lob-assets.com/postcards/psc_66a94c0e4b004efd_thumb_large_1.png?expires=1540372221&signature=wHVaxsN3JYlLpK0Xk10wrc4A9l9CN7s"
        },
        {
          "small": "https://lob-assets.com/postcards/psc_66a94c0e4b004efd_thumb_small_2.png?expires=1540372221&signature=wPz79Nbg52B7HUGdTbaMkHhhpmt1AEz",
          "medium": "https://lob-assets.com/postcards/psc_66a94c0e4b004efd_thumb_medium_2.png?expires=1540372221&signature=NUesIQgypabWd0ePoGcFAqOaYVMO8x3",
          "large": "https://lob-assets.com/postcards/psc_66a94c0e4b004efd_thumb_large_2.png?expires=1540372221&signature=2wpbMog930SR2Ob2PqkTqlNbSjimQ21"
        }
      ],
      "size": "4x6",
      "mail_type": "usps_first_class",
      "date_created": "2017-09-05T17:47:54.182Z",
      "date_modified": "2017-09-05T17:47:54.182Z",
      "send_date": "2017-09-05T17:47:54.182Z",
      "expected_delivery_date": "2017-09-12",
      "object": "postcard"
    }
  ],
  "count": 2,
  "object": "list"
}

Letters

The letters endpoint allows you to easily print and mail letters. The API provides endpoints for creating letters, retrieving individual letters, canceling letters, and retrieving a list of letters.

The letter object

Fields

id: string

Unique identifier prefixed with ltr_.

description: string or null
metadata: object
to: an address object
from: an address object
color: boolean
double_sided: boolean
address_placement: string

Value is top_first_page or insert_blank_page.

return_envelope: boolean
perforated_page: integer or null

Value will be the final page to be perforated, including modifications made by insert_blank_page.

extra_service: string or null

Value is certified or registered.

mail_type: string

Value is usps_first_class or usps_standard.

url: string

A signed link to the rendered letter.

template_id: string or null

The unique ID of the HTML template used for the letter.

template_version_id: string or null

The unique ID of the specific version of the HTML template used for the letter.

carrier: string

Value is USPS.

tracking_number: string or null

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

tracking_events: array

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

thumbnails: array

Signed links to different sized thumbnails of each letter page.

expected_delivery_date: string

A date in ISO 8601 format of the letter's expected delivery date based on its send_date.

date_created: string

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

date_modified: string

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

send_date: string

A timestamp in ISO 8601 format of the date the letter will be dispatched for production. If the send_date of a letter has passed, it can no longer be canceled. send_date will be the date_created of the letter plus the cancellation window, if one was applied at the time of the letter's creation. If a letter was scheduled using the send_date parameter, that timestamp will be returned here. For billing purposes, mailings will count towards usage in the month of their send_date.

deleted: boolean

Only returned if the letter has been successfully canceled.

object: string

Value is letter.

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "extra_service": null,
  "mail_type": "usps_first_class",
  "url": "https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=qjatwPv3jPJlQayBYQeIm42qtavaP7q",
  "template_id": null,
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=GgFjpAduYT13yFYAJWVCAp8YRMRD7m1",
      "medium": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=0avnWJxyfhZ8Ccfd9m0ERYG1kSCJ0W2",
      "large": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=T8EwlE6P7QIKt3GIHU1Z1xrArNDZOkf"
    }
  ],
  "expected_delivery_date": "2017-09-12",
  "date_created": "2017-09-05T15:54:53.346Z",
  "date_modified": "2017-09-05T15:54:53.346Z",
  "send_date": "2017-09-05T15:54:53.346Z",
  "object": "letter"
}

Create a letter

Create a new letter.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

to: required

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail Strictness Setting, the request will fail. Read more here.

from: required

Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification.

color: required

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

file: required

Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML or PDF file. HTML files passed as remote URLs or local file upload have no character limit. All pages of a supplied PDF file must be sized at 8.5"x11", while supplied HTML will be rendered and trimmed to as many 8.5"x11" pages as necessary. For design specifications, please see our PDF and HTML templates. For domestic destinations, the file limit is 60 pages single-sided or 120 pages double-sided. For international destinations, the file limit is 6 pages single-sided or 12 pages double-sided. PDFs that surpass the file limit will error, while HTML that renders more pages than the file limit will be trimmed. See pricing for extra costs incurred. Letters over 6 pages single-sided or 12 pages double-sided will be placed in a flat envelope instead of the standard double window envelope.

merge_variables: optional

Variables can be defined in your HTML with double curly braces, e.g. {{variable_name}}. Use merge_variables to provide replacements for those variables to create custom content. merge_variables must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Nested objects are not supported. Depending on your Merge Variable Strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string.

double_sided: optional

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

address_placement: optional

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

return_envelope: optional

Boolean that defaults to false. If you would like to include a return envelope with your letter, set this key to true and specify the perforated_page. See pricing for extra costs incurred.

mail_type: optional

A string designating the mail postage type. Options are usps_first_class or usps_standard. Defaults to usps_first_class. usps_standard is a cheaper option which is less predictable and takes longer to deliver. usps_standard cannot be used with certified letters, registered letters, or any letters sent outside of the United States.

extra_service: optional

Add an extra service to your letter. Options are certified or registered. Certified provides tracking and delivery confirmation for domestic destinations. Registered provides tracking and confirmation for international addresses. See pricing for extra costs incurred.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 90 days in the future to send the letter off for production. This will override any letter cancellation window applied to the letter. Until the send_date has passed, the letter will be cancelable. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

perforated_page: optional

Required if return_envelope is true. The number of the page that should be perforated for use with the return envelope. Must be greater than or equal to 1. The blank page added by address_placement=insert_blank_page will be ignored when considering the perforated page number. To see how perforation will impact your letter design, view our perforation guide.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a letter object upon successful creation.

Example Definition

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

Example Request with an HTML string


Lob.Letter.create(%{
  description: "Demo Letter",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  file: "<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>",
  merge_variables: %{
    name: "Harry"
  },
  color: true
})

Example Request with a saved HTML template


Lob.Letter.create(%{
  description: "Demo Letter",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  file: "tmpl_cf5068f529da670",
  merge_variables: %{
    name: "Harry"
  },
  color: true
})

Example Request with Remote File


Lob.Letter.create(%{
  description: "Demo Letter",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  file: "https://s3-us-west-2.amazonaws.com/lob-assets/letter-goblue.pdf",
  color: true
})

Example Request with Local File


Lob.Letter.create(%{
  description: "Demo Letter",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: %{
    name: "Leore Avidar",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  file: %{
    local_path: "/path/to/your/letter.pdf"
  },
  color: true
})

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "extra_service": null,
  "mail_type": "usps_first_class",
  "url": "https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=qjatwPv3jPJlQayBYQeIm42qtavaP7q",
  "template_id": null,
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=GgFjpAduYT13yFYAJWVCAp8YRMRD7m1",
      "medium": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=0avnWJxyfhZ8Ccfd9m0ERYG1kSCJ0W2",
      "large": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=T8EwlE6P7QIKt3GIHU1Z1xrArNDZOkf"
    }
  ],
  "expected_delivery_date": "2017-09-12",
  "date_created": "2017-09-05T15:54:53.346Z",
  "date_modified": "2017-09-05T15:54:53.346Z",
  "send_date": "2017-09-05T15:54:53.346Z",
  "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.

Path Parameters

id: required

The identifier of the letter to be retrieved.

Returns

Returns a letter object if a valid identifier was provided.

Example Definition

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

Example Request


Lob.Letter.find("ltr_4868c3b754655f90")

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T15:54:53.264Z",
    "date_modified": "2017-09-05T15:54:53.264Z",
    "deleted": true,
    "object": "address"
  },
  "color": true,
  "double_sided": true,
  "address_placement": "top_first_page",
  "return_envelope": false,
  "perforated_page": null,
  "extra_service": null,
  "mail_type": "usps_first_class",
  "url": "https://lob-assets.com/letters/ltr_4868c3b754655f90.pdf?expires=1540372221&signature=8r94fse8uam7wGWmW5baxXulU88X2CA",
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_small_1.png?expires=1540372221&signature=a5fRBJ22ZA78Vgpg34M9UfmHWTS3eha",
      "medium": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_medium_1.png?expires=1540372221&signature=bAzL8sv935PY09FWSkpDpWKkyvGSWYF",
      "large": "https://lob-assets.com/letters/ltr_4868c3b754655f90_thumb_large_1.png?expires=1540372221&signature=gsKvxXgrm4v4iZD3bOibK7jApNkEMdW"
    }
  ],
  "expected_delivery_date": "2017-09-12",
  "date_created": "2017-09-05T15:54:53.346Z",
  "date_modified": "2017-09-05T15:54:53.346Z",
  "send_date": "2017-09-05T15:54:53.346Z",
  "object": "letter"
}

Cancel a letter

Completely removes a letter from production. This can only be done if the letter send_date has not yet passed. If the letter is successfully canceled, you will not be charged for it. Read more on letter cancellation windows and scheduling letters. This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.

Path Parameters

id: required

The identifier of the letter to be canceled.

Returns

Returns a message that the cancellation was successful.

Example Definition

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

Example Request


Lob.Letter.destroy("ltr_4868c3b754655f90")

Example Response


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

List all letters

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

Query Parameters

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

include: optional

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

metadata: optional

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

date_created: optional

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

scheduled: optional

Set scheduled to true to only return orders (past or future) where send_date is greater than date_created. Set scheduled to false to only return orders where send_date is equal to date_created.

send_date: optional

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

mail_type: optional
color: optional

A boolean that represents which letters to return. Set to true to return only color letters or false to return only black & white letters.

sort_by: optional

Sorts letters in a desired order. sort_by accepts an object with the key being either date_created or send_date and the value being either asc or desc.

Returns

A dictionary with a data property that contains an array of up to limit 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


Lob.Letter.list(%{limit: 2, offset: 0})

Example Response


{
  "data": [
    {
      "id": "ltr_b6bfe21858208b46",
      "description": "Demo Letter",
      "metadata": {},
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "color": true,
      "double_sided": true,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "extra_service": null,
      "mail_type": "usps_first_class",
      "url": "https://lob-assets.com/letters/ltr_b6bfe21858208b46.pdf?expires=1540372221&signature=SzbJEpyzXD99q3x2fpmUQm2vAhcQBVv",
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/letters/ltr_b6bfe21858208b46_thumb_small_1.png?expires=1540372221&signature=0g9P7QWDZ91HJrecMbLS4JwpjXddqMz",
          "medium": "https://lob-assets.com/letters/ltr_b6bfe21858208b46_thumb_medium_1.png?expires=1540372221&signature=8Tc6oOZOcVhEL3ZlQeer53uqlbsY9Nm",
          "large": "https://lob-assets.com/letters/ltr_b6bfe21858208b46_thumb_large_1.png?expires=1540372221&signature=D77JBqVsV4amGENqsWDEk570Tv6bOYD"
        }
      ],
      "expected_delivery_date": "2017-09-12",
      "date_created": "2017-09-05T15:54:54.416Z",
      "date_modified": "2017-09-05T15:54:54.416Z",
      "send_date": "2017-09-05T15:54:54.416Z",
      "object": "letter"
    },
    {
      "id": "ltr_8ea22b5354337084",
      "description": "Demo Letter 2",
      "metadata": {},
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T15:54:53.264Z",
        "date_modified": "2017-09-05T15:54:53.264Z",
        "deleted": true,
        "object": "address"
      },
      "color": true,
      "double_sided": true,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "extra_service": null,
      "mail_type": "usps_first_class",
      "url": "https://lob-assets.com/letters/ltr_8ea22b5354337084.pdf?expires=1540372221&signature=JFouUSNxBcegzED6BKP4lO23TAqbGkl",
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/letters/ltr_8ea22b5354337084_thumb_small_1.png?expires=1540372221&signature=bk8XIj3lV4rPlKkqbGj4ZU8VN8ecYxj",
          "medium": "https://lob-assets.com/letters/ltr_8ea22b5354337084_thumb_medium_1.png?expires=1540372221&signature=bYDOjJ0uOhfPtPQxQZRF60pbbgfDpvG",
          "large": "https://lob-assets.com/letters/ltr_8ea22b5354337084_thumb_large_1.png?expires=1540372221&signature=abKbcoVgh870xMUaBmjX8PnjJelvEeJ"
        }
      ],
      "expected_delivery_date": "2017-09-12",
      "date_created": "2017-09-05T15:54:53.346Z",
      "date_modified": "2017-09-05T15:54:53.346Z",
      "send_date": "2017-09-05T15:54:53.346Z",
      "object": "letter"
    }
  ],
  "count": 2,
  "object": "list"
}

Checks

Checks allow you to send payments via physical checks. The API provides endpoints for creating checks, retrieving individual checks, canceling checks, and retrieving a list of checks.

The check object

Fields

id: string

Unique identifier prefixed with chk_.

description: string or null
metadata: object
check_number: integer
memo: string or null
amount: decimal
message: string or null
url: string

A signed link to the rendered check.

check_bottom_template_id: string or null

The unique ID of the HTML template used for the check bottom.

attachment_template_id: string or null

The unique ID of the HTML template used for the attachment.

check_bottom_template_version_id: string or null

The unique ID of the specific version of the HTML template used for the check bottom.

attachment_template_version_id: string or null

The unique ID of the specific version of the HTML template used for the attachment.

to: an address object
from: an address object
bank_account: a bank account object
carrier: string

Value is USPS normally and UPS when mail_type is ups_next_day_air.

tracking_number: string or null

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

tracking_events: array

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

thumbnails: array

Signed links to different sized thumbnails of each check page.

expected_delivery_date: string

A date in ISO 8601 format of the check's expected delivery date based on its send_date.

mail_type: string

Value is usps_first_class or ups_next_day_air.

date_created: string

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

date_modified: string

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

send_date: string

A timestamp in ISO 8601 format of the date the check will be dispatched for production. If the send_date of a check has passed, it can no longer be canceled. send_date will be the date_created of the check plus the cancellation window, if one was applied at the time of the check's creation. If a check was scheduled using the send_date parameter, that timestamp will be returned here. For billing purposes, mailings will count towards usage in the month of their send_date.

deleted: boolean

Only returned if the check has been successfully canceled.

object: string

Value is check.

Example Response


{
  "id": "chk_534f10783683daa0",
  "description": "Demo Check",
  "metadata": {},
  "check_number": 10062,
  "memo": "rent",
  "amount": 22.50,
  "message": null,
  "url": "https://lob-assets.com/checks/chk_534f10783683daa0.pdf?expires=1540372221&signature=duqMIo2WaM9vUHrBsrHpzde9bmDZSfK",
  "check_bottom_template_id": null,
  "attachment_template_id": null,
  "check_bottom_template_version_id": null,
  "attachment_template_version_id": null,
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_small_1.png?expires=1540372221&signature=AyxdLiwEej3ukIyiXyWKTlDV2MacsOb",
      "medium": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_medium_1.png?expires=1540372221&signature=s6qu4bDimVuEmmJfhvBPavdBj1XBN79",
      "large": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_large_1.png?expires=1540372221&signature=nMdvVVGP5sL1vccRrvGZcC09iUY5b0e"
    }
  ],
  "expected_delivery_date": "2017-09-12",
  "mail_type": "usps_first_class",
  "date_created": "2017-09-05T17:47:53.896Z",
  "date_modified": "2017-09-05T17:47:53.896Z",
  "send_date": "2017-09-05T17:47:53.896Z",
  "object": "check"
}

Create a check

Create a new check.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

to: required

Must either be an address ID or an inline object with correct address parameters. The total string of the sum of address_line1 and address_line2 must be no longer than 50 characters combined. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail Strictness Setting, the request will fail. Read more here.

from: required

Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification.

bank_account: required

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

amount: required

A number that specifies the payment amount to be sent in dollars. Amounts will be rounded to 2 decimal places and must be less than $1,000,000 (1000000).

memo: optional

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

check_number: optional

An integer that designates the check number. If check_number is not explicitly passed, checks created from a new bank_account will start at 10000 and increment accordingly every time a check is created with that bank_account. If a check_number is ever explicitly passed, that will override any defaults. Afterwards, checks created with that bank_account will increment from there without needing to pass check_number.

logo: optional

This can be a URL or local file to an image to print (in grayscale) in the upper-left corner of your check. The image must have a color model of RGB or CMYK, be a square, be at least 100px X 100px, and have a transparent background. The accepted file types are PNG and JPG.

message: optional

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

check_bottom: optional

Either message or check_bottom, choose one. The artwork to use on the bottom of the check page. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. PDF, PNG, and JPGs must be sized at 8.5"x11" at 300 DPI, while supplied HTML will be rendered and trimmed to fit on a 8.5"x11" page. The check bottom will always be printed in black & white. You must follow this template. See here for HTML examples.

attachment: optional

A document to include with the check. Accepts an HTML string of under 10,000 characters, the ID of a saved HTML template, or a remote URL or a local upload of an HTML, PDF, PNG, or JPG file. HTML files passed as remote URLs or local file uploads have no character limit. All pages of PDF, PNG, and JPGs must be sized at 8.5"x11" at 300 DPI, while supplied HTML will be rendered and trimmed to as many 8.5"x11" pages as necessary. If a PDF is provided, it must be 6 pages or fewer. The attachment will be printed double-sided in black & white and will be included in the envelope after the check page. Please follow these design guidelines. See pricing for extra costs incurred. See here for HTML examples.

merge_variables: optional

Variables can be defined in your HTML with double curly braces, e.g. {{variable_name}}. Use merge_variables to provide replacements for those variables to create custom content. merge_variables must be an object with up to 40 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Nested objects are not supported. Depending on your Merge Variable Strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string.

mail_type: optional

A string designating the mail postage type. Options are usps_first_class or ups_next_day_air. Defaults to usps_first_class. Passing ups_next_day_air will create an overnight check, which is guaranteed to reach its recipient by the next business day if the API request is sent in before 10AM PT. ups_next_day_air can only be sent to US destinations with non-PO Box addresses. See pricing for extra costs incurred for ups_next_day_air.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 90 days in the future to send the check off for production. This will override any check cancellation window applied to the check. Until the send_date has passed, the check will be cancelable. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a check object upon successful creation.

Example Definition

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

Example Request with HTML string


Lob.Check.create(%{
  description: "Demo Check",
  bank_account: "bank_8cad8df5354d33f",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: "adr_eae4448bb64c07f0",
  amount: 22.50,
  memo: "rent",
  logo: "https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png",
  check_bottom: "<h1 style='padding-top:4in;'>Demo Check for {{name}}</h1>",
  merge_variables: %{
    name: "Harry"
  }
})

Example Request with saved HTML template


Lob.Check.create(%{
  description: "Demo Check",
  bank_account: "bank_8cad8df5354d33f",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: "adr_eae4448bb64c07f0",
  amount: 22.50,
  memo: "rent",
  logo: "https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png",
  check_bottom: "tmpl_23668b406d5afef",
  merge_variables: %{
    name: "Harry"
  }
})

Example Request with Remote Files


Lob.Check.create(%{
  description: "Demo Check",
  bank_account: "bank_8cad8df5354d33f",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: "adr_eae4448bb64c07f0",
  amount: 22.50,
  memo: "rent",
  logo: "https://s3-us-west-2.amazonaws.com/lob-assets/lob_check_logo.png",
  check_bottom: "https://s3-us-west-2.amazonaws.com/lob-assets/check-file-example.pdf"
})

Example Request with Local Files


Lob.Check.create(%{
  description: "Demo Check",
  bank_account: "bank_8cad8df5354d33f",
  to: %{
    name: "Harry Zhang",
    address_line1: "185 Berry St",
    address_line2: "# 6100",
    address_city: "San Francisco",
    address_state: "CA",
    address_zip: "94107"
  },
  from: "adr_eae4448bb64c07f0",
  amount: 22.50,
  memo: "rent",
  logo: %{
    local_path: "/path/to/your/logo.png"
  },
  check_bottom: %{
    local_path: "/path/to/your/file.pdf"
  }
})

Example Response


{
  "id": "chk_534f10783683daa0",
  "description": "Demo Check",
  "metadata": {},
  "check_number": 10062,
  "memo": "rent",
  "amount": 22.50,
  "message": null,
  "url": "https://lob-assets.com/checks/chk_534f10783683daa0.pdf?expires=1540372221&signature=duqMIo2WaM9vUHrBsrHpzde9bmDZSfK",
  "check_bottom_template_id": null,
  "attachment_template_id": null,
  "check_bottom_template_version_id": null,
  "attachment_template_version_id": null,
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_small_1.png?expires=1540372221&signature=AyxdLiwEej3ukIyiXyWKTlDV2MacsOb",
      "medium": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_medium_1.png?expires=1540372221&signature=s6qu4bDimVuEmmJfhvBPavdBj1XBN79",
      "large": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_large_1.png?expires=1540372221&signature=nMdvVVGP5sL1vccRrvGZcC09iUY5b0e"
    }
  ],
  "expected_delivery_date": "2017-09-12",
  "mail_type": "usps_first_class",
  "date_created": "2017-09-05T17:47:53.896Z",
  "date_modified": "2017-09-05T17:47:53.896Z",
  "send_date": "2017-09-05T17:47:53.896Z",
  "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.

Path Parameters

id: required

The identifier of the check to be retrieved.

Returns

Returns a check object if a valid identifier was provided.

Example Definition

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

Example Request


Lob.Check.find("chk_534f10783683daa0")

Example Response


{
  "id": "chk_534f10783683daa0",
  "description": "Demo Check",
  "metadata": {},
  "check_number": 10062,
  "memo": "rent",
  "amount": 22.50,
  "message": null,
  "url": "https://lob-assets.com/checks/chk_534f10783683daa0.pdf?expires=1540372221&signature=Ty3IV2bGPEoQfrdraYHlNYTaarnHLXb",
  "to": {
    "id": "adr_d3489cd64c791ab5",
    "description": null,
    "name": "HARRY ZHANG",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "deleted": true,
    "object": "address"
  },
  "from": {
    "id": "adr_b8fb5acf3a2b55db",
    "description": null,
    "name": "LEORE AVIDAR",
    "company": null,
    "phone": null,
    "email": null,
    "address_line1": "185 BERRY ST STE 6100",
    "address_line2": null,
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94107-1741",
    "address_country": "UNITED STATES",
    "metadata": {},
    "date_created": "2017-09-05T17:47:53.767Z",
    "date_modified": "2017-09-05T17:47:53.767Z",
    "object": "address"
  },
  "bank_account": {
    "id": "bank_8cad8df5354d33f",
    "description": "Test Bank Account",
    "metadata": {},
    "routing_number": "322271627",
    "account_number": "123456789",
    "signatory": "John Doe",
    "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
    "verified": true,
    "account_type": "company",
    "date_created": "2015-11-06T19:24:24.440Z",
    "date_modified": "2015-11-06T19:41:28.312Z",
    "object": "bank_account"
  },
  "carrier": "USPS",
  "tracking_number": null,
  "tracking_events": [],
  "thumbnails": [
    {
      "small": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_small_1.png?expires=1540372221&signature=ShhPpH74wYkNiAj7Il9B6q8ZKkzlGd4",
      "medium": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_medium_1.png?expires=1540372221&signature=tmIOq6aAyKgzAECp7STj1rvJuMS5Svd",
      "large": "https://lob-assets.com/checks/chk_534f10783683daa0_thumb_large_1.png?expires=1540372221&signature=04nLEwE9d2qgQJNgJYWSOgPnU0FZbEv"
    }
  ],
  "expected_delivery_date": "2017-09-12",
  "mail_type": "usps_first_class",
  "date_created": "2017-09-05T17:47:53.896Z",
  "date_modified": "2017-09-05T17:47:53.896Z",
  "send_date": "2017-09-05T17:47:53.896Z",
  "object": "check"
}

Cancel a check

Completely removes a check from production. This can only be done if the check send_date has not yet passed. If the check is successfully canceled, you will not be charged for it. Read more on check cancellation windows and scheduling checks. This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.

Path Parameters

id: required

The identifier of the check to be canceled.

Returns

Returns a message that the cancellation was successful.

Example Definition

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

Example Request


Lob.Check.destroy("chk_534f10783683daa0")

Example Response


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

List all checks

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

Query Parameters

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

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.

mail_type: optional
scheduled: optional

Set scheduled to true to only return orders (past or future) where send_date is greater than date_created. Set scheduled to false to only return orders where send_date is equal to date_created.

date_created: optional

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

send_date: optional

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

sort_by: optional

Sorts checks in a desired order. sort_by accepts an object with the key being either date_created or send_date and the value being either asc or desc.

Returns

A dictionary with a data property that contains an array of up to limit 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


Lob.Check.list(%{limit: 2, offset: 0})

Example Response


{
  "data": [
    {
      "id": "chk_fa2d38a6f0ce638e",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 10006,
      "memo": "rent",
      "amount": 2200,
      "message": null,
      "url": "https://lob-assets.com/checks/chk_fa2d38a6f0ce638e.pdf?expires=1540372221&signature=J4gdRbTNp040Mjm3eq8vyapQSTSnbPB",
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.778Z",
        "date_modified": "2017-09-05T17:47:53.778Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_8cad8df5354d33f",
        "description": "Test Bank Account",
        "metadata": {},
        "routing_number": "322271627",
        "account_number": "123456789",
        "signatory": "John Doe",
        "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
        "verified": true,
        "account_type": "company",
        "date_created": "2015-11-06T19:24:24.440Z",
        "date_modified": "2015-11-06T19:41:28.312Z",
        "object": "bank_account"
      },
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/checks/chk_fa2d38a6f0ce638e_thumb_small_1.png?expires=1540372221&signature=bQFHuxibQsJoaq0M2RfZ6Qow5O2yEYY,
          "medium": "https://lob-assets.com/checks/chk_fa2d38a6f0ce638e_thumb_medium_1.png?expires=1540372221&signature=SNUydOaH4CJeWnvdy4CGJVXbuHTc6mV,
          "large": "https://lob-assets.com/checks/chk_fa2d38a6f0ce638e_thumb_large_1.png?expires=1540372221&signature=gaFfMgXhKQAHZJHJ44m7NS8cCZSAwiT"
        }
      ],
      "expected_delivery_date": "2017-09-12",
      "mail_type": "usps_first_class",
      "date_created": "2017-09-05T17:47:54.128Z",
      "date_modified": "2017-09-05T17:47:54.128Z",
      "send_date": "2017-09-05T17:47:54.128Z",
      "object": "check"
    },
    {
      "id": "chk_213657231f256688",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 10005,
      "memo": "rent",
      "amount": 2200,
      "message": null,
      "url": "https://lob-assets.com/checks/chk_213657231f256688.pdf?expires=1540372221&signature=rlvl2Ncr0jRAEwR29aj1ZVCauLZPRnn",
      "to": {
        "id": "adr_d3489cd64c791ab5",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_b8fb5acf3a2b55db",
        "description": null,
        "name": "LEORE AVIDAR",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "185 BERRY ST STE 6100",
        "address_line2": null,
        "address_city": "SAN FRANCISCO",
        "address_state": "CA",
        "address_zip": "94107-1741",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2017-09-05T17:47:53.767Z",
        "date_modified": "2017-09-05T17:47:53.767Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_8cad8df5354d33f",
        "description": "Test Bank Account",
        "metadata": {},
        "routing_number": "322271627",
        "account_number": "123456789",
        "signatory": "John Doe",
        "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
        "verified": true,
        "account_type": "company",
        "date_created": "2015-11-06T19:24:24.440Z",
        "date_modified": "2015-11-06T19:41:28.312Z",
        "object": "bank_account"
      },
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/checks/chk_213657231f256688_thumb_small_1.png?expires=1540372221&signature=wJugMVURs9VayYfHH6p7OHU648dUdpW",
          "medium": "https://lob-assets.com/checks/chk_213657231f256688_thumb_medium_1.png?expires=1540372221&signature=fNGKQGGvDVUiLiiBV8qnWg3doLuZYha",
          "large": "https://lob-assets.com/checks/chk_213657231f256688_thumb_large_1.png?expires=1540372221&signature=A40h2k5LLj4c7Jlz0S1blb5nbZpYgBq"
        }
      ],
      "expected_delivery_date": "2017-09-12",
      "mail_type": "usps_first_class",
      "date_created": "2017-09-05T17:47:54.078Z",
      "date_modified": "2017-09-05T17:47:54.078Z",
      "send_date": "2017-09-05T17:47:54.078Z",
      "object": "check"
    }
  ],
  "count": 2,
  "object": "list"
}

Bank Accounts

Bank Accounts allow you to store your bank account securely in our system. The API provides endpoints for creating bank accounts, deleting bank accounts, verifying bank accounts, retrieving individual bank accounts, and retrieving a list of bank accounts.

The bank account object

Fields

id: string

Unique identifier prefixed with bank_.

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

Value is company or individual.

signatory: string
signature_url: string or null

A signed link to the signature image.

bank_name: string

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

verified: boolean
date_created: string

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

date_modified: string

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

deleted: boolean

Only returned if the bank account has been successfully deleted.

object: string

Value is bank_account.

Example Response


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

Create a bank account

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

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

routing_number: required

Must be a valid US routing number of 9 characters.

account_number: required

Must be no longer than 17 characters.

account_type: required

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

signatory: required

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

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a bank object upon successful creation.

Example Definition

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

Example Request


Lob.BankAccount.create(%{
  description: "Test Bank Account",
  routing_number: "322271627",
  account_number: "123456789",
  signatory: "John Doe",
  account_type: "company"
})

Example Response


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

Retrieve a bank account

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

Path Parameters

id: required

The identifier of the bank account to be retrieved.

Returns

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

Example Definition

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

Example Request


Lob.BankAccount.find("bank_8cad8df5354d33f")

Example Response


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

Delete a bank account

Permanently deletes a bank account. It cannot be undone.

Path Parameters

id: required

The identifier of the bank account to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request


Lob.BankAccount.destroy("bank_3e64d9904356b20")

Example Response


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

Verify a bank account

Verify a bank account in order to create a check.

Path Parameters

id: required

The identifier of the bank account to be verified.

Payload Parameters

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, so any two integers between 1 and 100 will work.

Returns

Returns a bank account object upon successful verification.

Example Definition

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

Example Request


Lob.BankAccount.verify("bank_dfceb4a2a05b57e", %{amounts: [25, 63]})

Example Response


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

List all bank accounts

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

Query Parameters

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

include: optional

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

metadata: optional

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

date_created: optional

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

Returns

A dictionary with a data property that contains an array of up to limit 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


Lob.BankAccount.list(%{limit: 2, offset: 0})

Example Response


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

Templates Beta

These API endpoints allow you to create, retrieve, update and delete reusable HTML templates for use with the print & mail API.

The template object

Fields

id: string

Unique identifier prefixed with tmpl_.

description: string or null
versions: array

An array of all non-deleted version objects associated with the template.

published_version: a version object

The template's currently published version.

metadata: object
date_created: string

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

date_modified: string

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

deleted: boolean

Only returned if the template has been successfully deleted.

object: string

Value is template.

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Create a template

Creates a new template for use with the print & mail API. In Live mode, you can only have as many non-deleted templates as allotted in your current Print & Mail Edition. If you attempt to create a template past your limit, you will receive a 403 error. There is no limit in Test mode.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

html: required

An HTML string of less than 100,000 characters to be used as the published_version of this template. See here for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details.

metadata: optional

Use metadata to store custom information for tagging and labeling back to your internal systems. Must be an object with up to 20 key-value pairs. Keys must be at most 40 characters and values must be at most 500 characters. Neither can contain the characters " and \. Nested objects are not supported. See Metadata for more information.

Returns

Returns a template object upon successful creation.

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Retrieve a template

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

Path Parameters

id: required

The identifier of the template to be retrieved.

Returns

Returns a template object if a valid identifier was provided.

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Update a template

Updates the template with a given ID.

Path Parameters

id: required

The identifier of the template to update.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

published_version: optional

Update the published version of a template. The published version is the one that will be used in any print & mail requests that reference the specified template. Will err if the version attempting to be set as the published_version has been deleted or does not exist.

Returns

Returns the updated template object if a valid identifier was provided.

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "tmpl_c94e83ca2cd5121",
  "description": "Test Template",
  "versions": [
    {
      "id": "vrsn_362184d96d9b0c9",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-07T22:56:10.962Z",
      "object": "version"
    }
  ],
  "published_version": {
    "id": "vrsn_362184d96d9b0c9",
    "description": "Test Template",
    "html": "<html>HTML for {{name}}</html>",
    "date_created": "2017-11-07T22:56:10.962Z",
    "date_modified": "2017-11-07T22:56:10.962Z",
    "object": "version"
  },
  "metadata": {},
  "date_created": "2017-11-07T22:56:10.962Z",
  "date_modified": "2017-11-07T22:56:10.962Z",
  "object": "template"
}

Delete a template

Permanently deletes a template. Deleting a template also deletes its associated versions. Deleted templates can not be used to create postcard, letter, or check resources.

Path Parameters

id: required

The identifier of the template to be deleted.

Returns

Returns a message that the deletion was successful.

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


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

List all templates

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

Query Parameters

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

include: optional

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

metadata: optional

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

date_created: optional

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

Returns

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

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "data": [
    {
      "id": "tmpl_3a15ef6349eb353",
      "description": "Test Template",
      "versions": [
        {
          "id": "vrsn_44cae6231509e8c",
          "description": "Test Template",
          "html": "<html>HTML for {{name}}</html>",
          "date_created": "2017-11-09T04:05:13.116Z",
          "date_modified": "2017-11-09T04:05:13.116Z",
          "object": "version"
        }
      ],
      "published_version": {
        "id": "vrsn_44cae6231509e8c",
        "description": "Test Template",
        "html": "<html>HTML for {{name}}</html>",
        "date_created": "2017-11-09T04:05:13.116Z",
        "date_modified": "2017-11-09T04:05:13.116Z",
        "object": "version"
      },
      "metadata": {},
      "date_created": "2017-11-09T04:05:13.116Z",
      "date_modified": "2017-11-09T04:05:13.116Z",
      "object": "template"
    },
    {
      "id": "tmpl_c94e83ca2cd5121",
      "description": "Updated description",
      "versions": [
        {
          "id": "vrsn_362184d96d9b0c9",
          "description": "Test Template",
          "html": "<html>HTML for {{name}}</html>",
          "date_created": "2017-11-07T22:56:10.962Z",
          "date_modified": "2017-11-07T22:56:10.962Z",
          "object": "version"
        }
      ],
      "published_version": {
        "id": "vrsn_362184d96d9b0c9",
        "description": "Test Template",
        "html": "<html>HTML for {{name}}</html>",
        "date_created": "2017-11-07T22:56:10.962Z",
        "date_modified": "2017-11-07T22:56:10.962Z",
        "object": "version"
      },
      "metadata": {},
      "date_created": "2017-11-07T22:56:10.962Z",
      "date_modified": "2017-11-09T03:42:21.264Z",
      "object": "template"
    }
  ],
  "count": 2,
  "object": "list"
}

Template Versions Beta

These API endpoints allow you to create, retrieve, update and delete versions of reusable HTML templates for use with the print & mail API.

The version object

Fields

id: string

Unique identifier prefixed with vrsn_.

description: string or null
html: string
date_created: string

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

date_modified: string

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

deleted: boolean

Only returned if the version has been successfully deleted.

object: string

Value is version.

Example Response


{
  "id": "vrsn_534e339882d2282",
  "description": "Second Version",
  "html": "<html>Second HTML for {{name}}</html>",
  "date_created": "2017-11-09T04:49:38.016Z",
  "date_modified": "2017-11-09T04:49:38.016Z",
  "object": "version"
}

Create a version

Create a new version attached to the specified template.

Path Parameters

id: required

The identifier of the template the new version will be attached to.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

html: required

An HTML string of less than 100,000 characters. See here for guidance on designing HTML templates. Please see endpoint specific documentation for any other product-specific HTML details. Newly created versions will not be published until the published_version of the template is updated.

Returns

Returns a version object upon successful creation.

Example Definition

POST https://api.lob.com/v1/templates/{id}/versions

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "vrsn_534e339882d2282",
  "description": "Second Version",
  "html": "<html>Second HTML for {{name}}</html>",
  "date_created": "2017-11-09T04:49:38.016Z",
  "date_modified": "2017-11-09T04:49:38.016Z",
  "object": "version"
}

Retrieve a version

Retrieves the version with the given template ID and version ID.

Path Parameters

template_id: required

The identifier of the template the version belongs to.

version_id: required

The identifier of the version to be retrieved.

Returns

Returns a version object if valid identifiers were provided.

Example Definition

GET https://api.lob.com/v1/templates/{template_id}/versions/{version_id}

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "vrsn_534e339882d2282",
  "description": "Second Version",
  "html": "<html>Second HTML for {{name}}</html>",
  "date_created": "2017-11-09T04:49:38.016Z",
  "date_modified": "2017-11-09T04:49:38.016Z",
  "object": "version"
}

Update a version

Updates the version with the given template ID and version ID.

Path Parameters

template_id: required

The identifier of the template the version belongs to.

version_id: required

The identifier of the version to be retrieved.

Payload Parameters

description: optional

An internal description that identifies this resource. Must be no longer than 255 characters.

Returns

Returns the updated version object if valid identifiers were provided.

Example Definition

POST https://api.lob.com/v1/templates/{template_id}/versions/{version_id}

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "vrsn_534e339882d2282",
  "description": "Updated description",
  "html": "<html>Second HTML for {{name}}</html>",
  "date_created": "2017-11-09T04:49:38.016Z",
  "date_modified": "2017-11-09T04:49:38.016Z",
  "object": "version"
}

Delete a version

Permanently deletes a version. A template's published_version can not be deleted.

Path Parameters

template_id: required

The identifier of the template the version belongs to.

version_id: required

The identifier of the version to be retrieved.

Returns

Returns a confirmation upon successful deletion.

Example Definition

DELETE https://api.lob.com/v1/templates/{template_id}/versions/{version_id}

Example Request

This feature is not currently supported by this library.

Example Response


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

List all versions

Returns a list of versions. The returned versions all belong to the template of the id passed, and are sorted by creation date with the most recently created appearing first.

Query Parameters

offset: optional

An integer that designates the offset at which to begin returning results. Defaults to 0.

limit: optional

An integer that designates how many results to return. Defaults to 10 and must be no more than 100.

include: optional

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

date_created: optional

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

Path Parameters

id: required

The identifier of the template associated with the retrieved versions.

Returns

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "data": [
    {
      "id": "vrsn_4d6ff5d868bf630",
      "description": "Second Version",
      "html": "<html>Second HTML for {{name}}</html>",
      "date_created": "2017-11-09T05:09:03.665Z",
      "date_modified": "2017-11-09T05:09:03.665Z",
      "object": "version"
    },
    {
      "id": "vrsn_2a17159c1911919",
      "description": "Test Template",
      "html": "<html>HTML for {{name}}</html>",
      "date_created": "2017-11-09T05:08:40.004Z",
      "date_modified": "2017-11-09T05:08:40.004Z",
      "object": "version"
    }
  ],
  "count": 2,
  "object": "list"
}

Changelog

2018-06-05

  • remove rate-limit headers

2018-03-30

  • updated letter template which includes a white box behind the address block area to ensure deliverability

2018-03-01

  • US verification deliverability value no_match deprecated and merged into undeliverable
  • US verification deliverability value deliverable_extra_secondary is split into deliverable_unnecessary_unit and deliverable_incorrect_unit
  • US verification deliverability value deliverable_missing_secondary renamed to deliverable_missing_unit
  • US verifications zip_code special values deprecated in favor of more comprehensive primary_line special values

2018-02-08

  • enforce 50 character limit on the sum of address_line1 and address_line2 for check recipients

2017-11-08

  • split extra_secondary_information into extra_secondary_designator and extra_secondary_number for /v1/us_verifications

2017-10-17

  • remove support for the /v1/states endpoint
  • remove support for the /v1/countries endpoint
  • remove support for the message field from the POST /v1/postcards endpoint

2017-09-08

  • renames input parameters and restructures response object for /v1/intl_verifications

2017-08-14

  • automatically standardizes and corrects US addresses created via POST /v1/addresses. non-US addresses will be standardized into uppercase only.
  • automatically standardizes and corrects inline US addresses used in POST /v1/postcards, POST /v1/letters, and POST /v1/checks. non-US addresses will be standardized into uppercase only.
  • enforce 40 character limit on name and company for all addresses
  • enforce 64 character limit on address_line1 and address_line2 for US addresses

2017-06-16

  • enforce 10,000 character limit on HTML strings
  • rename data parameter for all products to merge_variables

2017-05-17

  • discontinues the /v1/verify endpoint - please use /v1/us_verifications or /v1/intl_verifications instead

2016-06-30

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

2016-05-02

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

2016-03-21

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

2016-01-19

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

2015-12-22

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

2015-11-23

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

2015-11-06

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

2015-10-21

  • use the new HTML renderer for all products

2015-06-25

  • remove the status field from all endpoints

2015-04-11

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

2014-12-18 Sunsetted

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

The tracking event object

Fields

id: string

Unique identifier prefixed with evnt_.

name: string

A string representing what event occurred. Possible values are In Transit, In Local Area, Processed for Delivery, Re-Routed, and Returned to Sender. Depending on your Print & Mail Edition, you may also have access to Mailed for letters. See here for more detailed descriptions of each type of event.

location: string or null

The zip code in which the event occurred. Will be null for Mailed events.

time: string

A timestamp in ISO 8601 format of the date USPS registered the event.

date_created: string

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

date_modified: string

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

object: string

Value is tracking_event.

Example Response

      
{
  "id": "evnt_9e84094c9368cfb",
  "name": "In Local Area",
  "location": "72231",
  "time": "2016-06-30T15:51:41.000Z",
  "date_created": "2016-06-30T17:41:59.771Z",
  "date_modified": "2016-06-30T17:41:59.771Z",
  "object": "tracking_event"
}
      
    

Events

When various notable things happen within the Lob architecture, Events will be created. To get these events sent to your server automatically when they occur, you can set up Webhooks.

The event object

Fields

id: string

Unique identifier prefixed with evt_.

body: object

The body of the associated resource as they were at the time of the event, i.e. the postcard object, the letter object, the check object, the address object, or the bank account object.

reference_id: string

Unique identifier of the related resource for the event.

event_type: an event type object
date_created: string

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

object: string

Value is event.

Example Response


{
  "id": "evt_d95ff8ffd2b5cfb4",
  "body": {
    "id": "psc_d2d10a2e9cba991c",
    "description": "Test Postcard",
    "metadata": {},
    "to": {
      "id": "adr_8e783523dd7f0e70",
      "description": "Test Address",
      "name": "Harry Zhang",
      "address_line1": "123 Test St",
      "address_line2": "Unit 1",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_zip": "94107",
      "address_country": "United States",
      "metadata": {},
      "date_created": "2016-12-04T10:51:51.844Z",
      "date_modified": "2016-12-04T10:51:51.844Z",
      "object": "address"
    },
    "from": {
      "id": "adr_d2e26faf793ed422",
      "description": "Test Address",
      "name": "Harry Zhang",
      "address_line1": "123 Test St",
      "address_line2": "Unit 1",
      "address_city": "San Francisco",
      "address_state": "CA",
      "address_zip": "94107",
      "address_country": "United States",
      "metadata": {},
      "date_created": "2016-12-04T10:51:51.845Z",
      "date_modified": "2016-12-04T10:51:51.845Z",
      "object": "address"
    },
    "url": "https://lob-assets.com/postcards/psc_d2d10a2e9cba991c.pdf?expires=1540372221&signature=dNE8OtbDymujUxBIMYle4H1cv1aZNFk",
    "carrier": "USPS",
    "tracking_events": [],
    "thumbnails": [
      {
        "small": "https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_small_1.png?expires=1540372221&signature=McmqScxPgbe7yQY5X31U3vhU8VUlfA1",
        "medium": "https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_medium_1.png?expires=1540372221&signature=VBClptOuCcj9Ybay6gE5aetT5j3C7KS",
        "large": "https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_large_1.png?expires=1540372221&signature=RAHpIwoYKYM17f0bbaoOiamCkjpzYfH"
      },
      {
        "small": "https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_small_2.png?expires=1540372221&signature=5biHoaCmkphQaGJymOZxmTF0hHdiH4N",
        "medium": "https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_medium_2.png?expires=1540372221&signature=1ApGx0kn5EO4qQKGJzCe6zEPnQpzpRY",
        "large": "https://lob-assets.com/postcards/psc_d2d10a2e9cba991c_thumb_large_2.png?expires=1540372221&signature=z80p90RBak6T26IAfg5yg7a6qKF53a8"
      }
    ],
    "size": "4x6",
    "expected_delivery_date": "2016-12-09",
    "date_created": "2016-12-04T10:51:51.843Z",
    "date_modified": "2016-12-04T10:51:51.843Z",
    "object": "postcard"
  },
  "reference_id": "psc_d2d10a2e9cba991c",
  "event_type": {
    "id": "postcard.created",
    "enabled_for_test": true,
    "resource": "postcards",
    "object": "event_type"
  },
  "date_created": "2016-12-04T22:50:08.180Z",
  "object": "event"
}

The event type object

Fields

id: string

Unique identifier, full list of possible values can be found here.

enabled_for_test: boolean

Value is true if the event type is enabled in both the test and live environments and false if it is only enabled in the live environment.

resource: string

Value is postcards, letters, checks, addresses, or bank accounts.

object: string

Value is event_type.

Example Response


{
  "id": "postcard.created",
  "enabled_for_test": true,
  "resource": "postcards",
  "object": "event_type"
}

All event types

These are all the event types Lob currently creates and are available for subscription.

Postcards

Event Type When Event Type Occurs
postcard.created Occurs when a postcard is successfully created (Lob returns a 200 status code).
postcard.rendered_pdf Occurs when a postcard's PDF proof is successfully rendered.
postcard.rendered_thumbnails Occurs when a postcard's thumbnails are successfully rendered.
postcard.in_transit Occurs when a postcard receives an "In Transit" tracking event. Only created in the Live Environment.
postcard.in_local_area Occurs when a postcard receives an "In Local Area" tracking event. Only created in the Live Environment.
postcard.processed_for_delivery Occurs when a postcard receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
postcard.re-routed Occurs when a postcard receives a "Re-Routed" tracking event. Only created in the Live Environment.
postcard.returned_to_sender Occurs when a postcard receives a "Returned to Sender" tracking event. Only created in the Live Environment.

Letters

Event Type When Event Type Occurs
letter.created Occurs when a letter is successfully created (Lob returns a 200 status code).
letter.rendered_pdf Occurs when a letter's PDF proof is successfully rendered.
letter.rendered_thumbnails Occurs when a letter's thumbnails are successfully rendered.
letter.mailed Occurs when a letter receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. Only created in the Live Environment.
letter.in_transit Occurs when a letter receives an "In Transit" tracking event. Only created in the Live Environment.
letter.in_local_area Occurs when a letter receives an "In Local Area" tracking event. Only created in the Live Environment.
letter.processed_for_delivery Occurs when a letter receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
letter.re-routed Occurs when a letter receives a "Re-Routed" tracking event. Only created in the Live Environment.
letter.returned_to_sender Occurs when a letter receives a "Returned to Sender" tracking event. Only created in the Live Environment.

Checks

Event Type When Event Type Occurs
check.created Occurs when a check is successfully created (Lob returns a 200 status code).
check.rendered_pdf Occurs when a check's PDF proof is successfully rendered.
check.rendered_thumbnails Occurs when a check's thumbnails are successfully rendered.
check.in_transit Occurs when a check receives an "In Transit" tracking event. Only created in the Live Environment.
check.in_local_area Occurs when a check receives an "In Local Area" tracking event. Only created in the Live Environment.
check.processed_for_delivery Occurs when a check receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
check.re-routed Occurs when a check receives a "Re-Routed" tracking event. Only created in the Live Environment.
check.returned_to_sender Occurs when a check receives a "Returned to Sender" tracking event. Only created in the Live Environment.

Addresses

Event Type When Event Type Occurs
address.created Occurs when an address is successfully created (Lob returns a 200 status code).
address.deleted Occurs when an address is successfully deleted.

Bank Accounts

Event Type When Event Type Occurs
bank_account.created Occurs when a bank account is successfully created (Lob returns a 200 status code).
bank_account.deleted Occurs when a bank account is successfully deleted.
bank_account.verified Occurs when a bank account is successfully verified.

US Verification Details

These are detailed definitions for various fields in the US verification object.

ZIP Code Types - components[zip_code_type]

standard The default ZIP code type. Used when none of the other types apply.
po_box The ZIP code contains only PO Boxes.
unique The ZIP code is uniquely assigned to a single organization (such as a government agency) that receives a large volume of mail.
military The ZIP code contains military addresses.
empty string A match could not be made with the provided inputs.

Record Types - components[record_type]

street The default address type.
highrise The address is a commercial building, apartment complex, highrise, etc.
firm The address is of an organizational entity which receives a minimum number of mailpieces per day.
po_box The address is a PO Box.
rural_route The address exists on a Rural Route. This is an older system of mail delivery which is still used in some parts of the country.
general_delivery The address is part of the USPS General Delivery service, which allows individuals without permanent addresses to receive mail.
empty string A match could not be made with the provided inputs.

Carrier Route Types - components[carrier_route_type]

city_delivery The default carrier route type. Used when none of the other types apply.
rural_route The carrier route is a Rural Route. This is an older system of mail delivery which is still used in some parts of the country.
highway_contract The carrier route is a Highway Contract Route. This is an older system of mail delivery which is still used in some parts of the country.
po_box The carrier route consists of PO Boxes.
general_delivery The carrier route is part of the USPS General Delivery service, which allows individuals without permanent addresses to receive mail.
empty string A match could not be made with the provided inputs.

DPV Footnotes - deliverability_analysis[dpv_footnotes]

AA Some parts of the address (such as the street and ZIP code) are valid.
A1 The address is invalid based on given inputs.
BB The address is deliverable.
CC The address is deliverable by removing the provided secondary unit designator.
N1 The address is deliverable but is missing a secondary information (apartment, unit, etc).
F1 The address is a deliverable military address.
G1 The address is a deliverable General Delivery address. General Delivery is a USPS service which allows individuals without permanent addresses to receive mail.
U1 The address is a deliverable unique address. A unique ZIP code is assigned to a single organization (such as a government agency) that receives a large volume of mail.
M1 The primary number is missing.
M3 The primary number is invalid.
P1 PO Box, Rural Route, or Highway Contract box number is missing.
P3 PO Box, Rural Route, or Highway Contract box number is invalid.
R1 The address matched to a CMRA and private mailbox information is present.
RR The address matched to a CMRA and private mailbox information is not present.