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.
https://api.lob.com/
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_.
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.
[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.
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.
Lob.init("test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc")
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.
Lob.init("yourApiKey", "2020-02-11")
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.
| message: | A human-readable message with more details about the error |
| status_code: | A conventional HTTP status code |
| 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 |
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 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) |
X-Rate-Limit-Limit:150
X-Rate-Limit-Remaining:100
X-Rate-Limit-Reset:1528749846
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.",
"status_code": 429
}
}
Lob supports idempotency for safely retrying POST requests to create postcards, letters, and checks without accidentally creating duplicates.
For example, if a request to create a check fails due to a network error, you can safely retry the same request with the same idempotency key and guarantee that only one check will ultimately be created and sent. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.
To perform an idempotent POST request to one of the three product endpoints, provide an additional Idempotency-Key header to the request. How you create unique keys is up to you, but we suggest using random values, such as V4 UUIDs. Idempotency keys are intended to prevent issues over a short periods of time, therefore keys expire after 24 hours. Keys are unique by mode (Test vs. Live) as well as by resource (postcard vs. letter vs. check).
By default, all GET and DELETE requests are idempotent by nature, so they do not require an additional idempotency key.
For more help integrating idempotency keys, refer to our implementation guide.
| Idempotency-Key: |
optional
A string of no longer than 256 characters that uniquely identifies this resource. |
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 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.
By default, all new accounts have a 5 minute cancellation window for postcards, letters, and checks. Within that timeframe, you can cancel mailings from production, free of charge. Once the window has passed for a postcard, letter, or check, the mailing is no longer cancelable. In addition, certain customers can customize their cancellation windows by product in their Dashboard Settings. Upgrade to the appropriate Print & Mail Edition to automatically gain access to this ability. For more details on this feature, check out our Cancellation Guide.
If you schedule a postcard, letter, or check for up to 180 days in the future by supplying the send_date parameter, that will override any cancellation window you may have for that product.
Postcards, letters, and checks can be scheduled to be sent up to 180 days in advance. You can use this feature to:
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.
DateTime futureDate = new DateTime(DateTime.parse("2020-09-30"))
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();
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.
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();
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();
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.
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
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
}
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--
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.
Please visit our Github for a list of our supported libraries.
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!
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.
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();
Use a pre-designed template from our gallery or follow these basic guidelines as starting points for creating custom Postcards, Letters, and Checks.
Please follow the standards used in these templates, such as:
-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.
Currently we support the following file types for all endpoints:
You can find pre-made templates that already adhere to all of these guidelines here:
The following guidelines apply to image types:
To ensure that you are producing PDF's correctly please follow the guidelines below:
To ensure that you are producing PNG's/JPEG's correctly please follow the guidelines below:
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 |
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.
| id: |
string
Unique identifier prefixed with |
| 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_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 |
| 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 |
{
"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"
}
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.
| description: |
optional
An internal description that identifies this resource. Must be no longer than 255 characters. |
| name: |
optional
Either |
| company: |
optional
Either |
| 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_state: |
optional
Required and must be a 2 letter state short-name code or a valid full state name if |
| address_zip: |
optional
Required and must follow the ZIP format of |
| address_country: |
optional
Must be a 2 letter country short-name code (ISO 3166). Defaults to |
| 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 |
Returns an address object upon successful creation.
POST https://api.lob.com/v1/addresses
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();
{
"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"
}
Retrieves the details of an existing address. You need only supply the unique customer identifier that was returned upon address creation.
| id: |
required
The identifier of the address to be retrieved. |
Returns an address object if a valid identifier was provided.
GET https://api.lob.com/v1/addresses/{id}
LobResponse<Address> response = Address.retrieve("adr_fa85158b26c3eb7c");
Address address = response.getResponseBody();
{
"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"
}
Permanently deletes a customer. It cannot be undone.
| id: |
required
The identifier of the address to be deleted. |
Returns a message that the deletion was successful.
DELETE https://api.lob.com/v1/addresses/{id}
LobResponse<Address> response = Address.delete("adr_43769b47aed248c2");
Address address = response.getResponseBody();
{
"id": "adr_43769b47aed248c2",
"deleted": true
}
Returns a list of your addresses. The addresses are returned sorted by creation date, with the most recently created addresses appearing first.
| limit: |
optional
An integer that designates how many results to return. Defaults to
|
| after: |
optional
A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the |
| before: |
optional
A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the |
| include: |
optional
Request that the response include the total count by specifying
|
| metadata: |
optional
Filter by metadata key-value pair, e.g. |
| date_created: |
optional
Filter by ISO-8601 date or datetime, e.g. |
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.
GET https://api.lob.com/v1/addresses
Map<String, Object> params = new HashMap<>();
params.put("limit", 2);
LobResponse<AddressCollection> response = Address.list(params);
AddressCollection addresses = response.getResponseBody();
{
"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
}
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.
| id: |
string
Unique identifier prefixed with |
||||||||||||||||||||||||||
| 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
|
||||||||||||||||||||||||||
| secondary_line: |
string
The secondary delivery line of the address. This field is typically empty but may contain information if |
||||||||||||||||||||||||||
| 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
|
||||||||||||||||||||||||||
| deliverability: |
string
Summarizes the deliverability of the
|
||||||||||||||||||||||||||
| components: |
object
A nested object containing a breakdown of each component of an address.
|
||||||||||||||||||||||||||
| deliverability_analysis: |
object
A nested object containing a breakdown of the deliverability of an address.
|
||||||||||||||||||||||||||
| object: |
string
Value is |
{
"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": ""
},
"object": "us_verification"
}
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.
| case: |
optional
Casing of the verified address. Possible values are |
| 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
|
| state: |
optional
|
| zip_code: |
optional
Required if no |
| 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. |
A US verification object with detailed information about the corrected address.
POST https://api.lob.com/v1/us_verifications
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();
{
"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": ""
},
"object": "us_verification"
}
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).
LobResponse<USVerification> response = new USVerification.RequestBuilder()
.setRecipient("Donald")
.setPrimaryLine("po box")
.setZipCode("11111")
.verify();
USVerification usVerification = response.getResponseBody();
{
"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"
}
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:
Additionally, the suggested addresses are not guaranteed to be deliverable, each suggested address needs to be verified.
| id: |
string
Unique identifier prefixed with |
||||
| suggestions: |
array
An array of objects representing suggested addresses. The suggested address object is as follows:
|
||||
| object: |
string
Value is |
{
"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"
}
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.
| 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 |
A US autocompletion object with up to ten suggested addresses.
POST https://api.lob.com/v1/us_autocompletions
LobResponse<USAutocompletion> response = new USAutocompletion.RequestBuilder()
.setAddressPrefix("185 B")
.setCity("San Francisco")
.setState("CA")
.setZipCode("94107")
.autocomplete();
USAutocompletion usAutocompletion = response.getResponseBody();
{
"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"
}
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.
LobResponse<USAutocompletion> response = new USAutocompletion.RequestBuilder()
.setAddressPrefix("1 sugg")
.autocomplete();
USAutocompletion usAutocompletion = response.getResponseBody();
{
"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"
}
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.
| id: |
string
Unique identifier prefixed with |
|||||
| 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 |
|||||
| cities: |
array
An array of city objects containing valid cities for the
|
|||||
| object: |
string
Value is |
{
"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. 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.
| zip_code: |
required
Must be a valid 5-digit US ZIP code. |
A US ZIP Lookup object with detailed information about the input ZIP code.
POST https://api.lob.com/v1/us_zip_lookups
LobResponse<USZipLookup> response = new USZipLookup.RequestBuilder()
.setZipCode("94107")
.lookup();
USZipLookup usZipLookup = response.getResponseBody();
{
"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"
}
Address verification for international (non-US) addresses.
| id: |
string
Unique identifier prefixed with |
|||||
| 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 |
|||||
| last_line: |
string
Combination of the following applicable
|
|||||
| country: |
string
The country of the address. Will be returned as a 2 letter country short-name code (ISO 3166). |
|||||
| deliverability: |
string
Summarizes the deliverability of the
|
|||||
| components: |
object
A nested object containing a breakdown of each component of an address.
|
|||||
| object: |
string
Value is |
{
"id": "intl_ver_c7cb63d68f8d6",
"recipient": null,
"primary_line": "370 WATER ST",
"secondary_line": "",
"last_line": "SUMMERSIDE PE C1N 1C4",
"country": "CA",
"deliverability": "deliverable",
"components": {
"primary_number": "370",
"street_name": "WATER ST",
"city": "SUMMERSIDE",
"state": "PE",
"postal_code": "C1N 1C4"
},
"object": "intl_verification"
}
Verify an international (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.
| 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 |
Returns the validated address object, along with its deliverability status.
POST https://api.lob.com/v1/intl_verifications
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();
{
"id": "intl_ver_c7cb63d68f8d6",
"recipient": null,
"primary_line": "370 WATER ST",
"secondary_line": "",
"last_line": "SUMMERSIDE PE C1N 1C4",
"country": "CA",
"deliverability": "deliverable",
"components": {
"primary_number": "370",
"street_name": "WATER ST",
"city": "SUMMERSIDE",
"state": "PE",
"postal_code": "C1N 1C4"
},
"object": "intl_verification"
}
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).
LobResponse<IntlVerification> response = new IntlVerification.RequestBuilder()
.setPrimaryLine("deliverable")
.setCountry("CA")
.verify();
IntlVerification intlVerification = response.getResponseBody();
{
"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",
"deliverability": "deliverable",
"components": {
"primary_number": "370",
"street_name": "WATER ST",
"city": "SUMMERSIDE",
"state": "PE",
"postal_code": "C1N 1C4"
},
"object": "intl_verification"
}
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.
| id: |
string
Unique identifier prefixed with |
| 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 |
| tracking_events: |
array
An array of tracking_event objects ordered by ascending |
| thumbnails: |
array
Signed links to different sized thumbnails of each postcard page. |
| merge_variables: | object or null |
| size: |
string
Value is |
| mail_type: |
string
Value is |
| expected_delivery_date: |
string
A date in ISO 8601 format of the postcard's expected delivery date based on its |
| 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 |
| deleted: |
boolean
Only returned if the postcard has been successfully canceled. |
| object: |
string
Value is |
{
"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 new postcard.
| 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 |
| 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
|
| 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: |
optional
Specifies the size of the postcard. Must be either |
| mail_type: |
optional
A string designating the mail postage type. Options are |
| 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: |
| 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 |
Returns a postcard object upon successful creation.
POST https://api.lob.com/v1/postcards
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();
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();
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();
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();
{
"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"
}
Retrieves the postcard with a given ID. You need only supply the unique postcard ID that was returned upon postcard creation.
| id: |
required
The identifier of the postcard to be retrieved. |
Returns a postcard object if a valid identifier was provided.
GET https://api.lob.com/v1/postcards/{id}
LobResponse<Postcard> response = Postcard.retrieve("psc_5c002b86ce47537a");
Postcard postcard = response.getResponseBody();
{
"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"
}
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.
| id: |
required
The identifier of the postcard to be canceled. |
Returns a message that the cancellation was successful.
DELETE https://api.lob.com/v1/postcards/{id}
LobResponse<Postcard> deleteResponse = Postcard.delete("psc_5c002b86ce47537a");
{
"id": "psc_5c002b86ce47537a",
"deleted": true
}
Returns a list of postcards. The returned postcards are sorted by creation date, with the most recently created postcards appearing first.
| limit: |
optional
An integer that designates how many results to return. Defaults to
|
| after: |
optional
A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the |
| before: |
optional
A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the |
| include: |
optional
Request that the response include the total count by specifying |
| metadata: |
optional
Filter by metadata key-value pair, e.g. |
| date_created: |
optional
Filter by ISO-8601 date or datetime, e.g. |
| size: |
optional
The postcard sizes to be returned. Must be a non-empty string array of valid sizes.
Acceptable values are |
| scheduled: |
optional
Set |
| send_date: |
optional
Filter by ISO-8601 date or datetime, e.g. |
| mail_type: | optional |
| sort_by: |
optional
Sorts postcards in a desired order. |
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.
GET https://api.lob.com/v1/postcards
Map<String, Object> params = new HashMap<>>();
params.put("limit", 2);
LobResponse<PostcardCollection> response = Postcard.list(params);
PostcardCollection postcards = response.getResponseBody();
{
"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
}
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.
| id: |
string
Unique identifier prefixed with |
|||
| description: | string or null | |||
| metadata: | object | |||
| to: | an address object | |||
| from: | an address object | |||
| color: | boolean | |||
| double_sided: | boolean | |||
| address_placement: |
string
Value is |
|||
| return_envelope: | boolean | |||
| perforated_page: |
integer or null
Value will be the final page to be perforated, including modifications made by |
|||
| 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.
|
|||
| extra_service: |
string or null
Value is |
|||
| mail_type: |
string
Value is |
|||
| 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 |
|||
| tracking_number: |
string or null
If the letter is being sent as |
|||
| tracking_events: |
array
An array of tracking_event objects ordered by ascending |
|||
| 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 |
|||
| 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 |
|||
| deleted: |
boolean
Only returned if the letter has been successfully canceled. |
|||
| object: |
string
Value is |
{
"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 new letter.
| 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 |
| 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 |
| color: |
required
Set this key to |
| 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 |
| double_sided: |
optional
Boolean that defaults to |
| address_placement: |
optional
Specifies the location of the address information that will show through the double-window envelope.
Options are |
| mail_type: |
optional
A string designating the mail postage type. Options are
|
| extra_service: |
optional
Add an extra service to your letter. Options are |
| return_envelope: |
optional
Boolean that defaults to |
| bleed: | optional |
| perforated_page: |
optional
Required if |
| 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: |
| 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 |
Returns a letter object upon successful creation.
POST https://api.lob.com/v1/letters
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();
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();
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();
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();
{
"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"
}
Retrieves the letter with a given ID. You need only supply the unique letter ID that was returned upon letter creation.
| id: |
required
The identifier of the letter to be retrieved. |
Returns a letter object if a valid identifier was provided.
GET https://api.lob.com/v1/letters/{id}
LobResponse<Letter> response = Letter.retrieve("ltr_4868c3b754655f90");
Letter letter = response.getResponseBody();
{
"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"
}
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.
| id: |
required
The identifier of the letter to be canceled. |
Returns a message that the cancellation was successful.
DELETE https://api.lob.com/v1/letters/{id}
LobResponse<Letter> response = Letter.delete("ltr_4868c3b754655f90");
Letter letter= = response.getResponseBody();
{
"id": "ltr_4868c3b754655f90",
"deleted": true
}
Returns a list of letters. The letters are returned sorted by creation date, with the most recently created letters appearing first.
| limit: |
optional
An integer that designates how many results to return. Defaults to
|
| after: |
optional
A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the |
| before: |
optional
A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the |
| include: |
optional
Request that the response include the total count by specifying |
| metadata: |
optional
Filter by metadata key-value pair, e.g. |
| date_created: |
optional
Filter by ISO-8601 date or datetime, e.g. |
| scheduled: |
optional
Set |
| send_date: |
optional
Filter by ISO-8601 date or datetime, e.g. |
| mail_type: | optional |
| color: |
optional
A boolean that represents which letters to return. Set to |
| sort_by: |
optional
Sorts letters in a desired order. |
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.
GET https://api.lob.com/v1/letters
Map<String, Object> params = new HashMap<>>();
params.put("limit", 2);
LobResponse<LetterCollection> response = Letter.list(params);
LetterCollection letters = response.getResponseBody();
{
"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 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.
| id: |
string
Unique identifier prefixed with |
| 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 |
| tracking_events: |
array
An array of tracking_event objects ordered by ascending |
| 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 |
| mail_type: |
string
Value is |
| 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 |
| deleted: |
boolean
Only returned if the check has been successfully canceled. |
| object: |
string
Value is |
{
"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 new check.
| 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 ( |
| 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 ( |
| 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 |
| 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 |
| check_bottom: |
optional
Either |
| 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. |
| 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: |
| mail_type: |
optional
A string designating the mail postage type.
Defaults to |
| 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 |
| 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 |
Returns a check object upon successful creation.
POST https://api.lob.com/v1/checks
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();
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();
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();
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();
{
"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"
}
Retrieves the check with a given ID. You need only supply the unique ID that was returned upon check creation.
| id: |
required
The identifier of the check to be retrieved. |
Returns a check object if a valid identifier was provided.
GET https://api.lob.com/v1/checks/{id}
LobResponse<Check> response = Check.retrieve("chk_534f10783683daa0");
Check check = response.getResponseBody();
{
"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"
}
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.
| id: |
required
The identifier of the check to be canceled. |
Returns a message that the cancellation was successful.
DELETE https://api.lob.com/v1/checks/{id}
LobResponse<Check> response = Check.delete("chk_534f10783683daa0");
Check check = response.getResponseBody();
{
"id": "chk_534f10783683daa0",
"deleted": true
}
Returns a list of checks. The returned checks are sorted by creation date, with the most recently created checks appearing first.
| limit: |
optional
An integer that designates how many results to return. Defaults to
|
| after: |
optional
A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the |
| before: |
optional
A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the |
| include: |
optional
Request that the response include the total count by specifying |
| metadata: |
optional
Filter by metadata key-value pair, e.g. |
| mail_type: | optional |
| scheduled: |
optional
Set |
| date_created: |
optional
Filter by ISO-8601 date or datetime, e.g. |
| send_date: |
optional
Filter by ISO-8601 date or datetime, e.g. |
| sort_by: |
optional
Sorts checks in a desired order. |
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.
GET https://api.lob.com/v1/checks
Map<String, Object> params = new HashMap<>();
params.put("limit", 2);
LobResponse<CheckCollection> response = Check.list(params);
CheckCollection checks = response.getResponseBody();
{
"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
}
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.
| id: |
string
Unique identifier prefixed with |
| description: | string or null |
| metadata: | object |
| routing_number: | string |
| account_number: | string |
| account_type: |
string
Value is |
| 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. |
| 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 |
{
"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 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".
| 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 |
| 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 |
Returns a bank object upon successful creation.
POST https://api.lob.com/v1/bank_accounts
LobResponse<BankAccount> response = new BankAccount.RequestBuilder()
.setDescription("Test Bank Account")
.setRoutingNumber("322271627")
.setAccountNumber("123456789")
.setSignatory("John Doe")
.setAccountType("company")
.create();
BankAccount bankAccount = response.getResponseBody();
{
"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"
}
Retrieves the bank account with a given ID. You need only supply the unique ID that was returned upon bank account creation.
| id: |
required
The identifier of the bank account to be retrieved. |
Returns a bank account object if a valid identifier was provided.
GET https://api.lob.com/v1/bank_accounts/{id}
LobResponse<BankAccount> response = BankAccount.retrieve("bank_8cad8df5354d33f");
BankAccount bankAccount = response.getResponseBody();
{
"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"
}
Permanently deletes a bank account. It cannot be undone.
| id: |
required
The identifier of the bank account to be deleted. |
Returns a message that the deletion was successful.
DELETE https://api.lob.com/v1/bank_accounts/{id}
LobResponse<BankAccount> response = BankAccount.delete("bank_3e64d9904356b20");
BankAccount bankAccount = response.getResponseBody();
{
"id": "bank_3e64d9904356b20",
"deleted": true
}
Verify a bank account in order to create a check.
| id: |
required
The identifier of the bank account to be verified. |
| 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 |
Returns a bank account object upon successful verification.
POST https://api.lob.com/v1/bank_accounts/{id}/verify
LobResponse<BankAccount> response = BankAccount.verify(newBankAccount.getId(), Arrays.asList(25, 63));
BankAccount bankAccount = response.getResponseBody();
{
"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"
}
Returns a list of bank accounts. The bank accounts are returned sorted by creation date, with the most recently created bank account appearing first.
| limit: |
optional
An integer that designates how many results to return. Defaults to
|
| after: |
optional
A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the |
| before: |
optional
A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the |
| include: |
optional
Request that the response include the total count by specifying
|
| metadata: |
optional
Filter by metadata key-value pair, e.g. |
| date_created: |
optional
Filter by ISO-8601 date or datetime, e.g. |
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.
GET https://api.lob.com/v1/bank_accounts
Map<String, Object> params = new HashMap<>();
params.put("limit", 2);
LobResponse<BankAccountCollection> response = BankAccount.list(params);
BankAccountCollection bankAccounts = response.getResponseBody();
{
"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
}
These API endpoints allow you to create, retrieve, update and delete reusable HTML templates for use with the print & mail API.
| id: |
string
Unique identifier prefixed with |
| 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 |
{
"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"
}
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.
| 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 |
| 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 |
Returns a template object upon successful creation.
POST https://api.lob.com/v1/templates
This feature is not currently supported by this library.
{
"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"
}
Retrieves the template with a given ID. You need only supply the unique template ID that was returned upon template creation.
| id: |
required
The identifier of the template to be retrieved. |
Returns a template object if a valid identifier was provided.
GET https://api.lob.com/v1/templates/{id}
This feature is not currently supported by this library.
{
"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"
}
Updates the template with a given ID.
| id: |
required
The identifier of the template to update. |
| 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 |
Returns the updated template object if a valid identifier was provided.
POST https://api.lob.com/v1/templates/{id}
This feature is not currently supported by this library.
{
"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"
}
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.
| id: |
required
The identifier of the template to be deleted. |
Returns a message that the deletion was successful.
DELETE https://api.lob.com/v1/templates/{id}
This feature is not currently supported by this library.
{
"id": "tmpl_df934eeda694203",
"deleted": true
}
Returns a list of templates. The returned templates are sorted by creation date, with the most recently created templates appearing first.
| limit: |
optional
An integer that designates how many results to return. Defaults to
|
| after: |
optional
A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the |
| before: |
optional
A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the |
| include: |
optional
Request that the response include the total count by specifying |
| metadata: |
optional
Filter by metadata key-value pair, e.g. |
| date_created: |
optional
Filter by ISO-8601 date or datetime, e.g. |
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.
GET https://api.lob.com/v1/templates
This feature is not currently supported by this library.
{
"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
}
These API endpoints allow you to create, retrieve, update and delete versions of reusable HTML templates for use with the print & mail API.
| id: |
string
Unique identifier prefixed with |
| 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 |
{
"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 new version attached to the specified template.
| id: |
required
The identifier of the template the new version will be attached to. |
| 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 |
Returns a version object upon successful creation.
POST https://api.lob.com/v1/templates/{id}/versions
This feature is not currently supported by this library.
{
"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"
}
Retrieves the version with the given template ID and version ID.
| template_id: |
required
The identifier of the template the version belongs to. |
| version_id: |
required
The identifier of the version to be retrieved. |
Returns a version object if valid identifiers were provided.
GET https://api.lob.com/v1/templates/{template_id}/versions/{version_id}
This feature is not currently supported by this library.
{
"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"
}
Updates the version with the given template ID and version ID.
| template_id: |
required
The identifier of the template the version belongs to. |
| version_id: |
required
The identifier of the version to be retrieved. |
| description: |
optional
An internal description that identifies this resource. Must be no longer than 255 characters. |
Returns the updated version object if valid identifiers were provided.
POST https://api.lob.com/v1/templates/{template_id}/versions/{version_id}
This feature is not currently supported by this library.
{
"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"
}
Permanently deletes a version. A template's published_version can not be deleted.
| template_id: |
required
The identifier of the template the version belongs to. |
| version_id: |
required
The identifier of the version to be retrieved. |
Returns a confirmation upon successful deletion.
DELETE https://api.lob.com/v1/templates/{template_id}/versions/{version_id}
This feature is not currently supported by this library.
{
"id": "vrsn_534e339882d2282",
"deleted": true
}
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.
| limit: |
optional
An integer that designates how many results to return. Defaults to
|
| after: |
optional
A reference to a list entry used for paginating to the previous set of entries. This field is pre-populated in the |
| before: |
optional
A reference to a list entry used for paginating to the next set of entries. This field is pre-populated in the |
| include: |
optional
Request that the response include the total count by specifying |
| date_created: |
optional
Filter by ISO-8601 date or datetime, e.g. |
| id: |
required
The identifier of the template associated with the retrieved versions. |
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.
GET https://api.lob.com/v1/templates/{id}/versions
This feature is not currently supported by this library.
{
"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
}
As mail pieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events.
| id: |
string
Unique identifier prefixed with |
||||
| type: |
string
|
||||
| name: |
string
A descriptive name about the tracking event.
|
||||
| details: | object or null
Will be
|
||||
| location: |
string or null
A string describing the location of the event.
|
||||
| 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 |
{
"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"
}
{
"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"
}
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.
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 |
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.
| id: |
string
Unique identifier prefixed with |
| 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 |
| 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 |
{
"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"
}
| id: |
string
Unique identifier, full list of possible values can be found here. |
| enabled_for_test: |
boolean
Value is |
| resource: |
string
Value is |
| object: |
string
Value is |
{
"id": "postcard.created",
"enabled_for_test": true,
"resource": "postcards",
"object": "event_type"
}
These are all the event types Lob currently creates and are available for subscription.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
These are detailed definitions for various fields in the US verification object.
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. |
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. |
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. |
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) 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.
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_line1address_line2
{
"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"
}
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/addressesPOST /v1/checksPOST /v1/lettersPOST /v1/postcardsA static address will always be returned, as documented to the right.
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();
{
"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"
}