diff --git a/docs/index.html b/docs/index.html index 9c3d5159..b8992beb 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2989,7 +2989,7 @@ -
API docs by Redocly
API docs by Redocly

Lob (1.19.39)

Lob Developer Experience: lob-openapi@lob.com URL: https://support.lob.com/ License: MIT Terms of Service

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.

+ " fill="currentColor">

Lob (1.19.42)

Lob Developer Experience: lob-openapi@lob.com URL: https://support.lob.com/ License: MIT Terms of Service

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.

Introduction

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.

@@ -3268,7 +3268,7 @@

3. Learn more

Array of objects or null (tracking_event_normal)

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

campaign_id
string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$

Denotes resources created by the provided campaign id, prefixed with cmp_. In the case of snap packs, booklets, and letters with size us_legal, however, the campaign id is prefixed with camp_ instead of cmp_.

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 4x6 or A5 postcard sizes.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 4x6 or A5 postcard sizes.

status
string (status)
Enum: "processed" "rendered" "failed"

A string describing the PDF render status:

  • processed - the rendering process is currently in progress.
    • @@ -3363,7 +3363,7 @@

    3. Learn more

adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object)))

Required if to address is international. 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.

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 4x6 or A5 postcard sizes.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 4x6 or A5 postcard sizes.

Responses

Response Headers
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.

@@ -3393,7 +3393,7 @@

3. Learn more

Array of objects or null (tracking_event_normal)

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

campaign_id
string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$

Denotes resources created by the provided campaign id, prefixed with cmp_. In the case of snap packs, booklets, and letters with size us_legal, however, the campaign id is prefixed with camp_ instead of cmp_.

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 4x6 or A5 postcard sizes.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 4x6 or A5 postcard sizes.

status
string (status)
Enum: "processed" "rendered" "failed"

A string describing the PDF render status:

  • processed - the rendering process is currently in progress.
    • @@ -3424,7 +3424,7 @@

    3. Learn more

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: {{variable_name}}, pass in {"variable_name": "Harry"} to render Harry. merge_variables must be an object. Any type of value is accepted as long as the object is valid JSON; you can use strings, numbers, booleans, arrays, objects, or null. The max length of the object is 25,000 characters. If you call JSON.stringify on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: !, ", #, %, &, ', (, ), *, +, ,, /, ;, <, =, >, @, [, \, ], ^, `, {, |, }, ~. More instructions can be found in our guide to using html and merge variables. Depending on your Merge Variable strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs.

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 send_date has passed, the mailpiece can be canceled. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

-
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 17.75x9_trifold size is in beta. Contact support@lob.com or your account contact to learn more.

+
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 17.75x9_trifold size is in beta. Contact support@lob.com or your account contact to learn more.

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 send_date.

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.

@@ -3435,7 +3435,7 @@

3. Learn more

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 time. Not populated in test mode.

-
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 11x9_bifold self-mailer size.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 11x9_bifold self-mailer size.

status
string (status)
Enum: "processed" "rendered" "failed"

A string describing the PDF render status:

  • processed - the rendering process is currently in progress.
    • @@ -3526,11 +3526,11 @@

    3. Learn more

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: {{variable_name}}, pass in {"variable_name": "Harry"} to render Harry. merge_variables must be an object. Any type of value is accepted as long as the object is valid JSON; you can use strings, numbers, booleans, arrays, objects, or null. The max length of the object is 25,000 characters. If you call JSON.stringify on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: !, ", #, %, &, ', (, ), *, +, ,, /, ;, <, =, >, @, [, \, ], ^, `, {, |, }, ~. More instructions can be found in our guide to using html and merge variables. Depending on your Merge Variable strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs.

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 send_date has passed, the mailpiece can be canceled. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

-
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 17.75x9_trifold size is in beta. Contact support@lob.com or your account contact to learn more.

+
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 17.75x9_trifold size is in beta. Contact support@lob.com or your account contact to learn more.

adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object)))

Required if to address is international. 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.

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 11x9_bifold self-mailer size.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 11x9_bifold self-mailer size.

Responses

Response Headers
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.

@@ -3549,7 +3549,7 @@

3. Learn more

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: {{variable_name}}, pass in {"variable_name": "Harry"} to render Harry. merge_variables must be an object. Any type of value is accepted as long as the object is valid JSON; you can use strings, numbers, booleans, arrays, objects, or null. The max length of the object is 25,000 characters. If you call JSON.stringify on your object, it can be no longer than 25,000 characters. Your variable names cannot contain any whitespace or any of the following special characters: !, ", #, %, &, ', (, ), *, +, ,, /, ;, <, =, >, @, [, \, ], ^, `, {, |, }, ~. More instructions can be found in our guide to using html and merge variables. Depending on your Merge Variable strictness setting, if you define variables in your HTML but do not pass them here, you will either receive an error or the variable will render as an empty string. These settings only apply on HTML templates and not on QR code redirect URLs.

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 send_date has passed, the mailpiece can be canceled. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

-
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 17.75x9_trifold size is in beta. Contact support@lob.com or your account contact to learn more.

+
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 17.75x9_trifold size is in beta. Contact support@lob.com or your account contact to learn more.

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 send_date.

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.

@@ -3560,7 +3560,7 @@

3. Learn more

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 time. Not populated in test mode.

-
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 11x9_bifold self-mailer size.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for 11x9_bifold self-mailer size.

status
string (status)
Enum: "processed" "rendered" "failed"

A string describing the PDF render status:

  • processed - the rendering process is currently in progress.
    • @@ -3614,7 +3614,7 @@

    3. Learn more

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 cmp_. In the case of snap packs, booklets, and letters with size us_legal, however, the campaign id is prefixed with camp_ instead of cmp_.

-
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for A4 letter size.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for A4 letter size.

status
string (status)
Enum: "processed" "rendered" "failed"

A string describing the PDF render status:

  • processed - the rendering process is currently in progress.
    • @@ -3721,7 +3721,7 @@

    3. Learn more

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 A4 and us_legal letter size.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for A4 and us_legal letter size.

size
string (ltr_size)
Default: "us_letter"
Enum: "us_letter" "us_legal"

Specifies the size of the letter. It accepts two values us_letter and us_legal. If the Lob-Version header in the request is set to 2024-01-01 and above, the size property is automatically included with the default value of us_letter, unless explicitly specified.

Please note that attempting to include the size property in the request with the Lob-Version header predating to 2024-01-01 will result in an error.

Responses

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 cmp_. In the case of snap packs, booklets, and letters with size us_legal, however, the campaign id is prefixed with camp_ instead of cmp_.

-
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for A4 letter size.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for A4 letter size.

status
string (status)
Enum: "processed" "rendered" "failed"

A string describing the PDF render status:

  • processed - the rendering process is currently in progress.
    • @@ -3973,7 +3973,7 @@

    3. Learn more

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 time. Not populated in test mode.

-
fsc
boolean
Default: false

Contact support@lob.com or your account contact to learn more. Not available for snap_pack currently.

+
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:

  • processed - the rendering process is currently in progress.
    • @@ -4091,7 +4091,7 @@

    3. Learn more

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 time. Not populated in test mode.

-
fsc
boolean
Default: false

Contact support@lob.com or your account contact to learn more. Not available for snap_pack currently.

+
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:

  • processed - the rendering process is currently in progress.
    • @@ -4130,7 +4130,7 @@

    3. Learn more

campaign_id
string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$

Denotes resources created by the provided campaign id, prefixed with cmp_. In the case of snap packs, booklets, and letters with size us_legal, however, the campaign id is prefixed with camp_ instead of cmp_.

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.

+
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:

  • processed - the rendering process is currently in progress.
    • @@ -4208,7 +4208,7 @@

    3. Learn more

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 send_date has passed, the mailpiece can be canceled. If a date in the format 2017-11-01 is passed, it will evaluate to midnight UTC of that date (2017-11-01T00:00:00.000Z). If a datetime is passed, that exact time will be used. A send_date passed with no time zone will default to UTC, while a send_date passed with a time zone will be converted to UTC.

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 A4 and us_legal letter size.

+
fsc
boolean
Default: false

This is in beta. Contact support@lob.com or your account contact to learn more. Not available for A4 and us_legal letter size.

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 size equal to 8.375x5.375 inches, the default source material is 60# Gloss Text.

Responses

Response Headers
ratelimit-limit
integer
Example: 150

The rate limit for a given endpoint.

@@ -4238,7 +4238,7 @@

3. Learn more

campaign_id
string or null (campaign_id) ^(cmp|camp)_[a-zA-Z0-9]+$

Denotes resources created by the provided campaign id, prefixed with cmp_. In the case of snap packs, booklets, and letters with size us_legal, however, the campaign id is prefixed with camp_ instead of cmp_.

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.

+
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:

  • processed - the rendering process is currently in progress.
    • @@ -5305,7 +5305,157 @@

    Example Create Request using Sen

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/exports/ex_6a94fe68fd151e0f8 \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "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"
}

US Verifications

Validate, automatically correct, and standardize the addresses in your +

Response samples

Content type
application/json
{
  • "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"
}

Informed Delivery Campaign

The Informed Delivery campaigns API allows you to create and view Informed Delivery campaigns.

+
back to top
+

List

List Informed Delivery campaigns

+
Authorizations:
basicAuth

Responses

Response Schema: application/json
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

+

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "object": "list",
  • "next_url": null,
  • "previous_url": null,
  • "count": 2
}

Create

Creates a new Informed Delivery campaign

+
Authorizations:
basicAuth
Request Body schema: multipart/form-data
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 pending_approval the Informed Delivery campaign will not be active, and you can not send mail using it. +It will be editable in this status however, and changes can be made until approved. +NOTE that the default status is approved which makes the campaign active, but un-editable.

+
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

+

Responses

Response Schema: application/json
id
required
string (infd_id) ^infd_[a-zA-Z0-9]+$

Unique identifier prefixed with infd_.

+
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).

+

Request samples 

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
+

Response samples

Content type
application/json
{
  • "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_url": "https://www.lob.com",
  • "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
}

Retrieve

Retrieves the details of an existing Informed Delivery campaign. You need only supply the usps_campaign_id returned in the campaign creation request.

+
Authorizations:
basicAuth
path Parameters
usps_campaign_id
required
string (usps_campaign_id) ^[0-9]+$
Example: 1200772869

usps_campaign_id of the Informed Delivery campaign

+

Responses

Response Schema: application/json
id
required
string (infd_id) ^infd_[a-zA-Z0-9]+$

Unique identifier prefixed with infd_.

+
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).

+

Request samples 

curl https://api.lob.com/v1/informed_delivery_campaign/1200772869 \
+  -u <YOUR API KEY>:
+

Response samples

Content type
application/json
{
  • "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_url": "https://www.lob.com",
  • "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

Update the details of an existing Informed Delivery campaign.
NOTE: you can only update a campaign in the pending_approval status.

+
Authorizations:
basicAuth
path Parameters
usps_campaign_id
required
string (usps_campaign_id) ^[0-9]+$
Example: 1200772869

usps_campaign_id of the Informed Delivery campaign

+
Request Body schema: multipart/form-data
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

+

Responses

Response Schema: application/json
id
required
string (infd_id) ^infd_[a-zA-Z0-9]+$

Unique identifier prefixed with infd_.

+
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).

+

Request samples 

curl -X PATCH https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \
+  -u <YOUR API KEY>: \
+  -d '{"status":"approved"}'
+

Response samples

Content type
application/json
{
  • "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_url": "https://www.lob.com",
  • "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
}

US Verifications

Validate, automatically correct, and standardize the addresses in your address book based on USPS's Coding Accuracy Support System (CASS).

back to top
@@ -5407,7 +5557,7 @@

Example Create Request using Sen

Response Schema: application/json
required
Array of us_verification (object) or error (object)
errors
required
boolean

Indicates whether any errors occurred during the verification process.

Request samples

Content type
{
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    • {
      }
    ],
  • "errors": false
}

Single Verify

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.

+
https://api.lob.com/v1/bulk/us_verifications

Request samples

Content type
{
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    • {
      }
    ],
  • "errors": false
}

Single Verify

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.

Authorizations:
basicAuth
query Parameters
case
string
Default: "upper"
Enum: "upper" "proper"

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

Request Body schema:
One of
Any of
city
required
string <= 200 characters

The name of the city. city and state are required if no zip_code is passed.

state
required
string <= 50 characters

The ISO 3166-2 two letter code or subdivision name for the state. city and state are required if no zip_code is passed.

@@ -5473,7 +5623,7 @@

Example Create Request using Sen

object
string
Default: "us_verification"
Value: "us_verification"

Value is resource type.

Request samples

Content type
Example
{
  • "primary_line": "210 King Street",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107"
}

Response samples

Content type
application/json
Example
{
  • "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": [
      ],
    • "ews_match": false,
    • "lacs_indicator": "",
    • "lacs_return_code": "",
    • "suite_return_code": ""
    },
  • "lob_confidence_score": {
    • "score": 100,
    • "level": "high"
    },
  • "object": "us_verification"
}

US Verification Types

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

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

Request samples

Content type
Example
{
  • "primary_line": "210 King Street",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107"
}

Response samples

Content type
application/json
Example
{
  • "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": [
      ],
    • "ews_match": false,
    • "lacs_indicator": "",
    • "lacs_return_code": "",
    • "suite_return_code": ""
    },
  • "lob_confidence_score": {
    • "score": 100,
    • "level": "high"
    },
  • "object": "us_verification"
}

US Verification Types

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

ZIP Code Types - components[zip_code_type]

@@ -5678,7 +5828,7 @@

DPV Footnotes - deliverability_analysis[dpv_footnotes]

object
string
Default: "us_autocompletion"
Value: "us_autocompletion"

Value is resource type.

Request samples

Content type
Example
{
  • "address_prefix": "185 B",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107",
  • "geo_ip_sort": false
}

Response samples

Content type
application/json
Example
{
  • "id": "us_auto_a3ac97bcfbb2460ab20c",
  • "suggestions": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "object": "us_autocompletion"
}

Reverse Geocode Lookups

Find a list of zip codes associated with a valid US location via latitude and longitude.

back to top

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

Request samples

Content type
Example
{
  • "address_prefix": "185 B",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107",
  • "geo_ip_sort": false
}

Response samples

Content type
application/json
Example
{
  • "id": "us_auto_a3ac97bcfbb2460ab20c",
  • "suggestions": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "object": "us_autocompletion"
}

Reverse Geocode Lookups

Find a list of zip codes associated with a valid US location via latitude and longitude.

back to top

Reverse Geocode Lookup

Reverse geocode a valid US location with a live API key.

Authorizations:
basicAuth
query Parameters
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.

Request Body schema:
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 to pinpoint locations on a map.

@@ -5692,7 +5842,7 @@

DPV Footnotes - deliverability_analysis[dpv_footnotes]

object
string
Default: "us_reverse_geocode_lookup"
Value: "us_reverse_geocode_lookup"

Value is resource type.

Request samples

Content type
{
  • "latitude": 37.7749,
  • "longitude": 122.4194
}

Response samples

Content type
application/json
{
  • "id": "us_reverse_geocode_8a013f3e",
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Zip Lookups

Find a list of cities, states and associated information about a US ZIP code.

back to top

+
https://api.lob.com/v1/us_reverse_geocode_lookups

Request samples

Content type
{
  • "latitude": 37.7749,
  • "longitude": 122.4194
}

Response samples

Content type
application/json
{
  • "id": "us_reverse_geocode_8a013f3e",
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Zip Lookups

Find a list of cities, states and associated information about a US ZIP code.

back to top

Lookups

Returns information about a ZIP code

Authorizations:
basicAuth
Request Body schema:
zip_code
required
string^\d{5}$

A 5-digit ZIP code.

Responses

object
required
string
Default: "us_zip_lookup"
Value: "us_zip_lookup"

Value is resource type.

Request samples

Content type
{
  • "zip_code": "94107"
}

Response samples

Content type
application/json
{
  • "id": "us_zip_c7cb63d68f8d6",
  • "cities": [
    • {
      }
    ],
  • "zip_code_type": "standard",
  • "object": "us_zip_lookup",
  • "zip_code": "94107"
}

Identity Validation

Validates whether a given name is associated with an address.

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

Request samples

Content type
{
  • "zip_code": "94107"
}

Response samples

Content type
application/json
{
  • "id": "us_zip_c7cb63d68f8d6",
  • "cities": [
    • {
      }
    ],
  • "zip_code_type": "standard",
  • "object": "us_zip_lookup",
  • "zip_code": "94107"
}

Identity Validation

Validates whether a given name is associated with an address.

back to top

Identity Validation

Validates whether a given name is associated with an address.

Authorizations:
basicAuth
Request Body schema:
One of
Any of
city
required
string <= 200 characters

The name of the city. city and state are required if no zip_code is passed.

@@ -5768,7 +5918,7 @@

DPV Footnotes - deliverability_analysis[dpv_footnotes]

object
string
Default: "id_validation"
Value: "id_validation"

Value is resource type.

Request samples

Content type
{
  • "recipient": "Larry Lobster",
  • "primary_line": "210 King St.",
  • "secondary_line": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107"
}

Response samples

Content type
application/json
{
  • "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"
}

Intl Autocompletions

Address autocompletion for non-US addresses. Given partial address information, this endpoint returns up to 10 address suggestions.

+
https://api.lob.com/v1/identity_validation

Request samples

Content type
{
  • "recipient": "Larry Lobster",
  • "primary_line": "210 King St.",
  • "secondary_line": "",
  • "city": "San Francisco",
  • "state": "CA",
  • "zip_code": "94107"
}

Response samples

Content type
application/json
{
  • "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"
}

Intl Autocompletions

Address autocompletion for non-US addresses. Given partial address information, this endpoint returns up to 10 address suggestions.

Autocompletion Test Env

Your test API key does not autocomplete international 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:

@@ -5804,7 +5954,7 @@

DPV Footnotes - deliverability_analysis[dpv_footnotes]

Array of objects (intl_suggestions) [ 0 .. 10 ] items

An array of objects representing suggested addresses.

Request samples

Content type
Example
{
  • "address_prefix": "340 Wat",
  • "city": "Summerside",
  • "state": "Prince Edward Island",
  • "zip_code": "C1N 1C4",
  • "country": "CA",
  • "geo_ip_sort": false
}

Response samples

Content type
application/json
Example
{
  • "id": "intl_auto_a3ac97bcfbb2460ab20c",
  • "suggestions": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "object": "intl_autocompletion"
}

Intl Verifications

Address verification for non-US addresses +

https://api.lob.com/v1/intl_autocompletions

Request samples

Content type
Example
{
  • "address_prefix": "340 Wat",
  • "city": "Summerside",
  • "state": "Prince Edward Island",
  • "zip_code": "C1N 1C4",
  • "country": "CA",
  • "geo_ip_sort": false
}

Response samples

Content type
application/json
Example
{
  • "id": "intl_auto_a3ac97bcfbb2460ab20c",
  • "suggestions": [
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      },
    • {
      }
    ],
  • "object": "intl_autocompletion"
}

Intl Verifications

Address verification for non-US addresses

back to top
@@ -5850,7 +6000,7 @@

DPV Footnotes - deliverability_analysis[dpv_footnotes]

Response Schema: application/json
required
Array of intl_verification (object) or error (object)
errors
required
boolean

Indicates whether any errors occurred during the verification process.

Request samples

Content type
{
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    • {
      }
    ],
  • "errors": false
}

Single Verify

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.

+
https://api.lob.com/v1/bulk/intl_verifications

Request samples

Content type
{
  • "addresses": [
    • {
      },
    • {
      }
    ]
}

Response samples

Content type
application/json
{
  • "addresses": [
    • {
      }
    ],
  • "errors": false
}

Single Verify

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.

Authorizations:
basicAuth
header Parameters
x-lang-output
string
Enum: "native" "match"
  • native - Translate response to the native language of the country in the request
  • match - match the response to the language in the request
    • @@ -5915,7 +6065,7 @@

    DPV Footnotes - deliverability_analysis[dpv_footnotes]

object
string
Default: "intl_verification"
Value: "intl_verification"

Value is resource type.

Request samples

Content type
Example
{
  • "recipient": "Harry Zhang",
  • "primary_line": "370 Water St",
  • "secondary_line": "",
  • "city": "Summerside",
  • "state": "Prince Edward Island",
  • "postal code": "C1N 1C4",
  • "country": "CA"
}

Response samples

Content type
application/json
Example
{
  • "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

Webhooks are an easy way to get notifications on events happening asynchronously +

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

Request samples

Content type
Example
{
  • "recipient": "Harry Zhang",
  • "primary_line": "370 Water St",
  • "secondary_line": "",
  • "city": "Summerside",
  • "state": "Prince Edward Island",
  • "postal code": "C1N 1C4",
  • "country": "CA"
}

Response samples

Content type
application/json
Example
{
  • "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

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 @@ -6371,7 +6521,7 @@

Bank Accounts

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.

-

Response samples

Content type
application/json
{}

Tracking Events

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

+

Response samples

Content type
application/json
{}

Tracking Events

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

Certified Tracking Event Details

Letters sent with USPS Certified Mail are fully tracked by USPS, and @@ -6596,7 +6746,7 @@

Certified Tracking Event Details

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 null for type=normal events

location
string or null

The zip code in which the scan event occurred. Null for Mailed events.

-

Response samples

Content type
application/json
Example
{
  • "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"
}

Billing Groups

The Billing Groups API allows you to create and view labels that can be attached to certain consumption-based +

Response samples

Content type
application/json
Example
{
  • "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"
}

Billing Groups

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.

back to top
@@ -6611,9 +6761,9 @@

Certified Tracking Event Details

object
string
Default: "billing_group"
Value: "billing_group"

Value is resource type.

Request samples 

curl https://api.lob.com/v1/billing_groups/bg_4bb02b527a72667d0 \
+
https://api.lob.com/v1/billing_groups/{bg_id}

Request samples 

curl https://api.lob.com/v1/billing_groups/bg_4bb02b527a72667d0 \
 -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "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"
}

Update

Updates all editable attributes of the billing_group with the given id.

+

Response samples

Content type
application/json
{
  • "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"
}

Update

Updates all editable attributes of the billing_group with the given id.

Authorizations:
basicAuth
path Parameters
bg_id
required
string (bg_id) ^bg_[a-zA-Z0-9]+$

id of the billing_group

Request Body schema:
description
string (bg_description) <= 255 characters

Description of the billing group.

name
string (name) <= 255 characters

Name of the billing group.

@@ -6629,7 +6779,7 @@

Certified Tracking Event Details

object
string
Default: "billing_group"
Value: "billing_group"

Value is resource type.

Request samples

Content type
{
  • "name": "Marketing Dept",
  • "description": "Usage group used for the Marketing Dept resource sends"
}

Response samples

Content type
application/json
{
  • "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"
}

List

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.

+
https://api.lob.com/v1/billing_groups/{bg_id}

Request samples

Content type
{
  • "name": "Marketing Dept",
  • "description": "Usage group used for the Marketing Dept resource sends"
}

Response samples

Content type
application/json
{
  • "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"
}

List

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.

Authorizations:
basicAuth
query Parameters
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 include=["total_count"].

@@ -6645,9 +6795,9 @@

Certified Tracking Event Details

Array of objects (billing_group)

list of billing_groups

Request samples 

curl -X GET "https://api.lob.com/v1/billing_groups?limit=2" \
+
https://api.lob.com/v1/billing_groups

Request samples 

curl -X GET "https://api.lob.com/v1/billing_groups?limit=2" \
 -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "object": "list",
  • "next_url": null,
  • "prev_url": null,
  • "count": 2
}

Create

Creates a new billing_group with the provided properties.

+

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "object": "list",
  • "next_url": null,
  • "prev_url": null,
  • "count": 2
}

Create

Creates a new billing_group with the provided properties.

Authorizations:
basicAuth
Request Body schema:
name
required
string (name) <= 255 characters

Name of the billing group.

description
string (bg_description) <= 255 characters

Description of the billing group.

Responses

object
string
Default: "billing_group"
Value: "billing_group"

Value is resource type.

Request samples

Content type
{
  • "name": "Marketing Dept",
  • "description": "Usage group used for the Marketing Dept resource sends"
}

Response samples

Content type
application/json
{
  • "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"
}

Buckslips

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. +

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

Request samples

Content type
{
  • "name": "Marketing Dept",
  • "description": "Usage group used for the Marketing Dept resource sends"
}

Response samples

Content type
application/json
{
  • "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"
}

Buckslips

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.

back to top

List

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

@@ -6678,9 +6828,9 @@

Certified Tracking Event Details

Array of objects (buckslip)

list of buckslips

Request samples 

curl -X GET "https://api.lob.com/v1/buckslips?limit=2" \
+
https://api.lob.com/v1/buckslips

Request samples 

curl -X GET "https://api.lob.com/v1/buckslips?limit=2" \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{}

Create

Creates a new buckslip given information

+

Response samples

Content type
application/json
{}

Create

Creates a new buckslip given information

Authorizations:
basicAuth
Request Body schema:
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

@@ -6708,7 +6858,7 @@

Certified Tracking Event Details

size
string
Default: "8.75x3.75"
Value: "8.75x3.75"

The size of the buckslip

Request samples

Content type
{}

Response samples

Content type
application/json
{}

Retrieve

Retrieves the details of an existing buckslip. You need only supply the unique customer identifier that was returned upon buckslip creation.

+
https://api.lob.com/v1/buckslips

Request samples

Content type
{}

Response samples

Content type
application/json
{}

Retrieve

Retrieves the details of an existing buckslip. You need only supply the unique customer identifier that was returned upon buckslip creation.

Authorizations:
basicAuth
path Parameters
buckslip_id
required
string (buckslip_id) ^bck_[a-zA-Z0-9]+$

id of the buckslip

Responses

Response Schema: application/json
date_created
required
string <date-time> (date_created)

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

@@ -6733,9 +6883,9 @@

Certified Tracking Event Details

size
string
Default: "8.75x3.75"
Value: "8.75x3.75"

The size of the buckslip

Request samples 

curl https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
+
https://api.lob.com/v1/buckslips/{buckslip_id}

Request samples 

curl https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{}

Update

Update the details of an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.

+

Response samples

Content type
application/json
{}

Update

Update the details of an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.

Authorizations:
basicAuth
path Parameters
buckslip_id
required
string (buckslip_id) ^bck_[a-zA-Z0-9]+$

id of the buckslip

Request Body schema:
description
string or null (buckslip_description) <= 255 characters

Description of the buckslip.

auto_reorder
boolean

Allows for auto reordering

@@ -6763,16 +6913,16 @@

Certified Tracking Event Details

size
string
Default: "8.75x3.75"
Value: "8.75x3.75"

The size of the buckslip

Request samples

Content type
{
  • "description": "Test buckslip",
  • "auto_reorder": true
}

Response samples

Content type
application/json
{}

Delete

Delete an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.

+
https://api.lob.com/v1/buckslips/{buckslip_id}

Request samples

Content type
{
  • "description": "Test buckslip",
  • "auto_reorder": true
}

Response samples

Content type
application/json
{}

Delete

Delete an existing buckslip. You need only supply the unique identifier that was returned upon buckslip creation.

Authorizations:
basicAuth
path Parameters
buckslip_id
required
string (buckslip_id) ^bck_[a-zA-Z0-9]+$

id of the buckslip

Responses

Response Schema: application/json
id
string (buckslip_id) ^bck_[a-zA-Z0-9]+$

Unique identifier prefixed with bck_.

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples 

curl -X DELETE https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
+
https://api.lob.com/v1/buckslips/{buckslip_id}

Request samples 

curl -X DELETE https://api.lob.com/v1/buckslips/bck_7a6d73c5c8457fc \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "id": "buckslip_123456789",
  • "deleted": true
}

Buckslip Orders

The Buckslip Orders endpoint allows you to easily create buckslip orders for existing buckslips. +

Response samples

Content type
application/json
{
  • "id": "buckslip_123456789",
  • "deleted": true
}

Buckslip Orders

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.

back to top

Retrieve

Retrieves the buckslip orders associated with the given buckslip id.

@@ -6788,9 +6938,9 @@

Certified Tracking Event Details

Array of objects (buckslip_order)

List of buckslip orders

Request samples 

curl https://api.lob.com/v1/buckslips/bck_6afffd19045076c/orders/ \
+
https://api.lob.com/v1/buckslips/{buckslip_id}/orders

Request samples 

curl https://api.lob.com/v1/buckslips/bck_6afffd19045076c/orders/ \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "object": "list",
  • "next_url": null,
  • "previous_url": null,
  • "count": 1
}

Create

Creates a new buckslip order given information

+

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "object": "list",
  • "next_url": null,
  • "previous_url": null,
  • "count": 1
}

Create

Creates a new buckslip order given information

Authorizations:
basicAuth
path Parameters
buckslip_id
required
string (buckslip_id) ^bck_[a-zA-Z0-9]+$

The ID of the buckslip to which the buckslip orders belong.

Request Body schema:
quantity
required
integer [ 5000 .. 10000000 ]

The quantity of buckslips in the order (minimum 5,000).

Responses

expected_availability_date
string <date-time>

The fixed deadline for the buckslips to be printed.

Request samples

Content type
{
  • "quantity": 10000
}

Response samples

Content type
application/json
{
  • "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"
}

Cards

The cards endpoint allows you to easily create cards that can later be affixed to Letters. +

https://api.lob.com/v1/buckslips/{buckslip_id}/orders

Request samples

Content type
{
  • "quantity": 10000
}

Response samples

Content type
application/json
{
  • "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"
}

Cards

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.

back to top

List

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

@@ -6825,9 +6975,9 @@

Certified Tracking Event Details

Array of objects (card)

list of cards

Request samples 

curl -X GET "https://api.lob.com/v1/cards?limit=2" \
+
https://api.lob.com/v1/cards

Request samples 

curl -X GET "https://api.lob.com/v1/cards?limit=2" \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{}

Create

Creates a new card given information

+

Response samples

Content type
application/json
{}

Create

Creates a new card given information

Authorizations:
basicAuth
Request Body schema:
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

@@ -6852,7 +7002,7 @@

Certified Tracking Event Details

size
string
Default: "2.125x3.375"
Enum: "3.375x2.125" "2.125x3.375"

The size of the card

Request samples

Content type
{}

Response samples

Content type
application/json
{}

Retrieve

Retrieves the details of an existing card. You need only supply the unique customer identifier that was returned upon card creation.

+
https://api.lob.com/v1/cards

Request samples

Content type
{}

Response samples

Content type
application/json
{}

Retrieve

Retrieves the details of an existing card. You need only supply the unique customer identifier that was returned upon card creation.

Authorizations:
basicAuth
path Parameters
card_id
required
string (card_id) ^card_[a-zA-Z0-9]+$

id of the card

Responses

Response Schema: application/json
date_created
required
string <date-time> (date_created)

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

@@ -6874,9 +7024,9 @@

Certified Tracking Event Details

size
string
Default: "2.125x3.375"
Enum: "3.375x2.125" "2.125x3.375"

The size of the card

Request samples 

curl https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
+
https://api.lob.com/v1/cards/{card_id}

Request samples 

curl https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{}

Update

Update the details of an existing card. You need only supply the unique identifier that was returned upon card creation.

+

Response samples

Content type
application/json
{}

Update

Update the details of an existing card. You need only supply the unique identifier that was returned upon card creation.

Authorizations:
basicAuth
path Parameters
card_id
required
string (card_id) ^card_[a-zA-Z0-9]+$

id of the card

Request Body schema:
description
string or null (card_description) <= 255 characters

Description of the card.

auto_reorder
boolean

Allows for auto reordering

@@ -6901,16 +7051,16 @@

Certified Tracking Event Details

size
string
Default: "2.125x3.375"
Enum: "3.375x2.125" "2.125x3.375"

The size of the card

Request samples

Content type
{
  • "description": "Test card",
  • "auto_reorder": true
}

Response samples

Content type
application/json
{}

Delete

Delete an existing card. You need only supply the unique identifier that was returned upon card creation.

+
https://api.lob.com/v1/cards/{card_id}

Request samples

Content type
{
  • "description": "Test card",
  • "auto_reorder": true
}

Response samples

Content type
application/json
{}

Delete

Delete an existing card. You need only supply the unique identifier that was returned upon card creation.

Authorizations:
basicAuth
path Parameters
card_id
required
string (card_id) ^card_[a-zA-Z0-9]+$

id of the card

Responses

Response Schema: application/json
id
string (card_id) ^card_[a-zA-Z0-9]+$

Unique identifier prefixed with card_.

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples 

curl -X DELETE https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
+
https://api.lob.com/v1/cards/{card_id}

Request samples 

curl -X DELETE https://api.lob.com/v1/cards/card_7a6d73c5c8457fc \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "id": "card_123456789",
  • "deleted": true
}

Card Orders

The card orders endpoint allows you to easily create card orders for existing cards. +

Response samples

Content type
application/json
{
  • "id": "card_123456789",
  • "deleted": true
}

Card Orders

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.

back to top

Retrieve

Retrieves the card orders associated with the given card id.

@@ -6926,9 +7076,9 @@

Certified Tracking Event Details

Array of objects (card_order)

List of card orders

Request samples 

curl https://api.lob.com/v1/cards/card_6afffd19045076c/orders/ \
+
https://api.lob.com/v1/cards/{card_id}/orders

Request samples 

curl https://api.lob.com/v1/cards/card_6afffd19045076c/orders/ \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "object": "list",
  • "next_url": null,
  • "previous_url": null,
  • "count": 1
}

Create

Creates a new card order given information

+

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ],
  • "object": "list",
  • "next_url": null,
  • "previous_url": null,
  • "count": 1
}

Create

Creates a new card order given information

Authorizations:
basicAuth
path Parameters
card_id
required
string (card_id) ^card_[a-zA-Z0-9]+$

The ID of the card to which the card orders belong.

Request Body schema:
quantity
required
integer [ 10000 .. 10000000 ]

The quantity of cards in the order (minimum 10,000).

Responses

expected_availability_date
string <date-time>

The fixed deadline for the cards to be printed.

Request samples

Content type
{
  • "quantity": 10000
}

Response samples

Content type
application/json
{
  • "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"
}

QR Codes

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.

+
https://api.lob.com/v1/cards/{card_id}/orders

Request samples

Content type
{
  • "quantity": 10000
}

Response samples

Content type
application/json
{
  • "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"
}

QR Codes

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!

back to top
@@ -6965,9 +7115,9 @@

Certified Tracking Event Details

scanned_count
integer

Indicates the number of QR Codes out of count that were scanned atleast once.

Array of objects (qr_code_scans)

List of QR code analytics

Request samples 

curl -X GET "https://api.lob.com/v1/qr_code_analytics?limit=2&scanned=true" \
+
https://api.lob.com/v1/qr_code_analytics

Request samples 

curl -X GET "https://api.lob.com/v1/qr_code_analytics?limit=2&scanned=true" \
 -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "object": "list",
  • "count": 2,
  • "scanned_count": 2,
  • "total_count": 2
}

URL Shortener

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.

+

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "object": "list",
  • "count": 2,
  • "scanned_count": 2,
  • "total_count": 2
}

URL Shortener

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.

back to top
@@ -6976,135 +7126,100 @@

Certified Tracking Event Details

Responses

Response Schema: application/json
id
string

Unique identifier for a domain.

domain
string

The registered domain/hostname.

-
account_id
string

Unique identifier associated with the account the domain is registered for.

+
error_redirect_link
string

The 404 error redirect link.

+
created_at
string

The date and time the domain was created.

+
updated_at
string

The date and time the domain was last updated.

Request samples 

curl -X GET "https://api.lob.com/v1/domains/{domain_id}" \
+
https://api.lob.com/v1/domains/{domain_id}

Request samples 

curl -X GET "https://api.lob.com/v1/domains/{domain_id}" \
   -u <YOUR_LIVE_API_KEY>:
-

Response samples

Content type
application/json
{
  • "id": "string",
  • "domain": "string",
  • "account_id": "string"
}

Delete a Domain

Delete a registered domain. This operation can only be performed if all associated links with the domain are deleted.

+

Response samples

Content type
application/json
{
  • "id": "string",
  • "domain": "string",
  • "error_redirect_link": "string",
  • "created_at": "string",
  • "updated_at": "string"
}

Delete a Domain

Delete a registered domain. This operation can only be performed if all associated links with the domain are deleted.

Authorizations:
basicAuth
path Parameters
domain_id
required
string

Unique identifier for a domain.

Responses

Response Schema: application/json
id
string

Unique identifier for a domain.

-
domain
string

The registered domain/hostname.

-
account_id
string

Unique identifier associated with the account the domain is registered for.

+
deleted
boolean

Only returned if the domain was successfully deleted.

Response samples

Content type
application/json
{
  • "id": "string",
  • "domain": "string",
  • "account_id": "string"
}

Create Domain

Add a new custom domain that can be used to create custom links.

-
Authorizations:
basicAuth
Request Body schema:
domain
required
string (domain)

The registered domain/hostname.

+
https://api.lob.com/v1/domains/{domain_id}

Response samples

Content type
application/json
{
  • "id": "string",
  • "deleted": true
}

Create Domain

Add a new custom domain that can be used to create custom links.

+
Authorizations:
basicAuth
Request Body schema:
domain
required
string (domain)

The registered domain/hostname.

+
error_redirect_link
string (error_redirect_link)

The 404 error redirect link.

Responses

Response Schema: application/json
id
string

Unique identifier for a domain.

domain
string

The registered domain/hostname.

-
account_id
string

Unique identifier associated with the account the domain is registered for.

+
error_redirect_link
string

The 404 error redirect link.

+
created_at
string

The date and time the domain was created.

+
updated_at
string

The date and time the domain was last updated.

Request samples

Content type
Example
{
  • "domain": "lob.st"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "domain": "string",
  • "account_id": "string"
}

List all domains

Retrieve a list of all created domains.

+
https://api.lob.com/v1/domains

Request samples

Content type
Example
{
  • "domain": "lob.st"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "domain": "string",
  • "error_redirect_link": "string",
  • "created_at": "string",
  • "updated_at": "string"
}

List all domains

Retrieve a list of all created domains.

Authorizations:
basicAuth

Responses

Response Schema: application/json
Array of objects (domain_response)

List of domains.

Request samples 

curl -X GET "https://api.lob.com/v1/domains?limit=2" \
-  -u <YOUR_LIVE_API_KEY>:
-

Response samples

Content type
application/json
{
  • "data": [
    • {
      }
    ]
}