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/self_mailers
  • /v1/self_mailers/{id}
  • /v1/letters
  • /v1/letters/{id}
  • /v1/checks
  • /v1/checks/{id}
  • /v1/billing_groups
  • /v1/billing_groups/{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 & International verification services trigger behavior with specific argument values, and, if you plan on using those, we recommend reading US Verification Test Environment and Int'l 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


Lob.init("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 2020-02-11. You can view your version and upgrade to the latest version in your Dashboard Settings. You will only need to specify a version if you would like to test a newer version of the API without doing a full upgrade. 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


Lob.init("yourApiKey", "2020-02-11")

Errors

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

Attributes

message: A human-readable, subject-to-change message with more details about the error
code: A consistent machine-keyable string identifying 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

Error Codes - Generic

bad_request422An invalid request was made. See error message for details.
conflict409/422This operation would leave data in a conflicted state.
feature_limit_reached403The account has reached its resource limit and requires upgrading to add more.
internal_server_error500An error has occured on Lob's servers. Please try request again.
invalid422An invalid request was made. See error message for details.
not_deletable422An attempt was made to delete a resource, but the resource cannot be deleted.
not_found404The requested resource was not found.
request_timeout408The request took too long. Please try again.
service_unavailable503The Lob servers are temporarily unavailable. Please try again.
unrecognized_endpoint404The requested endpoint doesn't exist.
unsupported_lob_version422An unsupported Lob API version was requested.

Error Codes - Authentication

email_required401Account must have a verified email address before creating live resources.
invalid_api_key401/403The API key is invalid.
publishable_key_not_allowed403The requested operation needs a secret key, not a publishable key. See API Keys for more information.
rate_limit_exceeded429Requests were sent too quickly and must be slowed down.
unauthorized401The request isn't authorized.
unauthorized_token401Token isn't authorized.

Error Codes - Advanced

address_length_exceeds_limit422The sum of to.address_line1 and to.address_line2 cannot surpass 50 characters.
bank_account_already_verified422The bank account has already been verified.
bank_error422There's an issue with the bank account.
custom_envelope_inventory_depleted422Custom envelope inventory is depleted, and more will need to be ordered.
deleted_bank_account404Checks cannot be created with a deleted bank account.
failed_deliverability_strictness422The to address doesn't meet strictness requirements. See Account Settings to configure strictness.
file_pages_below_min422Not enough pages.
file_pages_exceed_max422Too many pages.
file_size_exceeds_limit422The file size is too large. See description for details.
foreign_return_address422The 'from' address must be a US address.
inconsistent_page_dimensions422All pages of the input file must have the same dimensions.
invalid_bank_account422The provided bank routing number is invalid.
invalid_bank_account_verification422Verification amounts do not match.
invalid_check_international422Checks cannot be sent internationally.
invalid_country_covid422The postal service in the specified country is currently unable to process the request due to COVID-19 restrictions.
invalid_file422The file is invalid.
invalid_file_dimensions422File dimensions are incorrect for the selected mail type.
invalid_file_download_time422File download from remote server took too long.
invalid_file_url422The file URL when creating a resource is invalid.
invalid_image_dpi422DPI must be at least 300.
invalid_international_feature422The specified product cannot be sent to the destination.
invalid_perforation_return_envelope422Both return_envelope and perforation must be used together.
invalid_template_html422The provided HTML is invalid.
merge_variable_required422A required merge variable is missing.
merge_variable_whitespace422Merge variable names cannot contain whitespace.
payment_method_unverified401You must have a verified bank account or credit card to submit live requests.
pdf_encrypted422An encrypted PDF was provided.
special_characters_restricted422Cannot use special characters for merge variable names.
unembedded_fonts422The provided PDF contains non-standard unembedded fonts. See description for details.

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 and POST /v1/us_autocompletions endpoints have 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

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

While the headers are documented here in titlecase, HTTP headers are case insensitive and certain libraries may transform them to lowercase. Please inspect your headers carefully to see how they will be represented in your chosen development scenario.

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 5 seconds and try your request again.",
    "code": "rate_limit_exceeded",
    "status_code": 429
  }
}

Idempotent Requests

Lob supports idempotency for safely retrying POST requests to create postcards, self mailers, 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 mailpiece product endpoints, provide an additional Idempotency-Key header or an idempotency_key query parameter to the request. If multiple idempotency keys are provided, the request will fail. 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, etc.).

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.

Query Parameters

idempotency_key: optional

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

Example Request


final RequestOptions options = new RequestOptions.RequestOptionsBuilder()
        .setIdempotencyKey("026e7634-24d7-486c-a0bb-4a17fd0eebc5")
        .build();

LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .setFront("https://lob.com/postcardfront.pdf")
        .setBack("https://lob.com/postcardback.pdf")
        .create(options);

Postcard postcard = response.getResponseBody();

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, self mailers, letters, and checks. Within that timeframe, you can cancel mailings from production, free of charge. Once the window has passed for a postcard, self mailer, 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, self mailer, letter, or check for up to 180 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, self mailers, letters, and checks can be scheduled to be sent up to 180 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


DateTime futureDate = new DateTime(DateTime.parse("2021-07-02"))

Map<String, String> metadata = new HashMap<>();
metadata.put("campaign", "NEWYORK2015");

Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .setFront("tmpl_b846a20859ae11a")
        .setBack("tmpl_01b0d396a10c268")
        .setMergeVariables(mergeVariables)
        .setMetadata(metadata)
        .setSendDate(futureDate)
        .create();

Postcard postcard = response.getResponseBody();

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


Map<String, String> metadata = new HashMap<>();
metadata.put("campaign", "NEWYORK2015");

Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .setFront("<html style="margin: 130px; font-size: 50;">Front HTML for {{name}}</html>")
        .setBack("<html style="margin: 130px; font-size: 50;">Back HTML</html>")
        .setMergeVariables(mergeVariables)
        .setMetadata(metadata)
        .create();

Postcard postcard = response.getResponseBody();

Example List Request with Metadata Filter


Map<String, String> metadata = new HashMap<>();
metadata.put("campaign", "NEWYORK2015");

Map<String, String> params = new HashMap<>();
params.put("metadata", metadata);

PostcardCollection postcardCollection = Postcard.list(params).getResponseBody();

Request Bodies

When manually sending a POST HTTP request directly to the Lob API, without the use of a library, you may represent the body as either a Form URL Encoded request, a JSON document, or a Multipart Form Data request.

However, if you're using one of our libraries, the generation of the request bodies is done for you automatically and you don't need to worry about the format.

Form URL Encoded

This request body encoding is accompanied with the Content-Type: application/x-www-form-urlencoded header. The content is an example of what the Verify a US address endpoint accepts. An example of a request body encoded in this format follows.


primary_line=185 Berry Street&city=San Francisco&state=CA&zip_code=94107

JSON

This request body encoding is accompanied with the Content-Type: application/json header. The content is an example of what the Verify a US address endpoint accepts. An example of a request body encoded in this format follows.


{
  "primary_line": "185 Berry Street",
  "city": "San Francisco",
  "state": "CA",
  "zip_code": 94107
}

Multipart Form Data

This request body encoding is accompanied with the Content-Type: multipart/form-data header. This is the only format that can be used for uploading a file to the API. The content is an example of what the Create a check endpoint accepts. An example of a request body encoded in this format follows.


--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="description"

Demo Letter
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="to"

adr_bae820679f3f536b
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="from"

adr_210a8d4b0b76d77b
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="file"; filename="file.pdf"
Content-Type: application/pdf

<FILE CONTENT>
--------------------------7015ebe79c0a5f8c
Content-Disposition: form-data; name="color"

true
--------------------------7015ebe79c0a5f8c--

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


Map<String, String> metadata = new HashMap<>();
metadata.put("campaign", "NEWYORK2015");

Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setDescription("Demo Postcard")
        .setFront("tmpl_b846a20859ae11a")
        .setBack("tmpl_01b0d396a10c268")
        .setTo("adr_78c304d54912c502")
        .setFrom("adr_61a0865c8c573139")
        .setMergeVariables(mergeVariables)
        .setMetadata(metadata)
        .create();

Postcard postcard = response.getResponseBody();

HTML Examples

Use a pre-designed template from our gallery or follow these basic guidelines as starting points for creating custom Postcards, Self Mailers, 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.
recipient_moved: boolean or null

Only returned for accounts on certain Print & Mail Editions. Value is true if the address was altered because the recipient filed for a National Change of Address (NCOA), false if the NCOA check was run but no altered address was found, and null if the NCOA check was not run. The NCOA check does not happen for non-US addresses, for non-deliverable US addresses, or for addresses created before the NCOA feature was added to your account.
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. Depending on your Print & Mail Edition, US addresses may also be run additionally through National Change of Address (NCOA). 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. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc).

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


LobResponse<Address> response = new Address.RequestBuilder()
        .setDescription("Harry - Office")
        .setName("Harry Zhang")
        .setCompany("Lob")
        .setLine1("185 Berry St")
        .setLine2("# 6100")
        .setCity("San Francisco")
        .setState("CA")
        .setZip("94107")
        .setCountry("US")
        .setPhone("555-555-5555")
        .setEmail("harry@lob.com")
        .create();

Address address = response.getResponseBody();

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


LobResponse<Address> response = Address.retrieve("adr_fa85158b26c3eb7c");
Address address = response.getResponseBody();

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


LobResponse<Address> response = Address.delete("adr_43769b47aed248c2");
Address address = response.getResponseBody();

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

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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. Each entry in the array is a separate address object. The previous and next page of address entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more addresses are available beyond the current set of returned results, the next_url field will be empty.

Example Definition

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

Example Request


Map<String, Object> params = new HashMap<>();
params.put("limit", 2);

LobResponse<AddressCollection> response = Address.list(params);
AddressCollection addresses = response.getResponseBody();

Example Response


{
  "data": [
    {
      "id": "adr_e68217bd744d65c8",
      "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": "2019-08-12T00:16:00.361Z",
      "date_modified": "2019-08-12T00:16:00.361Z",
      "object": "address"
    },
    {
      "id": "adr_830bf0eabdaaa409",
      "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": "2019-08-07T21:59:46.764Z",
      "date_modified": "2019-08-07T21:59:46.764Z",
      "object": "address"
    }
  ],
  "object": "list",
  "next_url": "https://api.lob.com/v1/addresses?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wN1QyMTo1OTo0Ni43NjRaIiwiaWRPZmZzZXQiOiJhZHJfODMwYmYwZWFiZGFhYTQwOSJ9",
  "previous_url": null,
  "count": 2
}

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_active:
string

Corresponds to the USPS field dpv_no_stat. Indicates that an address has been vacated in the recent past, and is no longer receiving deliveries. If it's been unoccupied for 90+ days, or temporarily vacant, this will be flagged. Possible values are:

  • Y — Address is active
  • N — Address is not active
  • 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.
lob_confidence_score: object

Lob Confidence Score is a nested object that provides a numerical value between 0-100 of the likelihood that an address is deliverable based on Lob’s mail delivery data to over a fourth of US households.

score:
decimal

A numerical score between 0 and 100 that represents the percentage of mailpieces Lob has sent to this addresses that have been delivered successfully. Will be null if no tracking data exists for this address.
level:
string

Indicates the likelihood that the address is a valid, mail-receiving address. Possible values are:

  • high — Over 70% of mailpieces Lob has sent to this address were delivered successfully.
  • medium — Between 40% and 70% of mailpieces Lob has sent to this address were delivered successfully.
  • low — Less than 40% of mailpieces Lob has sent to this address were delivered successfully.
  • empty string — No tracking data exists for this address.
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_active": "Y",
    "dpv_footnotes": [
      "AA",
      "BB"
    ],
    "ews_match": false,
    "lacs_indicator": "",
    "lacs_return_code": "",
    "suite_return_code": ""
  },
  "lob_confidence_score": {
    "score": 100,
    "level": "high"
  },
  "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


LobResponse<USVerification> response = new USVerification.RequestBuilder()
        .setRecipient("Donald")
        .setPrimaryLine("185 Berry St")
        .setSecondaryLine("Ste 6100")
        .setCity("San Francisco")
        .setState("CA")
        .setZipCode("94107")
        .verify();

USVerification usVerification = response.getResponseBody();

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_active": "Y",
    "dpv_footnotes": [
      "AA",
      "BB"
    ],
    "ews_match": false,
    "lacs_indicator": "",
    "lacs_return_code": "",
    "suite_return_code": ""
  },
  "lob_confidence_score": {
    "score": 100,
    "level": "high"
  },
  "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 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


LobResponse<USVerification> response = new USVerification.RequestBuilder()
        .setRecipient("Donald")
        .setPrimaryLine("po box")
        .setZipCode("11111")
        .verify();

USVerification usVerification = response.getResponseBody();

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_active": "Y",
    "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_a3ac97bcfbb2460ab20c",
  "suggestions": [
      {
          "primary_line": "185 BAYSIDE VILLAGE PL",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BRANNAN ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BONIFACIO ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BLAIR TER",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BLUXOME ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BERRY ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BRYANT ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      }
  ],
  "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.
zip_code: optional

An optional ZIP Code input to filter suggestions by. Matches partial entries.
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


LobResponse<USAutocompletion> response = new USAutocompletion.RequestBuilder()
    .setAddressPrefix("185 B")
    .setCity("San Francisco")
    .setState("CA")
    .setZipCode("94107")
    .autocomplete();

USAutocompletion usAutocompletion = response.getResponseBody();

Example Response


  {
  "id": "us_auto_a3ac97bcfbb2460ab20c",
  "suggestions": [
      {
          "primary_line": "185 BAYSIDE VILLAGE PL",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BRANNAN ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BONIFACIO ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BLAIR TER",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BLUXOME ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BERRY ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      },
      {
          "primary_line": "185 BRYANT ST",
          "city": "SAN FRANCISCO",
          "state": "CA",
          "zip_code": "94107"
      }
  ],
  "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


LobResponse<USAutocompletion> response = new USAutocompletion.RequestBuilder()
    .setAddressPrefix("1 sugg")
    .autocomplete();

USAutocompletion usAutocompletion = response.getResponseBody();

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


LobResponse<USZipLookup> response = new USZipLookup.RequestBuilder()
        .setZipCode("94107")
        .lookup();

USZipLookup usZipLookup = response.getResponseBody();

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).
coverage: string

The coverage level for the country. This represents the maximum level of accuracy an input address can be verified to.

  • SUBBUILDING - Coverage down to unit numbers. For example, in an apartment or a large building
  • HOUSENUMBER/BUILDING - Coverage down to house number. For example, the address where a house or building may be located
  • STREET - Coverage down to street. This means that we can verify that an street exists in a city, state, country
  • LOCALITY - Coverage down to city, state, or village or province. This means that we can verify that a city, village, province, or state exists in a country. Countries differ in how they define what is a province, state, city, village, etc. This attempts to group eveyrthing together.
  • SPARSE - Some addresses for this country exist in our databases
deliverability: string

Summarizes the deliverability of the international verification's status 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.
status: string

The status level for the country. This represents the maximum level of accuracy an input address can be verified to.

  • LV4 - Verified. The input data is correct. All input data was able to match in databases.
  • LV3 - Verified. The input data is correct. All input data was able to match in databases after some or all elements were standarized. The input data may also be using outdated city, state, or country names.
  • LV2 - Verified. The input data is correct although some input data is unverifiable due to incomplete data.
  • LV1 - Verified. The input data is acceptable but in an attempt to standarize user input, errors were introduced.
  • LF4 - Fixed. The input data is matched and fixed. (Example: Brighon, UK -> Brighton, UK)
  • LF3 - Fixed. The input data is matched and fixed but some elements such as Subbuilding number and house number cannot be checked.
  • LF2 - Fixed. The input data is matched but some elements such as Street cannot be checked.
  • LF1 - Fixed. The input data is acceptable but in an attempt to standarize user input, errors were introduced.
  • LM4 - Missing Info. The input data cannot be corrected completely.
  • LM3 - Missing Info. The input data cannot be corrected completely and there were multiple matches found in databases.
  • LM2 - Missing Info. The input data cannot be corrected completely and only some elements were found.
  • LU1 - Unverfied. The input data cannot be corrected or matched.
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",
  "coverage": "SUBBUILDING"
  "deliverability": "deliverable",
  "status": "LV4",
  "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 dummy response based on the primary line you input.

Headers

x-lang-output: optional

Translate response to the native language of the country (native) or match the response to the language in the request (match). Default response is in English. Allowed values are native, match.

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. Also does not accept PS, which is not currently supported.

Returns

Returns the validated address object, along with its deliverability status.

Example Definition

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

Example Request


LobResponse<IntlVerification> response = new IntlVerification.RequestBuilder()
        .setPrimaryLine("370 Water St")
        .setCity("Summerside")
        .setState("Prince Edward Island")
        .setPostalCode("C1N 1C4")
        .setCountry("CA")
        .verify();

IntlVerification intlVerification = response.getResponseBody();

Example Response


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

The International verifications test environment

When verifying international 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 primary_line let you explore the responses to many types of addresses:

to get a sample response for set primary_line to
deliverable deliverable
deliverable_missing_info deliverable missing info
undeliverable undeliverable
no_match 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


LobResponse<IntlVerification> response = new IntlVerification.RequestBuilder()
        .setPrimaryLine("deliverable")
        .setCountry("CA")
        .verify();

IntlVerification intlVerification = response.getResponseBody();

Example Response


{
  "id": "intl_ver_c7cb63d68f8d6",
  "recipient": "TEST KEYS DO NOT VERIFY ADDRESSES",
  "primary_line": "370 WATER ST",
  "secondary_line": "",
  "last_line": "SUMMERSIDE PE C1N 1C4",
  "country": "CA",
  "coverage": "SUBBUILDING"
  "deliverability": "deliverable",
  "status": "LV4",
  "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 ordered by ascending time. Will not be populated for postcards created in test mode.
thumbnails: array

Signed links to different sized thumbnails of each postcard page.
merge_variables: object or null
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_bae820679f3f536b",
    "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_210a8d4b0b76d77b",
    "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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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.

Headers

idempotency-key: optional

Query Parameters

idempotency_key: optional

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. Depending on your Print & Mail Edition, US addresses may also be run additionally through National Change of Address (NCOA). 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. Must be a US address. All addresses will be standardized into uppercase without being modified by verification.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 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.

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. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds. HTML files passed as remote URLs or local file uploads have no character limit. HTML merge variables should not include delimiting whitespace. 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. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds. HTML files passed as remote URLs or local file uploads have no character limit. HTML merge variables should not include delimiting whitespace. 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.

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.

merge_variables: optional

You can input a merge variable payload object to your template to render dynamic content. For example, if you have a template like: {{variable_name}}, pass in {"variable_name": "Harry"} to render Harry. merge_variables must be an object. Any type of value is accepted as long as the object is valid JSON. That means you can use strings, numbers, booleans, arrays, objects, or null. The max length of the object is 25,000 characters. This means if you call JSON.stringify on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: !, ", #, %, &, ', (, ), *, +, ,, /, ;, <, =, >, @, [, \, ], ^, `, {, |, }, ~. More instructions can be found in this guide. 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.

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


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setDescription("Demo Postcard job")
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("185 Berry St")
                        .setLine2("# 6100")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .setFront("<html style='padding: 1in; font-size: 50;'>Front HTML for {{name}}</html>")
        .setBack("<html style='padding: 1in; font-size: 20;'>Back HTML for {{name}}</html>")
        .setMergeVariables(mergeVariables)
        .create();

Postcard postcard = response.getResponseBody();

Example Request with saved HTML templates


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setDescription("Demo Postcard job")
        .setFront("tmpl_b846a20859ae11a")
        .setBack("tmpl_01b0d396a10c268")
        .setMergeVariables(mergeVariables)
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("185 Berry St")
                        .setLine2("# 6100")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

Postcard postcard = response.getResponseBody();

Example Request with Remote Files


LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setDescription("Demo Postcard job")
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .setFront("https://lob.com/postcardfront.pdf")
        .setBack("https://lob.com/postcardback.pdf")
        .create();

Postcard postcard = response.getResponseBody();

Example Request with Local Files


final File front = new File("/path/to/your/front.pdf");
final File back = new File("/path/to/your/back.pdf");

LobResponse<Postcard> response = new Postcard.RequestBuilder()
        .setDescription("Demo Postcard job")
        .setFront(front)
        .setBack(back)
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

Postcard postcard = response.getResponseBody();

Example Response


{
  "id": "psc_14c1b66f31264c34",
  "description": "Demo Postcard job",
  "metadata": {},
  "to": {
    "id": "adr_bae820679f3f536b",
    "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_210a8d4b0b76d77b",
    "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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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


LobResponse<Postcard> response = Postcard.retrieve("psc_5c002b86ce47537a");
Postcard postcard = response.getResponseBody();

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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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


LobResponse<Postcard> deleteResponse = Postcard.delete("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

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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. Each entry in the array is a separate postcard object. The previous and next page of postcard entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more postcards are available beyond the current set of returned results, the next_url field will be empty.

Example Definition

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

Example Request


Map<String, Object> params = new HashMap<>>();
params.put("limit", 2);

LobResponse<PostcardCollection> response = Postcard.list(params);
PostcardCollection postcards = response.getResponseBody();

Example Response


{
  "data": [
    {
      "id": "psc_3444edc7912a557e",
      "description": "Demo Postcard job",
      "metadata": {},
      "to": {
        "id": "adr_10f4024feb3a3c1d",
        "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": "2019-08-07T19:20:50.452Z",
        "date_modified": "2019-08-07T19:20:50.452Z",
        "deleted": true,
        "object": "address"
      },
      "from": {
        "id": "adr_210a8d4b0b76d77b",
        "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": "2018-12-08T03:01:07.651Z",
        "date_modified": "2018-12-08T03:01:07.651Z",
        "object": "address"
      },
      "url": "https://lob-assets.com/postcards/psc_3444edc7912a557e.pdf?version=v1&expires=1568239881&signature=Ho_tHZO-VTuxX21TLfJDUfyzzISnCTvdGKH8n_WBYfQEeiSZh6LD9cXhMlrfZk8ICX5gem7v90a6ks9o_-3SAQ",
      "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_3444edc7912a557e_thumb_small_1.png?version=v1&expires=1568239881&signature=zJMgrHI4_bKlGiJeUmYG6_mEgyNmN3HslmqOzIbZ8dmE2Did4TYrLCkCo41a90TAtpAwEur7n-Fq8E9vPckoDQ",
          "medium": "https://lob-assets.com/postcards/psc_3444edc7912a557e_thumb_medium_1.png?version=v1&expires=1568239881&signature=_YyAwH227ohr0Fl3_KELrJt-8Jj1aMtkalqZ2Ch1bucsTBJed8_sTBuvlsYsmSzmeX2E3icVxFRvuk6rSc0eAQ",
          "large": "https://lob-assets.com/postcards/psc_3444edc7912a557e_thumb_large_1.png?version=v1&expires=1568239881&signature=C1eBA40bN0nofI9S6CyCIe34FEPgc0WRTowECiZp9w_Mwk1q61elHSFzwaKCVsrrjiGxss77m4ZJQLckkaQ5DA"
        },
        {
          "small": "https://lob-assets.com/postcards/psc_3444edc7912a557e_thumb_small_2.png?version=v1&expires=1568239881&signature=oLImYWE9YSPfWNuG4cXyHcSnZNFJXkwmQUu6uzh--uU3ZdZu5uFMPatSaHxpUJP5THbuNBbo0RA4VGfF6CBtDQ",
          "medium": "https://lob-assets.com/postcards/psc_3444edc7912a557e_thumb_medium_2.png?version=v1&expires=1568239881&signature=KTA8KiqFkhDB1_VC1fG0GAevCRXR-FciZB51I8nsNnCy1DZbPA5mkJVPgvFWQ-5eELUAip4lmhp1MJ0lM_P4Aw",
          "large": "https://lob-assets.com/postcards/psc_3444edc7912a557e_thumb_large_2.png?version=v1&expires=1568239881&signature=V_i0oX1HsNsxKcuQb2ckEQpVjIOxhQOocWf41TCBa9lrI9JLgGYSAlEQxu4A82G7Xgmrs1kIGmHzqR7vsaSJBA"
        }
      ],
      "merge_variables": {
        "name": "Harry"
      },
      "size": "4x6",
      "mail_type": "usps_first_class",
      "expected_delivery_date": "2019-08-15",
      "date_created": "2019-08-07T19:20:50.556Z",
      "date_modified": "2019-08-07T19:20:51.999Z",
      "send_date": "2019-08-07T19:20:50.556Z",
      "object": "postcard"
    },
    {
      "id": "psc_4312e292dad93557",
      "description": "Demo Postcard job",
      "metadata": {},
      "to": {
        "id": "adr_1ac2db718d965060",
        "description": null,
        "name": "HARRY ZHANG",
        "company": null,
        "phone": null,
        "email": null,
        "address_line1": "123 TEST STREET",
        "address_line2": null,
        "address_city": "MOUNTAIN VIEW",
        "address_state": "CA",
        "address_zip": "94041",
        "address_country": "UNITED STATES",
        "metadata": {},
        "date_created": "2019-08-05T18:35:35.010Z",
        "date_modified": "2019-08-05T18:35:35.010Z",
        "deleted": true,
        "object": "address"
      },
      "from": null,
      "url": "https://lob-assets.com/postcards/psc_4312e292dad93557.pdf?version=v1&expires=1568239881&signature=SaWAfTvamA0EFkdd4x2EVscqzKWYx1W3KUN85nzdlKvLH3p4jEli77eaF3Y-oa5v1_9nS76szfXT0rzvQDAiBw",
      "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_4312e292dad93557_thumb_small_1.png?version=v1&expires=1568239881&signature=Rz9mTCRPP7Vk6zredfazkVrMSe4eK5tzOjXUbF-9aO-_gwnwyRFubmRajg0rM5RJJrrcxVA0zV_NQbTYyLJ9Dg",
          "medium": "https://lob-assets.com/postcards/psc_4312e292dad93557_thumb_medium_1.png?version=v1&expires=1568239881&signature=LGACLPmqGI8KgOoC2Pf4zLr0tfuTbPBfqNdd9EOOhMfD2ONqDaO2CbYKKjTu7vaP9aymn3Ia3RDyxzd0BtbHCg",
          "large": "https://lob-assets.com/postcards/psc_4312e292dad93557_thumb_large_1.png?version=v1&expires=1568239881&signature=E6w8LTyTPPbKXWKWazNFnj-Rlp7lwF5lubM4DsjekqhGIZc1crud_iLwfoNns_rWfQFJPBNw4-v6IvxXazxjBQ"
        },
        {
          "small": "https://lob-assets.com/postcards/psc_4312e292dad93557_thumb_small_2.png?version=v1&expires=1568239881&signature=CAiEoUpVZuCSuukGpYP_b2wBhpzOZlmKMy_j5BCHtbFblsWW4Fmcqb3uPesifo8gjsFLR3woLvHkLpR6kzlsDw",
          "medium": "https://lob-assets.com/postcards/psc_4312e292dad93557_thumb_medium_2.png?version=v1&expires=1568239881&signature=xILzgwnJs2L3e2ecmdDaX2wOsIn5dAj2DnduJcfRMCCfOF7OjuZ7puc-zjPC7W4Rx8duv4U52Y_4YqHE0jHOAg",
          "large": "https://lob-assets.com/postcards/psc_4312e292dad93557_thumb_large_2.png?version=v1&expires=1568239881&signature=NCekoqEBQ4yFY6JRFUwbLzsxcafClDkmckonCn_b-9ct8kPaOtmOwCuKXDD-8i0UXJKajolA9bksamo0rPMGDA"
        }
      ],
      "merge_variables": {
        "name": "Harry"
      },
      "size": "4x6",
      "mail_type": "usps_first_class",
      "expected_delivery_date": "2019-08-13",
      "date_created": "2019-08-05T18:35:35.137Z",
      "date_modified": "2019-08-05T18:35:36.487Z",
      "send_date": "2019-08-05T18:35:35.137Z",
      "object": "postcard"
    }
  ],
  "object": "list",
  "next_url": "https://api.lob.com/v1/postcards?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wNVQxODozNTozNS4xMzdaIiwiaWRPZmZzZXQiOiJwc2NfNDMxMmUyOTJkYWQ5MzU1NyJ9",
  "previous_url": null,
  "count": 2
}

Self Mailer

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

The self mailer object

Fields

id: string

Unique identifier prefixed with sfm_.
description: string or null
metadata: object
to: an address object
from: an address object or null
url: string

A signed link to the rendered self mailer.
outside_template_id: string or null

The unique ID of the HTML template used for the outside of the self mailer.
inside_template_id: string or null

The unique ID of the HTML template used for the inside of the self mailer.
outside_template_version_id: string or null

The unique ID of the specific version of the HTML template used for the outside of the self mailer.
inside_template_version_id: string or null

The unique ID of the specific version of the HTML template used for the inside of the self mailer.
carrier: string

Value is USPS.
tracking_events: array

An array of tracking_event objects ordered by ascending time. Will not be populated for self mailers created in test mode.
thumbnails: array

Signed links to different sized thumbnails of each self mailer page.
merge_variables: object or null
size: string

Value is 6x18_bifold or 12x9_bifold. Defaults to 6x18_bifold.
mail_type: string

Value is usps_first_class or usps_standard.
expected_delivery_date: string

A date in ISO 8601 format of the self mailer's expected delivery date based on its send_date.
date_created: string

A timestamp in ISO 8601 format of the date the self mailer was created.
date_modified: string

A timestamp in ISO 8601 format of the date the self mailer was last modified.
send_date: string

A timestamp in ISO 8601 format of the date the self mailer will be dispatched for production. If the send_date of a self mailer has passed, it can no longer be canceled. send_date will be the date_created of the self mailer plus the cancellation window, if one was applied at the time of the self mailer's creation. If a self mailer 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 self mailer has been successfully canceled.
object: string

Value is always self_mailer.

Example Response


  {
      "id": "sfm_8ffbe811dea49dcf",
      "description": "April Campaign",
      "metadata": {},
      "to": {
        "id": "adr_bae820679f3f536b",
        "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_210a8d4b0b76d77b",
        "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/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA",
      "outside_template_id": "tmpl_a3cb937f26d7eec",
      "inside_template_id": "tmpl_a3cb937f26d7eec",
      "inside_template_version_id": "vrsn_bfdf70893b00a85",
      "outside_template_version_id": "vrsn_bfdf70893b00a85",
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
          {
              "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA",
              "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ",
              "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg"
          },
          {
              "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ",
              "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA",
              "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw"
          }
      ],
      "merge_variables": {
          "name": null
      },
      "size": "6x18_bifold",
      "mail_type": "usps_first_class",
      "expected_delivery_date": "2021-03-24",
      "date_created": "2021-03-16T18:40:40.504Z",
      "date_modified": "2021-03-16T18:40:40.504Z",
      "send_date": "2021-03-16T18:45:40.493Z",
      "billing_group_id": "bg_79a178f7171f5795d",
      "object": "self_mailer"
  }

Create a self mailer

Create a new self mailer.

Headers

idempotency-key: optional

Query Parameters

idempotency_key: optional

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. Depending on your Print & Mail Edition, US addresses may also be run additionally through National Change of Address (NCOA). 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. Must be a US address. All addresses will be standardized into uppercase without being modified by verification.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 days in the future to send the self mailer off for production. This will override any self_mailer cancellation window applied to the self_mailer. Until the send_date has passed, the self_mailer 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.

outside: required

The artwork to use as the outside of your self mailer. 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. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds. HTML files passed as remote URLs or local file uploads have no character limit. HTML merge variables should not include delimiting whitespace. PDF, PNG, and JPGs must be sized at 6"x18" at 300 DPI, while supplied HTML will be rendered to the specified size. See here for HTML examples.

inside: required

The artwork to use as the inside of your self mailer. 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. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds. HTML files passed as remote URLs or local file uploads have no character limit. HTML merge variables should not include delimiting whitespace. PDF, PNG, and JPGs must be sized at 6"x18" 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: 6x18 bifold template, 12x9 bifold template. See here for HTML examples.

size: optional

Specifies the size of the self mailer. Must be 6x18_bifold (default) or 12x9_bifold

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 any self mailers sent outside of the United States.

merge_variables: optional

You can input a merge variable payload object to your template to render dynamic content. For example, if you have a template like: {{variable_name}}, pass in {"variable_name": "Harry"} to render Harry. merge_variables must be an object. Any type of value is accepted as long as the object is valid JSON. That means you can use strings, numbers, booleans, arrays, objects, or null. The max length of the object is 25,000 characters. This means if you call JSON.stringify on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: !, ", #, %, &, ', (, ), *, +, ,, /, ;, <, =, >, @, [, \, ], ^, `, {, |, }, ~. More instructions can be found in this guide. 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.

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 self mailer object upon successful creation.

Example Definition

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

Example Request with HTML strings


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<SelfMailer> response = new SelfMailer.RequestBuilder()
        .setDescription("Demo Self Mailer job")
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("210 King St")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .setInside("<html style='padding: 1in; font-size: 50;'>Inside HTML for {{name}}</html>")
        .setOutside("<html style='padding: 1in; font-size: 20;'>Outside HTML for {{name}}</html>")
        .setMergeVariables(mergeVariables)
        .create();

SelfMailer selfMailer = response.getResponseBody();

Example Request with saved HTML templates


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<SelfMailer> response = new SelfMailer.RequestBuilder()
        .setDescription("Demo Self Mailer job")
        .setInside("tmpl_b846a20859ae11a")
        .setOutside("tmpl_01b0d396a10c268")
        .setMergeVariables(mergeVariables)
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("210 King St")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

Postcard postcard = response.getResponseBody();

Example Request with Remote Files


LobResponse<SelfMailer> response = new SelfMailer.RequestBuilder()
        .setDescription("Demo Self Mailer job")
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .setInside("https://lob.com/selfmailerinside.pdf")
        .setOutside("https://lob.com/selfmaileroutside.pdf")
        .create();

SelfMailer selfMailer = response.getResponseBody();

Example Request with Local Files


final File inside = new File("/path/to/your/inside.pdf");
final File outside = new File("/path/to/your/outside.pdf");

LobResponse<SelfMailer> response = new SelfMailer.RequestBuilder()
        .setDescription("Demo Self Mailer job")
        .setInside(inside)
        .setOutside(outside)
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

SelfMailer selfMailer = response.getResponseBody();

Example Response


  {
      "id": "sfm_8ffbe811dea49dcf",
      "description": "April Campaign",
      "metadata": {},
      "to": {
        "id": "adr_bae820679f3f536b",
        "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_210a8d4b0b76d77b",
        "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/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618512040&signature=qvyCqXI1ndBvc4AjvG8FlirqLXEcfmYo4sDrRtabaXMOsX88to9G3K49uIk_aqevvZXe8HoRYD_nWydbQHqaCA",
      "outside_template_id": "tmpl_a3cb937f26d7eec",
      "inside_template_id": "tmpl_a3cb937f26d7eec",
      "inside_template_version_id": "vrsn_bfdf70893b00a85",
      "outside_template_version_id": "vrsn_bfdf70893b00a85",
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
          {
              "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618512040&signature=-bipeUHP-hAMcCBSrWM0ZH1VwRdSPNVGGZN9hAZKr6Lh4ly6uxvratVd5LXJCK_zOEMYk_mTWASt0ge7OY6SDA",
              "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618512040&signature=ryxN7bsXGtw_GRFSP3Cs3A3IYjxZi3cW9BHDCNgMt6p3nobVmsc_iFHt2e-S7ndAXhhN7nP-MQVov3bt3r37BQ",
              "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618512040&signature=kBrm00xkyCkJNJRHxH8HshFaebtOxnzjVWOs1VVmGMuw8H6OBNcMAMxt9s49K0jlpHoh3Nr9uSncEZMQaaNjAg"
          },
          {
              "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618512040&signature=3gTgU7Fd3KoT_vNlQnTGptRps5ZgnkhSnPrAwk7L98higIzSwfKoLvuu_DIpMM48dHbxckKT9waR8euJ4KSDBQ",
              "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618512040&signature=Ue1lw5CMj7KRx6cMQL8xPeazaHCdJzWcACd1w3acuYPnWkVIpSt62OIO7hAtpAQK9xm1dhhlFj0rqRZMdRMMBA",
              "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618512040&signature=cICc7HEm1xG_eyM4a_wtvPk2FqoLRmtgGa29kJisWnMIYBL0OkyzG4ZCYGMhp-5cZpJlSpXfTgGKh_Qmeo1TDw"
          }
      ],
      "merge_variables": {
          "name": null
      },
      "size": "6x18_bifold",
      "mail_type": "usps_first_class",
      "expected_delivery_date": "2021-03-24",
      "date_created": "2021-03-16T18:40:40.504Z",
      "date_modified": "2021-03-16T18:40:40.504Z",
      "send_date": "2021-03-16T18:45:40.493Z",
      "billing_group_id": "bg_79a178f7171f5795d",
      "object": "self_mailer"
  }

Retrieve a self mailer

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

Path Parameters

id: required

The identifier of the self mailer to be retrieved.

Returns

Returns a self mailer object if a valid identifier was provided.

Example Definition

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

Example Request


LobResponse<SelfMailer> response = SelfMailer.retrieve("sfm_8ffbe811dea49dcf");
SelfMailer selfMailer = response.getResponseBody();

Example Response


{
    "id": "sfm_8ffbe811dea49dcf",
    "description": "April Campaign",
    "metadata": {},
    "to": {
      "id": "adr_bae820679f3f536b",
      "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_210a8d4b0b76d77b",
      "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",
    },
    "from": null,
    "url": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618781264&signature=YP_bCwrgVA2lz1Gr1YVCJN1f-WspUGsH0aJp2ihjfLXU7lDUV12_xRv4uPch0mfWeOOxEqpyP8hGpgvjmQKNAw",
    "outside_template_id": "tmpl_a3cb937f26d7eec",
    "inside_template_id": "tmpl_a3cb937f26d7eec",
    "inside_template_version_id": "vrsn_bfdf70893b00a85",
    "outside_template_version_id": "vrsn_bfdf70893b00a85",
    "carrier": "USPS",
    "tracking_events": [],
    "thumbnails": [
        {
            "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618781264&signature=A7q5HbRO53sUYYnwGlmP5mTS6ylLE7kS2mYhfcEOdexjyqG7UseK0MD26DppE4Q0aE4u2msDVMxd5ukjMerYCg",
            "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618781264&signature=b9pynuawVpU_vrhnT_mTpksdE-FLF_ZjdIBOFR_ltIzEGlx-VKD4VvZrqP98lG2D8V7UKQ7SdRr2nUAk4LxvCg",
            "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618781264&signature=g2jifhCselPqIj8au6lsbJMNFN8ZX3aM6GkLoAXiHBCS8X5mF9nhVbmO0odpnmwNlV1CWIp-MXVsZkC3NmxqBQ"
        },
        {
            "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618781264&signature=biJY4-ZbNNRydPYg3cZkq7wxjILbPBK_nIVyoyQsg5X5q4jlsa-2fzeMa48V9jprUetsC6WEuYvasHosRfG_DQ",
            "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618781264&signature=xEAX7bURyc8fSphacuo5yb7iVIpT8Xvq05KgMaNQS4r3aCpx0z1p42wbPmW758B5Ae0li1YDYvVyzS7qJIoWAw",
            "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618781264&signature=NieHDnoQ7STZUvofHrFt7S987CzIkUJWpaSgpVQPZw-C3_wwTPsIrvxYdXEuFrr6ciTUcxRBFPlE0lurmMkyCA"
        }
    ],
    "merge_variables": {
        "name": null
    },
    "size": "6x18_bifold",
    "mail_type": "usps_first_class",
    "expected_delivery_date": "2021-03-24",
    "date_created": "2021-03-16T18:40:40.504Z",
    "date_modified": "2021-03-16T18:41:06.691Z",
    "send_date": "2021-03-16T18:45:40.493Z",
    "deleted": true,
    "billing_group_id": "bg_79a178f7171f5795d",
    "object": "self_mailer"
}

Cancel a self mailer

Completely removes a self mailer from production. This can only be done if the self mailer's send_date has not yet passed. If the self mailer is successfully canceled, you will not be charged for it. Read more on self mailer cancellation windows and scheduling self mailers. 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 self mailer to be canceled.

Returns

Returns a message that the cancellation was successful.

Example Definition

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

Example Request


LobResponse<SelfMailer> deleteResponse = SelfMailer.delete("sfm_8ffbe811dea49dcf");

Example Response


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

List all self mailers

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

Query Parameters

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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 self mailer sizes to be returned. Must be a non-empty string array of valid sizes. Acceptable value is 6x18_bifold or 12x9_bifold.

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 self mailers 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 self mailers. Each entry in the array is a separate self mailer object. The previous and next page of self mailer entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more self mailers are available beyond the current set of returned results, the next_url field will be empty.

Example Definition

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

Example Request


Map<String, Object> params = new HashMap<>>();
params.put("limit", 2);

LobResponse<SelfMailerCollection> response = SelfMailer.list(params);
SelfMailerCollection selfMailers = response.getResponseBody();

Example Response


{
  "data": [
    {
      "id": "sfm_8ffbe811dea49dcf",
      "description": "April Campaign",
      "metadata": {},
      "to": {
          "id": "adr_f9228b743884ff98",
          "description": null,
          "name": "AYA",
          "company": null,
          "phone": null,
          "email": null,
          "address_line1": "2812 PARK RD",
          "address_line2": null,
          "address_city": "CHARLOTTE",
          "address_state": "NC",
          "address_zip": "28209-1314",
          "address_country": "UNITED STATES",
          "metadata": {},
          "date_created": "2021-03-16T18:40:40.410Z",
          "date_modified": "2021-03-16T18:40:40.410Z",
          "deleted": true,
          "object": "address"
      },
      "from": null,
      "url": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf.pdf?version=v1&expires=1618781264&signature=YP_bCwrgVA2lz1Gr1YVCJN1f-WspUGsH0aJp2ihjfLXU7lDUV12_xRv4uPch0mfWeOOxEqpyP8hGpgvjmQKNAw",
      "outside_template_id": "tmpl_a3cb937f26d7eec",
      "inside_template_id": "tmpl_a3cb937f26d7eec",
      "inside_template_version_id": "vrsn_bfdf70893b00a85",
      "outside_template_version_id": "vrsn_bfdf70893b00a85",
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
          {
              "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_1.png?version=v1&expires=1618781264&signature=A7q5HbRO53sUYYnwGlmP5mTS6ylLE7kS2mYhfcEOdexjyqG7UseK0MD26DppE4Q0aE4u2msDVMxd5ukjMerYCg",
              "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_1.png?version=v1&expires=1618781264&signature=b9pynuawVpU_vrhnT_mTpksdE-FLF_ZjdIBOFR_ltIzEGlx-VKD4VvZrqP98lG2D8V7UKQ7SdRr2nUAk4LxvCg",
              "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_1.png?version=v1&expires=1618781264&signature=g2jifhCselPqIj8au6lsbJMNFN8ZX3aM6GkLoAXiHBCS8X5mF9nhVbmO0odpnmwNlV1CWIp-MXVsZkC3NmxqBQ"
          },
          {
              "small": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_small_2.png?version=v1&expires=1618781264&signature=biJY4-ZbNNRydPYg3cZkq7wxjILbPBK_nIVyoyQsg5X5q4jlsa-2fzeMa48V9jprUetsC6WEuYvasHosRfG_DQ",
              "medium": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_medium_2.png?version=v1&expires=1618781264&signature=xEAX7bURyc8fSphacuo5yb7iVIpT8Xvq05KgMaNQS4r3aCpx0z1p42wbPmW758B5Ae0li1YDYvVyzS7qJIoWAw",
              "large": "https://lob-assets.com/self-mailers/sfm_8ffbe811dea49dcf_thumb_large_2.png?version=v1&expires=1618781264&signature=NieHDnoQ7STZUvofHrFt7S987CzIkUJWpaSgpVQPZw-C3_wwTPsIrvxYdXEuFrr6ciTUcxRBFPlE0lurmMkyCA"
          }
      ],
      "merge_variables": {
          "name": null
      },
      "size": "6x18_bifold",
      "mail_type": "usps_first_class",
      "expected_delivery_date": "2021-03-24",
      "date_created": "2021-03-16T18:40:40.504Z",
      "date_modified": "2021-03-16T18:41:06.691Z",
      "send_date": "2021-03-16T18:45:40.493Z",
      "deleted": true,
      "billing_group_id": "bg_79a178f7171f5795d",
      "object": "self_mailer"
    }
  ]
}

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
return_address: an address object

Specifies the address the return envelope will be sent back to. This is an optional argument that is available if an account is signed up for the return envelope tracking beta, and has return_envelope, and perforated_page fields populated in the API request.
color: boolean
double_sided: boolean
address_placement: string

Value is top_first_page or insert_blank_page.
return_envelope: boolean (default) or string

Indicates if a return envelope is requested for the letter. Value-type switches from boolean to string if the account is signed up for custom return envelopes. In this case, value is no_9_single_window for a standard return envelope, and the custom return_envelope_id for non-standard return envelopes.
perforated_page: integer or null

Value will be the final page to be perforated, including modifications made by insert_blank_page.
custom_envelope: object or null

A nested custom envelope object containing more information about the custom envelope used or null if a custom envelope was not used.

id:
string

The unique identifier of the custom envelope used.
url:
string

The url of the envelope asset used.
object:
string

Value is envelope.
extra_service: string or null

Value is certified, certified_return_receipt, or registered.
mail_type: string

Value is usps_first_class or usps_standard.
url: string

A signed link to the rendered letter.
merge_variables: object or null
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 certified_return_receipt, the tracking number will be here immediately upon creation. If the letter is registered the tracking number will appear here when it becomes available. Will be a dummy tracking number for certified and certified_return_receipt letters created in test mode; will be null for registered letters created in test mode or for non extra_service letters.
tracking_events: array

An array of tracking_event objects ordered by ascending time. Will not be populated when extra_service=registered. 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_bae820679f3f536b",
    "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_210a8d4b0b76d77b",
    "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,
  "custom_envelope": 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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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.

Headers

idempotency-key: optional

Query Parameters

idempotency_key: optional

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. Depending on your Print & Mail Edition, US addresses may also be run additionally through National Change of Address (NCOA). 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. Must be a US address unless using a custom_envelope. All addresses will be standardized into uppercase without being modified by verification.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 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.

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. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds. HTML files passed as remote URLs or local file upload have no character limit. HTML merge variables should not include delimiting whitespace. 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. If a custom_envelope is used, follow this template. 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. Any 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.

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.

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, certified_return_receipt, or registered. Certified provides tracking and delivery confirmation for domestic destinations. When using Certified, an extra sheet (1 PDF page single-sided or 2 PDF pages double-sided) will be added to the beginning of your letter reserved for address and barcode information. See here for templates: #10 envelope and flat envelope (used for letters over 6 pages single-sided or 12 pages double-sided). You will not be charged for this extra sheet. Set certified_return_receipt to optionally request an electronic copy of the recipient's signature to prove delivery of your certified letter. Registered provides tracking and confirmation for international addresses. See pricing for extra costs incurred.

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.

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.

custom_envelope: optional

Accepts an envelope ID for any customized envelope with available inventory. If no inventory is available for the specified ID, the letter will not be sent, and an error will be returned. If the letter has more than 6 sheets, it will be sent in a blank flat envelope. Custom envelopes may be created and ordered from the dashboard. This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.

merge_variables: optional

You can input a merge variable payload object to your template to render dynamic content. For example, if you have a template like: {{variable_name}}, pass in {"variable_name": "Harry"} to render Harry. merge_variables must be an object. Any type of value is accepted as long as the object is valid JSON. That means you can use strings, numbers, booleans, arrays, objects, or null. The max length of the object is 25,000 characters. This means if you call JSON.stringify on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: !, ", #, %, &, ', (, ), *, +, ,, /, ;, <, =, >, @, [, \, ], ^, `, {, |, }, ~. More instructions can be found in this guide. 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.

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


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Letter> response = new Letter.RequestBuilder()
        .setDescription("Demo Letter")
        .setFile("<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>")
        .setColor(true)
        .setMergeVariables(mergeVariables)
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("185 Berry St Ste 6100")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

Letter letter = response.getResponseBody();

Example Request with a saved HTML template


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Letter> response = new Letter.RequestBuilder()
        .setDescription("Demo Letter")
        .setFile("tmpl_cf5068f529da670")
        .setColor(true)
        .setMergeVariables(mergeVariables)
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("185 Berry St Ste 6100")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

Letter letter = response.getResponseBody();

Example Request with Remote File


LobResponse<Letter> response = new Letter.RequestBuilder()
        .setDescription("Demo Letter")
        .setFile("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/us_letter_1pg.pdf")
        .setColor(true)
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

Letter letter = response.getResponseBody();

Example Request with Local File


final File file = new File("/path/to/your/letter.pdf");

LobResponse<Letter> response = new Letter.RequestBuilder()
        .setDescription("Demo Letter")
        .setFile(file)
        .setColor(true)
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .create();

Letter letter = response.getResponseBody();

Example Response


{
  "id": "ltr_4868c3b754655f90",
  "description": "Demo Letter",
  "metadata": {},
  "to": {
    "id": "adr_bae820679f3f536b",
    "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_210a8d4b0b76d77b",
    "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,
  "custom_envelope": 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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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


LobResponse<Letter> response = Letter.retrieve("ltr_4868c3b754655f90");
Letter letter = response.getResponseBody();

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,
  "custom_envelope": 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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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


LobResponse<Letter> response = Letter.delete("ltr_4868c3b754655f90");
Letter letter= = response.getResponseBody();

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

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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. Each entry in the array is a separate letter object. The previous and next page of letter entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more letters are available beyond the current set of returned results, the next_url field will be empty.

Example Definition

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

Example Request


Map<String, Object> params = new HashMap<>>();
params.put("limit", 2);

LobResponse<LetterCollection> response = Letter.list(params);
LetterCollection letters = response.getResponseBody();

Example Response


{
  "data": [
    {
      "id": "ltr_5ba44b462c79f07c",
      "description": "Demo Letter",
      "metadata": {},
      "to": {
        "id": "adr_210a8d4b0b76d77b",
        "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": "2018-12-08T03:01:07.651Z",
        "date_modified": "2018-12-08T03:01:07.651Z",
        "object": "address"
      },
      "from": {
        "id": "adr_210a8d4b0b76d77b",
        "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": "2018-12-08T03:01:07.651Z",
        "date_modified": "2018-12-08T03:01:07.651Z",
        "object": "address"
      },
      "color": true,
      "double_sided": false,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "custom_envelope": null,
      "extra_service": null,
      "mail_type": "usps_first_class",
      "url": "https://lob-assets.com/letters/ltr_5ba44b462c79f07c.pdf?version=v1&expires=1568239830&signature=Ob-DUPLJLM4scWQeCDNadPJ4j33MZw16pykOxwv2us-bA7utTYi6oZ8WrEtBYDBBo09XkapR3gdJf0NEr90xAA",
      "merge_variables": null,
      "template_id": null,
      "template_version_id": null,
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_small_1.png?version=v1&expires=1568239830&signature=xZUmE8rq8wSECHPEb9c37cUDZBzGUO3XK5LsIPZhI6dOXgm6zJEn8_7tKuZ3JWBmvNJNXdTl_ufkNu4avjQUDw",
          "medium": "https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_medium_1.png?version=v1&expires=1568239830&signature=H7354Qpcm9S4aXbrMsBe6QJ6lSNi9IWPgMJtLWLi4Kyx9tHF8Mp9YEc_IL9x89Jfw4-yRzKDXA410X4W0PssBQ",
          "large": "https://lob-assets.com/letters/ltr_5ba44b462c79f07c_thumb_large_1.png?version=v1&expires=1568239830&signature=54LUIDKZyItA9pnC87d1pJVAuw8bhKLCsMpNWkB3LgdVWxPxxb_c1IyIWAbSR-dyOYEOlDBCc40J4Kns-O_mAg"
        }
      ],
      "expected_delivery_date": "2019-08-16",
      "date_created": "2019-08-08T17:09:14.514Z",
      "date_modified": "2019-08-08T17:09:16.850Z",
      "send_date": "2019-08-08T17:09:14.514Z",
      "object": "letter"
    },
    {
      "id": "ltr_da8267c6a6545cd6",
      "description": "Demo Letter",
      "metadata": {},
      "to": {
        "id": "adr_210a8d4b0b76d77b",
        "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": "2018-12-08T03:01:07.651Z",
        "date_modified": "2018-12-08T03:01:07.651Z",
        "object": "address"
      },
      "from": {
        "id": "adr_210a8d4b0b76d77b",
        "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": "2018-12-08T03:01:07.651Z",
        "date_modified": "2018-12-08T03:01:07.651Z",
        "object": "address"
      },
      "color": true,
      "double_sided": false,
      "address_placement": "top_first_page",
      "return_envelope": false,
      "perforated_page": null,
      "custom_envelope": null,
      "extra_service": null,
      "mail_type": "usps_first_class",
      "url": "https://lob-assets.com/letters/ltr_da8267c6a6545cd6.pdf?version=v1&expires=1568239830&signature=HH-5RnbD4x0eJcnEC9HhqKSvQGsbkjovzvqSKgBijUHKIXwEKQJ4CbYhKs_U2q2A1k20Xefcaw7bfdPKozuqCQ",
      "merge_variables": null,
      "template_id": null,
      "template_version_id": null,
      "carrier": "USPS",
      "tracking_number": null,
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_small_1.png?version=v1&expires=1568239830&signature=C1Rs83187HpWGhsg_pJIOhDIKlDtC_IgBBxHiocCEzJ8CncJwqrq5yHke-p97Dv7o81G_pfhFmirai589O6DCw",
          "medium": "https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_medium_1.png?version=v1&expires=1568239830&signature=gz63l0yi3sK_sXjYfIVdLSvkknJFr_O5TWRulo_iKIgS-PosIl6J0tDR6bx_Tv5Ab_w7DABg3qdKZ846MZ7TCw",
          "large": "https://lob-assets.com/letters/ltr_da8267c6a6545cd6_thumb_large_1.png?version=v1&expires=1568239830&signature=4Y1OIymaWkSO3aBIHCeshFAVnF-pDcF2FFqkx_jovaUFuk4FT1SI24L7_POwTRXQHlETMGlzkP_CGgqselRUAA"
        }
      ],
      "expected_delivery_date": "2019-08-16",
      "date_created": "2019-08-08T17:08:12.224Z",
      "date_modified": "2019-08-08T17:08:13.990Z",
      "send_date": "2019-08-08T17:08:12.224Z",
      "object": "letter"
    }
  ],
  "object": "list",
  "next_url": "https://api.lob.com/v1/letters?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wOFQxNzowODoxMi4yMjRaIiwiaWRPZmZzZXQiOiJsdHJfZGE4MjY3YzZhNjU0NWNkNiJ9",
  "previous_url": null,
  "count": 2
}

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.
tracking_events: array

An array of tracking_event objects ordered by ascending time. Will not be populated for checks created in test mode.
thumbnails: array

Signed links to different sized thumbnails of each check page.
merge_variables: object or null
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.
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_bae820679f3f536b",
    "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_210a8d4b0b76d77b",
    "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_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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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.

Headers

idempotency-key: optional

Query Parameters

idempotency_key: optional

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. Checks cannot be sent internationally (address_country must be US). 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, and returned back with an ID. Depending on your Print & Mail Edition, addresses may also be run additionally through National Change of Address (NCOA). If an 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. Must be a US address. 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. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds. HTML files passed as remote URLs or local file uploads have no character limit. HTML merge variables should not include delimiting whitespace. 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. Remote URLs have a 20 MB file size limit and must be downloaded within 40 seconds. HTML files passed as remote URLs or local file uploads have no character limit. HTML merge variables should not include delimiting whitespace. 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.

mail_type: optional

A string designating the mail postage type. Defaults to usps_first_class.

send_date: optional

A timestamp in ISO 8601 format which specifies a date after the current time and up to 180 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.

merge_variables: optional

You can input a merge variable payload object to your template to render dynamic content. For example, if you have a template like: {{variable_name}}, pass in {"variable_name": "Harry"} to render Harry. merge_variables must be an object. Any type of value is accepted as long as the object is valid JSON. That means you can use strings, numbers, booleans, arrays, objects, or null. The max length of the object is 25,000 characters. This means if you call JSON.stringify on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: !, ", #, %, &, ', (, ), *, +, ,, /, ;, <, =, >, @, [, \, ], ^, `, {, |, }, ~. More instructions can be found in this guide. 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.

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


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Check> response = new Check.RequestBuilder()
        .setDescription("Demo Check")
        .setCheckBottom("<h1 style='padding-top:4in;'>Demo Check for {{name}}</h1>")
        .setMergeVariables(mergeVariables)
        .setAmount(22.50f)
        .memo("rent")
        .setLogo("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/check_logo.png")
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("185 Berry St Ste 6100")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .setBankAccount("bank_8cad8df5354d33f")
        .create();

Check check = response.getResponseBody();

Example Request with saved HTML template


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Harry");

LobResponse<Check> response = new Check.RequestBuilder()
        .setDescription("Demo Check")
        .setCheckBottom("tmpl_23668b406d5afef")
        .setMergeVariables(mergeVariables)
        .setAmount(22.50f)
        .memo("rent")
        .setLogo("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/check_logo.png")
        .setTo(
                new Address.RequestBuilder()
                        .setName("Harry Zhang")
                        .setLine1("185 Berry St Ste 6100")
                        .setCity("San Francisco")
                        .setState("CA")
                        .setZip("94107")
        )
        .setFrom("adr_210a8d4b0b76d77b")
        .setBankAccount("bank_8cad8df5354d33f")
        .create();

Check check = response.getResponseBody();

Example Request with Remote Files


Map<String, String> mergeVariables = new HashMap<>();
mergeVariables.put("name", "Lob");

LobResponse<Check> response = new Check.RequestBuilder()
        .setDescription("Demo Check")
        .setCheckBottom("<h1 style='padding-top:4in;'>Demo Check for {{name}}</h1>")
        .setMergeVariables(mergeVariables)
        .setAmount(22.50f)
        .memo("rent")
        .setLogo("https://s3-us-west-2.amazonaws.com/public.lob.com/assets/check_logo.png")
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .setBankAccount("bank_8cad8df5354d33f")
        .create();

Check check = response.getResponseBody();

Example Request with Local Files


final File logo = new File("/path/to/your/logo.png");
final File file = new File("/path/to/your/file.pdf");

LobResponse<Check> response = new Check.RequestBuilder()
        .setDescription("Demo Check")
        .setCheckBottom(file)
        .setMergeVariables(mergeVariables)
        .setAmount(22.50f)
        .memo("rent")
        .setLogo(logo)
        .setTo("adr_bae820679f3f536b")
        .setFrom("adr_210a8d4b0b76d77b")
        .setBankAccount("bank_8cad8df5354d33f")
        .create();

Check check = response.getResponseBody();

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_bae820679f3f536b",
    "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_210a8d4b0b76d77b",
    "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_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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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


LobResponse<Check> response = Check.retrieve("chk_534f10783683daa0");
Check check = response.getResponseBody();

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_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"
    }
  ],
  "merge_variables": {
    "name": "Harry"
  },
  "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


LobResponse<Check> response = Check.delete("chk_534f10783683daa0");
Check check = response.getResponseBody();

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

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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. Each entry in the array is a separate check object. The previous and next page of check entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more checks are available beyond the current set of returned results, the next_url field will be empty.

Example Definition

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

Example Request


Map<String, Object> params = new HashMap<>();
params.put("limit", 2);

LobResponse<CheckCollection> response = Check.list(params);
CheckCollection checks = response.getResponseBody();

Example Response


{
  "data": [
    {
      "id": "chk_0176bf6197100185",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 12559,
      "memo": "rent",
      "amount": 22.5,
      "message": null,
      "url": "https://lob-assets.com/checks/chk_0176bf6197100185.pdf?version=v1&expires=1568239682&signature=aqKV5lmg_ktxzyl-qEwIf8-7DbvcguLO0LrfFcyMrUDDt6hxX_da0MEEpElxKR876VUaZrpHq_i_ayDWrsK3BA",
      "check_bottom_template_id": null,
      "attachment_template_id": null,
      "check_bottom_template_version_id": null,
      "attachment_template_version_id": null,
      "to": {
        "id": "adr_bae820679f3f536b",
        "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": "2018-12-08T03:08:43.446Z",
        "date_modified": "2018-12-08T03:08:43.446Z",
        "object": "address"
      },
      "from": {
        "id": "adr_210a8d4b0b76d77b",
        "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": "2018-12-08T03:01:07.651Z",
        "date_modified": "2018-12-08T03:01:07.651Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_8cad8df5354d33f",
        "description": "Test Bank Account",
        "metadata": {},
        "routing_number": "322271627",
        "account_number": "123456789",
        "account_type": null,
        "signatory": "John Doe",
        "signature_url": null,
        "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
        "verified": true,
        "date_created": "2015-11-06T19:24:24.440Z",
        "date_modified": "2015-11-06T19:41:28.312Z",
        "object": "bank_account"
      },
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/checks/chk_0176bf6197100185_thumb_small_1.png?version=v1&expires=1568239682&signature=T8DfMm_mxJJzIPgm8I0lvYY4Z6I8aFjsGsrEAicEqw8Ei_FaOtiGQKGeY16rdugAt8lmS_iX0lveBoG2RgWDDw",
          "medium": "https://lob-assets.com/checks/chk_0176bf6197100185_thumb_medium_1.png?version=v1&expires=1568239682&signature=-iJD7C58xOCD8eQ01StqSlw9WbDymL0Ygze9twfTs9s17zQppr2Zx363_Z4bP3ATHNhF3osjHuAxIasI2Wf6DQ",
          "large": "https://lob-assets.com/checks/chk_0176bf6197100185_thumb_large_1.png?version=v1&expires=1568239682&signature=VJlOkVDPKZThstdd632r3Grm2WhoyPkC-pffpcePTw1i1NkpAObDSRaItKMOQgeWkAcUud3SH0tYcVOadaNiCw"
        },
        {
          "small": "https://lob-assets.com/checks/chk_0176bf6197100185_thumb_small_2.png?version=v1&expires=1568239682&signature=XpCkOjy2zIKXkuc0s-UAYGNwpD_pgt7c9FKTDUCYbyqXupAg1MV1l2tdqevr0L0LT5FJqrGZH9khD5QRMQTkAA",
          "medium": "https://lob-assets.com/checks/chk_0176bf6197100185_thumb_medium_2.png?version=v1&expires=1568239682&signature=sdgnJMzusEfndu7dNmk37eKc0AV7Hmqev6TQAqkCESs5pg7j6dDTsp7v4pnDvhsj8d7SIMcahl1aGiysoom0CA",
          "large": "https://lob-assets.com/checks/chk_0176bf6197100185_thumb_large_2.png?version=v1&expires=1568239682&signature=ybe8ovBh8Gf-AWKGRs4CB4XkU-erPVbY66umXARhTiJG2Dg1QlyCb9WmBXWt0tBCwD5NGMl20mHeAgHwecLxBA"
        }
      ],
      "merge_variables": null,
      "expected_delivery_date": "2019-08-16",
      "mail_type": "usps_first_class",
      "date_created": "2019-08-08T19:34:47.571Z",
      "date_modified": "2019-08-08T19:34:49.612Z",
      "send_date": "2019-08-08T19:34:47.571Z",
      "object": "check"
    },
    {
      "id": "chk_92b9a6714bc0557c",
      "description": "Demo Check",
      "metadata": {},
      "check_number": 12558,
      "memo": "rent",
      "amount": 22.5,
      "message": null,
      "url": "https://lob-assets.com/checks/chk_92b9a6714bc0557c.pdf?version=v1&expires=1568239682&signature=jCct5PvzU58Iz2pSo58nf6rgsMRcJfMbUWThmm6lztFl5Vn2Y204b9h7gvw0vJvkDK2ThfaYqaUbWc0KzTpvAg",
      "check_bottom_template_id": null,
      "attachment_template_id": null,
      "check_bottom_template_version_id": null,
      "attachment_template_version_id": null,
      "to": {
        "id": "adr_bae820679f3f536b",
        "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": "2018-12-08T03:08:43.446Z",
        "date_modified": "2018-12-08T03:08:43.446Z",
        "object": "address"
      },
      "from": {
        "id": "adr_210a8d4b0b76d77b",
        "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": "2018-12-08T03:01:07.651Z",
        "date_modified": "2018-12-08T03:01:07.651Z",
        "object": "address"
      },
      "bank_account": {
        "id": "bank_8cad8df5354d33f",
        "description": "Test Bank Account",
        "metadata": {},
        "routing_number": "322271627",
        "account_number": "123456789",
        "account_type": null,
        "signatory": "John Doe",
        "signature_url": null,
        "bank_name": "J.P. MORGAN CHASE BANK, N.A.",
        "verified": true,
        "date_created": "2015-11-06T19:24:24.440Z",
        "date_modified": "2015-11-06T19:41:28.312Z",
        "object": "bank_account"
      },
      "carrier": "USPS",
      "tracking_events": [],
      "thumbnails": [
        {
          "small": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_1.png?version=v1&expires=1568239682&signature=ublquO_xAdvAkAwGJuOjgZQwcz7c3Ao4NHWHeDVTBEBjcrQr8LavxWEwUc1KU105Zex3SajRQLd6hqJOrDl0Bw",
          "medium": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_1.png?version=v1&expires=1568239682&signature=vHyuOtsanX4HnY_0LNft6ZJ8C67JnbI8ZVCjA2d9nR0Rd6lCl0Nk1s6BAhefbBkzecX9Yp0B8NWN9Q5v1Z4ICw",
          "large": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_1.png?version=v1&expires=1568239682&signature=SzCLKJ5m_TKJPLlL9PMw-zW9wo5mVYEK1jCtHwWRwwEaNU2v4Aehy-YHtus3TFJIt8RD2M-0Y3MtCxHwhqSABg"
        },
        {
          "small": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_2.png?version=v1&expires=1568239682&signature=iElagODaOCkF_lCUxIw-lK50GhEU1ar_odmslCazZqD4Fsd_rQLx3M4Q5HzYWp4evfzuCoFvk4oAQVuIAaguAw",
          "medium": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_2.png?version=v1&expires=1568239682&signature=2vwvm_QsfmdtkAa-_F4uk-0yeUPRascyhfwOr-OX1ya9i_8gdFQAxMTrP-FfNBVSYFXeknFm6IUPJHggfgeiBg",
          "large": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_2.png?version=v1&expires=1568239682&signature=NQf7tP9F4rP66S16hQ8duFpZSbTjaGBGK61Sr3H5D4CWtRyaPdoQlIpT2Jw-eKRcuYRkDEtQse_oWtL5gPqXDQ"
        },
        {
          "small": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_small_3.png?version=v1&expires=1568239682&signature=dbjFd44H9TyZsc3d0fqKon5e0GqZ6GA1dT26MH6WnoX8lrQor2CA6sZJ5qmu0Z4SAFlMKAzb-twqN7faLjEbDQ",
          "medium": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_medium_3.png?version=v1&expires=1568239682&signature=vSgwVs7T9E6KKBK7XU-6jRL9i0jvgTqvNxkdRARFf0UNlryJFm8l_t_x5mPH0sCTFZcLp7ouRaR5hhdHC6vZBQ",
          "large": "https://lob-assets.com/checks/chk_92b9a6714bc0557c_thumb_large_3.png?version=v1&expires=1568239682&signature=If4tXlN13WYy7JDPpFkWw0HAQpYNJHqi2UstiPHxUA_8IAj6vXORb-22acI124Pd1bR1QSjBHAW1gbiJ0kjiAQ"
        }
      ],
      "merge_variables": null,
      "expected_delivery_date": "2019-08-16",
      "mail_type": "usps_first_class",
      "date_created": "2019-08-08T19:34:27.802Z",
      "date_modified": "2019-08-08T19:34:30.582Z",
      "send_date": "2019-08-08T19:34:27.802Z",
      "object": "check"
    }
  ],
  "object": "list",
  "next_url": "https://api.lob.com/v1/checks?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wOC0wOFQxOTozNDoyNy44MDJaIiwiaWRPZmZzZXQiOiJjaGtfOTJiOWE2NzE0YmMwNTU3YyJ9",
  "previous_url": null,
  "count": 2
}

Billing Groups Beta

Billing groups allow you to create and view labels that can be attached to certain consumption-based usages of Letters, Checks, Postcards and Self-Mailers to customize your bill. Please check each resource API section to learn more about how to attach billing groups in the API.

The billing group object

Fields

id: string

Unique identifier prefixed with bg_.
name string

Name of the billing group.
description string or null

Description of the billing group.
date_created string

A timestamp in ISO 8601 format of the date the billing group was created.
date_modified string

A timestamp in ISO 8601 format of the date the billing group was last modified.
object string

Value is billing_group.

Example Response


{
  "id": "bg_759954f540a1bfdb5",
  "name": "Marketing Department",
  "description": "Usage group used for the Marketing Department's resource sends",
  "date_created": "2021-06-03T17:59:43.118Z",
  "date_modified": "2021-06-03T17:59:43.118Z",
  "object": "billing_group"
}

Create a billing group

Creates a new billing group.

Payload Parameters

name: required

Must be no longer than 255 characters.
description: optional

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

Returns

Returns a billing group upon successful creation.

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "bg_759954f540a1bfdb5",
  "name": "Marketing Department",
  "description": "Usage group used for the Marketing Department's resource sends",
  "date_created": "2021-06-03T17:59:43.118Z",
  "date_modified": "2021-06-03T17:59:43.118Z",
  "object": "billing_group"
}

Retrieve a billing group

Retrieves the details of a billing group. You need only supply the unique identifier that was returned upon billing group creation.

Path Parameters

id: required

The identifier of the billing group to be retrieved.

Returns

Returns a billing group object if a valid identifier was provided

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "bg_4bb02b527a72667d0",
  "name": "Marketing Department",
  "description": "Usage group used for the Marketing Department's resource sends",
  "date_created": "2021-06-03T18:21:32.709Z",
  "date_modified": "2021-06-03T18:21:32.709Z",
  "object": "billing_group"
}

Update a billing group

Updates the billing group with a given ID.

Path Parameters

id: required

The identifier of the billing group to be updated.

Payload Parameters

name: optional

Must be no longer than 255 characters.
description: optional

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

Returns

Returns the updated billing group if a valid identifier was provided.

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "id": "bg_95d1e9f48fa8aa73a",
  "name": "Marketing Department",
  "description": "Updated usage group used for the Marketing Department's resource sends",
  "date_created": "2021-04-27T22:17:07.346Z",
  "date_modified": "2021-06-08T23:08:55.452Z",
  "object": "billing_group"
}

List all billing groups

Returns a list of billing groups. The billing groups are returned sorted by creation date, with the most recently created billing groups 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 ≤.

date_modified: 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 billing_group in a desired order. sort_by accepts an object with the key being either date_created or date_modified and the value being either asc or desc.

Returns

Returns a list of billing group objects

Example Definition

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

Example Request

This feature is not currently supported by this library.

Example Response


{
  "data": [
    {
      "id": "bg_4bb02b527a72667d0",
      "name": "Marketing Department",
      "description": "Usage group used for the Marketing Department's postcard sends",
      "date_created": "2021-06-03T18:21:32.709Z",
      "date_modified": "2021-06-03T18:21:32.709Z",
      "object": "billing_group"
    },
    {
      "id": "bg_759954f540a1bfdb5",
      "name": "Another Marketing Department",
      "description": "Usage group used for the Marketing Department's letter sends",
      "date_created": "2021-06-03T17:59:43.118Z",
      "date_modified": "2021-06-03T17:59:43.118Z",
      "object": "billing_group"
    }
  ],
  "object": "list",
  "count": 2
}

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


LobResponse<BankAccount> response = new BankAccount.RequestBuilder()
        .setDescription("Test Bank Account")
        .setRoutingNumber("322271627")
        .setAccountNumber("123456789")
        .setSignatory("John Doe")
        .setAccountType("company")
        .create();

BankAccount bankAccount = response.getResponseBody();

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


LobResponse<BankAccount> response = BankAccount.retrieve("bank_8cad8df5354d33f");
BankAccount bankAccount = response.getResponseBody();

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


LobResponse<BankAccount> response = BankAccount.delete("bank_3e64d9904356b20");
BankAccount bankAccount = response.getResponseBody();

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


LobResponse<BankAccount> response = BankAccount.verify(newBankAccount.getId(), Arrays.asList(25, 63));
BankAccount bankAccount = response.getResponseBody();

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

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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. Each entry in the array is a separate bank account object. The previous and next page of bank account entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more bank accounts are available beyond the current set of returned results, the next_url field will be empty.

Example Definition

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

Example Request


Map<String, Object> params = new HashMap<>();
params.put("limit", 2);

LobResponse<BankAccountCollection> response = BankAccount.list(params);
BankAccountCollection bankAccounts = response.getResponseBody();

Example Response


{
  "data": [
    {
      "id": "bank_0e3fb07eba0b35b",
      "description": "Example bank account",
      "metadata": {},
      "routing_number": "122100024",
      "account_number": "1234564789",
      "account_type": "company",
      "signatory": "John Doe",
      "signature_url": null,
      "bank_name": "JPMORGAN CHASE BANK, NA",
      "verified": true,
      "date_created": "2019-03-30T13:13:22.200Z",
      "date_modified": "2019-03-30T13:13:23.385Z",
      "object": "bank_account"
    },
    {
      "id": "bank_eba93f7de3c02d9",
      "description": "Example bank account",
      "metadata": {},
      "routing_number": "122100024",
      "account_number": "1234564789",
      "account_type": "company",
      "signatory": "John Doe",
      "signature_url": null,
      "bank_name": "JPMORGAN CHASE BANK, NA",
      "verified": true,
      "date_created": "2019-03-30T13:11:06.809Z",
      "date_modified": "2019-03-30T13:11:07.872Z",
      "object": "bank_account"
    }
  ],
  "object": "list",
  "next_url": "https://api.lob.com/v1/bank_accounts?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0zMFQxMzoxMTowNi44MDlaIiwiaWRPZmZzZXQiOiJiYW5rX2ViYTkzZjdkZTNjMDJkOSJ9",
  "previous_url": null,
  "count": 2
}

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. Merge variables should not include delimiting whitespace. If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a {{#users}} opening tag without the corresponding closing tag {{/users}}.

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.

engine: optional

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

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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. Each entry in the array is a separate template object. The previous and next page of template entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more templates are available beyond the current set of returned results, the next_url field 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_d5a5a89da9106f8",
      "description": "Test Template",
      "versions": [
        {
          "id": "vrsn_232a02fb8224791",
          "description": "Test Template",
          "html": "HTML for ",
          "date_created": "2019-07-27T23:49:01.512Z",
          "date_modified": "2019-07-27T23:49:01.512Z",
          "object": "version"
        }
      ],
      "published_version": {
        "id": "vrsn_232a02fb8224791",
        "description": "Test Template",
        "html": "HTML for ",
        "date_created": "2019-07-27T23:49:01.512Z",
        "date_modified": "2019-07-27T23:49:01.512Z",
        "object": "version"
      },
      "metadata": {},
      "preview_data": null,
      "date_created": "2019-07-27T23:49:01.511Z",
      "date_modified": "2019-07-27T23:49:01.511Z",
      "save_data": true,
      "object": "template"
    },
    {
      "id": "tmpl_59b2150ae120887",
      "description": "Test Template",
      "versions": [
        {
          "id": "vrsn_2a7eb63ccb795b9",
          "description": "Test Template",
          "html": "HTML for ",
          "date_created": "2019-03-29T10:22:34.643Z",
          "date_modified": "2019-03-29T10:22:34.643Z",
          "object": "version"
        }
      ],
      "published_version": {
        "id": "vrsn_2a7eb63ccb795b9",
        "description": "Test Template",
        "html": "HTML for ",
        "date_created": "2019-03-29T10:22:34.643Z",
        "date_modified": "2019-03-29T10:22:34.643Z",
        "object": "version"
      },
      "metadata": {},
      "preview_data": null,
      "date_created": "2019-03-29T10:22:34.642Z",
      "date_modified": "2019-03-29T10:22:34.642Z",
      "save_data": true,
      "object": "template"
    }
  ],
  "object": "list",
  "next_url": "https://api.lob.com/v1/templates?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0yOVQxMDoyMjozNC42NDJaIiwiaWRPZmZzZXQiOiJ0bXBsXzU5YjIxNTBhZTEyMDg4NyJ9",
  "previous_url": null,
  "count": 2
}

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. Merge variables should not include delimiting whitespace. If there is a syntax error within your variable names within your HTML, then an error will be thrown, e.g. using a {{#users}} opening tag without the corresponding closing tag {{/users}}.

engine: optional

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.
engine: optional

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

limit: optional

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

after: optional

A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the previous_url field in the return response.
before: optional

A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the next_url field in the return response.
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

A dictionary with a data property that contains an array of up to limit template versions. Each entry in the array is a separate template object. The previous and next page of template versions entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.

If no more template versions are available beyond the current set of returned results, the next_url field will be empty.

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": "Second HTML for ",
      "date_created": "2017-11-09T05:09:03.665Z",
      "date_modified": "2018-05-22T22:01:10.479Z",
      "object": "version"
    },
    {
      "id": "vrsn_2a17159c1911919",
      "description": "Test Template",
      "html": "HTML for ",
      "date_created": "2017-11-09T05:08:40.004Z",
      "date_modified": "2018-05-22T22:01:11.309Z",
      "object": "version"
    }
  ],
  "object": "list",
  "next_url": null,
  "previous_url": null,
  "count": 2
}

Changelog

2020-02-11

  • renders merge_variables into HTML with syntax that supports objects, conditionals, and loops

2019-06-01

  • changed pagination model of GET endpoints for postcards, letters, checks, addresses, bank accounts, templates, and template versions to a cursor-based model
  • offset parameter on these endpoints has been removed
  • previous_url and next_url response fields have been added

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 Sunsetted

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

2016-05-02 Sunsetted

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

2016-03-21 Sunsetted

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

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

2015-12-22 Sunsetted

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

2015-11-23 Sunsetted

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

2015-11-06 Sunsetted

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

2015-10-21 Sunsetted

  • use the new HTML renderer for all products

2015-06-25 Sunsetted

  • remove the status field from all endpoints

2015-04-11 Sunsetted

  • 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

Tracking Events

As mail pieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events.

The tracking event object

Fields

id: string

Unique identifier prefixed with evnt_.
type: string

certified to designate this is a Certified letter tracking event, normal otherwise for non-Certified postcards, letters, and checks.
name: string

A descriptive name about the tracking event.

  • For normal postcards, self mailers, letters, and checks, 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. See here for more detailed descriptions of each type of event.
  • For Certified letters, possible values are Mailed, In Transit, In Local Area, Processed for Delivery, Pickup Available, Delivered, Re-Routed, Returned to Sender, and Issue. For more details about each value, see here.
details: object or null

Will be null for type=normal events. For type=certified events, gives more details about the event. See here for more details about possible values.

event:
string

A detailed substatus about the event.
description:
string

A description of what the event means.
notes:
string

Event-specific notes from USPS about the tracking event.
action_required:
boolean

true if action is required by the end recipient, false if not.
location: string or null

A string describing the location of the event.

  • For type=normal postcards, self mailers, letters, and checks, the zip code in which the scan event occurred. Will be null for Mailed events.
  • For type=certified letters, will be the zip code in which the event occurred if it exists, otherwise will be the name of a Regional Distribution Center if it exists, otherwise will be null.
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 Normal Object

      
{
  "id": "evnt_9e84094c9368cfb",
  "type": "normal",
  "name": "In Local Area",
  "details": null,
  "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"
}

Example Certified Object

      
{
  "id": "evnt_9e84094c9368cfb",
  "type": "certified",
  "name": "Delivered",
  "details": {
    "event": "delivered",
    "description": "Package has been delivered.",
    "notes": "Delivered, Front Desk/Reception/Mail Room",
    "action_required": false
  },
  "location": "33408",
  "time": "2019-10-08T19:41:00Z",
  "date_created": "2019-10-08T19:41:00Z",
  "date_modified": "2019-10-08T19:41:00Z",
  "object": "tracking_event"
}

Certified Tracking Events

Letters sent with USPS Certified Mail are fully tracked by USPS, and therefore their tracking events have an additional details object with more detailed information about the tracking event. The table to the right shows the potential values for the fields in the details object mapped to the tracking event name.

Certified Tracking Event Details

name event description action_required
Mailed package_accepted Package has been accepted into the carrier network for delivery. false
In Transit package_arrived Package has arrived at an intermediate location in the carrier network. false
In Transit package_departed Package has departed from an intermediate location in the carrier network. false
In Transit package_processing Package is processing at an intermediate location in the carrier network. false
In Transit package_processed Package has been processed at an intermediate location. false
In Local Area package_in_local_area Package is at a location near the end destination. false
Processed for Delivery delivery_scheduled Package is scheduled for delivery. false
Processed for Delivery out_for_delivery Package is out for delivery. false
Pickup Available pickup_available Package is available for pickup at carrier location. true
Delivered delivered Package has been delivered. false
Re-Routed package_forwarded Package has been forwarded. false
Returned to Sender returned_to_sender Package is to be returned to sender. false
Issue address_issue Address information is incorrect. Contact carrier to ensure delivery. true
Issue contact_carrier Contact the carrier for more information. true
Issue delayed Delivery of package is delayed. false
Issue delivery_attempted Delivery of package has been attempted. Contact carrier to ensure delivery. true
Issue delivery_rescheduled Delivery of package has been rescheduled. false
Issue location_inaccessible Delivery location inaccessible to carrier. Contact carrier to ensure delivery. true
Issue notice_left Carrier left notice during attempted delivery. Follow carrier instructions on notice. true
Issue package_damaged Package has been damaged. Contact carrier for more details. true
Issue package_disposed Package has been disposed. false
Issue package_held Package held at carrier location. Contact carrier for more details. true
Issue package_lost Package has been lost. Contact carrier for more details. true
Issue package_unclaimed Package is unclaimed. true
Issue package_undeliverable Package is not able to be delivered. true
Issue reschedule_delivery Contact carrier to reschedule delivery. true
Issue other Unrecognized carrier status. false

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. For .deleted events, the body matches the response for the corresponding delete endpoint for that resource (e.g. the postcard delete response).

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, self mailers, 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.deleted Occurs when a postcard is successfully canceled.
postcard.mailed Occurs when a postcard receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. Only created in the Live Environment.
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.

Self Mailers

Event Type When Event Type Occurs
self_mailer.created Occurs when a self mailer is successfully created (Lob returns a 200 status code).
self_mailer.rendered_pdf Occurs when a self mailer's PDF proof is successfully rendered.
self_mailer.rendered_thumbnails Occurs when a self mailer's thumbnails are successfully rendered.
self_mailer.deleted Occurs when a self mailer is successfully canceled.
self_mailer.mailed Occurs when a self mailer receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. Only created in the Live Environment.
self_mailer.in_transit Occurs when a self mailer receives an "In Transit" tracking event. Only created in the Live Environment.
self_mailer.in_local_area Occurs when a self mailer receives an "In Local Area" tracking event. Only created in the Live Environment.
self_mailer.processed_for_delivery Occurs when a self mailer receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
self_mailer.re-routed Occurs when a self mailer receives a "Re-Routed" tracking event. Only created in the Live Environment.
self_mailer.returned_to_sender Occurs when a self mailer 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.deleted Occurs when a letter is successfully canceled.
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.
letter.certified.mailed Occurs when a Certified letter receives a "Mailed" tracking event. Only created in the Live Environment.
letter.certified.in_transit Occurs when a Certified letter receives an "In Transit" tracking event. Only created in the Live Environment.
letter.certified.in_local_area Occurs when a Certified letter receives an "In Local Area" tracking event. Only created in the Live Environment.
letter.certified.processed_for_delivery Occurs when a Certified letter receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
letter.certified.re-routed Occurs when a Certified letter receives a "Re-Routed" tracking event. Only created in the Live Environment.
letter.certified.returned_to_sender Occurs when a Certified letter receives a "Returned to Sender" tracking event. Only created in the Live Environment.
letter.certified.delivered Occurs when a Certified letter receives a "Delivered" tracking event. Only created in the Live Environment.
letter.certified.pickup_available Occurs when a Certified letter receives a "Pickup Available" tracking event. Only created in the Live Environment.
letter.certified.issue Occurs when a Certified letter receives an "Issue" tracking event. Only created in the Live Environment.
letter.return_envelope.created Occurs when a return envelope is first created. This occurs simultaneously with Letter creation.
letter.return_envelope.in_transit Occurs when a return envelope receives an "In Transit" tracking event. Only created in the Live Environment.
letter.return_envelope.in_local_area Occurs when a return envelope receives an "In Local Area" tracking event. Only created in the Live Environment.
letter.return_envelope.processed_for_delivery Occurs when a return envelope receives a "Processed for Delivery" tracking event. Only created in the Live Environment.
letter.return_envelope.re_routed Occurs when a return envelope receives a "Re-Routed" tracking event. Only created in the Live Environment.
letter.return_envelope.returned_to_sender Occurs when a return envelope 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.deleted Occurs when a check is successfully canceled.
check.mailed Occurs when a check receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. Only created in the Live Environment.
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 not present.
R7 The address matched to a Phantom Carrier Route (carrier_route of R777), which corresponds to physical addresses that are not eligible for delivery.
RR The address matched to a CMRA and private mailbox information is present.

National Change Of Address (NCOA)

National Change of Address (NCOA) is a service offered by the USPS, which allows individuals or businesses who have recently moved to have any mail forwarded from their previous address to their new address.

As a CASS-certified Address Verification Provider, Lob also offers NCOA functionality to our Print & Mail customers. With the Lob NCOA feature enabled, Postcards, Letters, Checks and Addresses can automatically be corrected to reflect an individual's or business' new address in the case that they have moved (only if they have registered for NCOA with the USPS).

Due to privacy concerns and USPS constraints, for customers with NCOA enabled, our API responses for a limited set of endpoints differ slightly in the case when an address has been changed through NCOA.

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

For more information, see our NCOA guide.

NCOA Live Environment

Though there are no changes to API requests, there are significant changes to our API responses, but only in the event that an address has been changed through NCOA. If an address has not been changed through NCOA, the response would be identical to our standard responses, except the addition of a recipient_moved field, which is false for unchanged addresses.

If an address has been changed through NCOA, we are required to suppress the following response fields for that address:

  • address_line1
  • address_line2
  • The +4 portion of the ZIP+4 (5-digit ZIP code will still be present).

Example Response - Live Mode


{
  "id": "adr_e463565030210f87",
  "description": null,
  "name": "LARRY LOBSTER",
  "company": "LOB",
  "phone": null,
  "email": null,
  "address_line1": "████",
  "address_line2": "████",
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2019-12-05T19:39:19.932Z",
  "date_modified": "2019-12-05T19:39:19.932Z",
  "recipient_moved": true,
  "inline": false,
  "object": "address"
}

NCOA Test Environment

In addition to sending live requests, you may also want to simulate what an NCOA response might look like so that you can ensure your application behaves as expected. The behavior of NCOA in Lob's Test Environment is very similar to our US Verifications Test Mode.

To simulate an NCOA request, send a POST request to any of the four endpoints below with an address_line1 field equal to NCOA:

  • POST /v1/addresses
  • POST /v1/checks
  • POST /v1/letters
  • POST /v1/postcards
  • POST /v1/self_mailers

A static address will always be returned, as documented to the right.

Example Request


LobResponse<Address> response = new Address.RequestBuilder()
        .setName("Harry Zhang")
        .setLine1("NCOA")
        .setCity("Ann Arbor")
        .setState("MI")
        .setZip("48109")
        .setCountry("US")
        .create();

Address address = response.getResponseBody();

Example Response - Test Mode


{
  "id": "adr_e463565030210e12",
  "description": null,
  "name": "TEST KEYS DO NOT VERIFY ADDRESSES",
  "company": null,
  "phone": null,
  "email": null,
  "address_line1": "████",
  "address_line2": "████",
  "address_city": "SAN FRANCISCO",
  "address_state": "CA",
  "address_zip": "94107",
  "address_country": "UNITED STATES",
  "metadata": {},
  "date_created": "2019-12-05T19:39:19.932Z",
  "date_modified": "2019-12-05T19:39:19.932Z",
  "recipient_moved": true,
  "inline": false,
  "object": "address"
}