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.
Lob’s Print & Mail and Address Verification APIs help companies transform outdated, manual print-and-mail processes; save 1,000s of hours in processing time by sending mail much more quickly; and increase ROI on offline communications.
Automate direct mail by triggering on-demand postcards, letters, and checks directly from your CRM or customer data systems.
Address Verification corrects, standardizes, and cleanses address data for assured delivery with instant verification across 240+ countries and territories.
Lob's print delivery network eliminates the hassle of vendor management with automated production and postage across a global network of vetted commercial printers.
Tracking & Analytics gives you complete visibility of production and delivery for each piece of mail you send to meet compliance requirements and measure campaign performance.
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.
curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password). One of our test API keys has been filled into all the examples on the page, so you can test out any example right away.
curl https://api.lob.com/v1/addresses \
-u test_0dc8dXXXXXXXXXXXXXXXXXXXXXX5b0cc:
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.
test_*.
for your Test API key and live_*.
for your Live API key.curl https://api.lob.com/v1/addresses \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
Try our quick start (TypeScript, Python, PHP, Java or Ruby):
Use Case guides
Please visit our Github for a list of our supported libraries.
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.
Returns a list of your addresses. The addresses are returned sorted by creation date, with the most recently created addresses appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) list of addresses |
curl -X GET "https://api.lob.com/v1/addresses?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "adr_e68217bd744d65c8",
- "description": "Harry - Office",
- "name": "HARRY ZHANG",
- "company": "LOB",
- "phone": "5555555555",
- "email": "harry@lob.com",
- "address_line1": "210 KING 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_asdi2y3riuasasoi",
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "phone": "5555555555",
- "email": "harry@lob.com",
- "metadata": { },
- "address_line1": "370 WATER ST",
- "address_line2": "",
- "address_city": "SUMMERSIDE",
- "address_state": "PRINCE EDWARD ISLAND",
- "address_zip": "C1N 1C4",
- "address_country": "CANADA",
- "date_created": "2019-09-20T00:14:00.361Z",
- "date_modified": "2019-09-20T00:14:00.361Z",
- "object": "address"
}
], - "object": "list",
- "previous_url": null,
- "count": 2
}
Creates a new address given information
name required | string or null <= 40 characters Either |
address_line1 required | string <= 64 characters The primary number, street name, and directional information. |
address_city required | string <= 200 characters |
address_state required | string^[a-zA-Z]{2}$ 2 letter state short-name code |
address_zip required | string^\d{5}(-\d{4})?$ Must follow the ZIP format of |
address_line2 | string or null <= 64 characters An optional field containing any information which can't fit into line 1. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
company | string or null (company) <= 40 characters Either |
phone | string or null <= 40 characters Must be no longer than 40 characters. |
string or null <= 100 characters Must be no longer than 100 characters. | |
address_country | string Default: "US" Value: "US" |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
name required | string or null <= 40 characters Either |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "address" Value: "address" Value is resource type. |
id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
address_line1 required | string <= 64 characters The primary number, street name, and directional information. |
address_city required | string <= 200 characters |
address_state required | string^[a-zA-Z]{2}$ 2 letter state short-name code |
address_zip required | string^\d{5}(-\d{4})?$ Must follow the ZIP format of |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
company | string or null <= 40 characters Either |
phone | string or null <= 40 characters Must be no longer than 40 characters. |
string or null <= 100 characters Must be no longer than 100 characters. | |
address_line2 | string or null <= 64 characters An optional field containing any information which can't fit into line 1. |
address_country | string = 13 characters Value: "UNITED STATES" Full name of country |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
recipient_moved | boolean or null Only returned for accounts on certain Print & Mail Editions. Value is |
{- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107",
- "address_country": "US"
}
{- "id": "adr_d3489cd64c791ab5",
- "description": "Harry - Office",
- "name": "HARRY ZHANG",
- "company": "LOB",
- "phone": "5555555555",
- "email": "harry@lob.com",
- "address_line1": "210 KING ST STE 6100",
- "address_city": "SAN FRANCISCO",
- "address_state": "CA",
- "address_zip": "94107",
- "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 identifier that was returned upon address creation.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ id of the address |
name required | string or null <= 40 characters Either |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "address" Value: "address" Value is resource type. |
id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
address_line1 required | string <= 64 characters The primary number, street name, and directional information. |
address_city required | string <= 200 characters |
address_state required | string^[a-zA-Z]{2}$ 2 letter state short-name code |
address_zip required | string^\d{5}(-\d{4})?$ Must follow the ZIP format of |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
company | string or null <= 40 characters Either |
phone | string or null <= 40 characters Must be no longer than 40 characters. |
string or null <= 100 characters Must be no longer than 100 characters. | |
address_line2 | string or null <= 64 characters An optional field containing any information which can't fit into line 1. |
address_country | string = 13 characters Value: "UNITED STATES" Full name of country |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
recipient_moved | boolean or null Only returned for accounts on certain Print & Mail Editions. Value is |
curl https://api.lob.com/v1/addresses/adr_fa85158b26c3eb7c \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "adr_e68217bd744d65c8",
- "description": "Harry - Office",
- "name": "HARRY ZHANG",
- "company": "LOB",
- "phone": "5555555555",
- "email": "harry@lob.com",
- "address_line1": "210 KING ST STE 6100",
- "address_line2": null,
- "address_city": "SAN FRANCISCO",
- "address_state": "CA",
- "address_zip": "94107-1741",
- "address_country": "UNITED STATES",
- "metadata": { },
- "recipient_moved": false,
- "date_created": "2019-08-12T00:16:00.361Z",
- "date_modified": "2019-08-12T00:16:00.361Z",
- "object": "address"
}
Deletes the details of an existing address. You need only supply the unique identifier that was returned upon address creation.
adr_id required | string (adr_id) ^adr_[a-zA-Z0-9]+$ id of the address |
id | string (adr_id) ^adr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/addresses/adr_43769b47aed248c2 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "adr_123456789",
- "deleted": true
}
National Change of Address Linkage (NCOALink) 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 NCOALink functionality to our Print & Mail customers. With the Lob NCOALink feature enabled, Postcards, Letters, Checks and Addresses can automatically be corrected to reflect an individual's or business's new address in the case that they have moved (only if they have registered for NCOALink with the USPS).
Due to privacy concerns and USPS constraints, for customers with NCOALink enabled, our API responses for a limited set of endpoints differ slightly in the case when an address has been changed through NCOALink.
NOTE: This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Editions to gain access.
For more information, see our NCOALink 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 NCOALink. If an address has not been changed
through NCOALink, 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 NCOALink, we are required to suppress the following response fields for that address:
address_line1
address_line2
See the ncoa_us_live
example under Response samples within the "Create an Address" section in Addresses
In addition to sending live requests, you may also want to simulate what an NCOALink response might look like so that you can ensure your application behaves as expected. The behavior of NCOALink in Lob's Test Environment is very similar to our US Verifications Test Mode.
To simulate an NCOALink request, send a POST request to any of the four endpoints below with an address_line1
field equal to NCOA
:
POST /v1/addresses
POST /v1/checks
POST /v1/letters
POST /v1/postcards
POST /v1/self_mailers
A static address will always be returned, as documented in the ncoa_us_test
example under Response samples within the "Create an Address"
section in Addresses (along with the corresponding request under "Request samples").
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.
Retrieves the details of an existing postcard. You need only supply the unique customer identifier that was returned upon postcard creation.
psc_id required | string (psc_id) ^psc_[a-zA-Z0-9]+$ id of the postcard |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (psc_id) ^psc_[a-zA-Z0-9]+$ Unique identifier prefixed with |
front_template_id required | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
back_template_id required | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (postcard_size) Default: "4x6" Enum: "4x6" "6x9" "6x11" Specifies the size of the postcard. Only |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
front_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
back_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
Array of objects or null (tracking_event_normal) An array of tracking_event objects ordered by ascending | |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
use_type | string or null (psc_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "postcard" Value: "postcard" Value is resource type. |
curl https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "psc_208e45e48d271294",
- "description": null,
- "metadata": { },
- "to": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": null,
- "company": "LOB",
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "carrier": "USPS",
- "front_template_id": null,
- "back_template_id": null,
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "postcard"
}
Completely removes a postcard from production. This can only be done if the postcard has a send_date
and the send_date
has not yet passed. If the postcard is successfully canceled, you will not be charged for it. Read more on cancellation windows and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition to gain access.
psc_id required | string (psc_id) ^psc_[a-zA-Z0-9]+$ id of the postcard |
id | string (psc_id) ^psc_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/postcards/psc_5c002b86ce47537a \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "psc_123456789",
- "deleted": true
}
Returns a list of your postcards. The addresses are returned sorted by creation date, with the most recently created addresses appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. | |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Filters resources created by the provided campaign id, prefixed with |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the render status:
|
size | Array of strings (postcard_size) Items Enum: "4x6" "6x9" "6x11" Specifies the size of the postcard. Only |
scheduled | boolean
|
string or string (send_date) Filter by ISO-8601 date or datetime, e.g. | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type: * |
object or object Sorts items by ascending or descending dates. Use either |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (postcard) list of postcards |
curl -X GET "https://api.lob.com/v1/postcards?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "psc_208e45e48d271294",
- "description": null,
- "metadata": { },
- "to": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": "LEORE AVIDAR",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "carrier": "USPS",
- "front_template_id": null,
- "back_template_id": null,
- "front_template_version_id": null,
- "back_template_version_id": null,
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "postcard"
}, - {
- "id": "psc_0e03d1ad7d31f151",
- "description": null,
- "metadata": { },
- "to": {
- "id": "adr_c7cb63d68f8d6",
- "description": null,
- "name": "JANE DOE",
- "company": "LOB",
- "phone": "5555555555",
- "email": "jane.doe@lob.com",
- "address_line1": "370 WATER ST",
- "address_line2": "",
- "address_city": "SUMMERSIDE",
- "address_state": "PE",
- "address_zip": "C1N 1C4",
- "address_country": "CANADA",
- "metadata": { },
- "date_created": "2018-12-08T03:01:07.651Z",
- "date_modified": "2018-12-08T03:01:07.651Z",
- "object": "address",
- "recipient_moved": false
}, - "from": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": "LEORE AVIDAR",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "carrier": "USPS",
- "front_template_id": null,
- "back_template_id": null,
- "front_template_version_id": null,
- "back_template_version_id": null,
- "tracking_events": [ ],
- "size": "6x11",
- "mail_type": "usps_first_class",
- "merge_variables": { },
- "thumbnails": [
- {
}
], - "expected_delivery_date": "2021-03-30",
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "postcard"
}
], - "object": "list",
- "previous_url": null,
- "next_url": null,
- "count": 2
}
Creates a new postcard given information
idempotency_key | string <= 256 characters Example: idempotency_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
Idempotency-Key | string <= 256 characters Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
required | adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) 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 through National Change of Address Linkage(NCOALink). 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. Lob Guide: Verification of Mailing Addresses |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) (psc_front) The artwork to use as the front of your postcard. Notes:
See here for HTML examples. |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) (psc_back) The artwork to use as the back of your postcard. Notes:
See here for HTML examples. |
use_type required | string or null (psc_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (postcard_size) Default: "4x6" Enum: "4x6" "6x9" "6x11" Specifies the size of the postcard. Only |
adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) Required if | |
billing_group_id | string (billing_group_id) An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See Billing Group API for more information. |
object (qr_code) Customize and place a QR code on the creative at the required position. | |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (psc_id) ^psc_[a-zA-Z0-9]+$ Unique identifier prefixed with |
front_template_id required | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
back_template_id required | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (postcard_size) Default: "4x6" Enum: "4x6" "6x9" "6x11" Specifies the size of the postcard. Only |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
front_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID. |
back_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID. |
Array of objects or null (tracking_event_normal) An array of tracking_event objects ordered by ascending | |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
use_type | string or null (psc_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "postcard" Value: "postcard" Value is resource type. |
{- "description": "demo",
- "to": {
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107",
- "address_country": "US"
}, - "from": {
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107",
- "address_country": "US"
}, - "front": "tmpl_a1234dddg",
- "back": "tmpl_a1234dddg",
- "size": "6x9",
- "mail_type": "usps_first_class",
- "merge_variables": {
- "name": "Harry"
}, - "metadata": {
- "spiffy": "true"
}, - "send_date": "2017-11-01T00:00:00.000Z",
- "use_type": "marketing",
- "qr_code": {
- "position": "relative",
- "width": "2.5",
- "top": "2.5",
- "right": "2.5",
- "pages": "front,back"
}, - "fsc": true
}
{- "id": "psc_208e45e48d271294",
- "description": null,
- "metadata": { },
- "to": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": null,
- "company": "LOB",
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "carrier": "USPS",
- "front_template_id": null,
- "back_template_id": null,
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "postcard"
}
The self mailer endpoint allows you to easily print and mail self mailers. The API provides endpoints for creating self mailers, retrieving individual self mailers, canceling self mailers, and retrieving a list of self mailers.
Retrieves the details of an existing self_mailer. You need only supply the unique self_mailer identifier that was returned upon self_mailer creation.
sfm_id required | string (sfm_id) ^sfm_[a-zA-Z0-9]+$ id of the self_mailer |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (sfm_id) ^sfm_[a-zA-Z0-9]+$ Unique identifier prefixed with |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
use_type required | string or null (sfm_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (self_mailer_size) Default: "6x18_bifold" Enum: "6x18_bifold" "11x9_bifold" "12x9_bifold" "17.75x9_trifold" Specifies the size of the self mailer. The |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
outside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the outside of the self mailer. |
inside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the inside of the self mailer. |
outside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the outside of the self mailer. |
inside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the inside of the self mailer. |
object | string Default: "self_mailer" Value: "self_mailer" Value is resource type. |
Array of objects (tracking_event_certified) An array of certified tracking events ordered by ascending | |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
object or null An object describing the reason for failure if the resource failed to render. |
curl -X GET "https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "sfm_8ffbe811dea49dcf",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "6x18_bifold",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "self_mailer"
}
Completely removes a self mailer from production. This can only be done if the self mailer's send_date
has not yet passed. If the self mailer is successfully canceled, you will not be charged for it. This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.
sfm_id required | string (sfm_id) ^sfm_[a-zA-Z0-9]+$ id of the self_mailer |
id | string (sfm_id) ^sfm_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/self_mailers/sfm_8ffbe811dea49dcf \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "sfm_123456789",
- "deleted": true
}
Returns a list of your self_mailers. The self_mailers are returned sorted by creation date, with the most recently created self_mailers appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. | |
size | Array of strings (self_mailer_size) Items Enum: "6x18_bifold" "11x9_bifold" "12x9_bifold" "17.75x9_trifold" The self mailer sizes to be returned. |
scheduled | boolean
|
string or string (send_date) Filter by ISO-8601 date or datetime, e.g. | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type: * |
object or object Sorts items by ascending or descending dates. Use either | |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Filters resources created by the provided campaign id, prefixed with |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the render status:
|
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (self_mailer) list of self_mailers |
curl -X GET "https://api.lob.com/v1/self_mailers?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "sfm_7239rhwqkrfaskas",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_asdi2y3riuasasoi",
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "phone": "5555555555",
- "email": "harry@lob.com",
- "metadata": { },
- "address_line1": "370 WATER ST",
- "address_line2": "",
- "address_city": "SUMMERSIDE",
- "address_state": "PRINCE EDWARD ISLAND",
- "address_zip": "C1N 1C4",
- "address_country": "CANADA",
- "recipient_moved": false,
- "date_created": "2019-09-20T00:14:00.361Z",
- "date_modified": "2019-09-20T00:14:00.361Z",
- "object": "address"
}, - "from": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": null,
- "company": "LOB",
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "6x18_bifold",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:41:06.691Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "deleted": true,
- "use_type": "marketing",
- "fsc": false,
- "object": "self_mailer"
}, - {
- "id": "sfm_8ffbe811dea49dcf",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_f9228b743884ff98",
- "description": null,
- "name": "AYA",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "2812 PARK RD",
- "address_line2": null,
- "address_city": "CHARLOTTE",
- "address_state": "NC",
- "address_zip": "28209-1314",
- "address_country": "UNITED STATES",
- "metadata": { },
- "date_created": "2021-03-16T18:40:40.410Z",
- "date_modified": "2021-03-16T18:40:40.410Z",
- "deleted": true,
- "object": "address"
}, - "from": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": null,
- "company": "LOB",
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "6x18_bifold",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:41:06.691Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "deleted": true,
- "use_type": "marketing",
- "fsc": true,
- "object": "self_mailer"
}
], - "object": "list",
- "next_url": null,
- "previous_url": null,
- "count": 2
}
Creates a new self_mailer given information
idempotency_key | string <= 256 characters Example: idempotency_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
Idempotency-Key | string <= 256 characters Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
required | adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) 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 through National Change of Address Linkage(NCOALink). 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. Lob Guide: Verification of Mailing Addresses |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) The artwork to use as the inside of your self mailer. Notes:
See here for HTML examples. |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) The artwork to use as the outside of your self mailer. Notes:
See here for HTML examples. |
use_type required | string or null (sfm_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (self_mailer_size) Default: "6x18_bifold" Enum: "6x18_bifold" "11x9_bifold" "12x9_bifold" "17.75x9_trifold" Specifies the size of the self mailer. The |
adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) Required if | |
billing_group_id | string (billing_group_id) An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See Billing Group API for more information. |
object (qr_code) Customize and place a QR code on the creative at the required position. | |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (sfm_id) ^sfm_[a-zA-Z0-9]+$ Unique identifier prefixed with |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
use_type required | string or null (sfm_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (self_mailer_size) Default: "6x18_bifold" Enum: "6x18_bifold" "11x9_bifold" "12x9_bifold" "17.75x9_trifold" Specifies the size of the self mailer. The |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
outside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the outside of the self mailer. |
inside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the inside of the self mailer. |
outside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the outside of the self mailer. |
inside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the inside of the self mailer. |
object | string Default: "self_mailer" Value: "self_mailer" Value is resource type. |
Array of objects (tracking_event_certified) An array of certified tracking events ordered by ascending | |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
object or null An object describing the reason for failure if the resource failed to render. |
{- "description": "Demo Self Mailer job",
- "to": "adr_bae820679f3f536b",
- "from": "adr_210a8d4b0b76d77b",
- "size": "12x9_bifold",
- "metadata": {
- "spiffy": "true"
}, - "mail_type": "usps_standard",
- "merge_variables": {
- "name": "Harry"
}, - "send_date": "2017-11-01T00:00:00.000Z",
- "use_type": "marketing",
- "qr_code": {
- "position": "relative",
- "width": "2.5",
- "top": "2.5",
- "right": "2.5",
- "pages": "inside,outside"
}, - "fsc": true
}
{- "id": "sfm_8ffbe811dea49dcf",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "6x18_bifold",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "self_mailer"
}
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.
Retrieves the details of an existing letter. You need only supply the unique letter identifier that was returned upon letter creation.
ltr_id required | string (ltr_id) ^ltr_[a-zA-Z0-9]+$ id of the letter |
color required | boolean (color) Set this key to |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (ltr_id) ^ltr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
use_type required | string or null (ltr_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
Array of objects (tracking_event_normal) An array of tracking events ordered by ascending | |
Array of objects or null (card) An array of cards associated with a specific letter | |
Array of objects or null (buckslip) An array of buckslip(s) associated with a specific letter | |
adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) (return_address) Specifies the address the return envelope will be sent back to. This is an optional argument that is available if an account is signed up for the return envelope tracking beta, and has | |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
double_sided | boolean (double_sided) Default: true Set this attribute to |
address_placement | string (address_placement) Default: "top_first_page" Enum: "top_first_page" "insert_blank_page" "bottom_first_page_center" "bottom_first_page" Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template. Some values are exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.
|
boolean or object (return_envelope_returned) | |
perforated_page | integer or null Required if |
object or null (custom_envelope_returned) A nested custom envelope object containing more information about the custom envelope used or | |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
url | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the letter. |
template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the letter. |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "letter" Value: "letter" Value is resource type. |
curl https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "ltr_4868c3b754655f90",
- "description": "Demo Letter",
- "metadata": { },
- "to": {
- "id": "adr_d3489cd64c791ab5",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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",
- "carrier": "USPS",
- "tracking_number": null,
- "tracking_events": [ ],
- "thumbnails": [
- {
}
], - "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",
- "cards": [
- {
- "id": "card_c51ae96f5cebf3e",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": null,
- "size": "2.125x3.375",
- "auto_reorder": false,
- "reorder_quantity": null,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 10000,
- "pending_quantity": 0,
- "countries": null,
- "status": "rendered",
- "mode": "test",
- "orientation": "horizontal",
- "threshold_amount": 0,
- "date_created": "2017-08-05T15:54:53.346Z",
- "date_modified": "2017-08-05T15:54:53.346Z",
- "object": "card"
}
], - "use_type": "marketing",
- "fsc": false,
- "object": "letter"
}
Completely removes a letter from production. This can only be done if the letter has a send_date
and the send_date
has not yet passed. If the letter is successfully canceled, you will not be charged for it. Read more on cancellation windows and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition to gain access.
ltr_id required | string (ltr_id) ^ltr_[a-zA-Z0-9]+$ id of the letter |
id | string (ltr_id) ^ltr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/letters/ltr_4868c3b754655f90 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "ltr_123456789",
- "deleted": true
}
Returns a list of your letters. The letters are returned sorted by creation date, with the most recently created letters appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. | |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Filters resources created by the provided campaign id, prefixed with |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the render status:
|
color | boolean Set to |
scheduled | boolean
|
string or string (send_date) Filter by ISO-8601 date or datetime, e.g. | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type: * |
object or object Sorts items by ascending or descending dates. Use either |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of regular (object) or registered (object) or certified (object) (letter) list of letters |
curl -X GET "https://api.lob.com/v1/letters?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "ltr_5ba44b462c79f07c",
- "description": "Demo Letter",
- "metadata": { },
- "to": {
- "id": "adr_asdi2y3riuasasoi",
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "phone": "5555555555",
- "email": "harry@lob.com",
- "metadata": { },
- "address_line1": "370 WATER ST",
- "address_line2": "",
- "address_city": "SUMMERSIDE",
- "address_state": "PRINCE EDWARD ISLAND",
- "address_zip": "C1N 1C4",
- "address_country": "CANADA",
- "recipient_moved": false,
- "date_created": "2019-09-20T00:14:00.361Z",
- "date_modified": "2019-09-20T00:14:00.361Z",
- "object": "address"
}, - "from": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": "LEORE AVIDAR",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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,
- "extra_service": "certified",
- "custom_envelope": null,
- "template_id": "tmpl_a",
- "template_version_id": "vrsn_a",
- "mail_type": "usps_first_class",
- "merge_variables": null,
- "carrier": "USPS",
- "tracking_number": "92071902358909000011275538",
- "tracking_events": [
- {
- "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"
}
], - "thumbnails": [
- {
}
], - "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-08",
- "use_type": "marketing",
- "fsc": false,
- "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": "210 KING 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": "210 KING 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,
- "extra_service": null,
- "custom_envelope": null,
- "mail_type": "usps_first_class",
- "merge_variables": null,
- "carrier": "USPS",
- "tracking_number": null,
- "tracking_events": [ ],
- "thumbnails": [
- {
}
], - "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",
- "cards": null,
- "use_type": "marketing",
- "fsc": true,
- "object": "letter"
}
], - "object": "list",
- "previous_url": null,
- "count": 2
}
Creates a new letter given information
idempotency_key | string <= 256 characters Example: idempotency_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
Idempotency-Key | string <= 256 characters Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
Lob-Version | string^[0-9]{4}-[0-9]{2}-[0-9]{2}$ Example: 2024-01-01 A string representing the version of the API being used. Specifically for letters, if this header is set to |
required | adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) 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 through National Change of Address Linkage(NCOALink). 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. Lob Guide: Verification of Mailing Addresses |
required | adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) Must either be an address ID or an inline object with correct address parameters. Must be a US address unless using a |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or string (ltr_file) Notes:
See pricing for extra costs incurred. |
color required | boolean Default: false Set this key to |
use_type required | string or null (ltr_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
extra_service | string or null (extra_service) Enum: "certified" "certified_return_receipt" "registered" null Add an extra service to your letter. Can only be non-
Not available for |
cards | Array of strings or null (card_id) [ 0 .. 1 ] items A single-element array containing an existing card id in a string format. See cards for more information. Not available for |
double_sided | boolean (double_sided) Default: true Set this attribute to |
address_placement | string (address_placement) Default: "top_first_page" Enum: "top_first_page" "insert_blank_page" "bottom_first_page_center" "bottom_first_page" Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template. Some values are exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.
|
boolean or string (return_envelope_user_provided) Default: false Indicates if a return envelope is requested for the letter. The value corresponding to this field is by default a boolean. But if the account is signed up for custom return envelopes, the value is of type string and is To include a return envelope with your letter, set to | |
perforated_page | integer or null Required if |
custom_envelope | string or null (user_provided) ^env_[a-zA-Z0-9]+$ 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. |
billing_group_id | string (billing_group_id) An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See Billing Group API for more information. |
object (qr_code) Customize and place a QR code on the creative at the required position. | |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
size | string (ltr_size) Default: "us_letter" Enum: "us_letter" "us_legal" Specifies the size of the letter. It accepts two values Please note that attempting to include the |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
color required | boolean (color) Set this key to |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (ltr_id) ^ltr_[a-zA-Z0-9]+$ Unique identifier prefixed with |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
use_type required | string or null (ltr_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
Array of objects (tracking_event_normal) An array of tracking events ordered by ascending | |
Array of objects or null (card) An array of cards associated with a specific letter | |
Array of objects or null (buckslip) An array of buckslip(s) associated with a specific letter | |
adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) (return_address) Specifies the address the return envelope will be sent back to. This is an optional argument that is available if an account is signed up for the return envelope tracking beta, and has | |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
double_sided | boolean (double_sided) Default: true Set this attribute to |
address_placement | string (address_placement) Default: "top_first_page" Enum: "top_first_page" "insert_blank_page" "bottom_first_page_center" "bottom_first_page" Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template. Some values are exclusive to certain customers. Upgrade to the appropriate Print & Mail Edition to gain access.
|
boolean or object (return_envelope_returned) | |
perforated_page | integer or null Required if |
object or null (custom_envelope_returned) A nested custom envelope object containing more information about the custom envelope used or | |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
url | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the letter. |
template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the letter. |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "letter" Value: "letter" Value is resource type. |
{- "description": "demo",
- "to": {
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107",
- "address_country": "US"
}, - "from": {
- "name": "Harry",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107"
}, - "file": "<html style='padding-top: 3in; margin: .5in;'>HTML Letter for {{name}}</html>",
- "color": true,
- "cards": [
- "card_c51ae96f5cebf3e"
], - "double_sided": false,
- "address_placement": "bottom_first_page",
- "mail_type": "usps_first_class",
- "return_envelope": true,
- "perforated_page": 1,
- "merge_variables": {
- "name": "Harry"
}, - "metadata": {
- "spiffy": "true"
}, - "send_date": "2017-11-01T00:00:00.000Z",
- "extra_service": "registered",
- "custom_envelope": null,
- "use_type": "marketing",
- "qr_code": {
- "position": "relative",
- "width": "2",
- "top": "2",
- "right": "2",
- "pages": "1-2,4-5"
}, - "fsc": true
}
{- "id": "ltr_4868c3b754655f90",
- "description": "Demo Letter",
- "metadata": { },
- "to": {
- "id": "adr_d3489cd64c791ab5",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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",
- "carrier": "USPS",
- "tracking_number": null,
- "tracking_events": [ ],
- "thumbnails": [
- {
}
], - "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",
- "cards": [
- {
- "id": "card_c51ae96f5cebf3e",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": null,
- "size": "2.125x3.375",
- "auto_reorder": false,
- "reorder_quantity": null,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 10000,
- "pending_quantity": 0,
- "countries": null,
- "status": "rendered",
- "mode": "test",
- "orientation": "horizontal",
- "threshold_amount": 0,
- "date_created": "2017-08-05T15:54:53.346Z",
- "date_modified": "2017-08-05T15:54:53.346Z",
- "object": "card"
}
], - "use_type": "marketing",
- "fsc": false,
- "object": "letter"
}
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.
Returns a list of your checks. The checks are returned sorted by creation date, with the most recently created checks appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. | |
scheduled | boolean
|
string or string (send_date) Filter by ISO-8601 date or datetime, e.g. | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type: * |
object or object Sorts items by ascending or descending dates. Use either | |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the render status:
|
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (check) list of checks |
curl -X GET "https://api.lob.com/v1/checks?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "chk_0176bf6197100185",
- "description": "Demo Check",
- "metadata": { },
- "check_number": 12559,
- "memo": "rent",
- "amount": 22.5,
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": "Harry - Office",
- "name": "HARRY ZHANG",
- "company": "LOB",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 KING ST STE 6100",
- "address_line2": "",
- "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",
- "recipient_moved": false
}, - "from": {
- "id": "adr_210a8d4b0b76d77b",
- "name": "LEORE AVIDAR",
- "address_line1": "210 KING ST STE 6100",
- "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": "individual",
- "signatory": "John Doe",
- "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": [
- {
}, - {
}
], - "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-08",
- "message": "pancakes are good",
- "object": "check",
- "check_bottom_template_id": "tmpl_a",
- "attachment_template_id": "tmpl_a",
- "check_bottom_template_version_id": "vrsn_a",
- "attachment_template_version_id": "vrsn_a",
- "merge_variables": { },
- "use_type": "operational",
- "deleted": true
}, - {
- "id": "chk_92b9a6714bc0557c",
- "description": "Demo Check",
- "metadata": { },
- "check_number": 12558,
- "memo": "rent",
- "amount": 22.5,
- "to": {
- "id": "adr_bae820679f3f536b",
- "name": "HARRY ZHANG",
- "address_line1": "210 KING ST STE 6100",
- "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",
- "name": "LEORE AVIDAR",
- "address_line1": "210 KING ST STE 6100",
- "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": "individual",
- "signatory": "John Doe",
- "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": [
- {
}, - {
}, - {
}
], - "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",
- "use_type": "operational",
- "object": "check"
}
], - "object": "list",
- "previous_url": null,
- "count": 2
}
Creates a new check with the provided properties.
idempotency_key | string <= 256 characters Example: idempotency_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
Idempotency-Key | string <= 256 characters Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
message required | string <= 400 characters Max of 400 characters to be included at the bottom of the check page. |
bank_account required | string^bank_[a-zA-Z0-9]+$ The id for a verified bank account. |
required | adr_id (string) or (inline_address_us_chk (address obj with `name` defined (object) or address obj with `company` defined (object))) Must either be an address ID or an inline object with correct address parameters. Checks cannot be sent internationally ( |
required | adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) Must either be an address ID or an inline object with correct address parameters. Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
amount required | number <float> <= 999999.99 The payment amount to be sent in US dollars. Amounts will be rounded to two decimal places. |
use_type required | string or null Enum: "marketing" "operational" null TThe use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
mail_type | string Default: "usps_first_class" Value: "usps_first_class" Checks must be sent |
memo | string or null <= 40 characters Text to include on the memo line of the check. |
check_number | integer [ 1 .. 500000000 ] An integer that designates the check number.
If |
string or string Accepts a remote URL or local file upload to an image to print (in grayscale) in the upper-left corner of your check. Image requirements:
| |
html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) (check_bottom) The artwork to use on the bottom of the check page. Notes:
Need more help? Consult our HTML examples. | |
html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) A document to include with the check. Notes:
See pricing for extra costs incurred. Need more help? Consult our HTML examples. | |
billing_group_id | string (billing_group_id) An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See Billing Group API for more information. |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
required | object (bank_account) |
id required | string (chk_id) ^chk_[a-zA-Z0-9]+$ Unique identifier prefixed with |
amount required | number <float> decimal places <= 2 <= 999999.99 The payment amount to be sent in US dollars. |
required | address obj with `name` defined (object) or address obj with `company` defined (object) (to_address_us_chk) |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
carrier required | string Default: "USPS" Value: "USPS" |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
use_type required | string or null Enum: "marketing" "operational" null TThe use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
mail_type | string Default: "usps_first_class" Value: "usps_first_class" Checks must be sent |
memo | string or null <= 40 characters Text to include on the memo line of the check. |
check_number | integer [ 1 .. 500000000 ] An integer that designates the check number.
If |
message | string <= 400 characters Max of 400 characters to be included at the bottom of the check page. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
check_bottom_template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the check bottom. |
attachment_template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the attachment. |
check_bottom_template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the check bottom. |
attachment_template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the attachment. |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
Array of objects or null (tracking_event_normal) An array of tracking_event objects ordered by ascending | |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "check" Value: "check" Value is resource type. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
{- "description": "Demo Check",
- "to": {
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107",
- "address_country": "US"
}, - "from": {
- "name": "Leore Avidar",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107-1741"
}, - "bank_account": "bank_8cad8df5354d33f",
- "amount": 22.5,
- "memo": "rent",
- "check_bottom": "tmpl_23668b406d5afef",
- "merge_variables": {
- "name": "Harry"
}, - "metadata": {
- "memo": "rafting trip"
}, - "attachment": "./cool.pdf",
- "send_date": "2017-11-01T00:00:00.000Z",
- "use_type": "operational",
- "mail_type": "usps_first_class",
- "check_number": 10001
}
{- "id": "chk_534f10783683daa0",
- "description": "Demo Check",
- "metadata": { },
- "check_number": 10062,
- "memo": "rent",
- "amount": 22.5,
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": "Harry - Office",
- "name": "HARRY ZHANG",
- "company": "LOB",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 KING ST STE 6100",
- "address_line2": "",
- "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",
- "recipient_moved": false
}, - "from": {
- "id": "adr_b8fb5acf3a2b55db",
- "name": "LEORE AVIDAR",
- "address_line1": "210 KING ST STE 6100",
- "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": [
- {
}
], - "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",
- "message": "pancakes are good",
- "check_bottom_template_id": "tmpl_a",
- "attachment_template_id": "tmpl_a",
- "check_bottom_template_version_id": "vrsn_a",
- "attachment_template_version_id": "vrsn_a",
- "use_type": "operational",
- "deleted": true
}
Retrieves the details of an existing check. You need only supply the unique check identifier that was returned upon check creation.
chk_id required | string (chk_id) ^chk_[a-zA-Z0-9]+$ id of the check |
required | object (bank_account) |
id required | string (chk_id) ^chk_[a-zA-Z0-9]+$ Unique identifier prefixed with |
amount required | number <float> decimal places <= 2 <= 999999.99 The payment amount to be sent in US dollars. |
required | address obj with `name` defined (object) or address obj with `company` defined (object) (to_address_us_chk) |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
carrier required | string Default: "USPS" Value: "USPS" |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
use_type required | string or null Enum: "marketing" "operational" null TThe use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
mail_type | string Default: "usps_first_class" Value: "usps_first_class" Checks must be sent |
memo | string or null <= 40 characters Text to include on the memo line of the check. |
check_number | integer [ 1 .. 500000000 ] An integer that designates the check number.
If |
message | string <= 400 characters Max of 400 characters to be included at the bottom of the check page. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
check_bottom_template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the check bottom. |
attachment_template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the attachment. |
check_bottom_template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the check bottom. |
attachment_template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the attachment. |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
Array of objects or null (tracking_event_normal) An array of tracking_event objects ordered by ascending | |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "check" Value: "check" Value is resource type. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl https://api.lob.com/v1/checks/chk_534f10783683daa0 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "chk_534f10783683daa0",
- "description": "Demo Check",
- "metadata": { },
- "check_number": 10062,
- "memo": "rent",
- "amount": 22.5,
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": "Harry - Office",
- "name": "HARRY ZHANG",
- "company": "LOB",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 KING ST STE 6100",
- "address_line2": "",
- "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",
- "recipient_moved": false
}, - "from": {
- "id": "adr_b8fb5acf3a2b55db",
- "name": "LEORE AVIDAR",
- "address_line1": "210 KING ST STE 6100",
- "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": [
- {
}
], - "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",
- "message": "pancakes are good",
- "check_bottom_template_id": "tmpl_a",
- "attachment_template_id": "tmpl_a",
- "check_bottom_template_version_id": "vrsn_a",
- "attachment_template_version_id": "vrsn_a",
- "use_type": "operational",
- "deleted": true
}
Completely removes a check from production. This can only be done if the check has a send_date
and the send_date
has not yet passed. If the check is successfully canceled, you will not be charged for it. Read more on cancellation windows and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition to gain access.
chk_id required | string (chk_id) ^chk_[a-zA-Z0-9]+$ id of the check |
id | string (chk_id) ^chk_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/checks/chk_534f10783683daa0 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "chk_123456789",
- "deleted": true
}
Retrieves the details of an existing snap_pack. You need to only supply the unique snap_pack identifier that was returned upon snap_pack creation.
snap_pack_id required | string (snap_pack_id) ^ord_[0-9a-f]{26}$ id of the snap_pack |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (snap_pack_id) ^ord_[0-9a-f]{26}$ Unique identifier prefixed with |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
use_type required | string or null (snap_pack_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (snap_pack_size) Default: "8.5x11" Value: "8.5x11" Specifies the size of the snap pack. |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
outside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the outside of the snap pack. |
inside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the inside of the snap pack. |
outside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the outside of the snap pack. |
inside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the inside of the snap pack. |
object | string Default: "snap_pack" Value: "snap_pack" Value is resource type. |
Array of objects (tracking_event_normal) An array of tracking events ordered by ascending | |
fsc | boolean Default: false Contact support@lob.com or your account contact to learn more. Not available for snap_pack currently. |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
object or null An object describing the reason for failure if the resource failed to render. | |
color | boolean (color) Set this key to |
curl -X GET "https://api.lob.com/v1/snap_packs/ord_0d6a16a3fff6318ac8f8008dc1" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "description": "April Campaign",
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "8.5x11",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "color": false,
- "object": "snap_pack"
}
Completely removes a snap pack from production. This can only be done if the snap pack's send_date
has not yet passed. If the snap pack is successfully canceled, you will not be charged for it.
snap_pack_id required | string (snap_pack_id) ^ord_[0-9a-f]{26}$ id of the snap_pack |
id | string (snap_pack_id) ^ord_[0-9a-f]{26}$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/snap_packs/ord_0d6a16a3fff6318ac8f8008dc1 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "deleted": true
}
Returns a list of your snap_packs. The snap_packs are returned sorted by creation date, with the most recently created snap_packs appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. | |
string or string (send_date) Filter by ISO-8601 date or datetime, e.g. | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type: * |
object or object Sorts items by ascending or descending dates. Use either | |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Filters resources created by the provided campaign id, prefixed with |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the render status:
|
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (snap_pack) list of snap_packs |
curl -X GET "https://api.lob.com/v1/snap_packs?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "description": "April Campaign",
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "8.5x11",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "color": false,
- "object": "snap_pack"
}, - {
- "id": "ord_851100000f31bb1a872f794cee",
- "description": "April Campaign",
- "to": {
- "id": "adr_f9228b743884ff98",
- "description": null,
- "name": "AYA",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "2812 PARK RD",
- "address_line2": null,
- "address_city": "CHARLOTTE",
- "address_state": "NC",
- "address_zip": "28209-1314",
- "address_country": "UNITED STATES",
- "metadata": { },
- "date_created": "2021-03-16T18:40:40.410Z",
- "date_modified": "2021-03-16T18:40:40.410Z",
- "deleted": true,
- "object": "address"
}, - "from": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": null,
- "company": "LOB",
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "8.5x11",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "color": false,
- "object": "snap_pack"
}
], - "object": "list",
- "next_url": null,
- "previous_url": null,
- "count": 2
}
Creates a new snap_pack given information
idempotency_key | string <= 256 characters Example: idempotency_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
Idempotency-Key | string <= 256 characters Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
required | adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) 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 through National Change of Address Linkage(NCOALink). 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. Lob Guide: Verification of Mailing Addresses |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) The artwork to use as the inside of your snap pack. Notes:
See here for HTML examples. |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or local_file_path (string) The artwork to use as the outside of your snap pack. Notes:
See here for HTML examples. |
use_type required | string or null (snap_pack_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (snap_pack_size) Default: "8.5x11" Value: "8.5x11" Specifies the size of the snap pack. |
adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) Required if | |
billing_group_id | string (billing_group_id) An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See Billing Group API for more information. |
color | boolean Default: false Set this key to |
object (qr_code) Customize and place a QR code on the creative at the required position. |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (snap_pack_id) ^ord_[0-9a-f]{26}$ Unique identifier prefixed with |
url required | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
use_type required | string or null (snap_pack_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
size | string (snap_pack_size) Default: "8.5x11" Value: "8.5x11" Specifies the size of the snap pack. |
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
address obj with `name` defined (object) or address obj with `company` defined (object) (address_us) | |
outside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the outside of the snap pack. |
inside_template_id | string or null^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the inside of the snap pack. |
outside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the outside of the snap pack. |
inside_template_version_id | string or null^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the inside of the snap pack. |
object | string Default: "snap_pack" Value: "snap_pack" Value is resource type. |
Array of objects (tracking_event_normal) An array of tracking events ordered by ascending | |
fsc | boolean Default: false Contact support@lob.com or your account contact to learn more. Not available for snap_pack currently. |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
object or null An object describing the reason for failure if the resource failed to render. | |
color | boolean (color) Set this key to |
{- "description": "Demo Snap Pack Job",
- "to": "adr_bae820679f3f536b",
- "from": "adr_210a8d4b0b76d77b",
- "size": "8.5x11",
- "metadata": {
- "spiffy": "true"
}, - "mail_type": "usps_standard",
- "merge_variables": {
- "name": "Harry"
}, - "send_date": "2017-11-01T00:00:00.000Z",
- "use_type": "marketing"
}
{- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "description": "April Campaign",
- "to": {
- "id": "adr_bae820679f3f536b",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "outside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_id": "tmpl_a3cb937f26d7eec",
- "inside_template_version_id": "vrsn_bfdf70893b00a85",
- "outside_template_version_id": "vrsn_bfdf70893b00a85",
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": {
- "name": null
}, - "size": "8.5x11",
- "mail_type": "usps_first_class",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "color": false,
- "object": "snap_pack"
}
Retrieves the details of an existing booklet. You need to only supply the unique booklet identifier that was returned upon booklet creation.
booklet_id required | string (booklet_id) ^ord_[0-9a-f]{26}$ id of the booklet |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (booklet_id) ^ord_[0-9a-f]{26}$ Unique identifier prefixed with |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
use_type required | string or null (booklet_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
Array of objects (tracking_event_normal) An array of tracking events ordered by ascending | |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
url | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the booklet. |
template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the booklet. |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
size | string (booklet_size) Default: "8.375x5.375" Value: "8.375x5.375" Specifies the size of the booklet. |
pages | integer (booklet_pages) Pages specifies the total number of pages in a booklet, where four pages make up one sheet. Pages must always be in increments of four to maintain booklet integrity. For a booklet with dimensions of 8.375x5.375 inches, we allow for 8, 12, 16, 20, 24, 28, or 32 pages. |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
source_material | string (booklet_source_material) Default: "60# Gloss Text" Value: "60# Gloss Text" Defines the material used to create the mail piece, specifically for booklets. This property is directly tied to the size of the booklet, ensuring that the appropriate material is selected based on the booklet's dimensions. For booklets with |
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "booklet" Value: "booklet" Value is resource type. |
curl -X GET "https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_d3489cd64c791ab5",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "mail_type": "usps_first_class",
- "carrier": "USPS",
- "tracking_number": null,
- "tracking_events": [ ],
- "thumbnails": [
- {
}
], - "merge_variables": {
- "name": "Harry"
}, - "size": "8.375x5.375",
- "pages": 8,
- "source_material": "60# Gloss Text",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "booklet"
}
Completely removes a booklet from production. This can only be done if the booklet's send_date
has not yet passed. If the booklet is successfully canceled, you will not be charged for it.
booklet_id required | string (booklet_id) ^ord_[0-9a-f]{26}$ id of the booklet |
id | string (booklet_id) ^ord_[0-9a-f]{26}$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "deleted": true
}
Returns a list of your booklets. The booklets are returned sorted by creation date, with the most recently created booklets appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. | |
string or string (send_date) Filter by ISO-8601 date or datetime, e.g. | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type: * |
object or object Sorts items by ascending or descending dates. Use either | |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Filters resources created by the provided campaign id, prefixed with |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the render status:
|
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (booklet) list of booklets |
curl -X GET "https://api.lob.com/v1/booklets?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_d3489cd64c791ab5",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "mail_type": "usps_first_class",
- "carrier": "USPS",
- "tracking_number": null,
- "tracking_events": [ ],
- "thumbnails": [
- {
}
], - "merge_variables": {
- "name": "Harry"
}, - "size": "8.375x5.375",
- "pages": 8,
- "source_material": "60# Gloss Text",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "booklet"
}, - {
- "id": "ord_851100000f31bb1a872f794cee",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_f9228b743884ff98",
- "description": null,
- "name": "AYA",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "2812 PARK RD",
- "address_line2": null,
- "address_city": "CHARLOTTE",
- "address_state": "NC",
- "address_zip": "28209-1314",
- "address_country": "UNITED STATES",
- "metadata": { },
- "date_created": "2021-03-16T18:40:40.410Z",
- "date_modified": "2021-03-16T18:40:40.410Z",
- "deleted": true,
- "object": "address"
}, - "from": {
- "id": "adr_210a8d4b0b76d77b",
- "description": null,
- "name": null,
- "company": "LOB",
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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"
}, - "mail_type": "usps_first_class",
- "carrier": "USPS",
- "tracking_number": null,
- "tracking_events": [ ],
- "thumbnails": [
- {
}
], - "merge_variables": {
- "name": "Harry"
}, - "size": "8.375x5.375",
- "pages": 8,
- "source_material": "60# Gloss Text",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "booklet"
}
], - "object": "list",
- "next_url": null,
- "previous_url": null,
- "count": 2
}
Creates a new booklet.
idempotency_key | string <= 256 characters Example: idempotency_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
Idempotency-Key | string <= 256 characters Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5 A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide. |
required | adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) 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 through National Change of Address Linkage(NCOALink). 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. Lob Guide: Verification of Mailing Addresses |
required | adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))))))) Must either be an address ID or an inline object with correct address parameters. Must be a US address unless using a |
required | html_string (string) or tmpl_id (string) or remote_file_url (string) or string (booklet_file) Notes:
|
use_type required | string or null (booklet_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
pages required | integer (booklet_pages) Pages specifies the total number of pages in a booklet, where four pages make up one sheet. Pages must always be in increments of four to maintain booklet integrity. For a booklet with dimensions of 8.375x5.375 inches, we allow for 8, 12, 16, 20, 24, 28, or 32 pages. |
size required | string (booklet_size) Default: "8.375x5.375" Value: "8.375x5.375" Specifies the size of the booklet. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
mail_type | string Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
billing_group_id | string (billing_group_id) An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See Billing Group API for more information. |
object (qr_code) Customize and place a QR code on the creative at the required position. | |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. Not available for |
source_material | string (booklet_source_material) Default: "60# Gloss Text" Value: "60# Gloss Text" Defines the material used to create the mail piece, specifically for booklets. This property is directly tied to the size of the booklet, ensuring that the appropriate material is selected based on the booklet's dimensions. For booklets with |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
carrier required | string Default: "USPS" Value: "USPS" |
id required | string (booklet_id) ^ord_[0-9a-f]{26}$ Unique identifier prefixed with |
required | (address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address) |
use_type required | string or null (booklet_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
Array of objects (tracking_event_normal) An array of tracking events ordered by ascending | |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
merge_variables | object or null (merge_variables) <= 25000 characters You can input a merge variable payload object to your template or QR code redirect URLs to render dynamic content. For example, if you have a template like: |
string or string (send_date) 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. Setting a send date overrides the default cancellation window applied to the mailpiece. Until the | |
mail_type | string (mail_type) Default: "usps_first_class" Enum: "usps_first_class" "usps_standard" A string designating the mail postage type:
|
Array of objects (thumbnail) | |
expected_delivery_date | string <date> (expected_delivery_date) A date in YYYY-MM-DD format of the mailpiece's expected delivery date based on its |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
url | string (signed_link) ^https://lob-assets.com/(letters|postcards|ba... A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. |
template_id | string^tmpl_[a-zA-Z0-9]+$ The unique ID of the HTML template used for the booklet. |
template_version_id | string^vrsn_[a-zA-Z0-9]+$ The unique ID of the specific version of the HTML template used for the booklet. |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Denotes resources created by the provided campaign id, prefixed with |
size | string (booklet_size) Default: "8.375x5.375" Value: "8.375x5.375" Specifies the size of the booklet. |
pages | integer (booklet_pages) Pages specifies the total number of pages in a booklet, where four pages make up one sheet. Pages must always be in increments of four to maintain booklet integrity. For a booklet with dimensions of 8.375x5.375 inches, we allow for 8, 12, 16, 20, 24, 28, or 32 pages. |
fsc | boolean Default: false This is in beta. Contact support@lob.com or your account contact to learn more. |
status | string (status) Enum: "processed" "rendered" "failed" A string describing the PDF render status:
|
source_material | string (booklet_source_material) Default: "60# Gloss Text" Value: "60# Gloss Text" Defines the material used to create the mail piece, specifically for booklets. This property is directly tied to the size of the booklet, ensuring that the appropriate material is selected based on the booklet's dimensions. For booklets with |
object or null An object describing the reason for failure if the resource failed to render. | |
object | string Default: "booklet" Value: "booklet" Value is resource type. |
{- "description": "demo",
- "to": {
- "description": "Harry - Office",
- "name": "Harry Zhang",
- "company": "Lob",
- "email": "harry@lob.com",
- "phone": "5555555555",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107",
- "address_country": "US"
}, - "from": {
- "name": "Harry",
- "address_line1": "210 King St",
- "address_line2": "# 6100",
- "address_city": "San Francisco",
- "address_state": "CA",
- "address_zip": "94107"
}, - "file": "<html style='padding-top: 3in; margin: .5in;'>HTML Booklet for {{name}}</html>",
- "mail_type": "usps_first_class",
- "merge_variables": {
- "name": "Harry"
}, - "metadata": {
- "spiffy": "true"
}, - "send_date": "2017-11-01T00:00:00.000Z",
- "use_type": "marketing",
- "qr_code": {
- "position": "relative",
- "width": "2",
- "top": "2",
- "right": "2",
- "pages": "1-2,4-5"
}, - "fsc": true,
- "size": "8.375x5.375"
}
{- "id": "ord_0d6a16a3fff6318ac8f8008dc1",
- "description": "April Campaign",
- "metadata": { },
- "to": {
- "id": "adr_d3489cd64c791ab5",
- "description": null,
- "name": "HARRY ZHANG",
- "company": null,
- "phone": null,
- "email": null,
- "address_line1": "210 KING 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": "210 KING 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"
}, - "mail_type": "usps_first_class",
- "carrier": "USPS",
- "tracking_number": null,
- "tracking_events": [ ],
- "thumbnails": [
- {
}
], - "merge_variables": {
- "name": "Harry"
}, - "size": "8.375x5.375",
- "pages": 8,
- "source_material": "60# Gloss Text",
- "expected_delivery_date": "2021-03-24",
- "date_created": "2021-03-16T18:40:40.504Z",
- "date_modified": "2021-03-16T18:40:40.504Z",
- "send_date": "2021-03-16T18:45:40.493Z",
- "use_type": "marketing",
- "fsc": false,
- "object": "booklet"
}
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.
Verify a bank account in order to create a check.
bank_id required | string (bank_id) ^bank_[a-zA-Z0-9]+$ id of the bank account to be verified |
amounts required | Array of integers (cents) = 2 items [ items [ 1 .. 100 ] ] 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 |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
routing_number required | string = 9 characters Must be a valid US routing number. |
account_number required | string <= 17 characters |
account_type required | string Enum: "company" "individual" The type of entity that holds the account. |
signatory required | string <= 30 characters The signatory associated with your account. 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. |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "bank_account" Value: "bank_account" Value is resource type. |
id required | string (bank_id) ^bank_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
check_template | string Enum: "common" "jpm" The check template used for printing. The defualt value is |
fractional_routing_number | string The fractional routing number for your home bank account. Required for the |
city | string The city associated with your home bank account. Required for the |
state | string The state associated with your home bank account. Required for the |
zipcode | string The zipcode associated with your home bank account. Required for the |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
signature_url | string or null^https://lob-assets.com/(letters|postcards|ba... 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 Default: false A bank account must be verified before a check can be created. More info here. |
{- "amounts": [
- 1,
- 100
]
}
{- "id": "bank_8cad8df5354d33f",
- "description": "Test Bank Account",
- "metadata": { },
- "routing_number": "322271627",
- "fractional_routing_number": "25-3/440",
- "check_template": "jpm",
- "account_number": "123456789",
- "account_type": "company",
- "signatory": "John Doe",
- "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
- "bank_city": "Columbus",
- "bank_state": "OH",
- "bank_zip": "43240",
- "verified": false,
- "date_created": "2015-11-06T19:24:24.440Z",
- "date_modified": "2015-11-06T19:24:24.440Z",
- "object": "bank_account"
}
Retrieves the details of an existing bank account. You need only supply the unique bank account identifier that was returned upon bank account creation.
bank_id required | string (bank_id) ^bank_[a-zA-Z0-9]+$ id of the bank account |
routing_number required | string = 9 characters Must be a valid US routing number. |
account_number required | string <= 17 characters |
account_type required | string Enum: "company" "individual" The type of entity that holds the account. |
signatory required | string <= 30 characters The signatory associated with your account. 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. |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "bank_account" Value: "bank_account" Value is resource type. |
id required | string (bank_id) ^bank_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
check_template | string Enum: "common" "jpm" The check template used for printing. The defualt value is |
fractional_routing_number | string The fractional routing number for your home bank account. Required for the |
city | string The city associated with your home bank account. Required for the |
state | string The state associated with your home bank account. Required for the |
zipcode | string The zipcode associated with your home bank account. Required for the |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
signature_url | string or null^https://lob-assets.com/(letters|postcards|ba... 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 Default: false A bank account must be verified before a check can be created. More info here. |
curl https://api.lob.com/v1/bank_accounts/bank_8cad8df5354d33f \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "bank_8cad8df5354d33f",
- "description": "Test Bank Account",
- "metadata": { },
- "routing_number": "322271627",
- "fractional_routing_number": "25-3/440",
- "check_template": "jpm",
- "account_number": "123456789",
- "account_type": "company",
- "signatory": "John Doe",
- "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
- "bank_city": "Columbus",
- "bank_state": "OH",
- "bank_zip": "43240",
- "verified": false,
- "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.
bank_id required | string (bank_id) ^bank_[a-zA-Z0-9]+$ id of the bank account |
id | string (bank_id) ^bank_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/bank_accounts/bank_3e64d9904356b20 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "bank_123456789",
- "deleted": true
}
Returns a list of your bank accounts. The bank accounts are returned sorted by creation date, with the most recently created bank accounts appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (bank_account) list of bank_accounts |
curl -X GET "https://api.lob.com/v1/bank_accounts?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "bank_0e3fb07eba0b35b",
- "description": "Example bank account",
- "metadata": { },
- "routing_number": "122100024",
- "account_number": "1234564789",
- "account_type": "company",
- "signatory": "John Doe",
- "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",
- "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",
- "previous_url": null,
- "count": 2
}
Creates a new bank account with the provided properties. 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".
routing_number required | string = 9 characters Must be a valid US routing number. |
account_number required | string <= 17 characters |
account_type required | string Enum: "company" "individual" The type of entity that holds the account. |
signatory required | string <= 30 characters The signatory associated with your account. 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. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
check_template | string Enum: "common" "jpm" The check template used for printing. The defualt value is |
fractional_routing_number | string The fractional routing number for your home bank account. Required for the |
city | string The city associated with your home bank account. Required for the |
state | string The state associated with your home bank account. Required for the |
zipcode | string The zipcode associated with your home bank account. Required for the |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
routing_number required | string = 9 characters Must be a valid US routing number. |
account_number required | string <= 17 characters |
account_type required | string Enum: "company" "individual" The type of entity that holds the account. |
signatory required | string <= 30 characters The signatory associated with your account. 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. |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "bank_account" Value: "bank_account" Value is resource type. |
id required | string (bank_id) ^bank_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
check_template | string Enum: "common" "jpm" The check template used for printing. The defualt value is |
fractional_routing_number | string The fractional routing number for your home bank account. Required for the |
city | string The city associated with your home bank account. Required for the |
state | string The state associated with your home bank account. Required for the |
zipcode | string The zipcode associated with your home bank account. Required for the |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
signature_url | string or null^https://lob-assets.com/(letters|postcards|ba... 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 Default: false A bank account must be verified before a check can be created. More info here. |
{- "description": "Test Bank Account",
- "routing_number": "322271627",
- "account_number": "123456789",
- "signatory": "Jane Doe",
- "account_type": "individual",
- "metadata": {
- "spiffy": "true"
}
}
{- "id": "bank_8cad8df5354d33f",
- "description": "Test Bank Account",
- "metadata": { },
- "routing_number": "322271627",
- "fractional_routing_number": "25-3/440",
- "check_template": "jpm",
- "account_number": "123456789",
- "account_type": "company",
- "signatory": "John Doe",
- "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
- "bank_city": "Columbus",
- "bank_state": "OH",
- "bank_zip": "43240",
- "verified": false,
- "date_created": "2015-11-06T19:24:24.440Z",
- "date_modified": "2015-11-06T19:24:24.440Z",
- "object": "bank_account"
}
These API endpoints allow you to create, retrieve, update and delete reusable HTML templates for use with the Print & Mail API.
Retrieves the details of an existing template. You need only supply the unique template identifier that was returned upon template creation.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ id of the template |
id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
required | Array of objects (template_version) An array of all non-deleted version objects associated with the template. |
required | object (template_version) The template's currently published version. This version will be used in any Print & Mail API requests that reference the specified template. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object | string Default: "template" Value: "template" Value is resource type. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "id": "tmpl_c94e83ca2cd5121",
- "description": "Test Template",
- "versions": [
- {
- "id": "vrsn_362184d96d9b0c9",
- "suggest_json_editor": true,
- "description": "Test Template",
- "engine": "legacy",
- "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",
- "suggest_json_editor": false,
- "description": "Test Template",
- "engine": "handlebars",
- "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 description and/or published version of the template with the given id. To update the template's html, create a new version of the template.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ id of the template |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
published_version | string^vrsn_[a-zA-Z0-9]+$ The ID of the published version of a template you'd like to update. The published version is the one that will be used in any Print & Mail API requests that reference the specified template. Will err if the referenced |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
required | Array of objects (template_version) An array of all non-deleted version objects associated with the template. |
required | object (template_version) The template's currently published version. This version will be used in any Print & Mail API requests that reference the specified template. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object | string Default: "template" Value: "template" Value is resource type. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
{- "description": "Updated Example",
- "published_version": "vrsn_a"
}
{- "id": "tmpl_c94e83ca2cd5121",
- "description": "Test Template",
- "versions": [
- {
- "id": "vrsn_362184d96d9b0c9",
- "suggest_json_editor": true,
- "description": "Test Template",
- "engine": "legacy",
- "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",
- "suggest_json_editor": false,
- "description": "Test Template",
- "engine": "handlebars",
- "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.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ id of the template |
id | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/templates/tmpl_df934eeda694203 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "value": {
- "id": "tmpl_123456789",
- "deleted": true
}
}
Returns a list of your templates. The templates are returned sorted by creation date, with the most recently created templates appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (metadata) <= 500 characters [^"\\]{0,500} Filter by metadata key-value pair`. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (template) list of templates |
curl -X GET "https://api.lob.com/v1/templates?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "data": [
- {
- "id": "tmpl_d5a5a89da9106f8",
- "description": "Test Template",
- "versions": [
- {
- "id": "vrsn_232a02fb8224791",
- "suggest_json_editor": true,
- "description": "Test Template",
- "engine": "legacy",
- "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",
- "suggest_json_editor": false,
- "description": "Test Template",
- "engine": "handlebars",
- "html": "HTML for ",
- "date_created": "2019-07-27T23:49:01.512Z",
- "date_modified": "2019-07-27T23:49:01.512Z",
- "object": "version"
}, - "metadata": { },
- "date_created": "2019-07-27T23:49:01.511Z",
- "date_modified": "2019-07-27T23:49:01.511Z",
- "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": { },
- "date_created": "2019-03-29T10:22:34.642Z",
- "date_modified": "2019-03-29T10:22:34.642Z",
- "object": "template"
}
], - "object": "list",
- "previous_url": null,
- "count": 2
}
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.
html required | string (template_html) <= 100000 characters An HTML string of less than 100,000 characters to be used as the
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
engine | string or null (engine) Default: "legacy" Enum: "legacy" "handlebars" The engine used to combine HTML template with merge variables.
|
required_vars | Array of strings (template_required_vars) An array of required variables to be used in a template. Only available for |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
required | Array of objects (template_version) An array of all non-deleted version objects associated with the template. |
required | object (template_version) The template's currently published version. This version will be used in any Print & Mail API requests that reference the specified template. |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object | string Default: "template" Value: "template" Value is resource type. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
{- "description": "demo",
- "html": "<html>HTML for {{name}}</html>",
- "metadata": {
- "spiffy": "true"
}, - "engine": "handlebars"
}
{- "id": "tmpl_c94e83ca2cd5121",
- "description": "Test Template",
- "versions": [
- {
- "id": "vrsn_362184d96d9b0c9",
- "suggest_json_editor": true,
- "description": "Test Template",
- "engine": "legacy",
- "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",
- "suggest_json_editor": false,
- "description": "Test Template",
- "engine": "handlebars",
- "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"
}
These API endpoints allow you to create, retrieve, update and delete versions of reusable HTML templates for use with the Print & Mail API.
Retrieves the template version with the given template and version ids.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ The ID of the template to which the version belongs. |
vrsn_id required | string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$ id of the template_version |
html required | string (template_html) <= 100000 characters An HTML string of less than 100,000 characters to be used as the
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "version" Value: "version" Value is resource type. |
id required | string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
engine | string or null (engine) Default: "legacy" Enum: "legacy" "handlebars" The engine used to combine HTML template with merge variables.
|
required_vars | Array of strings (template_required_vars) An array of required variables to be used in a template. Only available for |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
suggest_json_editor | boolean Used by frontend, true if the template uses advanced features. |
merge_variables | object Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings. |
curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121/versions/vrsn_534e339882d2282 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "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 template version with the given template and version ids.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ The ID of the template to which the version belongs. |
vrsn_id required | string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$ id of the template_version |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
engine | string or null (engine) Default: "legacy" Enum: "legacy" "handlebars" The engine used to combine HTML template with merge variables.
|
required_vars | Array of strings (template_required_vars) An array of required variables to be used in a template. Only available for |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
html required | string (template_html) <= 100000 characters An HTML string of less than 100,000 characters to be used as the
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "version" Value: "version" Value is resource type. |
id required | string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
engine | string or null (engine) Default: "legacy" Enum: "legacy" "handlebars" The engine used to combine HTML template with merge variables.
|
required_vars | Array of strings (template_required_vars) An array of required variables to be used in a template. Only available for |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
suggest_json_editor | boolean Used by frontend, true if the template uses advanced features. |
merge_variables | object Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings. |
{- "description": "Some description"
}
{- "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"
}
Permanently deletes a template version. A template's published_version
can not be deleted.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ The ID of the template to which the version belongs. |
vrsn_id required | string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$ id of the template_version |
id | string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/templates/tmpl_4aa14648113e45b/versions/vrsn_534e339882d2282 \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "value": {
- "id": "vrsn_123456789",
- "deleted": true
}
}
Returns a list of template versions for the given template ID. The template versions are sorted by creation date, with the most recently created appearing first.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ The ID of the template associated with the retrieved versions |
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (template_version) list of template versions |
curl -X GET "https://api.lob.com/v1/templates/tmpl_ea6e6a1abf01703/versions?limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
{- "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",
- "count": 2
}
Creates a new template version attached to the specified template.
tmpl_id required | string (tmpl_id) ^tmpl_[a-zA-Z0-9]+$ The ID of the template the new version will be attached to |
html required | string (template_html) <= 100000 characters An HTML string of less than 100,000 characters to be used as the
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
engine | string or null (engine) Default: "legacy" Enum: "legacy" "handlebars" The engine used to combine HTML template with merge variables.
|
required_vars | Array of strings (template_required_vars) An array of required variables to be used in a template. Only available for |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
html required | string (template_html) <= 100000 characters An HTML string of less than 100,000 characters to be used as the
If there is a syntax error with your variable names within your HTML, then an error will be thrown, e.g. using a |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "version" Value: "version" Value is resource type. |
id required | string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
engine | string or null (engine) Default: "legacy" Enum: "legacy" "handlebars" The engine used to combine HTML template with merge variables.
|
required_vars | Array of strings (template_required_vars) An array of required variables to be used in a template. Only available for |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
suggest_json_editor | boolean Used by frontend, true if the template uses advanced features. |
merge_variables | object Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings. |
{- "description": "Some Description",
- "html": "<html>HTML for {{name}}</html>"
}
{- "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"
}
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.
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-d "description=Demo Postcard job" \
-d "to=adr_78c304d54912c502" \
-d "from=adr_61a0865c8c573139" \
-d "front=tmpl_b846a20859ae11a" \
-d "back=tmpl_01b0d396a10c268" \
-d "merge_variables[name]=Harry"
Use a pre-designed template from our gallery or follow these basic guidelines as starting points for creating custom Postcards, Self Mailers, Letters, and Checks.
Please follow the standards used in these templates, such as:
-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:
Templates
You can find pre-made templates that already adhere to all of these guidelines here:
Prepping All Images
The following guidelines apply to image types:
Prepping PDFs
To ensure that you are producing PDF's correctly please follow the guidelines outlined in our help center here
Prepping PNGs/JPEGs
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.
Please note, only standard base14 fonts can be Type 1.
FONT NAME | TYPES |
---|---|
Arial |
TrueType, CID TrueType |
Arial,Bold |
TrueType, CID TrueType |
Arial,BoldItalic |
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 |
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 |
Verdana |
TrueType |
Verdana-Bold |
TrueType |
Verdana,Italic |
TrueType |
ZapfDingbats |
Type 1 |
By default, all new accounts have a 5 minute cancellation window for postcards, self mailers, letters, and checks. Within that timeframe, you can cancel mailings from production, free of charge. Once the window has passed for a postcard, self mailer, letter, or check, the mailing is no longer cancelable. In addition, certain customers can customize their cancellation windows by product in their Dashboard Settings. Upgrade to the appropriate Print & Mail Edition to automatically gain access to this ability. For more details on this feature, check out our Cancellation Guide.
If you schedule a postcard, self mailer, letter, or check for up to 180 days
in the future by supplying the send_date
parameter, that will override any
cancellation window you may have for that product.
Postcards, self mailers, 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.
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-d "description=Demo Future Postcard" \
-d "to=adr_bae820679f3f536b" \
-d "from=adr_210a8d4b0b76d77b" \
-d "front=tmpl_b846a20859ae11a" \
-d "back=tmpl_01b0d396a10c268" \
-d "merge_variables[name]=Harry" \
-d "send_date=2021-07-26"
The campaigns endpoint allows you to create and view campaigns that can be used to send multiple letters or postcards. The API provides endpoints for creating campaigns, updating campaigns, retrieving individual campaigns, listing campaigns, and deleting campaigns.
Returns a list of your campaigns. The campaigns are returned sorted by creation date, with the most recently created campaigns appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
include | Array of strings Request that the response include the total count by specifying |
object or object
|
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (campaign) list of campaigns |
curl https://api.lob.com/v1/campaigns \ -u <YOUR API KEY>:
{- "data": [
- {
- "id": "cmp_e05ee61ff80764b",
- "billing_group_id": "bg_fe3079dcdd80e5ae",
- "name": "My Campaign",
- "description": "My Campaign's description",
- "schedule_type": "immediate",
- "send_date": null,
- "target_delivery_date": null,
- "cancel_window_campaign_minutes": 60,
- "metadata": { },
- "use_type": "marketing",
- "is_draft": true,
- "deleted": false,
- "creatives": [ ],
- "uploads": [ ],
- "auto_cancel_if_ncoa": false,
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "campaign"
}
], - "object": "list",
- "previous_url": null,
- "next_url": null,
- "count": 1
}
Creates a new campaign with the provided properties. See how to launch your first campaign here.
x-lang-output | string Enum: "native" "match"
Default response is in English. |
name required | string Name of the campaign. |
schedule_type required | string (cmp_schedule_type) Value: "immediate" How the campaign should be scheduled. Only value available today is |
use_type required | string or null (cmp_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
billing_group_id | string or null^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
target_delivery_date | string or null <date-time> If |
send_date | string or null <date-time> If |
cancel_window_campaign_minutes | integer or null A window, in minutes, within which the campaign can be canceled. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
auto_cancel_if_ncoa | boolean Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "campaign" Value: "campaign" Value is resource type. |
name required | string Name of the campaign. |
schedule_type required | string (cmp_schedule_type) Value: "immediate" How the campaign should be scheduled. Only value available today is |
use_type required | string or null Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description required | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
is_draft required | boolean Default: true Whether or not the campaign is still a draft. |
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) >= 0 items An array of creatives that have been associated with this campaign. |
required | Array of objects (upload) [ 0 .. 1 ] items A single-element array containing the upload object that is assocated with this campaign. |
auto_cancel_if_ncoa required | boolean Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
billing_group_id | string or null^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
target_delivery_date | string or null <date-time> If |
send_date | string or null <date-time> If |
cancel_window_campaign_minutes | integer or null A window, in minutes, within which the campaign can be canceled. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
{- "name": "My Demo Campaign",
- "description": "My Campaign's description",
- "schedule_type": "immediate"
}
{- "id": "cmp_e05ee61ff80764b",
- "billing_group_id": "bg_fe3079dcdd80e5ae",
- "name": "My Campaign",
- "description": "My Campaign's description",
- "schedule_type": "immediate",
- "cancel_window_campaign_minutes": 60,
- "metadata": { },
- "use_type": "marketing",
- "is_draft": true,
- "deleted": false,
- "creatives": [ ],
- "uploads": [ ],
- "auto_cancel_if_ncoa": false,
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "campaign"
}
Retrieves the details of an existing campaign. You need only supply the unique campaign identifier that was returned upon campaign creation.
cmp_id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ id of the campaign |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "campaign" Value: "campaign" Value is resource type. |
name required | string Name of the campaign. |
schedule_type required | string (cmp_schedule_type) Value: "immediate" How the campaign should be scheduled. Only value available today is |
use_type required | string or null Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description required | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
is_draft required | boolean Default: true Whether or not the campaign is still a draft. |
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) >= 0 items An array of creatives that have been associated with this campaign. |
required | Array of objects (upload) [ 0 .. 1 ] items A single-element array containing the upload object that is assocated with this campaign. |
auto_cancel_if_ncoa required | boolean Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
billing_group_id | string or null^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
target_delivery_date | string or null <date-time> If |
send_date | string or null <date-time> If |
cancel_window_campaign_minutes | integer or null A window, in minutes, within which the campaign can be canceled. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \ -u <YOUR API KEY>:
{- "id": "cmp_e05ee61ff80764b",
- "billing_group_id": "bg_fe3079dcdd80e5ae",
- "name": "My Campaign",
- "description": "My Campaign's description",
- "schedule_type": "immediate",
- "cancel_window_campaign_minutes": 60,
- "metadata": { },
- "use_type": "marketing",
- "is_draft": true,
- "deleted": false,
- "creatives": [ ],
- "uploads": [ ],
- "auto_cancel_if_ncoa": false,
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "campaign"
}
Update the details of an existing campaign. You need only supply the unique identifier that was returned upon campaign creation.
cmp_id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ id of the campaign |
name | string (Name) |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
schedule_type | string (cmp_schedule_type) Value: "immediate" How the campaign should be scheduled. Only value available today is |
target_delivery_date | string <date-time> If |
send_date | string <date-time> If |
cancel_window_campaign_minutes | integer A window, in minutes, within which the campaign can be canceled. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
is_draft | boolean Whether or not the campaign is still a draft. Can either be excluded or |
use_type | string or null (cmp_use_type) Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
auto_cancel_if_ncoa | boolean Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "campaign" Value: "campaign" Value is resource type. |
name required | string Name of the campaign. |
schedule_type required | string (cmp_schedule_type) Value: "immediate" How the campaign should be scheduled. Only value available today is |
use_type required | string or null Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description required | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
is_draft required | boolean Default: true Whether or not the campaign is still a draft. |
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) >= 0 items An array of creatives that have been associated with this campaign. |
required | Array of objects (upload) [ 0 .. 1 ] items A single-element array containing the upload object that is assocated with this campaign. |
auto_cancel_if_ncoa required | boolean Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
billing_group_id | string or null^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
target_delivery_date | string or null <date-time> If |
send_date | string or null <date-time> If |
cancel_window_campaign_minutes | integer or null A window, in minutes, within which the campaign can be canceled. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
{- "description": "Test campaign"
}
{- "id": "cmp_e05ee61ff80764b",
- "billing_group_id": "bg_fe3079dcdd80e5ae",
- "name": "My Campaign",
- "description": "My Campaign's description",
- "schedule_type": "immediate",
- "cancel_window_campaign_minutes": 60,
- "metadata": { },
- "use_type": "marketing",
- "is_draft": true,
- "deleted": false,
- "creatives": [ ],
- "uploads": [ ],
- "auto_cancel_if_ncoa": false,
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "campaign"
}
Delete an existing campaign. You need only supply the unique identifier that was returned upon campaign creation. Deleting a campaign also deletes any associated mail pieces that have been created but not sent. A campaign's send_date
matches its associated mail pieces' send_date
s.
cmp_id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ id of the campaign |
id | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean True if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \ -u <YOUR API KEY>:
{- "id": "cmp_e05ee61ff80764b",
- "deleted": true
}
Sends a campaign. You need only supply the unique campaign identifier that was returned upon campaign creation.
cmp_id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ id of the campaign |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "campaign" Value: "campaign" Value is resource type. |
name required | string Name of the campaign. |
schedule_type required | string (cmp_schedule_type) Value: "immediate" How the campaign should be scheduled. Only value available today is |
use_type required | string or null Enum: "marketing" "operational" null The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article. |
id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description required | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
is_draft required | boolean Default: true Whether or not the campaign is still a draft. |
required | Array of Postcard Creative (object) or Letter Creative (object) or Self Mailer Creative (object) (creative) >= 0 items An array of creatives that have been associated with this campaign. |
required | Array of objects (upload) [ 0 .. 1 ] items A single-element array containing the upload object that is assocated with this campaign. |
auto_cancel_if_ncoa required | boolean Whether or not a mail piece should be automatically canceled and not sent if the address is updated via NCOA. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
billing_group_id | string or null^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
target_delivery_date | string or null <date-time> If |
send_date | string or null <date-time> If |
cancel_window_campaign_minutes | integer or null A window, in minutes, within which the campaign can be canceled. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b/send \ -u <YOUR API KEY>:
{- "id": "cmp_e05ee61ff80764b",
- "billing_group_id": "bg_fe3079dcdd80e5ae",
- "name": "My Campaign",
- "description": "My Campaign's description",
- "schedule_type": "immediate",
- "cancel_window_campaign_minutes": 60,
- "metadata": { },
- "use_type": "marketing",
- "is_draft": true,
- "deleted": false,
- "creatives": [ ],
- "uploads": [ ],
- "auto_cancel_if_ncoa": false,
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "campaign"
}
The creatives endpoint allows you to create and view creatives. Creatives are used to create reusable letter and postcard templates. The API provides endpoints for creating creatives, updating creatives, retrieving individual creatives, and deleting creatives.
Creates a new creative with the provided properties
x-lang-output | string Enum: "native" "match"
Default response is in English. |
required | tmpl_id (string) or local_file_path (string) (crv_front) The artwork to use as the front of your postcard. Notes:
See here for HTML examples. |
required | tmpl_id (string) or local_file_path (string) (crv_back) The artwork to use as the back of your postcard creative. Notes:
See here for HTML examples. |
campaign_id required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
resource_type required | string Value: "postcard" Mailpiece type for the creative |
required | object (writable) Properties that the postcards in your Creative should have. See the |
adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) (From) Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. | |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
resource_type required | string Value: "postcard" Mailpiece type for the creative |
required | object (returned) Properties that the postcards in your Creative should have. See the |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "creative" Value: "creative" Value is resource type. |
id required | string (crv_id) ^crv_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description required | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
required | adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) (From) Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
required | object (metadata) <= 500 characters [^"\\]{0,500} 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 |
template_preview_urls required | object (Template Preview URLs) Preview URLs associated with a creative's artwork asset(s) if the creative uses HTML templates as assets. An empty object will be returned if no |
template_previews required | Array of objects (Template Previews) A list of template preview objects if the creative uses HTML template(s) as artwork asset(s). An empty array will be returned if no |
required | Array of objects (campaign_list) Array of campaigns associated with the creative ID |
deleted required | boolean Only returned if the resource has been successfully deleted. |
{- "campaign_id": "cmp_e05ee61ff80764b",
- "resource_type": "postcard",
- "description": "Our 4x6 postcard creative",
- "details": { }
}
{- "id": "crv_2a3b096c409b32c",
- "description": "Our 4x6 postcard creative",
- "from": "adr_210a8d4b0b76d77b",
- "resource_type": "postcard",
- "details": { },
- "metadata": { },
- "template_preview_urls": { },
- "template_previews": [ ],
- "campaigns": [ ],
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "creative"
}
Retrieves the details of an existing creative. You need only supply the unique creative identifier that was returned upon creative creation.
crv_id required | string (crv_id) ^crv_[a-zA-Z0-9]+$ Example: crv_2a3b096c409b32c id of the creative |
resource_type required | string Value: "postcard" Mailpiece type for the creative |
required | object (returned) Properties that the postcards in your Creative should have. See the |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "creative" Value: "creative" Value is resource type. |
id required | string (crv_id) ^crv_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description required | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
required | adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) (From) Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
required | object (metadata) <= 500 characters [^"\\]{0,500} 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 |
template_preview_urls required | object (Template Preview URLs) Preview URLs associated with a creative's artwork asset(s) if the creative uses HTML templates as assets. An empty object will be returned if no |
template_previews required | Array of objects (Template Previews) A list of template preview objects if the creative uses HTML template(s) as artwork asset(s). An empty array will be returned if no |
required | Array of objects (campaign_list) Array of campaigns associated with the creative ID |
deleted required | boolean Only returned if the resource has been successfully deleted. |
curl https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \ -u <YOUR API KEY>:
{- "id": "crv_2a3b096c409b32c",
- "description": "Our 4x6 postcard creative",
- "from": "adr_210a8d4b0b76d77b",
- "resource_type": "postcard",
- "details": { },
- "metadata": { },
- "template_preview_urls": { },
- "template_previews": [ ],
- "campaigns": [ ],
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "creative"
}
Update the details of an existing creative. You need only supply the unique identifier that was returned upon creative creation.
crv_id required | string (crv_id) ^crv_[a-zA-Z0-9]+$ Example: crv_2a3b096c409b32c id of the creative |
adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) (From) Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. | |
description | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
resource_type required | string Value: "postcard" Mailpiece type for the creative |
required | object (returned) Properties that the postcards in your Creative should have. See the |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "creative" Value: "creative" Value is resource type. |
id required | string (crv_id) ^crv_[a-zA-Z0-9]+$ Unique identifier prefixed with |
description required | string or null (resource_description) <= 255 characters An internal description that identifies this resource. Must be no longer than 255 characters. |
required | adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) (From) Must either be an address ID or an inline object with correct address parameters. All addresses will be standardized into uppercase without being modified by verification. |
required | object (metadata) <= 500 characters [^"\\]{0,500} 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 |
template_preview_urls required | object (Template Preview URLs) Preview URLs associated with a creative's artwork asset(s) if the creative uses HTML templates as assets. An empty object will be returned if no |
template_previews required | Array of objects (Template Previews) A list of template preview objects if the creative uses HTML template(s) as artwork asset(s). An empty array will be returned if no |
required | Array of objects (campaign_list) Array of campaigns associated with the creative ID |
deleted required | boolean Only returned if the resource has been successfully deleted. |
{- "description": "Test creative"
}
{- "id": "crv_2a3b096c409b32c",
- "description": "Our 4x6 postcard creative",
- "from": "adr_210a8d4b0b76d77b",
- "resource_type": "postcard",
- "details": { },
- "metadata": { },
- "template_preview_urls": { },
- "template_previews": [ ],
- "campaigns": [ ],
- "date_created": "2017-09-05T17:47:53.767Z",
- "date_modified": "2017-09-05T17:47:53.767Z",
- "object": "creative"
}
The uploads endpoint allows you to upload audience files that are then associated with a given campaign. At this time, only CSV files are allowed. The API provides endpoints for creating uploads, uploading audience files, and marking uploaded files as ready for processing. The API also provides endpoints for downloading files that describe the results, both successful and not, of the processing.
Returns a list of your uploads. Optionally, filter uploads by campaign.
campaignId | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ id of the campaign |
campaignId required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
accountId required | string (Account ID) Account ID that made the request |
required | object (Required Address Columns) The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Optional Address Columns) The mapping of column headers in your file to Lob-optional fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Metadata) Default: {"columns":[]} The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our Campaign Audience Guide for additional details. |
mergeVariableColumnMapping required | object or null (Merge Variable Mapping) Default: null The mapping of column headers in your file to the merge variables present in your creative. See our Campaign Audience Guide for additional details. |
mode required | string Enum: "test" "live" The environment in which the mailpieces were created. Today, will only be |
state required | string (Upload State) Default: "Draft" Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored" The |
totalMailpieces required | integer (Total Mailpieces) Total number of recipients for the campaign |
failedMailpieces required | integer (Failed Mailpieces) Number of mailpieces that failed to create |
validatedMailpieces required | integer (Validated Mailpieces) Number of mailpieces that were successfully created |
bytesProcessed required | integer (Bytes Processed) Number of bytes processed in your CSV |
dateCreated required | string <date-time> (Date Created) A timestamp in ISO 8601 format of the date the upload was created |
dateModified required | string <date-time> (Date Modified) A timestamp in ISO 8601 format of the date the upload was last modified |
failuresUrl | string (Failures URL) Url where your campaign mailpiece failures can be retrieved |
originalFilename | string (Original Filename) Filename of the upload |
curl https://api.lob.com/v1/uploads \ -u <YOUR API KEY>:
[- {
- "id": "upl_71be866e430b11e9",
- "accountId": "fa9ea650fc7b31a89f92",
- "campaignId": "cmp_1933ad629bae1408",
- "mode": "test",
- "originalFilename": "my_audience.csv",
- "state": "Draft",
- "totalMailpieces": 100,
- "failedMailpieces": 5,
- "validatedMailpieces": 95,
- "bytesProcessed": 17268,
- "dateCreated": "2017-09-05T17:47:53.767Z",
- "dateModified": "2017-09-05T17:47:53.767Z",
- "requiredAddressColumnMapping": {
- "name": "recipient_name",
- "address_line1": "primary_line",
- "address_city": "city",
- "address_state": "state",
- "address_zip": "zip_code"
}, - "optionalAddressColumnMapping": {
- "address_line2": "secondary_line",
- "company": "company",
- "address_country": "country"
}, - "mergeVariableColumnMapping": {
- "gift_code": "code"
}, - "metadata": {
- "columns": [
- "recipient_name",
- "zip_code"
]
}
}
]
Creates a new upload with the provided properties.
campaignId required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
object (Required Address Columns) The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details. | |
object (Optional Address Columns) The mapping of column headers in your file to Lob-optional fields for the resource created. See our Campaign Audience Guide for additional details. | |
object (Metadata) Default: {"columns":[]} The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our Campaign Audience Guide for additional details. | |
mergeVariableColumnMapping | object or null (Merge Variable Mapping) Default: null The mapping of column headers in your file to the merge variables present in your creative. See our Campaign Audience Guide for additional details. |
campaignId required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
accountId required | string (Account ID) Account ID that made the request |
required | object (Required Address Columns) The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Optional Address Columns) The mapping of column headers in your file to Lob-optional fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Metadata) Default: {"columns":[]} The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our Campaign Audience Guide for additional details. |
mergeVariableColumnMapping required | object or null (Merge Variable Mapping) Default: null The mapping of column headers in your file to the merge variables present in your creative. See our Campaign Audience Guide for additional details. |
mode required | string Enum: "test" "live" The environment in which the mailpieces were created. Today, will only be |
state required | string (Upload State) Default: "Draft" Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored" The |
totalMailpieces required | integer (Total Mailpieces) Total number of recipients for the campaign |
failedMailpieces required | integer (Failed Mailpieces) Number of mailpieces that failed to create |
validatedMailpieces required | integer (Validated Mailpieces) Number of mailpieces that were successfully created |
bytesProcessed required | integer (Bytes Processed) Number of bytes processed in your CSV |
dateCreated required | string <date-time> (Date Created) A timestamp in ISO 8601 format of the date the upload was created |
dateModified required | string <date-time> (Date Modified) A timestamp in ISO 8601 format of the date the upload was last modified |
failuresUrl | string (Failures URL) Url where your campaign mailpiece failures can be retrieved |
originalFilename | string (Original Filename) Filename of the upload |
{- "campaignId": "cmp_1933ad629bae1408",
- "requiredAddressColumnMapping": {
- "name": "recipient_name",
- "address_line1": "primary_line",
- "address_city": "city",
- "address_state": "state",
- "address_zip": "zip_code"
}, - "optionalAddressColumnMapping": {
- "address_line2": "secondary_line",
- "company": "company",
- "address_country": "country,"
}, - "metadata": {
- "columns": [
- "recipient_name"
]
}, - "mergeVariableColumnMapping": {
- "name": "recipient_name",
- "gift_code": "code",
- "qr_code_redirect_url": "redirect_url"
}
}
{- "id": "upl_71be866e430b11e9",
- "accountId": "fa9ea650fc7b31a89f92",
- "campaignId": "cmp_1933ad629bae1408",
- "mode": "live",
- "originalFilename": "my_audience.csv",
- "state": "Draft",
- "totalMailpieces": 100,
- "failedMailpieces": 5,
- "validatedMailpieces": 95,
- "bytesProcessed": 17628,
- "dateCreated": "2017-09-05T17:47:53.767Z",
- "dateModified": "2017-09-05T17:47:53.767Z",
- "requiredAddressColumnMapping": {
- "name": null,
- "address_line1": null,
- "address_city": null,
- "address_state": null,
- "address_zip": null
}, - "optionalAddressColumnMapping": {
- "address_line2": null,
- "company": null,
- "address_country": null
}, - "mergeVariableColumnMapping": null,
- "metadata": {
- "columns": [ ]
}
}
Retrieves the details of an existing upload. You need only supply the unique upload identifier that was returned upon upload creation.
upl_id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ id of the upload |
campaignId required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
accountId required | string (Account ID) Account ID that made the request |
required | object (Required Address Columns) The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Optional Address Columns) The mapping of column headers in your file to Lob-optional fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Metadata) Default: {"columns":[]} The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our Campaign Audience Guide for additional details. |
mergeVariableColumnMapping required | object or null (Merge Variable Mapping) Default: null The mapping of column headers in your file to the merge variables present in your creative. See our Campaign Audience Guide for additional details. |
mode required | string Enum: "test" "live" The environment in which the mailpieces were created. Today, will only be |
state required | string (Upload State) Default: "Draft" Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored" The |
totalMailpieces required | integer (Total Mailpieces) Total number of recipients for the campaign |
failedMailpieces required | integer (Failed Mailpieces) Number of mailpieces that failed to create |
validatedMailpieces required | integer (Validated Mailpieces) Number of mailpieces that were successfully created |
bytesProcessed required | integer (Bytes Processed) Number of bytes processed in your CSV |
dateCreated required | string <date-time> (Date Created) A timestamp in ISO 8601 format of the date the upload was created |
dateModified required | string <date-time> (Date Modified) A timestamp in ISO 8601 format of the date the upload was last modified |
failuresUrl | string (Failures URL) Url where your campaign mailpiece failures can be retrieved |
originalFilename | string (Original Filename) Filename of the upload |
curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9 \ -u <YOUR API KEY>: \
{- "id": "upl_71be866e430b11e9",
- "accountId": "fa9ea650fc7b31a89f92",
- "campaignId": "cmp_1933ad629bae1408",
- "mode": "live",
- "originalFilename": "my_audience.csv",
- "state": "Draft",
- "totalMailpieces": 100,
- "failedMailpieces": 5,
- "validatedMailpieces": 95,
- "bytesProcessed": 17628,
- "dateCreated": "2017-09-05T17:47:53.767Z",
- "dateModified": "2017-09-05T17:47:53.767Z",
- "requiredAddressColumnMapping": {
- "name": null,
- "address_line1": null,
- "address_city": null,
- "address_state": null,
- "address_zip": null
}, - "optionalAddressColumnMapping": {
- "address_line2": null,
- "company": null,
- "address_country": null
}, - "mergeVariableColumnMapping": null,
- "metadata": {
- "columns": [ ]
}
}
Update the details of an existing upload. You need only supply the unique identifier that was returned upon upload creation.
upl_id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ id of the upload |
originalFilename | string (Original Filename) Original filename provided when the upload is created. |
object (Required Address Columns) The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details. | |
object (Optional Address Columns) The mapping of column headers in your file to Lob-optional fields for the resource created. See our Campaign Audience Guide for additional details. | |
object (Metadata) Default: {"columns":[]} The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our Campaign Audience Guide for additional details. | |
mergeVariableColumnMapping | object or null (Merge Variable Mapping) Default: null The mapping of column headers in your file to the merge variables present in your creative. See our Campaign Audience Guide for additional details. |
campaignId required | string (Campaign id) ^cmp_[a-zA-Z0-9]+$ Unique identifier prefixed with |
id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
accountId required | string (Account ID) Account ID that made the request |
required | object (Required Address Columns) The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Optional Address Columns) The mapping of column headers in your file to Lob-optional fields for the resource created. See our Campaign Audience Guide for additional details. |
required | object (Metadata) Default: {"columns":[]} The list of column headers in your file as an array that you want as metadata associated with each mailpiece. See our Campaign Audience Guide for additional details. |
mergeVariableColumnMapping required | object or null (Merge Variable Mapping) Default: null The mapping of column headers in your file to the merge variables present in your creative. See our Campaign Audience Guide for additional details. |
mode required | string Enum: "test" "live" The environment in which the mailpieces were created. Today, will only be |
state required | string (Upload State) Default: "Draft" Enum: "Preprocessing" "Draft" "Ready for Validation" "Validating" "Scheduled" "Cancelled" "Errored" The |
totalMailpieces required | integer (Total Mailpieces) Total number of recipients for the campaign |
failedMailpieces required | integer (Failed Mailpieces) Number of mailpieces that failed to create |
validatedMailpieces required | integer (Validated Mailpieces) Number of mailpieces that were successfully created |
bytesProcessed required | integer (Bytes Processed) Number of bytes processed in your CSV |
dateCreated required | string <date-time> (Date Created) A timestamp in ISO 8601 format of the date the upload was created |
dateModified required | string <date-time> (Date Modified) A timestamp in ISO 8601 format of the date the upload was last modified |
failuresUrl | string (Failures URL) Url where your campaign mailpiece failures can be retrieved |
originalFilename | string (Original Filename) Filename of the upload |
{- "originalFilename": "string",
- "requiredAddressColumnMapping": {
- "name": "recipient_name",
- "address_line1": "primary_line",
- "address_city": "city",
- "address_state": "state",
- "address_zip": "zip_code"
}, - "optionalAddressColumnMapping": {
- "address_line2": "secondary_line",
- "company": "company",
- "address_country": "country,"
}, - "metadata": {
- "columns": [
- "recipient_name"
]
}, - "mergeVariableColumnMapping": {
- "name": "recipient_name",
- "gift_code": "code",
- "qr_code_redirect_url": "redirect_url"
}
}
{- "id": "upl_71be866e430b11e9",
- "accountId": "fa9ea650fc7b31a89f92",
- "campaignId": "cmp_1933ad629bae1408",
- "mode": "live",
- "originalFilename": "my_audience.csv",
- "state": "Draft",
- "totalMailpieces": 100,
- "failedMailpieces": 5,
- "validatedMailpieces": 95,
- "bytesProcessed": 17628,
- "dateCreated": "2017-09-05T17:47:53.767Z",
- "dateModified": "2017-09-05T17:47:53.767Z",
- "requiredAddressColumnMapping": {
- "name": null,
- "address_line1": null,
- "address_city": null,
- "address_state": null,
- "address_zip": null
}, - "optionalAddressColumnMapping": {
- "address_line2": null,
- "company": null,
- "address_country": null
}, - "mergeVariableColumnMapping": null,
- "metadata": {
- "columns": [ ]
}
}
Delete an existing upload. You need only supply the unique identifier that was returned upon upload creation.
upl_id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ id of the upload |
curl -X DELETE https://api.lob.com/v1/uploads/upl_71be866e430b11e9 \ -u <YOUR API KEY>:
Upload an audience file and associate it with an upload.
upl_id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ ID of the upload |
file | string <binary> |
curl -X POST https://api.lob.com/v1/uploads/upl_71be866e430b11e9/file \ -u <YOUR API KEY>: \ -F file=@<YOUR FILE NAME HERE>
{- "message": "File uploaded successfully",
- "filename": "string"
}
Campaign Exports can help you understand exactly which records in a campaign could not be created. By initiating and retrieving an export, you will get row-by-row errors for your campaign. For a step-by-step walkthrough of creating a campaign and exporting failures, see our Campaigns Guide.
Create an export file associated with an upload.
upl_id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ ID of the upload |
type | string Enum: "all" "failures" "successes" |
message required | string (Message) Default: "Export is processing" Value: "Export is processing" |
exportId required | string (Export ID) |
{- "type": "all"
}
{- "message": "Export is processing",
- "exportId": "ex_2dafd758ed3da9c43"
}
Retrieves the line item data for each row from the csv file associated with the upload id record. NOTE: This endpoint is currently feature flagged. Please reach out to Lob's support team if you would like access to this API endpoint.
upl_id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ ID of the upload |
status | string Enum: "Validated" "Failed" "Processing" The status of line items to filter and retrieve. By default all line items are returned. |
limit | integer [ 1 .. 100 ] Default: 100 Example: limit=10 How many results to return. |
offset | integer Default: 0 An integer that designates the offset at which to begin returning results. Defaults to 0. |
required | Array of objects |
count required | integer (count) number of resources in a set |
total_count required | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
next_url | string or null Url of next page of items in list. |
prev_url | string or null Url of previous page of items in list. |
curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/report \ -u <YOUR API KEY>:
{- "id": "ex_6a94fe68fd151e0f8",
- "dateCreated": "2021-07-06T22:51:42.838Z",
- "dateModified": "2022-07-06T22:51:42.838Z",
- "deleted": false,
- "s3Url": null,
- "state": "in_progress",
- "type": "failures",
- "uploadId": "upl_71be866e430b11e9"
}
Retrieves the details of an existing export. You need only supply the unique export identifier that was returned upon export creation. If you try retrieving an export immediately after creating one (i.e., before we're done processing the export), you will get back an export object with state = in_progress
.
upl_id required | string (upl_id) ^upl_[a-zA-Z0-9]+$ ID of the upload |
ex_id required | string (ex_id) ^ex_[a-zA-Z0-9]+$ ID of the export |
id required | string (ex_id) ^ex_[a-zA-Z0-9]+$ Unique identifier prefixed with |
dateCreated required | string <date-time> A timestamp in ISO 8601 format of the date the export was created |
dateModified required | string <date-time> A timestamp in ISO 8601 format of the date the export was last modified |
deleted required | boolean Returns as |
s3Url required | string The URL for the generated export file. |
state required | string Enum: "in_progress" "failed" "succeeded" The state of the export file, which can be |
type required | string Enum: "all" "failures" "successes" The export file type, which can be |
uploadId required | string (upl_id) ^upl_[a-zA-Z0-9]+$ Unique identifier prefixed with |
curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/exports/ex_6a94fe68fd151e0f8 \ -u <YOUR API KEY>:
{- "id": "ex_6a94fe68fd151e0f8",
- "dateCreated": "2021-07-06T22:51:42.838Z",
- "dateModified": "2022-07-06T22:51:42.838Z",
- "deleted": false,
- "s3Url": null,
- "state": "in_progress",
- "type": "failures",
- "uploadId": "upl_71be866e430b11e9"
}
The Informed Delivery campaigns API allows you to create and view Informed Delivery campaigns.
List Informed Delivery campaigns
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (response) list of Informed Delivery campaigns |
curl https://api.lob.com/v1/informed_delivery_campaign \ -u <YOUR API KEY>:
{- "data": [
- {
- "id": "infd_234g5324g324g23",
- "object": "informed_delivery_campaign",
- "account_id": "xxxxxxxxxxxxxxxxxxxx",
- "quantity": 20,
- "usps_campaign_id": "1234567890",
- "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2",
- "start_date": "2024-08-31T00:00:00.000Z",
- "end_date": "2024-10-15T00:00:00.000Z",
- "start_serial": 3183487,
- "end_serial": 3183506,
- "ride_along_image_s3_link": "https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg",
- "representative_image_s3_link": null,
- "status": "approved",
- "date_created": "2024-08-30T23:30:02.980Z",
- "date_modified": "2024-08-30T23:30:05.027Z",
- "mode": "live",
- "lob_campaign_id": null,
- "deleted": false,
- "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code",
- "brand_name": "Lob",
- "service_request_number": null
}, - {
- "id": "infd_23g23g234g23g42",
- "object": "informed_delivery_campaign",
- "account_id": "xxxxxxxxxxxxxxxxxxxx",
- "quantity": 5,
- "usps_campaign_id": "23452345",
- "usps_title": "Campaign: 133d228e-f9e9-4056-aaea-f",
- "start_date": "2024-08-31T00:00:00.000Z",
- "end_date": "2024-10-15T00:00:00.000Z",
- "start_serial": null,
- "end_serial": null,
- "ride_along_image_s3_link": "https://lob-assets.com/informed-delivery/infd_23g23g234g23g42_ride_along.jpg",
- "representative_image_s3_link": null,
- "status": "pending_approval",
- "date_created": "2024-08-30T23:30:02.980Z",
- "date_modified": "2024-09-30T23:30:05.027Z",
- "mode": "live",
- "lob_campaign_id": null,
- "deleted": false,
- "campaign_code": "133d228e-f9e9-4056-aaea-f+Code",
- "brand_name": "Lob",
- "service_request_number": null
}
], - "object": "list",
- "next_url": null,
- "previous_url": null,
- "count": 2
}
Creates a new Informed Delivery campaign
quantity required | integer [ 2 .. 10000000 ] The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
ride_along_image required | object JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
ride_along_url required | string [ 10 .. 255 ] characters ^https:\/\/.{5,247}$ To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with https://lob.com then you could use any variation of https://lob.com such as https://lob.com/promotions/promo_123 |
start_date required | string <date> The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
status | string Value: "pending_approval" If setting a campaign to |
brand_name | string The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
usps_title | string Unique title for the campaign. One will be auto generated if not provided. |
lob_campaign_id | string or null^cmp_[a-zA-Z0-9]+$ When sending as part of Lob’s campaign workflow, include the lob_campaign_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
representative_image | object JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
id required | string (infd_id) ^infd_[a-zA-Z0-9]+$ Unique identifier prefixed with |
object required | string Value: "informed_delivery_campaign" Value is the resource type. |
account_id required | string Your Lob account id. |
quantity required | integer [ 2 .. 10000000 ] The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
usps_campaign_id required | string (usps_campaign_id) ^[0-9]+$ A numberical string up to 12 characters long. |
usps_title required | string Unique title for the campaign. One will be auto generated if not provided. |
start_date required | string <date> The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
end_date required | string <date-time> A timestamp in ISO 8601 format of the date the campaign ends. |
start_serial required | integer or null The first serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
end_serial required | integer or null The last serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
ride_along_url required | string [ 10 .. 255 ] characters ^https:\/\/.{5,247}$ To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with https://lob.com then you could use any variation of https://lob.com such as https://lob.com/promotions/promo_123 |
ride_along_image_s3_link required | string A URL link to the campaigns ride along image. |
representative_image_s3_link required | string or null A URL link to the campaigns representative image. |
status required | string |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
mode required | string Enum: "live" "test" The mode of the Informed Delivery campaign. This is set by the API token you used to create the campaign. |
lob_campaign_id required | string or null^cmp_[a-zA-Z0-9]+$ When sending as part of Lob’s campaign workflow, include the lob_campaign_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
deleted required | boolean Whether the resource has been deleted. |
campaign_code required | string The campaign code associated with the Informed Delivery campaign. |
brand_name required | string The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
service_request_number required | string or null The USPS promotion service request number used to create this campaign (if there was one used). |
curl --request POST \ --url https://api.lob.com/v1/informed_delivery_campaigns \ -u <YOUR API KEY>: \ --header 'Content-Type: multipart/form-data' \ --form ride_along_url=https://www.lob.com \ --form 'ride_along_image=@/path/to/ride_along.jpg' \ --form quantity=2 \ --form start_date=2024-01-01 \ --form status=pending_approval
{- "id": "infd_234g5324g324g23",
- "object": "informed_delivery_campaign",
- "account_id": "xxxxxxxxxxxxxxxxxxxx",
- "quantity": 20,
- "usps_campaign_id": "1234567890",
- "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2",
- "start_date": "2024-08-31T00:00:00.000Z",
- "end_date": "2024-10-15T00:00:00.000Z",
- "start_serial": 3183487,
- "end_serial": 3183506,
- "ride_along_image_s3_link": "https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg",
- "representative_image_s3_link": null,
- "status": "approved",
- "date_created": "2024-08-30T23:30:02.980Z",
- "date_modified": "2024-08-30T23:30:05.027Z",
- "mode": "live",
- "lob_campaign_id": null,
- "deleted": false,
- "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code",
- "brand_name": "Lob",
- "service_request_number": null
}
Retrieves the details of an existing Informed Delivery campaign. You need only supply the usps_campaign_id
returned in the campaign creation request.
usps_campaign_id required | string (usps_campaign_id) ^[0-9]+$ Example: 1200772869 usps_campaign_id of the Informed Delivery campaign |
id required | string (infd_id) ^infd_[a-zA-Z0-9]+$ Unique identifier prefixed with |
object required | string Value: "informed_delivery_campaign" Value is the resource type. |
account_id required | string Your Lob account id. |
quantity required | integer [ 2 .. 10000000 ] The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
usps_campaign_id required | string (usps_campaign_id) ^[0-9]+$ A numberical string up to 12 characters long. |
usps_title required | string Unique title for the campaign. One will be auto generated if not provided. |
start_date required | string <date> The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
end_date required | string <date-time> A timestamp in ISO 8601 format of the date the campaign ends. |
start_serial required | integer or null The first serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
end_serial required | integer or null The last serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
ride_along_url required | string [ 10 .. 255 ] characters ^https:\/\/.{5,247}$ To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with https://lob.com then you could use any variation of https://lob.com such as https://lob.com/promotions/promo_123 |
ride_along_image_s3_link required | string A URL link to the campaigns ride along image. |
representative_image_s3_link required | string or null A URL link to the campaigns representative image. |
status required | string |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
mode required | string Enum: "live" "test" The mode of the Informed Delivery campaign. This is set by the API token you used to create the campaign. |
lob_campaign_id required | string or null^cmp_[a-zA-Z0-9]+$ When sending as part of Lob’s campaign workflow, include the lob_campaign_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
deleted required | boolean Whether the resource has been deleted. |
campaign_code required | string The campaign code associated with the Informed Delivery campaign. |
brand_name required | string The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
service_request_number required | string or null The USPS promotion service request number used to create this campaign (if there was one used). |
curl https://api.lob.com/v1/informed_delivery_campaign/1200772869 \ -u <YOUR API KEY>:
{- "id": "infd_234g5324g324g23",
- "object": "informed_delivery_campaign",
- "account_id": "xxxxxxxxxxxxxxxxxxxx",
- "quantity": 20,
- "usps_campaign_id": "1234567890",
- "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2",
- "start_date": "2024-08-31T00:00:00.000Z",
- "end_date": "2024-10-15T00:00:00.000Z",
- "start_serial": 3183487,
- "end_serial": 3183506,
- "ride_along_image_s3_link": "https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg",
- "representative_image_s3_link": null,
- "status": "approved",
- "date_created": "2024-08-30T23:30:02.980Z",
- "date_modified": "2024-08-30T23:30:05.027Z",
- "mode": "live",
- "lob_campaign_id": null,
- "deleted": false,
- "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code",
- "brand_name": "Lob",
- "service_request_number": null
}
Update the details of an existing Informed Delivery campaign.
NOTE: you can only update a campaign in the pending_approval
status.
usps_campaign_id required | string (usps_campaign_id) ^[0-9]+$ Example: 1200772869 usps_campaign_id of the Informed Delivery campaign |
quantity | integer [ 2 .. 10000000 ] The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
status | string Value: "approved" After setting an Informed Delivery campaign to “approved” said campaign will activate, and you can start sending mail using it. You will no longer be able to edit an Informed Delivery campaign in this status. |
ride_along_url | string [ 10 .. 255 ] characters ^https:\/\/.{5,247}$ To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with https://lob.com then you could use any variation of https://lob.com such as https://lob.com/promotions/promo_123 |
start_date | string <date> The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
brand_name | string The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
usps_title | string Unique title for the campaign. One will be auto generated if not provided. |
lob_campaign_id | string or null^cmp_[a-zA-Z0-9]+$ When sending as part of Lob’s campaign workflow, include the lob_campaign_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
ride_along_image | object JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
representative_image | object JPG Image. Maximum file size is 200 KBs. Maximum pixel size is 300 pixels wide x 200 pixels high |
id required | string (infd_id) ^infd_[a-zA-Z0-9]+$ Unique identifier prefixed with |
object required | string Value: "informed_delivery_campaign" Value is the resource type. |
account_id required | string Your Lob account id. |
quantity required | integer [ 2 .. 10000000 ] The number of mail pieces that will be part of this Informed Delivery campaign. USPS requires that IMB Codes are in sequence, so any mail pieces sent beyond this quantity will be rejected. |
usps_campaign_id required | string (usps_campaign_id) ^[0-9]+$ A numberical string up to 12 characters long. |
usps_title required | string Unique title for the campaign. One will be auto generated if not provided. |
start_date required | string <date> The first date that mail can be handed off to USPS and still included in the informed delivery campaign. The start date must be at least two days in the future. The end date will be automatically calculated to be 45 days from the start. For Target Delivery Date, recommended to set the start date to the earliest possible date (2 days from now). |
end_date required | string <date-time> A timestamp in ISO 8601 format of the date the campaign ends. |
start_serial required | integer or null The first serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
end_serial required | integer or null The last serial number in the range of serial numbers for this campaign. Only non-null when campaign is approved. |
ride_along_url required | string [ 10 .. 255 ] characters ^https:\/\/.{5,247}$ To qualify as part of a promotion, the base domain must match the domain used to register the promotion. I.e. If the promo was registered with https://lob.com then you could use any variation of https://lob.com such as https://lob.com/promotions/promo_123 |
ride_along_image_s3_link required | string A URL link to the campaigns ride along image. |
representative_image_s3_link required | string or null A URL link to the campaigns representative image. |
status required | string |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
mode required | string Enum: "live" "test" The mode of the Informed Delivery campaign. This is set by the API token you used to create the campaign. |
lob_campaign_id required | string or null^cmp_[a-zA-Z0-9]+$ When sending as part of Lob’s campaign workflow, include the lob_campaign_id as part of the request to associate this Informed Delivery campaign with the Lob campaign |
deleted required | boolean Whether the resource has been deleted. |
campaign_code required | string The campaign code associated with the Informed Delivery campaign. |
brand_name required | string The brand name you would like included in the informed delivery email. Will default to the “company” on the users account. |
service_request_number required | string or null The USPS promotion service request number used to create this campaign (if there was one used). |
curl -X PATCH https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \ -u <YOUR API KEY>: \ -d '{"status":"approved"}'
{- "id": "infd_234g5324g324g23",
- "object": "informed_delivery_campaign",
- "account_id": "xxxxxxxxxxxxxxxxxxxx",
- "quantity": 20,
- "usps_campaign_id": "1234567890",
- "usps_title": "Campaign: 1a1a1a1a-9657-423b-b3c7-2",
- "start_date": "2024-08-31T00:00:00.000Z",
- "end_date": "2024-10-15T00:00:00.000Z",
- "start_serial": 3183487,
- "end_serial": 3183506,
- "ride_along_image_s3_link": "https://lob-assets.com/informed-delivery/infd_234g5324g324g23_ride_along.jpg",
- "representative_image_s3_link": null,
- "status": "approved",
- "date_created": "2024-08-30T23:30:02.980Z",
- "date_modified": "2024-08-30T23:30:05.027Z",
- "mode": "live",
- "lob_campaign_id": null,
- "deleted": false,
- "campaign_code": "1a1a1a1a-9657-423b-b3c7-2+Code",
- "brand_name": "Lob",
- "service_request_number": null
}
Validate, automatically correct, and standardize the addresses in your
address book based on USPS's Coding Accuracy Support System (CASS).
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 (if using primary_line
) an arbitrary five digit
number for zip_code
(e.g. "11111") let you explore the responses to many types of addresses:
ADDRESS TYPE FOR SAMPLE RESPONSE | DELIVERABILITY | SET primary_line OR address TO |
---|---|---|
Commercial highrise | deliverable |
commercial highrise |
Residential highrise | deliverable |
residential highrise |
Residential house | deliverable |
residential house |
PO Box | deliverable |
po box |
Rural route | deliverable |
rural route |
Puerty Rico address w/ urbanization | deliverable |
puerto rico |
Military address | deliverable |
military |
Department of state | deliverable |
department of state |
Generic deliverable | deliverable |
deliverable |
Missing a suite number | deliverable_missing_unit |
missing unit |
Suite number doesn't exist | deliverable_incorrect_unit |
incorrect unit |
Residential house with unnecessary suite number | deliverable_unnecessary_unit |
unnecessary unit |
Undeliverable and block matched | undeliverable |
undeliverable block match |
Undeliverable and no block matched | undeliverable |
undeliverable no match |
See the test
request & response examples under US Verification Examples within the
"Verify a US or US territory address" section in US Verifications.
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).
Verify a list of US or US territory addresses 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.
case | string Default: "upper" Enum: "upper" "proper" Casing of the verified address. Possible values are |
required | Array of US verification object with `city` and `state` (object) or US verification object with `zip_code` (object) (multiple_components) [ 1 .. 20 ] items |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
required | Array of us_verification (object) or error (object) |
errors required | boolean Indicates whether any errors occurred during the verification process. |
{- "addresses": [
- {
- "primary_line": "210 King Street",
- "city": "San Francisco",
- "state": "CA",
- "zip_code": "94107"
}, - {
- "recipient": "Walgreens",
- "primary_line": "Ave Wilson Churchill 123",
- "secondary_line": "",
- "urbanization": "URB FAIR OAKS",
- "city": "RIO PIEDRAS",
- "state": "PR",
- "zip_code": "00926"
}
]
}
{- "addresses": [
- {
- "id": "us_ver_c7cb63d68f8d6",
- "recipient": "LOB.COM",
- "primary_line": "210 KING ST",
- "secondary_line": "",
- "urbanization": "",
- "last_line": "SAN FRANCISCO CA 94107-1702",
- "deliverability": "deliverable",
- "valid_address": true,
- "components": {
- "primary_number": "210",
- "street_predirection": "",
- "street_name": "KING",
- "street_suffix": "ST",
- "street_postdirection": "",
- "secondary_designator": "",
- "secondary_number": "",
- "pmb_designator": "",
- "pmb_number": "",
- "extra_secondary_designator": "",
- "extra_secondary_number": "",
- "city": "SAN FRANCISCO",
- "state": "CA",
- "zip_code": "94107",
- "zip_code_plus_4": "1702",
- "zip_code_type": "standard",
- "delivery_point_barcode": "941071728506",
- "address_type": "commercial",
- "record_type": "street",
- "default_building_address": false,
- "county": "SAN FRANCISCO",
- "county_fips": "06075",
- "carrier_route": "C032",
- "carrier_route_type": "city_delivery",
- "po_box_only_flag": "N",
- "latitude": 37.77597542841264,
- "longitude": -122.3929557343685
}, - "deliverability_analysis": {
- "dpv_confirmation": "Y",
- "dpv_cmra": "N",
- "dpv_vacant": "N",
- "dpv_active": "Y",
- "dpv_inactive_reason": "",
- "dpv_throwback": "N",
- "dpv_non_delivery_day_flag": "N",
- "dpv_non_delivery_day_values": "",
- "dpv_no_secure_location": "N",
- "dpv_door_not_accessible": "N",
- "dpv_footnotes": [
- "AA",
- "BB"
], - "ews_match": false,
- "lacs_indicator": "",
- "lacs_return_code": "",
- "suite_return_code": ""
}, - "lob_confidence_score": {
- "score": 100,
- "level": "high"
}, - "object": "us_verification"
}
], - "errors": false
}
Verify a US or US territory address with a live API key. The address can be in components (e.g. primary_line
is "210 King Street", zip_code
is "94107") or as a single string (e.g. "210 King 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 | string Default: "upper" Enum: "upper" "proper" Casing of the verified address. Possible values are |
city required | string <= 200 characters The name of the city. |
state required | string <= 50 characters The ISO 3166-2 two letter code or subdivision name for the state. |
primary_line required | string (primary_line_us) <= 200 characters The primary delivery line (usually the street address) of the address.
Combination of the following applicable
|
recipient | string or null (recipient) <= 500 characters The intended recipient, typically a person's or firm's name. |
secondary_line | string (secondary_line) <= 200 characters The secondary delivery line of the address. This field is typically empty but may contain information if |
urbanization | string (urbanization) <= 200 characters Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See USPS documentation for clarification. |
zip_code | string^\d{5}((-)?\d{4})?$ Required if |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
id | string (us_ver_id) ^us_ver_[a-zA-Z0-9_]+$ Unique identifier prefixed with |
recipient | string or null (recipient) <= 500 characters The intended recipient, typically a person's or firm's name. |
primary_line | string (primary_line_us) <= 200 characters The primary delivery line (usually the street address) of the address.
Combination of the following applicable
|
secondary_line | string (secondary_line) <= 200 characters The secondary delivery line of the address. This field is typically empty but may contain information if |
urbanization | string (urbanization) <= 200 characters Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See USPS documentation for clarification. |
last_line | string Combination of the following applicable
|
deliverability | string Enum: "deliverable" "deliverable_unnecessary_unit" "deliverable_incorrect_unit" "deliverable_missing_unit" "undeliverable" Summarizes the deliverability of the
|
valid_address | boolean Enum: true false This field indicates whether an address was found in a more comprehensive address dataset that includes sources from the USPS, open source mapping data, and our proprietary mail delivery data. This field can be interpreted as a representation of whether an address is a real location or not. Additionally a valid address may contradict the deliverability field since an address can be a real valid location but the USPS may not deliver to that address. |
object (us_components) A nested object containing a breakdown of each component of an address. | |
object (deliverability_analysis) A nested object containing a breakdown of the deliverability of an address. | |
object (lob_confidence_score) Lob Confidence Score is a nested object that provides a numerical value between 0-100 of the likelihood that an address is deliverable based on Lob’s mail delivery data to over half of US households. | |
object | string Default: "us_verification" Value: "us_verification" Value is resource type. |
{- "primary_line": "210 King Street",
- "city": "San Francisco",
- "state": "CA",
- "zip_code": "94107"
}
{- "id": "us_ver_c7cb63d68f8d6",
- "recipient": "LOB.COM",
- "primary_line": "210 KING ST",
- "secondary_line": "",
- "urbanization": "",
- "last_line": "SAN FRANCISCO CA 94107-1702",
- "deliverability": "deliverable",
- "valid_address": true,
- "components": {
- "primary_number": "210",
- "street_predirection": "",
- "street_name": "KING",
- "street_suffix": "ST",
- "street_postdirection": "",
- "secondary_designator": "",
- "secondary_number": "",
- "pmb_designator": "",
- "pmb_number": "",
- "extra_secondary_designator": "",
- "extra_secondary_number": "",
- "city": "SAN FRANCISCO",
- "state": "CA",
- "zip_code": "94107",
- "zip_code_plus_4": "1702",
- "zip_code_type": "standard",
- "delivery_point_barcode": "941071702108",
- "address_type": "commercial",
- "record_type": "street",
- "default_building_address": false,
- "county": "SAN FRANCISCO",
- "county_fips": "06075",
- "carrier_route": "C032",
- "carrier_route_type": "city_delivery",
- "po_box_only_flag": "N",
- "latitude": 37.77597542841264,
- "longitude": -122.3929557343685
}, - "deliverability_analysis": {
- "dpv_confirmation": "Y",
- "dpv_cmra": "N",
- "dpv_vacant": "N",
- "dpv_active": "Y",
- "dpv_inactive_reason": "",
- "dpv_throwback": "N",
- "dpv_non_delivery_day_flag": "N",
- "dpv_non_delivery_day_values": "",
- "dpv_no_secure_location": "N",
- "dpv_door_not_accessible": "N",
- "dpv_footnotes": [
- "AA",
- "BB"
], - "ews_match": false,
- "lacs_indicator": "",
- "lacs_return_code": "",
- "suite_return_code": ""
}, - "lob_confidence_score": {
- "score": 100,
- "level": "high"
}, - "object": "us_verification"
}
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. |
TA |
The address is deliverable by dropping a trailing alphabet from the primary number. |
IA |
The address is an Informed Address. The recipient and the street address is replaced with a special code provided by the USPS. |
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. |
C1 |
The primary number was confirmed whereas the secondary number is unconfirmed and required to be deliverable. |
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. |
PB |
The address is identified as PO Box street address. |
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. |
Given partial address information, this endpoint returns up to 10 address suggestions.
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 - [PRIMARY NUMBER] s[uggestion]
- Returns a maximum of ten predefined suggested addresses.
[PRIMARY NUMBER]
does not have to be a valid primary number when sending a test request.
Each additional letter in suggestion
reduces the number of suggestions by one (e.g.
1 su
returns 9 suggested addresses). [PRIMARY NUMBER]
does not affect the number of
suggestions returned.City and state filters work as expected and filter the list of predetermined suggested addresses.
See the test
request & response examples under Autocomplete Examples within the "Autocomplete a partial address" section in US Autocompletions.
Given an address prefix consisting of a partial primary line, as well as optional input of city, state, and zip code, this functionality returns up to 10 full US address suggestions. Not all of them will turn out to be valid addresses; they'll need to be verified.
case | string Default: "upper" Enum: "upper" "proper" Casing of the verified address. Possible values are |
valid_addresses | boolean Default: false Enum: true false Possible values are |
address_prefix required | string Only accepts numbers and street names in an alphanumeric format. |
city | string An optional city input used to filter suggestions. Case insensitive and does not match partial abbreviations. |
state | string An optional state input used to filter suggestions. Case insensitive and does not match partial abbreviations. |
zip_code | string An optional ZIP Code input used to filter suggestions. Matches partial entries. |
geo_ip_sort | boolean If |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
id | string (us_auto_id) ^us_auto_[a-zA-Z0-9]+$ Unique identifier prefixed with |
Array of objects (suggestions) [ 0 .. 10 ] items An array of objects representing suggested addresses. | |
object | string Default: "us_autocompletion" Value: "us_autocompletion" Value is resource type. |
{- "address_prefix": "185 B",
- "city": "San Francisco",
- "state": "CA",
- "zip_code": "94107",
- "geo_ip_sort": false
}
{- "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": "210 KING 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"
}
Find a list of zip codes associated with a valid US location via latitude and longitude.
Reverse geocode a valid US location with a live API key.
size | integer [ 1 .. 50 ] Default: 5 Example: size=5 Determines the number of locations returned. Possible values are between 1 and 50 and any number higher will be rounded down to 50. Default size is a list of 5 reverse geocoded locations. |
latitude required | number or null <float> [ -90 .. 90 ] A positive or negative decimal indicating the geographic latitude of the address, specifying the north-to-south position of a location. This should be input with |
longitude required | number or null <float> [ -180 .. 180 ] A positive or negative decimal indicating the geographic longitude of the address, specifying the north-to-south position of a location. This should be input with |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
id | string (reverse_geocode_id) ^us_reverse_geocode_[a-zA-Z0-9_]+$ Unique identifier prefixed with |
Array of objects (addresses) list of addresses | |
object | string Default: "us_reverse_geocode_lookup" Value: "us_reverse_geocode_lookup" Value is resource type. |
{- "latitude": 37.7749,
- "longitude": 122.4194
}
{- "id": "us_reverse_geocode_8a013f3e",
- "addresses": [
- {
- "components": {
- "zip_code": "94107",
- "zip_code_plus_4": "1702"
}, - "location_analysis": {
- "latitude": 37.78271,
- "longitude": -122.416202,
- "distance": 1.32
}
}, - {
- "components": {
- "zip_code": "94107",
- "zip_code_plus_4": "1702"
}, - "location_analysis": {
- "latitude": 37.782917,
- "longitude": -122.416131,
- "distance": 1.33
}
}
]
}
Find a list of cities, states and associated information about a US ZIP code.
Returns information about a ZIP code
zip_code required | string^\d{5}$ A 5-digit ZIP code. |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
zip_code required | string^\d{5}$ A 5-digit ZIP code. |
id required | string (zip_id) ^us_zip_[a-zA-Z0-9]+$ Unique identifier prefixed with |
required | Array of objects (zip_lookup_city) An array of city objects containing valid cities for the |
zip_code_type required | string (zip_code_type) Enum: "standard" "po_box" "unique" "military" "" A description of the ZIP code type. For more detailed information about each ZIP code type, see US Verification Details. |
object required | string Default: "us_zip_lookup" Value: "us_zip_lookup" Value is resource type. |
{- "zip_code": "94107"
}
{- "id": "us_zip_c7cb63d68f8d6",
- "cities": [
- {
- "city": "SAN FRANCISCO",
- "state": "CA",
- "county": "SAN FRANCISCO",
- "county_fips": "06075",
- "preferred": true
}
], - "zip_code_type": "standard",
- "object": "us_zip_lookup",
- "zip_code": "94107"
}
Validates whether a given name is associated with an address.
Validates whether a given name is associated with an address.
city required | string <= 200 characters The name of the city. |
state required | string <= 50 characters The ISO 3166-2 two letter code or subdivision name for the state. |
recipient required | string or null (recipient) <= 500 characters The intended recipient, typically a person's or firm's name. |
primary_line required | string (primary_line_us) <= 200 characters The primary delivery line (usually the street address) of the address.
Combination of the following applicable
|
secondary_line | string (secondary_line) <= 200 characters The secondary delivery line of the address. This field is typically empty but may contain information if |
urbanization | string (urbanization) <= 200 characters Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See USPS documentation for clarification. |
zip_code | string^\d{5}((-)?\d{4})?$ Required if |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
id | string (identity_validation_id) ^id_validation_[a-zA-Z0-9_]+$ Unique identifier prefixed with |
recipient | string or null (identity_validation_recipient) <= 500 characters The name of the person whose identity is being validated. |
primary_line | string (primary_line_us) <= 200 characters The primary delivery line (usually the street address) of the address.
Combination of the following applicable
|
secondary_line | string (secondary_line) <= 200 characters The secondary delivery line of the address. This field is typically empty but may contain information if |
urbanization | string (urbanization) <= 200 characters Only present for addresses in Puerto Rico. An urbanization refers to an area, sector, or development within a city. See USPS documentation for clarification. |
last_line | string Combination of the following applicable
|
score | number or null <float> [ 0 .. 100 ] Default: null A numerical score between 0 and 100 that represents the likelihood the provided name is associated with a physical address. |
confidence | string Enum: "high" "medium" "low" "" Indicates the likelihood the recipient name and address match based on our custom internal calculation. Possible values are:
|
object | string Default: "id_validation" Value: "id_validation" Value is resource type. |
{- "recipient": "Larry Lobster",
- "primary_line": "210 King St.",
- "secondary_line": "",
- "city": "San Francisco",
- "state": "CA",
- "zip_code": "94107"
}
{- "id": "id_validation_8a013f3e",
- "recipient": "LARRY LOBSTER",
- "primary_line": "210 KING ST.",
- "secondary_line": "",
- "urbanization": "",
- "last_line": "SAN FRANCISCO CA 94107-1728",
- "score": 100,
- "confidence": "high",
- "object": "id_validation"
}
Address verification for non-US addresses
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:
DELIVERABILITY OF SAMPLE RESPONSE | SET primary_line TO |
---|---|
deliverable |
deliverable |
deliverable_missing_info |
deliverable missing info |
undeliverable |
undeliverable |
no_match |
no match |
See the test
request & response examples under Intl Verification Examples within the
"Verify an international address section" in Intl Verifications.
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).
Verify a list of 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.
required | Array of objects (multiple_components_intl) [ 1 .. 20 ] items |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
required | Array of intl_verification (object) or error (object) |
errors required | boolean Indicates whether any errors occurred during the verification process. |
{- "addresses": [
- {
- "recipient": "John Doe",
- "primary_line": "370 Water St",
- "secondary_line": "",
- "city": "Summerside",
- "state": "Prince Edwards Island",
- "postal_code": "C1N 1C4",
- "country": "CA"
}, - {
- "recipient": "Jane Doe",
- "primary_line": "UL. DOLSKAYA 1",
- "secondary_line": "",
- "city": "MOSCOW",
- "state": "MOSCOW G",
- "postal_code": "115569",
- "country": "RU"
}
]
}
{- "addresses": [
- {
- "id": "intl_ver_c7cb63d68f8d6",
- "recipient": null,
- "primary_line": "370 WATER ST",
- "secondary_line": "",
- "last_line": "SUMMERSIDE PE C1N 1C4",
- "country": "CA",
- "coverage": "SUBBUILDING",
- "deliverability": "deliverable",
- "status": "LV4",
- "components": {
- "primary_number": "370",
- "street_name": "WATER ST",
- "city": "SUMMERSIDE",
- "state": "PE",
- "postal_code": "C1N 1C4"
}, - "object": "intl_verification"
}
], - "errors": false
}
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.
x-lang-output | string Enum: "native" "match"
Default response is in English. |
primary_line required | string (primary_line) <= 200 characters The primary delivery line (usually the street address) of the address. |
country required | string (country_extended) Enum: "AD" "AE" "AF" "AG" "AI" "AL" "AN" "AO" "AQ" "AR" "AT" "AU" "AW" "AZ" "BA" … 202 more Must be a 2 letter country short-name code (ISO 3166). Does not accept |
recipient | string or null (recipient) <= 500 characters The intended recipient, typically a person's or firm's name. |
secondary_line | string (secondary_line) <= 200 characters The secondary delivery line of the address. This field is typically empty but may contain information if |
city | string (city) <= 200 characters The name of the city. |
state | string The name of the state. |
postal_code | string (postal_code) <= 12 characters The postal code. |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
recipient | string or null (recipient) <= 500 characters The intended recipient, typically a person's or firm's name. |
primary_line | string (primary_line) <= 200 characters The primary delivery line (usually the street address) of the address. |
secondary_line | string (secondary_line) <= 200 characters The secondary delivery line of the address. This field is typically empty but may contain information if |
id | string (intl_ver_id) ^intl_ver_[a-zA-Z0-9]+$ Unique identifier prefixed with |
last_line | string Combination of the following applicable
|
country | string (country_short) The country of the address. Will be returned as a 2 letter country short-name code (ISO 3166). |
coverage | string Enum: "SUBBUILDING" "HOUSENUMBER/BUILDING" "STREET" "LOCALITY" "SPARSE" The coverage level for the country. This represents the maximum level of accuracy an input address can be verified to.
|
deliverability | string Enum: "deliverable" "deliverable_missing_info" "undeliverable" "no_match" Summarizes the deliverability of the
|
status | string Enum: "LV4" "LV3" "LV2" "LV1" "LF4" "LF3" "LF2" "LF1" "LM4" "LM3" "LM2" "LU1" The status level for the country. This represents the maximum level of accuracy an input address can be verified to.
|
object (intl_components) A nested object containing a breakdown of each component of an address. | |
object | string Default: "intl_verification" Value: "intl_verification" Value is resource type. |
{- "recipient": "Harry Zhang",
- "primary_line": "370 Water St",
- "secondary_line": "",
- "city": "Summerside",
- "state": "Prince Edward Island",
- "postal code": "C1N 1C4",
- "country": "CA"
}
{- "id": "intl_ver_c7cb63d68f8d6",
- "recipient": null,
- "primary_line": "370 WATER ST",
- "secondary_line": "",
- "last_line": "SUMMERSIDE PE C1N 1C4",
- "country": "CA",
- "coverage": "SUBBUILDING",
- "deliverability": "deliverable",
- "status": "LV4",
- "components": {
- "primary_number": "370",
- "street_name": "WATER ST",
- "city": "SUMMERSIDE",
- "state": "PE",
- "postal_code": "C1N 1C4"
}, - "object": "intl_verification"
}
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.
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.
EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
---|---|---|
postcard.created |
false |
A postcard is successfully created (Lob returns a 200 status code). |
postcard.rejected |
false |
A postcard was not successfully created (Usually happens when one or more postcards fail the creation step during a batch request) |
postcard.rendered_pdf |
false |
A postcard's PDF proof is successfully rendered. |
postcard.rendered_thumbnails |
false |
A postcard's thumbnails are successfully rendered. |
postcard.deleted |
false |
A postcard is successfully canceled. |
postcard.mailed |
true |
A postcard receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. |
postcard.in_transit |
true |
A postcard receives an "In Transit" tracking event. |
postcard.in_local_area |
true |
A postcard receives an "In Local Area" tracking event. |
postcard.processed_for_delivery |
true |
A postcard receives a "Processed for Delivery" tracking event. |
postcard.delivered |
false |
A postcard receives a "Delivered" tracking event. |
postcard.failed |
false |
A postcard receives a "Failed" rendering error or tracking event. |
postcard.re-routed |
true |
A postcard receives a "Re-Routed" tracking event. |
postcard.returned_to_sender |
true |
A postcard receives a "Returned to Sender" tracking event. |
postcard.international_exit |
true |
A postcard receives a "International Exit" tracking event. |
postcard.viewed |
false |
A postcard QR code or URL was scanned or viewed by the recipient. |
EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
---|---|---|
self_mailer.created |
false |
A self_mailer is successfully created (Lob returns a 200 status code). |
self_mailer.rejected |
false |
A self_mailer was not successfully created (Usually happens when one or more self_mailers fail the creation step during a batch request) |
self_mailer.rendered_pdf |
false |
A self_mailer's PDF proof is successfully rendered. |
self_mailer.rendered_thumbnails |
false |
A self_mailer's thumbnails are successfully rendered. |
self_mailer.deleted |
false |
A self_mailer is successfully canceled. |
self_mailer.mailed |
true |
A self_mailer receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. |
self_mailer.in_transit |
true |
A self_mailer receives an "In Transit" tracking event. |
self_mailer.in_local_area |
true |
A self_mailer receives an "In Local Area" tracking event. |
self_mailer.processed_for_delivery |
true |
A self_mailer receives a "Processed for Delivery" tracking event. |
self_mailer.delivered |
true |
A self_mailer receives an "Delivered" tracking event. |
self_mailer.failed |
false |
A self_mailer receives an "Failed" rendering error or tracking event. |
self_mailer.re-routed |
true |
A self_mailer receives a "Re-Routed" tracking event. |
self_mailer.returned_to_sender |
true |
A self_mailer receives a "Returned to Sender" tracking event. |
self_mailer.international_exit |
true |
A self_mailer receives an "International Exit" tracking event. |
self_mailer.viewed |
false |
A self_mailer's QR code or URL was scanned or viewed by the recipient. |
EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
---|---|---|
letter.created |
false |
A letter is successfully created (Lob returns a 200 status code). |
letter.rejected |
false |
A letter was not successfully created (Usually happens when one or more letters fail the creation step during a batch request) |
letter.rendered_pdf |
false |
A letter's PDF proof is successfully rendered. |
letter.rendered_thumbnails |
false |
A letter's thumbnails are successfully rendered. |
letter.deleted |
false |
A letter is successfully canceled. |
letter.mailed |
true |
A letter receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. |
letter.in_transit |
true |
A letter receives an "In Transit" tracking event. |
letter.in_local_area |
true |
A letter receives an "In Local Area" tracking event. |
letter.processed_for_delivery |
true |
A letter receives a "Processed for Delivery" tracking event. |
letter.delivered |
true |
A letter receives a "Delivered" tracking event. |
letter.failed |
false |
A letter receives a "Failed" rendering error or tracking event. |
letter.re-routed |
true |
A letter receives a "Re-Routed" tracking event. |
letter.returned_to_sender |
true |
A letter receives a "Returned to Sender" tracking event. |
letter.international_exit |
true |
A letter receives a "International Exit" tracking event. |
letter.viewed |
false |
A letter's QR code or URL was scanned or viewed by the recipient. |
letter.certified.mailed |
true |
A certified letter receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. |
letter.certified.in_transit |
true |
A certified letter receives an "In Transit" tracking event. |
letter.certified.in_local_area |
true |
A certified letter receives an "In Transit" tracking event. |
letter.certified.processed_for_delivery |
true |
A certified letter receives a "Processed for Delivery" tracking event. |
letter.certified.re-routed |
true |
A certified letter receives a "Re-Routed" tracking event. |
letter.certified.returned_to_sender |
true |
A certified letter receives a "Returned to Sender" tracking event. |
letter.certified.delivered |
true |
A certified letter receives a "Delivered" tracking event. |
letter.certified.pickup_available |
true |
A certified letter receives a "Pickup Available" tracking event. |
letter.certified.issue |
true |
A certified letter receives an "Issue" tracking event. |
letter.return_envelope.created |
false |
A return envelope is created (occurs simultaneously with letter creation). |
letter.return_envelope.in_transit |
true |
A return envelope receives an "In Transit" tracking event. |
letter.return_envelope.in_local_area |
true |
A return envelope receives an "In Local Area" tracking event. |
letter.return_envelope.processed_for_delivery |
true |
A return envelope receives a "Processed for Delivery" tracking event. |
letter.return_envelope.re-routed |
true |
A return envelope receives a "Re-Routed" tracking event. |
letter.return_envelope.returned_to_sender |
true |
A return envelope receives a "Returned to Sender" tracking event. |
EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
---|---|---|
check.created |
false |
A check is successfully created (Lob returns a 200 status code). |
check.rejected |
false |
A check was not successfully created (Usually happens when one or more checks fail the creation step during a batch request) |
check.rendered_pdf |
false |
A check's PDF proof is successfully rendered. |
check.rendered_thumbnails |
false |
A check's thumbnails are successfully rendered. |
check.deleted |
false |
A check is successfully canceled. |
check.mailed |
true |
A check receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions. |
check.in_transit |
true |
A check receives an "In Transit" tracking event. |
check.in_local_area |
true |
A check receives an "In Local Area" tracking event. |
check.processed_for_delivery |
true |
A check receives a "Processed for Delivery" tracking event. |
check.delivered |
true |
A check receives a "Delivered" tracking event. |
check.failed |
false |
A check receives a "Failed" rendering error or tracking event. |
check.re-routed |
true |
A check receives a "Re-Routed" tracking event. |
check.returned_to_sender |
true |
A check receives a "Returned to Sender" tracking event. |
EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
---|---|---|
address.created |
false |
An address is successfully created (Lob returns a 200 status code). |
address.deleted |
false |
An address is successfully deleted. |
EVENT TYPE | LIVE-ONLY | WHEN EVENT TYPE OCCURS |
---|---|---|
bank_account.created |
false |
A bank account is successfully created (Lob returns a 200 status code). |
bank_account.deleted |
false |
A bank account is successfully deleted. |
bank_account.verified |
false |
A bank account is successfully verified. |
Information about an event
id required | string^evt_[a-zA-Z0-9_]+$ Unique identifier prefixed with |
body required | 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 required | string Unique identifier of the related resource for the event. |
required | object (event_type) |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
object required | string Default: "event" Value: "event" Value is resource type. |
{- "event_type": {
- "resource": "postcards",
- "enabled_for_test": true,
- "id": "postcard.created",
- "object": "event_type"
}, - "reference_id": "psc_d2d10a2e9cba991c",
- "id": "evt_d95ff8ffd2b5cfb4",
- "date_created": "2016-12-04T22:50:08.180Z",
- "body": {
- "id": "psc_d2d10a2e9cba991c",
- "description": "Test Postcard",
- "metadata": { },
- "to": {
- "id": "adr_8e783523dd7f0e70",
- "description": "Test Recipient Address",
- "name": "Harry Zhang",
- "company": "LOB",
- "phone": null,
- "email": null,
- "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 Sender Address",
- "name": "Harry Zhang",
- "company": "LOB",
- "phone": null,
- "email": null,
- "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"
}, - "front_template_id": null,
- "back_template_id": null,
- "carrier": "USPS",
- "tracking_events": [ ],
- "thumbnails": [
- {
}, - {
}
], - "merge_variables": null,
- "mail_type": "usps_first_class",
- "size": "4x6",
- "expected_delivery_date": "2016-12-09",
- "date_created": "2016-12-04T10:51:51.843Z",
- "date_modified": "2016-12-04T10:51:51.843Z",
- "send_date": "2016-12-04T10:56:51.843Z",
- "object": "postcard"
}, - "object": "event"
}
As mailpieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events.
Letters sent with USPS Certified Mail are fully tracked by USPS, and
therefore their tracking events have an
additional details
object with more detailed information about the
tracking event. The following table 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 |
Information about tracking events
id required | string (evnt_id) ^evnt_[a-zA-Z0-9]+$ Unique identifier prefixed with |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "tracking_event" Value: "tracking_event" Value is resource type. |
type required | string Value: "normal" non-Certified postcards, self mailers, letters, checks and snap packs |
name required | string Enum: "Mailed" "In Transit" "In Local Area" "Processed for Delivery" "Delivered" "Re-Routed" "Returned to Sender" "International Exit" Name of tracking event (for normal postcards, self mailers, letters, checks and snap packs):
|
time | string <date-time> A timestamp in ISO 8601 format of the date USPS registered the event. |
details | object or null Value: null Will be |
location | string or null The zip code in which the scan event occurred. Null for |
{- "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"
}
The Billing Groups API allows you to create and view labels that can be attached to certain consumption-based usages of Letters, Checks, Postcards and Self-Mailers to customize your bill. Please check each resource API section to learn more about how to access the Billing Groups API.
Retrieves the details of an existing billing_group. You need only supply the unique billing_group identifier that was returned upon billing_group creation.
bg_id required | string (bg_id) ^bg_[a-zA-Z0-9]+$ id of the billing_group |
description | string (bg_description) <= 255 characters Description of the billing group. |
name | string (name) <= 255 characters Name of the billing group. |
id | string (bg_id) ^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object | string Default: "billing_group" Value: "billing_group" Value is resource type. |
curl https://api.lob.com/v1/billing_groups/bg_4bb02b527a72667d0 \ -u <YOUR API KEY>:
{- "id": "bg_c94e83ca2cd5121",
- "name": "Marketing Dept",
- "description": "Usage group used for the Marketing Dept resource sends",
- "date_created": "2017-11-07T22:56:10.962Z",
- "date_modified": "2017-11-07T22:56:10.962Z",
- "object": "billing_group"
}
Updates all editable attributes of the billing_group with the given id.
bg_id required | string (bg_id) ^bg_[a-zA-Z0-9]+$ id of the billing_group |
description | string (bg_description) <= 255 characters Description of the billing group. |
name | string (name) <= 255 characters Name of the billing group. |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
description | string (bg_description) <= 255 characters Description of the billing group. |
name | string (name) <= 255 characters Name of the billing group. |
id | string (bg_id) ^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object | string Default: "billing_group" Value: "billing_group" Value is resource type. |
{- "name": "Marketing Dept",
- "description": "Usage group used for the Marketing Dept resource sends"
}
{- "id": "bg_c94e83ca2cd5121",
- "name": "Marketing Dept",
- "description": "Usage group used for the Marketing Dept resource sends",
- "date_created": "2017-11-07T22:56:10.962Z",
- "date_modified": "2017-11-07T22:56:10.962Z",
- "object": "billing_group"
}
Returns a list of your billing_groups. The billing_groups are returned sorted by creation date, with the most recently created billing_groups appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
offset | integer Default: 0 An integer that designates the offset at which to begin returning results. Defaults to 0. |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
object (date_filter) Filter by date modified. Accepted formats are ISO-8601 date or datetime, e.g. | |
object or object Sorts items by ascending or descending dates. Use either |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (billing_group) list of billing_groups |
curl -X GET "https://api.lob.com/v1/billing_groups?limit=2" \ -u <YOUR API KEY>:
{- "data": [
- {
- "id": "bg_d5a5a89da9106f8",
- "description": "Test billing_group",
- "metadata": { },
- "date_created": "2019-07-27T23:49:01.511Z",
- "date_modified": "2019-07-27T23:49:01.511Z",
- "object": "billing_group"
}, - {
- "id": "bg_59b2150ae120887",
- "description": "Test billing_group",
- "metadata": { },
- "date_created": "2019-03-29T10:22:34.642Z",
- "date_modified": "2019-03-29T10:22:34.642Z",
- "object": "billing_group"
}
], - "object": "list",
- "next_url": null,
- "prev_url": null,
- "count": 2
}
Creates a new billing_group with the provided properties.
name required | string (name) <= 255 characters Name of the billing group. |
description | string (bg_description) <= 255 characters Description of the billing group. |
ratelimit-limit | integer Example: 150 The rate limit for a given endpoint. |
ratelimit-remaining | integer Example: 100 The number of requests remaining in the current window. |
ratelimit-reset |
description | string (bg_description) <= 255 characters Description of the billing group. |
name | string (name) <= 255 characters Name of the billing group. |
id | string (bg_id) ^bg_[a-zA-Z0-9]+$ Unique identifier prefixed with |
date_created | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object | string Default: "billing_group" Value: "billing_group" Value is resource type. |
{- "name": "Marketing Dept",
- "description": "Usage group used for the Marketing Dept resource sends"
}
{- "id": "bg_c94e83ca2cd5121",
- "name": "Marketing Dept",
- "description": "Usage group used for the Marketing Dept resource sends",
- "date_created": "2017-11-07T22:56:10.962Z",
- "date_modified": "2017-11-07T22:56:10.962Z",
- "object": "billing_group"
}
The Buckslips endpoint allows you to easily create buckslips that can later be used as add-ons for Letters Campaigns. Note that a Letter Campaign with Buckslip add-on requires a minimum send quantity of 5,000 letters. The API provides endpoints for creating buckslips, retrieving individual buckslips, creating buckslip orders, and retrieving a list of buckslips.
Returns a list of your buckslips. The buckslips are returned sorted by creation date, with the most recently created buckslips appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (buckslip) list of buckslips |
curl -X GET "https://api.lob.com/v1/buckslips?limit=2" \ -u <YOUR API KEY>:
{- "data": [
- {
- "id": "bck_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": null,
- "size": "8.75x3.75",
- "has_front": true,
- "has_back": true,
- "auto_reorder": false,
- "reorder_quantity": null,
- "threshold_amount": 0,
- "thumbnails": [
- {
}
], - "available_quantity": 0,
- "allocated_quantity": 0,
- "onhand_quantity": 0,
- "pending_quantity": 0,
- "projected_quantity": 0,
- "buckslip_orders": [ ],
- "stock": "text",
- "weight": "80#",
- "finish": "gloss",
- "status": "rendered",
- "mode": "test",
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "buckslip"
}
], - "object": "list",
- "previous_url": null,
- "next_url": null,
- "count": 1
}
Creates a new buckslip given information
required | remote_file_url (string) or local_file_path (string) A PDF template for the front of the buckslip |
description | string or null (buckslip_description) <= 255 characters Description of the buckslip. |
size | string Default: "8.75x3.75" Value: "8.75x3.75" The size of the buckslip |
remote_file_url (string) or local_file_path (string) A PDF template for the back of the buckslip |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "buckslip" Value: "buckslip" Value is resource type. |
description required | string or null (buckslip_description) <= 255 characters Description of the buckslip. |
id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ Unique identifier prefixed with |
auto_reorder required | boolean Default: false True if the buckslips should be auto-reordered. |
reorder_quantity required | integer or null The number of buckslips to be reordered. |
threshold_amount required | integer Default: 0 The threshold amount of the buckslip |
url required | string <uri> [ 1 .. 2083 ] characters The signed link for the buckslip. |
raw_url required | string <uri> [ 1 .. 2083 ] characters The raw URL of the buckslip. |
front_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the front template. |
back_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the back template. |
required | Array of objects (thumbnail) |
available_quantity required | number Default: 0 The available quantity of buckslips. |
allocated_quantity required | number Default: 0 The allocated quantity of buckslips. |
onhand_quantity required | number Default: 0 The onhand quantity of buckslips. |
pending_quantity required | number Default: 0 The pending quantity of buckslips. |
projected_quantity required | number Default: 0 The sum of pending and onhand quantities of buckslips. |
required | Array of objects (buckslip_order) >= 0 items An array of buckslip orders that are associated with the buckslip. |
stock required | string (The stock of the buckslip.) Enum: "text" "cover" |
weight required | string (The weight of the buckslip.) Value: "80#" |
finish required | string (The finish of the buckslip.) Enum: "gloss" "matte" |
status required | string (The status of the buckslip.) Enum: "processed" "rendered" "failed" |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
size | string Default: "8.75x3.75" Value: "8.75x3.75" The size of the buckslip |
{- "description": "Test buckslip",
}
{- "id": "bck_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": "Test buckslip",
- "size": "8.75x3.755",
- "auto_reorder": false,
- "reorder_quantity": null,
- "threshold_amount": 0,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 0,
- "allocated_quantity": 0,
- "onhand_quantity": 0,
- "pending_quantity": 0,
- "projected_quantity": 0,
- "buckslip_orders": [ ],
- "stock": "text",
- "weight": "80#",
- "finish": "gloss",
- "status": "rendered",
- "mode": "test",
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "buckslip"
}
Retrieves the details of an existing buckslip. You need only supply the unique customer identifier that was returned upon buckslip creation.
buckslip_id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ id of the buckslip |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "buckslip" Value: "buckslip" Value is resource type. |
description required | string or null (buckslip_description) <= 255 characters Description of the buckslip. |
id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ Unique identifier prefixed with |
auto_reorder required | boolean Default: false True if the buckslips should be auto-reordered. |
reorder_quantity required | integer or null The number of buckslips to be reordered. |
threshold_amount required | integer Default: 0 The threshold amount of the buckslip |
url required | string <uri> [ 1 .. 2083 ] characters The signed link for the buckslip. |
raw_url required | string <uri> [ 1 .. 2083 ] characters The raw URL of the buckslip. |
front_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the front template. |
back_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the back template. |
required | Array of objects (thumbnail) |
available_quantity required | number Default: 0 The available quantity of buckslips. |
allocated_quantity required | number Default: 0 The allocated quantity of buckslips. |
onhand_quantity required | number Default: 0 The onhand quantity of buckslips. |
pending_quantity required | number Default: 0 The pending quantity of buckslips. |
projected_quantity required | number Default: 0 The sum of pending and onhand quantities of buckslips. |
required | Array of objects (buckslip_order) >= 0 items An array of buckslip orders that are associated with the buckslip. |
stock required | string (The stock of the buckslip.) Enum: "text" "cover" |
weight required | string (The weight of the buckslip.) Value: "80#" |
finish required | string (The finish of the buckslip.) Enum: "gloss" "matte" |
status required | string (The status of the buckslip.) Enum: "processed" "rendered" "failed" |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
size | string Default: "8.75x3.75" Value: "8.75x3.75" The size of the buckslip |
curl https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \ -u <YOUR API KEY>:
{- "id": "bck_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": "Test buckslip",
- "size": "8.75x3.755",
- "auto_reorder": false,
- "reorder_quantity": null,
- "threshold_amount": 0,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 0,
- "allocated_quantity": 0,
- "onhand_quantity": 0,
- "pending_quantity": 0,
- "projected_quantity": 0,
- "buckslip_orders": [ ],
- "stock": "text",
- "weight": "80#",
- "finish": "gloss",
- "status": "rendered",
- "mode": "test",
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "buckslip"
}
Update the details of an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.
buckslip_id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ id of the buckslip |
description | string or null (buckslip_description) <= 255 characters Description of the buckslip. |
auto_reorder | boolean Allows for auto reordering |
reorder_quantity | number [ 5000 .. 10000000 ] The quantity of items to be reordered (only required when auto_reorder is true). |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "buckslip" Value: "buckslip" Value is resource type. |
description required | string or null (buckslip_description) <= 255 characters Description of the buckslip. |
id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ Unique identifier prefixed with |
auto_reorder required | boolean Default: false True if the buckslips should be auto-reordered. |
reorder_quantity required | integer or null The number of buckslips to be reordered. |
threshold_amount required | integer Default: 0 The threshold amount of the buckslip |
url required | string <uri> [ 1 .. 2083 ] characters The signed link for the buckslip. |
raw_url required | string <uri> [ 1 .. 2083 ] characters The raw URL of the buckslip. |
front_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the front template. |
back_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the back template. |
required | Array of objects (thumbnail) |
available_quantity required | number Default: 0 The available quantity of buckslips. |
allocated_quantity required | number Default: 0 The allocated quantity of buckslips. |
onhand_quantity required | number Default: 0 The onhand quantity of buckslips. |
pending_quantity required | number Default: 0 The pending quantity of buckslips. |
projected_quantity required | number Default: 0 The sum of pending and onhand quantities of buckslips. |
required | Array of objects (buckslip_order) >= 0 items An array of buckslip orders that are associated with the buckslip. |
stock required | string (The stock of the buckslip.) Enum: "text" "cover" |
weight required | string (The weight of the buckslip.) Value: "80#" |
finish required | string (The finish of the buckslip.) Enum: "gloss" "matte" |
status required | string (The status of the buckslip.) Enum: "processed" "rendered" "failed" |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
size | string Default: "8.75x3.75" Value: "8.75x3.75" The size of the buckslip |
{- "description": "Test buckslip",
- "auto_reorder": true
}
{- "id": "bck_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": "Test buckslip",
- "size": "8.75x3.755",
- "auto_reorder": false,
- "reorder_quantity": null,
- "threshold_amount": 0,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 0,
- "allocated_quantity": 0,
- "onhand_quantity": 0,
- "pending_quantity": 0,
- "projected_quantity": 0,
- "buckslip_orders": [ ],
- "stock": "text",
- "weight": "80#",
- "finish": "gloss",
- "status": "rendered",
- "mode": "test",
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "buckslip"
}
Delete an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.
buckslip_id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ id of the buckslip |
id | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \ -u <YOUR API KEY>:
{- "id": "buckslip_123456789",
- "deleted": true
}
The Buckslip Orders endpoint allows you to easily create buckslip orders for existing buckslips. The API provides endpoints for creating buckslip orders and listing buckslip orders for a given buckslip.
Retrieves the buckslip orders associated with the given buckslip id.
buckslip_id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ The ID of the buckslip to which the buckslip orders belong. |
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
offset | integer Default: 0 An integer that designates the offset at which to begin returning results. Defaults to 0. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (buckslip_order) List of buckslip orders |
curl https://api.lob.com/v1/buckslips/bck_6afffd19045076c/orders/ \ -u <YOUR API KEY>:
{- "data": [
- {
- "id": "bo_e0f8a0562a06bea7f",
- "buckslip_id": "bck_6afffd19045076c",
- "status": "available",
- "quantity_ordered": 5000,
- "unit_price": 0.75,
- "cancelled_reason": "No longer needed",
- "availability_date": "2021-10-12T21:41:48.326Z",
- "expected_availability_date": "2021-11-04T21:03:18.871Z",
- "date_created": "2021-10-07T21:03:18.871Z",
- "date_modified": "2021-10-16T01:00:30.144Z",
- "object": "buckslip_order"
}
], - "object": "list",
- "next_url": null,
- "previous_url": null,
- "count": 1
}
Creates a new buckslip order given information
buckslip_id required | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ The ID of the buckslip to which the buckslip orders belong. |
quantity required | integer [ 5000 .. 10000000 ] The quantity of buckslips in the order (minimum 5,000). |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string (object) Value is resource type. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
id | string (bo_id) ^bo_[a-zA-Z0-9]+$ Unique identifier prefixed with |
buckslip_id | string (buckslip_id) ^bck_[a-zA-Z0-9]+$ Unique identifier prefixed with |
status | string Enum: "pending" "printing" "available" "cancelled" "depleted" The status of the buckslip order. |
quantity_ordered | number Default: 0 The quantity of buckslips ordered. |
unit_price | number Default: 0 The unit price for the buckslip order. |
inventory | number Default: 0 The inventory of the buckslip order. |
cancelled_reason | string The reason for cancellation. |
availability_date | string <date-time> A timestamp in ISO 8601 format of the date the resource was created. |
expected_availability_date | string <date-time> The fixed deadline for the buckslips to be printed. |
{- "quantity": 10000
}
{- "id": "bo_e0f8a0562a06bea7f",
- "buckslip_id": "bck_6afffd19045076c",
- "status": "available",
- "quantity_ordered": 10000,
- "unit_price": 0.75,
- "cancelled_reason": "No longer needed",
- "availability_date": "2021-10-12T21:41:48.326Z",
- "expected_availability_date": "2021-11-04T21:03:18.871Z",
- "date_created": "2021-10-07T21:03:18.871Z",
- "date_modified": "2021-10-16T01:00:30.144Z",
- "object": "buckslip_order"
}
The cards endpoint allows you to easily create cards that can later be affixed to Letters. The API provides endpoints for creating cards, retrieving individual cards, creating card orders, and retrieving a list of cards.
Returns a list of your cards. The cards are returned sorted by creation date, with the most recently created addresses appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
include | Array of strings Request that the response include the total count by specifying |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (card) list of cards |
curl -X GET "https://api.lob.com/v1/cards?limit=2" \ -u <YOUR API KEY>:
{- "data": [
- {
- "id": "card_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": null,
- "size": "2.125x3.375",
- "auto_reorder": false,
- "reorder_quantity": null,
- "thumbnails": [
- {
}
], - "available_quantity": 10000,
- "pending_quantity": 0,
- "countries": null,
- "status": "rendered",
- "mode": "test",
- "orientation": "horizontal",
- "threshold_amount": 0,
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "card"
}
], - "object": "list",
- "previous_url": null,
- "next_url": null,
- "count": 1
}
Creates a new card given information
required | remote_file_url (string) or local_file_path (string) A PDF template for the front of the card |
description | string or null (card_description) <= 255 characters Description of the card. |
size | string Default: "2.125x3.375" Enum: "3.375x2.125" "2.125x3.375" The size of the card |
remote_file_url (string) or local_file_path (string) Default: "https://s3.us-west-2.amazonaws.com/public.lob.com/assets/card_blank_horizontal.pdf" A PDF template for the back of the card |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "card" Value: "card" Value is resource type. |
description required | string or null (card_description) <= 255 characters Description of the card. |
id required | string (card_id) ^card_[a-zA-Z0-9]+$ Unique identifier prefixed with |
url required | string <uri> [ 1 .. 2083 ] characters The signed link for the card. |
auto_reorder required | boolean Default: false True if the cards should be auto-reordered. |
reorder_quantity required | integer or null The number of cards to be reordered. |
raw_url required | string <uri> [ 1 .. 2083 ] characters The raw URL of the card. |
front_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the front template. |
back_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the back template. |
required | Array of objects (thumbnail) |
available_quantity required | integer Default: 0 The available quantity of cards. |
pending_quantity required | integer Default: 0 The pending quantity of cards. |
status required | string (The status of the card.) Enum: "processed" "rendered" |
orientation required | string Default: "horizontal" Enum: "horizontal" "vertical" The orientation of the card. |
threshold_amount required | integer Default: 0 The threshold amount of the card |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
size | string Default: "2.125x3.375" Enum: "3.375x2.125" "2.125x3.375" The size of the card |
{- "description": "Test card",
- "size": "2.125x3.375"
}
{- "id": "card_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": "Test card",
- "size": "2.125x3.375",
- "auto_reorder": false,
- "reorder_quantity": null,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 10000,
- "pending_quantity": 0,
- "countries": null,
- "status": "rendered",
- "mode": "test",
- "orientation": "horizontal",
- "threshold_amount": 0,
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "card"
}
Retrieves the details of an existing card. You need only supply the unique customer identifier that was returned upon card creation.
card_id required | string (card_id) ^card_[a-zA-Z0-9]+$ id of the card |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "card" Value: "card" Value is resource type. |
description required | string or null (card_description) <= 255 characters Description of the card. |
id required | string (card_id) ^card_[a-zA-Z0-9]+$ Unique identifier prefixed with |
url required | string <uri> [ 1 .. 2083 ] characters The signed link for the card. |
auto_reorder required | boolean Default: false True if the cards should be auto-reordered. |
reorder_quantity required | integer or null The number of cards to be reordered. |
raw_url required | string <uri> [ 1 .. 2083 ] characters The raw URL of the card. |
front_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the front template. |
back_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the back template. |
required | Array of objects (thumbnail) |
available_quantity required | integer Default: 0 The available quantity of cards. |
pending_quantity required | integer Default: 0 The pending quantity of cards. |
status required | string (The status of the card.) Enum: "processed" "rendered" |
orientation required | string Default: "horizontal" Enum: "horizontal" "vertical" The orientation of the card. |
threshold_amount required | integer Default: 0 The threshold amount of the card |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
size | string Default: "2.125x3.375" Enum: "3.375x2.125" "2.125x3.375" The size of the card |
curl https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \ -u <YOUR API KEY>:
{- "id": "card_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": "Test card",
- "size": "2.125x3.375",
- "auto_reorder": false,
- "reorder_quantity": null,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 10000,
- "pending_quantity": 0,
- "countries": null,
- "status": "rendered",
- "mode": "test",
- "orientation": "horizontal",
- "threshold_amount": 0,
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "card"
}
Update the details of an existing card. You need only supply the unique identifier that was returned upon card creation.
card_id required | string (card_id) ^card_[a-zA-Z0-9]+$ id of the card |
description | string or null (card_description) <= 255 characters Description of the card. |
auto_reorder | boolean Allows for auto reordering |
reorder_quantity | number [ 10000 .. 10000000 ] The quantity of items to be reordered (only required when auto_reorder is true). |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string Default: "card" Value: "card" Value is resource type. |
description required | string or null (card_description) <= 255 characters Description of the card. |
id required | string (card_id) ^card_[a-zA-Z0-9]+$ Unique identifier prefixed with |
url required | string <uri> [ 1 .. 2083 ] characters The signed link for the card. |
auto_reorder required | boolean Default: false True if the cards should be auto-reordered. |
reorder_quantity required | integer or null The number of cards to be reordered. |
raw_url required | string <uri> [ 1 .. 2083 ] characters The raw URL of the card. |
front_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the front template. |
back_original_url required | string <uri> [ 1 .. 2083 ] characters The original URL of the back template. |
required | Array of objects (thumbnail) |
available_quantity required | integer Default: 0 The available quantity of cards. |
pending_quantity required | integer Default: 0 The pending quantity of cards. |
status required | string (The status of the card.) Enum: "processed" "rendered" |
orientation required | string Default: "horizontal" Enum: "horizontal" "vertical" The orientation of the card. |
threshold_amount required | integer Default: 0 The threshold amount of the card |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
size | string Default: "2.125x3.375" Enum: "3.375x2.125" "2.125x3.375" The size of the card |
{- "description": "Test card",
- "auto_reorder": true
}
{- "id": "card_7a6d73c5c8457fc",
- "account_id": "fa9ea650fc7b31a89f92",
- "description": "Test card",
- "size": "2.125x3.375",
- "auto_reorder": false,
- "reorder_quantity": null,
- "thumbnails": [
- {
}, - {
}
], - "available_quantity": 10000,
- "pending_quantity": 0,
- "countries": null,
- "status": "rendered",
- "mode": "test",
- "orientation": "horizontal",
- "threshold_amount": 0,
- "date_created": "2021-03-24T22:51:42.838Z",
- "date_modified": "2021-03-24T22:51:42.838Z",
- "send_date": "2021-03-24T22:51:42.838Z",
- "object": "card"
}
Delete an existing card. You need only supply the unique identifier that was returned upon card creation.
card_id required | string (card_id) ^card_[a-zA-Z0-9]+$ id of the card |
id | string (card_id) ^card_[a-zA-Z0-9]+$ Unique identifier prefixed with |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
curl -X DELETE https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \ -u <YOUR API KEY>:
{- "id": "card_123456789",
- "deleted": true
}
The card orders endpoint allows you to easily create card orders for existing cards. The API provides endpoints for creating card orders and listing card orders for a given card.
Retrieves the card orders associated with the given card id.
card_id required | string (card_id) ^card_[a-zA-Z0-9]+$ The ID of the card to which the card orders belong. |
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
offset | integer Default: 0 An integer that designates the offset at which to begin returning results. Defaults to 0. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (card_order) List of card orders |
curl https://api.lob.com/v1/cards/card_6afffd19045076c/orders/ \ -u <YOUR API KEY>:
{- "data": [
- {
- "id": "co_e0f8a0562a06bea7f",
- "card_id": "card_6afffd19045076c",
- "status": "available",
- "inventory": 9500,
- "quantity_ordered": 10000,
- "unit_price": 0.75,
- "cancelled_reason": "No longer needed",
- "availability_date": "2021-10-12T21:41:48.326Z",
- "expected_availability_date": "2021-11-04T21:03:18.871Z",
- "date_created": "2021-10-07T21:03:18.871Z",
- "date_modified": "2021-10-16T01:00:30.144Z",
- "object": "card_order"
}
], - "object": "list",
- "next_url": null,
- "previous_url": null,
- "count": 1
}
Creates a new card order given information
card_id required | string (card_id) ^card_[a-zA-Z0-9]+$ The ID of the card to which the card orders belong. |
quantity required | integer [ 10000 .. 10000000 ] The quantity of cards in the order (minimum 10,000). |
date_created required | string <date-time> (date_created) A timestamp in ISO 8601 format of the date the resource was created. |
date_modified required | string <date-time> (date_modified) A timestamp in ISO 8601 format of the date the resource was last modified. |
object required | string (object) Value is resource type. |
deleted | boolean (deleted) Only returned if the resource has been successfully deleted. |
id | string (co_id) ^co_[a-zA-Z0-9]+$ Unique identifier prefixed with |
card_id | string (card_id) ^card_[a-zA-Z0-9]+$ Unique identifier prefixed with |
status | string Enum: "pending" "printing" "available" "cancelled" "depleted" The status of the card order. |
inventory | number Default: 0 The inventory of the card order. |
quantity_ordered | number Default: 0 The quantity of cards ordered |
unit_price | number Default: 0 The unit price for the card order. |
cancelled_reason | string The reason for cancellation. |
availability_date | string <date-time> A timestamp in ISO 8601 format of the date the resource was created. |
expected_availability_date | string <date-time> The fixed deadline for the cards to be printed. |
{- "quantity": 10000
}
{- "id": "co_e0f8a0562a06bea7f",
- "card_id": "card_6afffd19045076c",
- "status": "available",
- "inventory": 9500,
- "quantity_ordered": 10000,
- "unit_price": 0.75,
- "cancelled_reason": "No longer needed",
- "availability_date": "2021-10-12T21:41:48.326Z",
- "expected_availability_date": "2021-11-04T21:03:18.871Z",
- "date_created": "2021-10-07T21:03:18.871Z",
- "date_modified": "2021-10-16T01:00:30.144Z",
- "object": "card_order"
}
Lob QR codes allow you to generate a QR code that is unique to each mailpiece, thereby allowing each and every customers to receive a personalized link. See the Create endpoint for Letters, Postcards or Self Mailers to learn how to embed a QR code into your mail piece.
Webhooks can be used to integrate Lob QR code scans into your omni channel marketing strategy. See the Webhooks section of our documentation to learn how to enable the letter.viewed
, postcard.viewed
and self_mailer.viewed
event notifications for your mail pieces.
Furthermore, our QR code Analytics endpoint can be used to track the impact and engagement rate of your mail sends. Lob can tell you exactly which recipients opened your mailpiece. Our Analytics endpoint allows you to see exactly which recipient scanned a mailpiece, when they scanned it, and more!
Returns a list of your QR codes. The QR codes are returned sorted by scan date, with the most recently scanned QR codes appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
offset | integer Default: 0 An integer that designates the offset at which to begin returning results. Defaults to 0. |
include | Array of strings Request that the response include the total count by specifying |
object (date_filter) Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. | |
scanned | boolean Filter list of responses to only include QR codes with at least one scan event. |
resource_ids | Array of arrays <= 100 items Default: [] Filter by the resource ID. |
object | string (object) Value is resource type. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
scanned_count | integer Indicates the number of QR Codes out of |
Array of objects (qr_code_scans) List of QR code analytics |
curl -X GET "https://api.lob.com/v1/qr_code_analytics?limit=2&scanned=true" \ -u <YOUR API KEY>:
{- "data": [
- {
- "resource_id": "ltr_d5a5a89da9106f8",
- "date_created": "2019-07-27T23:49:01.511Z",
- "number_of_scans": 2,
- "scans": [
- {
- "ip_location": "127.0.0.1",
- "scan_date": "2022-07-27T23:49:01.511Z"
}, - {
- "ip_location": "127.0.0.1",
- "scan_date": "2022-07-29T23:45:00.436Z"
}
]
}, - {
- "resource_id": "psc_d5a5a89da9106f8",
- "date_created": "2022-09-27T23:49:01.511Z",
- "number_of_scans": 1,
- "scans": [
- {
- "ip_location": "127.0.0.1",
- "scan_date": "2022-09-27T23:49:01.511Z"
}
]
}
], - "object": "list",
- "count": 2,
- "scanned_count": 2,
- "total_count": 2
}
Lob's URL shortener allows you to generate unique short links, either with Lob's own domain or your own custom domains. Each custom link enables Lob to track mail individually and provide customers the relevant tracking data in their dashboard.
Webhooks can be used to integrate Lob's URL Shortener scans into your omni channel marketing stratergy. See the Webhooks section of our documentation to learn how to enable the letter.viewed
, postcard.viewed
and self_mailer.viewed
event notifications for your mail pieces.
Furthermore, you can use our Retrieve endpoints to track the impact and engagement rate of links created.
Retrieve details for a single domain.
domain_id required | string Unique identifier for a domain. |
id | string Unique identifier for a domain. |
domain | string The registered domain/hostname. |
error_redirect_link | string URL to redirect customers if a short link is broken or inactive. |
status | string Enum: "configured" "not_configured" The configuration status of the domain. |
created_at | string The date and time the domain was created. |
updated_at | string The date and time the domain was last updated. |
curl -X GET "https://api.lob.com/v1/domains/{domain_id}" \ -u <YOUR_LIVE_API_KEY>:
{- "id": "string",
- "domain": "string",
- "error_redirect_link": "string",
- "status": "configured",
- "created_at": "string",
- "updated_at": "string"
}
Delete a registered domain. This operation can only be performed if all associated links with the domain are deleted.
domain_id required | string Unique identifier for a domain. |
id | string Unique identifier for a domain. |
deleted | boolean Only returned if the domain was successfully deleted. |
{- "id": "string",
- "deleted": true
}
Add a new custom domain that can be used to create custom links.
domain required | string (domain) The registered domain/hostname. |
error_redirect_link | string (error_redirect_link) URL to redirect customers if a short link is broken or inactive. |
id | string Unique identifier for a domain. |
domain | string The registered domain/hostname. |
error_redirect_link | string URL to redirect customers if a short link is broken or inactive. |
status | string Enum: "configured" "not_configured" The configuration status of the domain. |
created_at | string The date and time the domain was created. |
updated_at | string The date and time the domain was last updated. |
{- "domain": "lob.st"
}
{- "id": "string",
- "domain": "string",
- "error_redirect_link": "string",
- "status": "configured",
- "created_at": "string",
- "updated_at": "string"
}
Retrieve a list of all created domains.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
status | string Enum: "configured" "not_configured" Filter domains by their configuration status. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (domain_response) List of domains. |
curl -X GET "https://api.lob.com/v1/domains?limit=2" \ -u <YOUR_LIVE_API_KEY>:
{- "object": "string",
- "next_url": "string",
- "previous_url": "string",
- "count": 0,
- "total_count": 0,
- "data": [
- {
- "id": "string",
- "domain": "string",
- "error_redirect_link": "string",
- "status": "configured",
- "created_at": "string",
- "updated_at": "string"
}
]
}
Retrieves a single shortened link.
link_id required | string Unique identifier for a link. |
id | string Unique identifier prefixed with |
title | string The title of the URL. |
domain_id | string A unique identifier for the registered domain. |
redirect_link | string (redirect_link) The original target URL. |
short_link | string The shortened URL for the associated original URL. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
created_at | string The date and time the link was created. |
updated_at | string The date and time the link was last updated. |
curl -X GET "https://api.lob.com/v1/links/<link_id>" \ -u <YOUR_LIVE_API_KEY>:
{- "id": "string",
- "title": "string",
- "domain_id": "string",
- "redirect_link": "string",
- "short_link": "string",
- "metadata": {
- "property1": "string",
- "property2": "string"
}, - "created_at": "string",
- "updated_at": "string"
}
Update any of the properties of a shortened link.
link_id required | string Unique identifier for a link. |
redirect_link required | string (redirect_link) The original target URL. |
title | string The title of the URL. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
id | string Unique identifier prefixed with |
title | string The title of the URL. |
domain_id | string A unique identifier for the registered domain. |
redirect_link | string (redirect_link) The original target URL. |
short_link | string The shortened URL for the associated original URL. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
created_at | string The date and time the link was created. |
updated_at | string The date and time the link was last updated. |
{- "resource_id": "ltr_133"
}
{- "id": "string",
- "title": "string",
- "domain_id": "string",
- "redirect_link": "string",
- "short_link": "string",
- "metadata": {
- "property1": "string",
- "property2": "string"
}, - "created_at": "string",
- "updated_at": "string"
}
Delete the shortened link.
link_id required | string Unique identifier for a link. |
id | string Unique identifier for a link. |
deleted | boolean Only returned if the link was successfully deleted. |
{- "id": "string",
- "deleted": true
}
Given a long URL, shorten your URL either by using a custom domain or Lob's own short domain.
redirect_link required | string (redirect_link) The original target URL. |
title | string The title of the URL. |
domain | string Default: "lob.st" The registered domain to be used for the short URL. |
slug | string The unique path for the shortened URL, if empty a unique path will be used. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 |
id | string Unique identifier prefixed with |
title | string The title of the URL. |
domain_id | string A unique identifier for the registered domain. |
redirect_link | string (redirect_link) The original target URL. |
short_link | string The shortened URL for the associated original URL. |
object (metadata) <= 500 characters [^"\\]{0,500} 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 | |
created_at | string The date and time the link was created. |
updated_at | string The date and time the link was last updated. |
{- "slug": "a1b2c3"
}
{- "id": "string",
- "title": "string",
- "domain_id": "string",
- "redirect_link": "string",
- "short_link": "string",
- "metadata": {
- "property1": "string",
- "property2": "string"
}, - "created_at": "string",
- "updated_at": "string"
}
Retrieves a list of shortened links. The list is sorted by creation date, with the most recently created appearing first.
limit | integer [ 1 .. 100 ] Default: 10 Example: limit=10 How many results to return. |
object or object
| |
campaign_id | string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$ Filters resources created by the provided campaign id, prefixed with |
domain_id | string^(dom)_[a-zA-Z0-9]+$ Filters links by the provided domain id. |
object | string (object) Value is resource type. |
next_url | string or null Url of next page of items in list. |
previous_url | string or null Url of previous page of items in list. |
count | integer (count) number of resources in a set |
total_count | integer Indicates the total number of records. Provided when the request specifies an "include" query parameter |
Array of objects (link_response) List of links |
curl -X GET "https://api.lob.com/v1/links?limit=2" \ -u <YOUR_LIVE_API_KEY>:
{- "object": "string",
- "next_url": "string",
- "previous_url": "string",
- "count": 0,
- "total_count": 0,
- "data": [
- {
- "id": "string",
- "title": "string",
- "domain_id": "string",
- "redirect_link": "string",
- "short_link": "string",
- "metadata": {
- "property1": "string",
- "property2": "string"
}, - "created_at": "string",
- "updated_at": "string"
}
]
}
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!
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.
ATTRIBUTE | DESCRIPTION |
---|---|
code |
A consistent machine-keyable string identifying the error |
status_code |
A conventional HTTP status code |
message |
A human-readable, subject-to-change message with more details about the error |
STATUS_CODE | CODE | MESSAGE |
---|---|---|
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 amount of time |
500 |
SERVER ERROR | An internal server error occurred, please contact support@lob.com |
STATUS_CODE | CODE | MESSAGE |
---|---|---|
422 |
BAD_REQUEST | An invalid request was made. See error message for details. |
409/422 |
CONFLICT | This operation would leave data in a conflicted state. |
403 |
FEATURE_LIMIT_REACHED | The account has reached its resource limit and requires upgrading to add more. |
500 |
INTERNAL_SERVER_ERROR | An error has occured on Lob's servers. Please try request again. |
422 |
INVALID | An invalid request was made. See error message for details. |
422 |
NOT_DELETABLE | An attempt was made to delete a resource, but the resource cannot be deleted. |
404 |
NOT_FOUND | The requested resource was not found. |
408 |
REQUEST_TIMEOUT | The request took too long. Please try again. |
503 |
SERVICE_UNAVAILABLE | The Lob servers are temporarily unavailable. Please try again. |
404 |
UNRECOGNIZED_ENDPOINT | The requested endpoint doesn't exist. |
422 |
UNSUPPORTED_LOB_VERSION | An unsupported Lob API version was requested. |
STATUS_CODE | CODE | MESSAGE |
---|---|---|
401 |
EMAIL_REQUIRED | Account must have a verified email address before creating live resources. |
401 |
UNAUTHORIZED | The request isn't authorized. |
401 |
UNAUTHORIZED_TOKEN | Token isn't authorized. |
401/403 |
INVALID_API_KEY | The API key is invalid. |
403 |
PUBLISHABLE_KEY_NOT_ALLOWED | The requested operation needs a secret key, not a publishable key. See [API Keys](#tag/API-Keys) for more information. |
429 |
RATE_LIMIT_EXCEEDED | Requests were sent too quickly and must be slowed down. |
STATUS_CODE | CODE | MESSAGE |
---|---|---|
401 |
PAYMENT_METHOD_UNVERIFIED | You must have a verified bank account or credit card to submit live requests. |
404 |
DELETED_BANK_ACCOUNT | Checks cannot be created with a deleted bank account. |
422 |
ADDRESS_LENGTH_EXCEEDS_LIMIT | The sum of to.address_line1 and to.address_line2 cannot surpass 50 characters. |
422 |
BANK_ACCOUNT_ALREADY_VERIFIED | The bank account has already been verified. |
422 |
BANK_ERROR | There's an issue with the bank account. |
403 |
BILLING_ADDRESS_REQUIRED | In order to create a live mail piece, your account needs to set up a billing address. |
422 |
CUSTOM_ENVELOPE_INVENTORY_DEPLETED | Custom envelope inventory is depleted, and more will need to be ordered. |
422 |
FAILED_DELIVERABILITY_STRICTNESS | The to address doesn't meet strictness requirements. See Account Settings to configure strictness. |
422 |
FILE_PAGES_BELOW_MIN | Not enough pages. |
422 |
FILE_PAGES_EXCEED_MAX | Too many pages. |
422 |
FILE_SIZE_EXCEEDS_LIMIT | The file size is too large. See description for details. |
422 |
FOREIGN_RETURN_ADDRESS | The 'from' address must be a US address. |
422 |
INCONSISTENT_PAGE_DIMENSIONS | All pages of the input file must have the same dimensions. |
422 |
INVALID_BANK_ACCOUNT | The provided bank routing number is invalid. |
422 |
INVALID_BANK_ACCOUNT_VERIFICATION | Verification amounts do not match. |
422 |
INVALID_CHECK_INTERNATIONAL | Checks cannot be sent internationally. |
422 |
INVALID_COUNTRY_COVID | The postal service in the specified country is currently unable to process the request due to COVID-19 restrictions. |
422 |
INVALID_FILE | The file is invalid. |
422 |
INVALID_FILE_DIMENSIONS | File dimensions are incorrect for the selected mail type. |
422 |
INVALID_FILE_DOWNLOAD_TIME | File download from remote server took too long. |
422 |
INVALID_FILE_URL | The file URL when creating a resource is invalid. |
422 |
INVALID_IMAGE_DPI | DPI must be at least 300. |
422 |
INVALID_INTERNATIONAL_FEATURE | The specified product cannot be sent to the destination. |
422 |
INVALID_PERFORATION_RETURN_ENVELOPE | Both `return_envelope` and `perforation` must be used together. |
422 |
INVALID_TEMPLATE_HTML | The provided HTML is invalid. |
422 |
MAIL_USE_TYPE_CAN_NOT_BE_NULL | `use_type` must be one of "marketing" or "operational". Alternatively, an admin can set the account default use type in Account Settings. |
422 |
MERGE_VARIABLE_REQUIRED | A required merge variable is missing. |
422 |
MERGE_VARIABLE_WHITESPACE | Merge variable names cannot contain whitespace. |
422 |
PDF_ENCRYPTED | An encrypted PDF was provided. |
422 |
SPECIAL_CHARACTERS_RESTRICTED | Cannot use special characters for merge variable names. |
422 |
UNEMBEDDED_FONTS | The provided PDF contains non-standard unembedded fonts. See description for details. |
To prevent misuse, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits. By default, all accounts and their corresponding Test and Live API Keys have a rate limit of 150 requests per 5 seconds per endpoint. The POST /v1/us_verifications
and POST /v1/us_autocompletions
endpoints have a limit of 300 requests per 5 seconds for all accounts.
When your application exceeds the rate limit for a given API endpoint, the Lob API will return an HTTP 429 "Too Many Requests" response code instead of the variety of codes you would find across the other API endpoints.
HTTP Headers
HTTP headers are returned on each request to a rate limited endpoint. Ensure that you inspect these headers during your requests as they provide relevant data on how many more requests your application is allowed to make for the endpoint you just utilized.
While the headers are documented here in titlecase, HTTP headers are case insensitive and certain libraries may transform them to lowercase. Please inspect your headers carefully to see how they will be represented in your chosen development scenario.
X-Rate-Limit-Limit: | the rate limit ceiling for a given request |
X-Rate-Limit-Remaining: | the number of requests remaining in this window |
X-Rate-Limit-Reset: | the time at which the rate limit window resets (in UTC epoch seconds) |
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:
javascript { "error": { "message": "Rate limit exceeded. Please wait 5 seconds and try your request again.", "code": "rate_limit_exceeded", "status_code": 429 } }
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.
Query parameters which consist of lists of strings require that all elements of
the list be double-quoted, as per query filter standards.
Lob supports idempotency for safely retrying POST
requests to create
postcards, self mailers, letters, and checks without accidentally creating
duplicates.
For example, if a request to create a check fails due to a network error, you can safely retry the same request with the same idempotency key and guarantee that only one check will ultimately be created and sent. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned.
To perform an idempotent POST
request to one of the mailpiece product
endpoints, provide an additional Idempotency-Key
header or an idempotency_key
query parameter to the request. If multiple idempotency keys are provided,
the request will fail. How you create unique keys is up to you, but we
suggest using random values, such as V4 UUIDs. Idempotency keys are intended
to prevent issues over a short periods of time, therefore keys expire after
24 hours. Keys are unique by mode (Test vs. Live) as well as by resource
(postcard vs. letter, etc.).
By default, all GET
and DELETE
requests are idempotent by nature, so
they do not require an additional idempotency key.
For more help integrating idempotency keys, refer to our implementation guide.
Headers
Idempotency-Key: |
optional
A string of no longer than 256 characters that uniquely identifies this resource. |
Query Parameters
idempotency-key: |
optional
A string of no longer than 256 characters that uniquely identifies this resource. |
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-H "Idempotency-Key: 026e7634-24d7-486c-a0bb-4a17fd0eebc5" \
-d "to=adr_bae820679f3f536b" \
-d "from=adr_210a8d4b0b76d77b" \
--data-urlencode "front=<html style='margin: 130px; font-size: 50;'>Front HTML for {{name}}</html>" \
--data-urlencode "back=<html style='margin: 130px; font-size: 50;'>Back HTML</html>" \
-d "merge_variables[name]=Harry"
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.
curl https://api.lob.com/v1/postcards \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-d "description=Demo Postcard job" \
-d "metadata[campaign]=NEWYORK2015" \
-d "to=adr_bae820679f3f536b" \
-d "from=adr_210a8d4b0b76d77b" \
--data-urlencode "front=<html style='margin: 130px; font-size: 50;'>Front HTML for {{name}}</html>" \
--data-urlencode "back=<html style='margin: 130px; font-size: 50;'>Back HTML</html>" \
-d "merge_variables[name]=Harry"
curl -g "https://api.lob.com/v1/postcards?metadata[campaign]=NEWYORK2015&limit=2" \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
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 SDKs, the generation of the request bodies is done for you automatically and you don't need to worry about the format.
For fields that are intended to accept only string values, submitting JSON objects in string format (stringified JSON objects) is not supported. Our system automatically parses and validates incoming data according to their expected types. As a result, providing a stringified JSON object in a field designated for string input can cause parsing errors or lead to unexpected validation results.
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=210 King 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": "210 King 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--
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 Intl 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_
.
When backwards-incompatible changes are made to the API, a new dated version is released. The latest version of the API is version 2024-01-01. All versions prior to, and inclusive of, 2019-02-11 have been sunsetted. 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.
curl https://api.lob.com/v1/addresses \
-u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \
-H "Lob-Version: 2024-01-01"
You might be wondering why our API and specification use different versioning schemes. Lob's API predates our specification and follows the Stripe versioning approach. This works well to manage backwards-incompatible changes to our API.
For our API specification (used to create this documentation), we've chosen semantic versioning. This versioning reflects the backward-compatible changes that do not require a versioning of Lob's API.
Lob's API specification will be used to generate artifacts like documentation, client SDKs, and other developer tooling. Semantic versioning of our specification will inform how we version those artifacts like SDKs. It is helpful to know the version of a specification used to produce an artifact in order reference the specification release notes.