From c02f78f779f35fd61b7374f25268bdfbfe885045 Mon Sep 17 00:00:00 2001 From: Sachin Muralidhara Date: Wed, 3 Jul 2024 13:28:10 -0700 Subject: [PATCH] CMB-586: add booklets CRUD documentation (#498) * CMB-645: add list, get and delete endpoints for snap packs (#495) * booklet create * add code samples for create; start on get * get and delete endpoints * remove color; update campaign_id verbiage * remove color from the response examples --- docs/index.html | 419 +++++++++----- lob-api-public.yml | 7 +- package-lock.json | 2 +- package.json | 2 +- .../booklets/attributes/booklet_file.yml | 21 + resources/booklets/attributes/booklet_id.yml | 5 + .../booklets/attributes/booklet_size.yml | 10 + .../booklets/attributes/booklet_use_type.yml | 7 + resources/booklets/booklet.yml | 62 ++ resources/booklets/booklets.yml | 540 ++++++++++++++++++ resources/booklets/models/booklet.yml | 26 + .../booklets/models/booklet_editable.yml | 37 ++ .../models/booklet_generated_base.yml | 54 ++ resources/booklets/responses/all_booklets.yml | 143 +++++ resources/booklets/responses/booklet.yml | 62 ++ resources/booklets/responses/post_booklet.yml | 12 + resources/snap_packs/snap_pack.yml | 2 +- shared/attributes/campaign_id.yml | 2 +- .../deletion_models/booklet_deletion.yml | 9 + shared/models/qr_code.yml | 2 +- shared/models/qr_code_campaigns.yml | 2 +- shared/parameters/campaign_id.yml | 2 +- shared/responses/booklet_deleted.yml | 10 + 23 files changed, 1290 insertions(+), 148 deletions(-) create mode 100644 resources/booklets/attributes/booklet_file.yml create mode 100644 resources/booklets/attributes/booklet_id.yml create mode 100644 resources/booklets/attributes/booklet_size.yml create mode 100644 resources/booklets/attributes/booklet_use_type.yml create mode 100644 resources/booklets/booklet.yml create mode 100644 resources/booklets/booklets.yml create mode 100644 resources/booklets/models/booklet.yml create mode 100644 resources/booklets/models/booklet_editable.yml create mode 100644 resources/booklets/models/booklet_generated_base.yml create mode 100644 resources/booklets/responses/all_booklets.yml create mode 100644 resources/booklets/responses/booklet.yml create mode 100644 resources/booklets/responses/post_booklet.yml create mode 100644 shared/models/deletion_models/booklet_deletion.yml create mode 100644 shared/responses/booklet_deleted.yml diff --git a/docs/index.html b/docs/index.html index ab97f56b..6f4f19b2 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2989,7 +2989,7 @@ -
API docs by Redocly
API docs by Redocly

Lob (1.19.35)

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

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.

@@ -3266,9 +3266,9 @@

3. Learn more

address obj with `name` defined (object) or address obj with `company` defined (object) (address_us)
front_template_version_id
string or null^vrsn_[a-zA-Z0-9]+$

The unique ID of the specific version of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID.

back_template_version_id
string or null^vrsn_[a-zA-Z0-9]+$

The unique ID of the specific version of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID.

Array of objects or null (tracking_event_normal)

An array of tracking_event objects ordered by ascending 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 and letters with size us_legal, the campaign id is prefixed with camp_ instead of cmp_.

+
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.
    • @@ -3296,7 +3296,7 @@

    3. Learn more

include
Array of strings

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

object (date_filter)

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.

object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

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

Filters resources created by the provided campaign id, prefixed with cmp_.

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

Filters 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_.

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

A string describing the render status:

  • processed - the rendering process is currently underway.
    • @@ -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.

@@ -3391,9 +3391,9 @@

3. Learn more

address obj with `name` defined (object) or address obj with `company` defined (object) (address_us)
front_template_version_id
string or null^vrsn_[a-zA-Z0-9]+$

The unique ID of the specific version of the HTML template used for the front of the postcard. Only filled out when the request contains a valid postcard template ID.

back_template_version_id
string or null^vrsn_[a-zA-Z0-9]+$

The unique ID of the specific version of the HTML template used for the back of the postcard. Only filled out when the request contains a valid postcard template ID.

Array of objects or null (tracking_event_normal)

An array of tracking_event objects ordered by ascending 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 and letters with size us_legal, the campaign id is prefixed with camp_ instead of cmp_.

+
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,14 +3435,14 @@

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.
  • rendered - a PDF has been successfully rendered of the mailpiece.
  • failed - one or more issues has caused the rendering process to fail.
-
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 and letters with size us_legal, the campaign id is prefixed with camp_ instead of cmp_.

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

object or null

An object describing the reason for failure if the resource failed to render.

string or string (send_date)

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

mail_type
string (mail_type)
Default: "usps_first_class"
Enum: "usps_first_class" "usps_standard"

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

object or object

Sorts items by ascending or descending dates. Use either date_created or send_date, not both.

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

Filters resources created by the provided campaign id, prefixed with cmp_.

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

Filters 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_.

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

A string describing the render status:

  • processed - the rendering process is currently underway.
    • @@ -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,14 +3560,14 @@

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.
  • rendered - a PDF has been successfully rendered of the mailpiece.
  • failed - one or more issues has caused the rendering process to fail.
-
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 and letters with size us_legal, the campaign id is prefixed with camp_ instead of cmp_.

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

object or null

An object describing the reason for failure if the resource failed to render.

url
string (signed_link) ^https://lob-assets.com/(letters|postcards|ba...

A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated.

template_id
string^tmpl_[a-zA-Z0-9]+$

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

template_version_id
string^vrsn_[a-zA-Z0-9]+$

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

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

Denotes resources created by the provided campaign id, prefixed with cmp_. In the case of snap packs and letters with size us_legal, 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.

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

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

A string describing the PDF render status:

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

    3. Learn more

include
Array of strings

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

object (date_filter)

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.

object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

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

Filters resources created by the provided campaign id, prefixed with cmp_.

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

Filters 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_.

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

A string describing the render status:

  • processed - the rendering process is currently underway.
    • @@ -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

url
string (signed_link) ^https://lob-assets.com/(letters|postcards|ba...

A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated.

template_id
string^tmpl_[a-zA-Z0-9]+$

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

template_version_id
string^vrsn_[a-zA-Z0-9]+$

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

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

Denotes resources created by the provided campaign id, prefixed with cmp_. In the case of snap packs and letters with size us_legal, 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.

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

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

A string describing the PDF render status:

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

    3. Learn more

Request samples 

curl -X DELETE https://api.lob.com/v1/checks/chk_534f10783683daa0 \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

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

Snap Packs

Retrieve

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

+

Response samples

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

Snap Packs

Retrieve

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

Authorizations:
basicAuth
path Parameters
snap_pack_id
required
string (snap_pack_id) ^ord_[0-9a-f]{26}$

id of the snap_pack

Responses

Response Schema: application/json
required
(address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address)
carrier
required
string
Default: "USPS"
Value: "USPS"
id
required
string (snap_pack_id) ^ord_[0-9a-f]{26}$

Unique identifier prefixed with ord_.

@@ -3973,14 +3973,14 @@

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.
  • rendered - a PDF has been successfully rendered of the mailpiece.
  • failed - one or more issues has caused the rendering process to fail.
-
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 and letters with size us_legal, the campaign id is prefixed with camp_ instead of cmp_.

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

object or null

An object describing the reason for failure if the resource failed to render.

color
boolean (color)

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

string or string (send_date)

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

mail_type
string (mail_type)
Default: "usps_first_class"
Enum: "usps_first_class" "usps_standard"

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

object or object

Sorts items by ascending or descending dates. Use either date_created or send_date, not both.

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

Filters resources created by the provided campaign id, prefixed with cmp_.

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

Filters 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_.

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

A string describing the render status:

  • processed - the rendering process is currently underway.
    • @@ -4091,19 +4091,158 @@

    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.
  • rendered - a PDF has been successfully rendered of the mailpiece.
  • failed - one or more issues has caused the rendering process to fail.
-
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 and letters with size us_legal, the campaign id is prefixed with camp_ instead of cmp_.

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

object or null

An object describing the reason for failure if the resource failed to render.

color
boolean (color)

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

Request samples

Content type
{
  • "description": "Demo Snap Pack Job",
  • "to": "adr_bae820679f3f536b",
  • "from": "adr_210a8d4b0b76d77b",
  • "inside": "https://lob.com/snappackinside.pdf",
  • "outside": "https://lob.com/snappackoutside.pdf",
  • "size": "8.5x11",
  • "metadata": {
    • "spiffy": "true"
    },
  • "mail_type": "usps_standard",
  • "merge_variables": {
    • "name": "Harry"
    },
  • "send_date": "2017-11-01T00:00:00.000Z",
  • "use_type": "marketing"
}

Response samples

Content type
application/json
{}

Bank Accounts

Bank Accounts allow you to store your bank account securely in our system. The API provides +

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

Request samples

Content type
{
  • "description": "Demo Snap Pack Job",
  • "to": "adr_bae820679f3f536b",
  • "from": "adr_210a8d4b0b76d77b",
  • "inside": "https://lob.com/snappackinside.pdf",
  • "outside": "https://lob.com/snappackoutside.pdf",
  • "size": "8.5x11",
  • "metadata": {
    • "spiffy": "true"
    },
  • "mail_type": "usps_standard",
  • "merge_variables": {
    • "name": "Harry"
    },
  • "send_date": "2017-11-01T00:00:00.000Z",
  • "use_type": "marketing"
}

Response samples

Content type
application/json
{}

Booklets

Retrieve

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

+
Authorizations:
basicAuth
path Parameters
booklet_id
required
string (booklet_id) ^ord_[0-9a-f]{26}$

id of the booklet

+

Responses

Response Schema: application/json
required
(address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address)
carrier
required
string
Default: "USPS"
Value: "USPS"
id
required
string (booklet_id) ^ord_[0-9a-f]{26}$

Unique identifier prefixed with ord_.

+
required
(address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address)
use_type
required
string or null (booklet_use_type)
Enum: "marketing" "operational" null

The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article.

+
Array of objects (tracking_event_normal)

An array of tracking events ordered by ascending time.

+
description
string or null (resource_description) <= 255 characters

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

+
object (metadata) <= 500 characters [^"\\]{0,500}

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

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

+
mail_type
string (mail_type)
Default: "usps_first_class"
Enum: "usps_first_class" "usps_standard"

A string designating the mail postage type:

+
    +
  • usps_first_class - (default)
    • +
  • usps_standard - a cheaper option which is +less predictable and takes longer to deliver. usps_standard cannot be used with 4x6 +postcards or for any postcards sent outside of the United States.
    • +
+
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.

+
deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

+
url
string (signed_link) ^https://lob-assets.com/(letters|postcards|ba...

A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated.

+
template_id
string^tmpl_[a-zA-Z0-9]+$

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

+
template_version_id
string^vrsn_[a-zA-Z0-9]+$

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

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

Denotes resources created by the provided campaign id, prefixed with 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.

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

A string describing the PDF render status:

+
    +
  • processed - the rendering process is currently in progress.
    • +
  • rendered - a PDF has been successfully rendered of the mailpiece.
    • +
  • failed - one or more issues has caused the rendering process to fail.
    • +
+
object or null

An object describing the reason for failure if the resource failed to render.

+
object
string
Default: "booklet"
Value: "booklet"

Value is resource type.

+

Request samples 

curl -X GET "https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1" \
+  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
+

Response samples

Content type
application/json
{}

Delete

Completely removes a booklet from production. This can only be done if the booklet's send_date has not yet passed. If the booklet is successfully canceled, you will not be charged for it.

+
Authorizations:
basicAuth
path Parameters
booklet_id
required
string (booklet_id) ^ord_[0-9a-f]{26}$

id of the booklet

+

Responses

Response Schema: application/json
id
string (booklet_id) ^ord_[0-9a-f]{26}$

Unique identifier prefixed with ord_.

+
deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

+

Request samples 

curl -X DELETE https://api.lob.com/v1/booklets/ord_0d6a16a3fff6318ac8f8008dc1 \
+  -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
+

Response samples

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

List

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

+
Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

How many results to return.

+
object or object

before and after are both optional but only one of them can be in the query at a time.

+
include
Array of strings

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

+
object (date_filter)

Filter by date created. Accepted formats are ISO-8601 date or datetime, e.g. { "gt": "2012-01-01", "lt": "2012-01-31T12:34:56Z" } where gt is >, lt is <, gte is ≥, and lte is ≤.

+
object (metadata) <= 500 characters [^"\\]{0,500}

Filter by metadata key-value pair`.

+
string or string (send_date)

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

+
mail_type
string (mail_type)
Default: "usps_first_class"
Enum: "usps_first_class" "usps_standard"

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

+
object or object

Sorts items by ascending or descending dates. Use either date_created or send_date, not both.

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

Filters 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_.

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

A string describing the render status:

+
    +
  • processed - the rendering process is currently underway.
    • +
  • rendered - the rendering process has completed successfully.
    • +
  • failed - the rendering process has failed.
    • +
+

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 (booklet)

list of booklets

+

Request samples 

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

Response samples

Content type
application/json
{}

Create

Creates a new booklet.

+
Authorizations:
basicAuth
query Parameters
idempotency_key
string <= 256 characters
Example: idempotency_key=026e7634-24d7-486c-a0bb-4a17fd0eebc5

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.

+
header Parameters
Idempotency-Key
string <= 256 characters
Example: 026e7634-24d7-486c-a0bb-4a17fd0eebc5

A string of no longer than 256 characters that uniquely identifies this resource. For more help integrating idempotency keys, refer to our implementation guide.

+
Request Body schema:
required
adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object)))))))

Must either be an address ID or an inline object with correct address parameters. If an object is used, an address will be created, corrected, and standardized for free whenever possible using our US Address Verification engine (if it is a US address), and returned back with an ID. Depending on your Print & Mail Edition, US addresses may also be run through National Change of Address Linkage(NCOALink). Non-US addresses will be standardized into uppercase only. If a US address used does not meet your account’s US Mail strictness setting, the request will fail. Lob Guide: Verification of Mailing Addresses

+
required
adr_id (string) or (inline_address ((address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (inline_address_intl ((address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_editable_intl (address obj with `name` defined (object) or address obj with `company` defined (object)))))))

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

+
required
html_string (string) or tmpl_id (string) or remote_file_url (string) or string (booklet_file)

Notes:

+
    +
  • HTML merge variables should not include delimiting whitespace.
    • +
  • All pages of a supplied PDF file must be sized per the size attribute, while supplied HTML will be rendered and trimmed to as many size pages as necessary.
    • +
  • For design specifications, please see our PDF and HTML templates. +See pricing for extra costs incurred.
    • +
+
use_type
required
string or null (booklet_use_type)
Enum: "marketing" "operational" null

The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article.

+
description
string or null (resource_description) <= 255 characters

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

+
object (metadata) <= 500 characters [^"\\]{0,500}

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

+
mail_type
string
Default: "usps_first_class"
Enum: "usps_first_class" "usps_standard"

A string designating the mail postage type:

+
    +
  • usps_first_class - (default)
    • +
  • usps_standard - a cheaper option which is +less predictable and takes longer to deliver. usps_standard cannot be used with 4x6 +postcards or for any postcards sent outside of the United States.
    • +
+
merge_variables
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.

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

+
size
string (booklet_size)
Default: "9x6"
Enum: "9x6" "8.375x5.375"

Specifies the size of the booklet.

+

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.

+
ratelimit-reset
integer
Example: 1528749846

The time at which the rate limit window resets in UTC epoch seconds

+
Response Schema: application/json
required
(address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address)
carrier
required
string
Default: "USPS"
Value: "USPS"
id
required
string (booklet_id) ^ord_[0-9a-f]{26}$

Unique identifier prefixed with ord_.

+
required
(address_us (address obj with `name` defined (object) or address obj with `company` defined (object))) or (address_intl (address obj with `name` defined (object) or address obj with `company` defined (object))) (address)
use_type
required
string or null (booklet_use_type)
Enum: "marketing" "operational" null

The use type for each mailpiece. Can be one of marketing, operational, or null. Null use_type is only allowed if an account default use_type is selected in Account Settings. For more information on use_type, see our Help Center article.

+
Array of objects (tracking_event_normal)

An array of tracking events ordered by ascending time.

+
description
string or null (resource_description) <= 255 characters

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

+
object (metadata) <= 500 characters [^"\\]{0,500}

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

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

+
mail_type
string (mail_type)
Default: "usps_first_class"
Enum: "usps_first_class" "usps_standard"

A string designating the mail postage type:

+
    +
  • usps_first_class - (default)
    • +
  • usps_standard - a cheaper option which is +less predictable and takes longer to deliver. usps_standard cannot be used with 4x6 +postcards or for any postcards sent outside of the United States.
    • +
+
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.

+
deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

+
url
string (signed_link) ^https://lob-assets.com/(letters|postcards|ba...

A signed link served over HTTPS. The link returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated.

+
template_id
string^tmpl_[a-zA-Z0-9]+$

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

+
template_version_id
string^vrsn_[a-zA-Z0-9]+$

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

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

Denotes resources created by the provided campaign id, prefixed with 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.

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

A string describing the PDF render status:

+
    +
  • processed - the rendering process is currently in progress.
    • +
  • rendered - a PDF has been successfully rendered of the mailpiece.
    • +
  • failed - one or more issues has caused the rendering process to fail.
    • +
+
object or null

An object describing the reason for failure if the resource failed to render.

+
object
string
Default: "booklet"
Value: "booklet"

Value is resource type.

+

Request samples

Content type
{
  • "description": "demo",
  • "to": {
    • "description": "Harry - Office",
    • "name": "Harry Zhang",
    • "company": "Lob",
    • "email": "harry@lob.com",
    • "phone": "5555555555",
    • "address_line1": "210 King St",
    • "address_line2": "# 6100",
    • "address_city": "San Francisco",
    • "address_state": "CA",
    • "address_zip": "94107",
    • "address_country": "US"
    },
  • "from": {
    • "name": "Harry",
    • "address_line1": "210 King St",
    • "address_line2": "# 6100",
    • "address_city": "San Francisco",
    • "address_state": "CA",
    • "address_zip": "94107"
    },
  • "file": "<html style='padding-top: 3in; margin: .5in;'>HTML Booklet for {{name}}</html>",
  • "mail_type": "usps_first_class",
  • "merge_variables": {
    • "name": "Harry"
    },
  • "metadata": {
    • "spiffy": "true"
    },
  • "send_date": "2017-11-01T00:00:00.000Z",
  • "use_type": "marketing",
  • "qr_code": {
    • "position": "relative",
    • "redirect_url": "https://www.lob.com",
    • "width": "2",
    • "top": "2",
    • "right": "2",
    • "pages": "1-2,4-5"
    },
  • "fsc": true,
  • "size": "9x6"
}

Response samples

Content type
application/json
{}

Bank Accounts

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

back to top
@@ -4134,7 +4273,7 @@

3. Learn more

verified
boolean
Default: false

A bank account must be verified before a check can be created. More info here.

Request samples

Content type
{
  • "amounts": [
    • 1,
    • 100
    ]
}

Response samples

Content type
application/json
{
  • "id": "bank_8cad8df5354d33f",
  • "signature_url": "https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a",
  • "description": "Test Bank Account",
  • "metadata": { },
  • "routing_number": "322271627",
  • "fractional_routing_number": "25-3/440",
  • "check_template": "jpm",
  • "account_number": "123456789",
  • "account_type": "company",
  • "signatory": "John Doe",
  • "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
  • "bank_city": "Columbus",
  • "bank_state": "OH",
  • "bank_zip": "43240",
  • "verified": false,
  • "date_created": "2015-11-06T19:24:24.440Z",
  • "date_modified": "2015-11-06T19:24:24.440Z",
  • "object": "bank_account"
}

Retrieve

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

+
https://api.lob.com/v1/bank_accounts/{bank_id}/verify

Request samples

Content type
{
  • "amounts": [
    • 1,
    • 100
    ]
}

Response samples

Content type
application/json
{
  • "id": "bank_8cad8df5354d33f",
  • "signature_url": "https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a",
  • "description": "Test Bank Account",
  • "metadata": { },
  • "routing_number": "322271627",
  • "fractional_routing_number": "25-3/440",
  • "check_template": "jpm",
  • "account_number": "123456789",
  • "account_type": "company",
  • "signatory": "John Doe",
  • "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
  • "bank_city": "Columbus",
  • "bank_state": "OH",
  • "bank_zip": "43240",
  • "verified": false,
  • "date_created": "2015-11-06T19:24:24.440Z",
  • "date_modified": "2015-11-06T19:24:24.440Z",
  • "object": "bank_account"
}

Retrieve

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

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

id of the bank account

Responses

Response Schema: application/json
routing_number
required
string = 9 characters

Must be a valid US routing number.

@@ -4157,18 +4296,18 @@

3. Learn more

verified
boolean
Default: false

A bank account must be verified before a check can be created. More info here.

Request samples 

curl https://api.lob.com/v1/bank_accounts/bank_8cad8df5354d33f \
+
https://api.lob.com/v1/bank_accounts/{bank_id}

Request samples 

curl https://api.lob.com/v1/bank_accounts/bank_8cad8df5354d33f \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

Content type
application/json
{
  • "id": "bank_8cad8df5354d33f",
  • "signature_url": "https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a",
  • "description": "Test Bank Account",
  • "metadata": { },
  • "routing_number": "322271627",
  • "fractional_routing_number": "25-3/440",
  • "check_template": "jpm",
  • "account_number": "123456789",
  • "account_type": "company",
  • "signatory": "John Doe",
  • "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
  • "bank_city": "Columbus",
  • "bank_state": "OH",
  • "bank_zip": "43240",
  • "verified": false,
  • "date_created": "2015-11-06T19:24:24.440Z",
  • "date_modified": "2015-11-06T19:24:24.440Z",
  • "object": "bank_account"
}

Delete

Permanently deletes a bank account. It cannot be undone.

+

Response samples

Content type
application/json
{
  • "id": "bank_8cad8df5354d33f",
  • "signature_url": "https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a",
  • "description": "Test Bank Account",
  • "metadata": { },
  • "routing_number": "322271627",
  • "fractional_routing_number": "25-3/440",
  • "check_template": "jpm",
  • "account_number": "123456789",
  • "account_type": "company",
  • "signatory": "John Doe",
  • "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
  • "bank_city": "Columbus",
  • "bank_state": "OH",
  • "bank_zip": "43240",
  • "verified": false,
  • "date_created": "2015-11-06T19:24:24.440Z",
  • "date_modified": "2015-11-06T19:24:24.440Z",
  • "object": "bank_account"
}

Delete

Permanently deletes a bank account. It cannot be undone.

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

id of the bank account

Responses

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

Unique identifier prefixed with bank_.

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples 

curl -X DELETE https://api.lob.com/v1/bank_accounts/bank_3e64d9904356b20 \
+
https://api.lob.com/v1/bank_accounts/{bank_id}

Request samples 

curl -X DELETE https://api.lob.com/v1/bank_accounts/bank_3e64d9904356b20 \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

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

List

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

+

Response samples

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

List

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

Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

How many results to return.

object or object

before and after are both optional but only one of them can be in the query at a time.

include
Array of strings

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

@@ -4183,9 +4322,9 @@

3. Learn more

Array of objects (bank_account)

list of bank_accounts

Request samples 

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

Request samples 

curl -X GET "https://api.lob.com/v1/bank_accounts?limit=2" \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

Content type
application/json
{}

Create

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

+

Response samples

Content type
application/json
{}

Create

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

Authorizations:
basicAuth
Request Body schema:
routing_number
required
string = 9 characters
account_number
required
string <= 17 characters
account_type
required
string
Enum: "company" "individual"

The type of entity that holds the account.

signatory
required
string <= 30 characters

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

@@ -4220,7 +4359,7 @@

3. Learn more

verified
boolean
Default: false

A bank account must be verified before a check can be created. More info here.

Request samples

Content type
{
  • "description": "Test Bank Account",
  • "routing_number": "322271627",
  • "account_number": "123456789",
  • "signatory": "Jane Doe",
  • "account_type": "individual",
  • "metadata": {
    • "spiffy": "true"
    }
}

Response samples

Content type
application/json
{
  • "id": "bank_8cad8df5354d33f",
  • "signature_url": "https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a",
  • "description": "Test Bank Account",
  • "metadata": { },
  • "routing_number": "322271627",
  • "fractional_routing_number": "25-3/440",
  • "check_template": "jpm",
  • "account_number": "123456789",
  • "account_type": "company",
  • "signatory": "John Doe",
  • "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
  • "bank_city": "Columbus",
  • "bank_state": "OH",
  • "bank_zip": "43240",
  • "verified": false,
  • "date_created": "2015-11-06T19:24:24.440Z",
  • "date_modified": "2015-11-06T19:24:24.440Z",
  • "object": "bank_account"
}

Templates

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

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

Request samples

Content type
{
  • "description": "Test Bank Account",
  • "routing_number": "322271627",
  • "account_number": "123456789",
  • "signatory": "Jane Doe",
  • "account_type": "individual",
  • "metadata": {
    • "spiffy": "true"
    }
}

Response samples

Content type
application/json
{
  • "id": "bank_8cad8df5354d33f",
  • "signature_url": "https://lob-assets.com/letters/asd_asdfghjklqwertyu.pdf?version=45&expires=1234567890&signature=a",
  • "description": "Test Bank Account",
  • "metadata": { },
  • "routing_number": "322271627",
  • "fractional_routing_number": "25-3/440",
  • "check_template": "jpm",
  • "account_number": "123456789",
  • "account_type": "company",
  • "signatory": "John Doe",
  • "bank_name": "J.P. MORGAN CHASE BANK, N.A.,",
  • "bank_city": "Columbus",
  • "bank_state": "OH",
  • "bank_zip": "43240",
  • "verified": false,
  • "date_created": "2015-11-06T19:24:24.440Z",
  • "date_modified": "2015-11-06T19:24:24.440Z",
  • "object": "bank_account"
}

Templates

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

back to top

Retrieve

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

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

id of the template

@@ -4236,9 +4375,9 @@

3. Learn more

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples 

curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121 \
+
https://api.lob.com/v1/templates/{tmpl_id}

Request samples 

curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121 \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

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

Update

Updates the description and/or published version of the template with the given id. To update the template's html, create a new version of the template.

+

Response samples

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

Update

Updates the description and/or published version of the template with the given id. To update the template's html, create a new version of the template.

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

id of the template

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

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

published_version
string^vrsn_[a-zA-Z0-9]+$

The ID of the published version of a template you'd like to update. The published version is the one that will be used in any Print & Mail API requests that reference the specified template. Will err if the referenced published_version has been deleted or does not exist.

@@ -4257,16 +4396,16 @@

3. Learn more

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples

Content type
{
  • "description": "Updated Example",
  • "published_version": "vrsn_a"
}

Response samples

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

Delete

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

+
https://api.lob.com/v1/templates/{tmpl_id}

Request samples

Content type
{
  • "description": "Updated Example",
  • "published_version": "vrsn_a"
}

Response samples

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

Delete

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

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

id of the template

Responses

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

Unique identifier prefixed with tmpl_. ID of a saved HTML template.

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples 

curl -X DELETE https://api.lob.com/v1/templates/tmpl_df934eeda694203 \
+
https://api.lob.com/v1/templates/{tmpl_id}

Request samples 

curl -X DELETE https://api.lob.com/v1/templates/tmpl_df934eeda694203 \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

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

List

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

+

Response samples

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

List

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

Authorizations:
basicAuth
query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

How many results to return.

object or object

before and after are both optional but only one of them can be in the query at a time.

include
Array of strings

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

@@ -4281,9 +4420,9 @@

3. Learn more

Array of objects (template)

list of templates

Request samples 

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

Request samples 

curl -X GET "https://api.lob.com/v1/templates?limit=2" \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "object": "list",
  • "previous_url": null,
  • "next_url": "https://api.lob.com/v1/templates?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0yOVQxMDoyMjozNC42NDJaIiwiaWRPZmZzZXQiOiJ0bXBsXzU5YjIxNTBhZTEyMDg4NyJ9",
  • "count": 2
}

Create

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

+

Response samples

Content type
application/json
{
  • "data": [
    • {
      },
    • {
      }
    ],
  • "object": "list",
  • "previous_url": null,
  • "next_url": "https://api.lob.com/v1/templates?limit=2&after=eyJkYXRlT2Zmc2V0IjoiMjAxOS0wMy0yOVQxMDoyMjozNC42NDJaIiwiaWRPZmZzZXQiOiJ0bXBsXzU5YjIxNTBhZTEyMDg4NyJ9",
  • "count": 2
}

Create

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

Authorizations:
basicAuth
Request Body schema:
html
required
string (template_html) <= 100000 characters

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

  • Postcards - front and back
    • @@ -4316,7 +4455,7 @@

    3. Learn more

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples

Content type
{
  • "description": "demo",
  • "html": "<html>HTML for {{name}}</html>",
  • "metadata": {
    • "spiffy": "true"
    },
  • "engine": "handlebars"
}

Response samples

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

Template Versions

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

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

Request samples

Content type
{
  • "description": "demo",
  • "html": "<html>HTML for {{name}}</html>",
  • "metadata": {
    • "spiffy": "true"
    },
  • "engine": "handlebars"
}

Response samples

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

Template Versions

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

back to top

Retrieve

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

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

The ID of the template to which the version belongs.

@@ -4347,9 +4486,9 @@

3. Learn more

merge_variables
object

Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings.

Request samples 

curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121/versions/vrsn_534e339882d2282 \
+
https://api.lob.com/v1/templates/{tmpl_id}/versions/{vrsn_id}

Request samples 

curl https://api.lob.com/v1/templates/tmpl_c94e83ca2cd5121/versions/vrsn_534e339882d2282 \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

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

Update

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

+

Response samples

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

Update

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

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

The ID of the template to which the version belongs.

vrsn_id
required
string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$

id of the template_version

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

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

@@ -4388,7 +4527,7 @@

3. Learn more

merge_variables
object

Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings.

Request samples

Content type
{
  • "description": "Some description"
}

Response samples

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

Delete

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

+
https://api.lob.com/v1/templates/{tmpl_id}/versions/{vrsn_id}

Request samples

Content type
{
  • "description": "Some description"
}

Response samples

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

Delete

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

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

The ID of the template to which the version belongs.

vrsn_id
required
string (vrsn_id) ^vrsn_[a-zA-Z0-9]+$

id of the template_version

Responses

deleted
boolean (deleted)

Only returned if the resource has been successfully deleted.

Request samples 

curl -X DELETE https://api.lob.com/v1/templates/tmpl_4aa14648113e45b/versions/vrsn_534e339882d2282 \
+
https://api.lob.com/v1/templates/{tmpl_id}/versions/{vrsn_id}

Request samples 

curl -X DELETE https://api.lob.com/v1/templates/tmpl_4aa14648113e45b/versions/vrsn_534e339882d2282 \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

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

List

Returns a list of template versions for the given template ID. The template versions are sorted by creation date, with the most recently created appearing first.

+

Response samples

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

List

Returns a list of template versions for the given template ID. The template versions are sorted by creation date, with the most recently created appearing first.

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

The ID of the template associated with the retrieved versions

query Parameters
limit
integer [ 1 .. 100 ]
Default: 10
Example: limit=10

How many results to return.

object or object

before and after are both optional but only one of them can be in the query at a time.

@@ -4413,9 +4552,9 @@

3. Learn more

Array of objects (template_version)

list of template versions

Request samples 

curl -X GET "https://api.lob.com/v1/templates/tmpl_ea6e6a1abf01703/versions?limit=2" \
+
https://api.lob.com/v1/templates/{tmpl_id}/versions

Request samples 

curl -X GET "https://api.lob.com/v1/templates/tmpl_ea6e6a1abf01703/versions?limit=2" \
   -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc:
-

Response samples

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

Create

Creates a new template version attached to the specified template.

+

Response samples

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

Create

Creates a new template version attached to the specified template.

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

The ID of the template the new version will be attached to

Request Body schema:
html
required
string (template_html) <= 100000 characters

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

    @@ -4462,7 +4601,7 @@

    3. Learn more

merge_variables
object

Object representing the keys of every merge variable present in the template. It has one key named 'keys', and its value is an array of strings.

Request samples

Content type
{
  • "description": "Some Description",
  • "html": "<html>HTML for {{name}}</html>"
}

Response samples

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

Template Design

HTML Templates

You can save commonly used HTML as templates within Lob to more easily manage them. You can reference +

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

Request samples

Content type
{
  • "description": "Some Description",
  • "html": "<html>HTML for {{name}}</html>"
}

Response samples

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

Template Design

HTML Templates

You can save commonly used HTML as templates within Lob to more easily manage them. You can reference your saved templates in postcard, letter, and check requests instead of having to pass a long HTML string on each request. Additionally, you can make changes to your HTML templates and update them independently, without having to touch your API integration. Templates can be created, edited, @@ -4780,9 +4919,9 @@

Example Create Request using Sen

total_count
integer

Indicates the total number of records. Provided when the request specifies an "include" query parameter

Array of objects (campaign)

list of campaigns

Request samples 

curl https://api.lob.com/v1/campaigns \
+
https://api.lob.com/v1/campaigns

Request samples 

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

Response samples

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

Create

Creates a new campaign with the provided properties. See how to launch your first campaign here.

+

Response samples

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

Create

Creates a new campaign with the provided properties. See how to launch your first campaign here.

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
    • @@ -4819,7 +4958,7 @@

    Example Create Request using Sen

object (metadata) <= 500 characters [^"\\]{0,500}

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

Request samples

Content type
{
  • "name": "My Demo Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate"
}

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Retrieve

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

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

Request samples

Content type
{
  • "name": "My Demo Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate"
}

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Retrieve

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

Authorizations:
basicAuth
path Parameters
cmp_id
required
string (Campaign id) ^cmp_[a-zA-Z0-9]+$

id of the campaign

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.

@@ -4842,9 +4981,9 @@

Example Create Request using Sen

object (metadata) <= 500 characters [^"\\]{0,500}

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

Request samples 

curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \
+
https://api.lob.com/v1/campaigns/{cmp_id}

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Update

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

+

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Update

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

Authorizations:
basicAuth
path Parameters
cmp_id
required
string (Campaign id) ^cmp_[a-zA-Z0-9]+$

id of the campaign

Request Body schema:
name
string (Name)
description
string or null (resource_description) <= 255 characters

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

schedule_type
string (cmp_schedule_type)
Value: "immediate"

How the campaign should be scheduled. Only value available today is immediate.

@@ -4876,16 +5015,16 @@

Example Create Request using Sen

object (metadata) <= 500 characters [^"\\]{0,500}

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

Request samples

Content type
{
  • "description": "Test campaign"
}

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Delete

Delete an existing campaign. You need only supply the unique identifier that was returned upon campaign creation. Deleting a campaign also deletes any associated mail pieces that have been created but not sent. A campaign's send_date matches its associated mail pieces' send_dates.

+
https://api.lob.com/v1/campaigns/{cmp_id}

Request samples

Content type
{
  • "description": "Test campaign"
}

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Delete

Delete an existing campaign. You need only supply the unique identifier that was returned upon campaign creation. Deleting a campaign also deletes any associated mail pieces that have been created but not sent. A campaign's send_date matches its associated mail pieces' send_dates.

Authorizations:
basicAuth
path Parameters
cmp_id
required
string (Campaign id) ^cmp_[a-zA-Z0-9]+$

id of the campaign

Responses

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

Unique identifier prefixed with cmp_.

deleted
boolean

True if the resource has been successfully deleted.

Request samples 

curl -X DELETE https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b \
+
https://api.lob.com/v1/campaigns/{cmp_id}

Request samples 

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

Response samples

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

Send Campaign

Sends a campaign. You need only supply the unique campaign identifier that was returned upon campaign creation.

+

Response samples

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

Send Campaign

Sends a campaign. You need only supply the unique campaign identifier that was returned upon campaign creation.

Authorizations:
basicAuth
path Parameters
cmp_id
required
string (Campaign id) ^cmp_[a-zA-Z0-9]+$

id of the campaign

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.

@@ -4908,9 +5047,9 @@

Example Create Request using Sen

object (metadata) <= 500 characters [^"\\]{0,500}

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

Request samples 

curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b/send \
+
https://api.lob.com/v1/campaigns/{cmp_id}/send

Request samples 

curl https://api.lob.com/v1/campaigns/cmp_e05ee61ff80764b/send \
   -u <YOUR API KEY>:
-

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Creatives

The creatives endpoint allows you to create and view creatives. Creatives are used to create +

Response samples

Content type
application/json
{
  • "id": "cmp_e05ee61ff80764b",
  • "billing_group_id": "bg_fe3079dcdd80e5ae",
  • "name": "My Campaign",
  • "description": "My Campaign's description",
  • "schedule_type": "immediate",
  • "cancel_window_campaign_minutes": 60,
  • "metadata": { },
  • "use_type": "marketing",
  • "is_draft": true,
  • "deleted": false,
  • "creatives": [ ],
  • "uploads": [ ],
  • "auto_cancel_if_ncoa": false,
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "campaign"
}

Creatives

The creatives endpoint allows you to create and view creatives. Creatives are used to create reusable letter and postcard templates. The API provides endpoints for creating creatives, updating creatives, retrieving individual creatives, and deleting creatives.

Create

Creates a new creative with the provided properties

@@ -4961,7 +5100,7 @@

Example Create Request using Sen

deleted
required
boolean

Only returned if the resource has been successfully deleted.

Request samples

Content type
{
  • "campaign_id": "cmp_e05ee61ff80764b",
  • "resource_type": "postcard",
  • "description": "Our 4x6 postcard creative",
  • "details": { }
}

Response samples

Content type
application/json
{
  • "id": "crv_2a3b096c409b32c",
  • "description": "Our 4x6 postcard creative",
  • "from": "adr_210a8d4b0b76d77b",
  • "resource_type": "postcard",
  • "details": { },
  • "metadata": { },
  • "template_preview_urls": { },
  • "template_previews": [ ],
  • "campaigns": [ ],
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "creative"
}

Retrieve

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

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

Request samples

Content type
{
  • "campaign_id": "cmp_e05ee61ff80764b",
  • "resource_type": "postcard",
  • "description": "Our 4x6 postcard creative",
  • "details": { }
}

Response samples

Content type
application/json
{
  • "id": "crv_2a3b096c409b32c",
  • "description": "Our 4x6 postcard creative",
  • "from": "adr_210a8d4b0b76d77b",
  • "resource_type": "postcard",
  • "details": { },
  • "metadata": { },
  • "template_preview_urls": { },
  • "template_previews": [ ],
  • "campaigns": [ ],
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "creative"
}

Retrieve

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

Authorizations:
basicAuth
path Parameters
crv_id
required
string (crv_id) ^crv_[a-zA-Z0-9]+$
Example: crv_2a3b096c409b32c

id of the creative

Responses

Response Schema: application/json
One of
resource_type
required
string
Value: "postcard"

Mailpiece type for the creative

@@ -4979,9 +5118,9 @@

Example Create Request using Sen

deleted
required
boolean

Only returned if the resource has been successfully deleted.

Request samples 

curl https://api.lob.com/v1/creatives/crv_2a3b096c409b32c \
+
https://api.lob.com/v1/creatives/{crv_id}

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "crv_2a3b096c409b32c",
  • "description": "Our 4x6 postcard creative",
  • "from": "adr_210a8d4b0b76d77b",
  • "resource_type": "postcard",
  • "details": { },
  • "metadata": { },
  • "template_preview_urls": { },
  • "template_previews": [ ],
  • "campaigns": [ ],
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "creative"
}

Update

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

+

Response samples

Content type
application/json
{
  • "id": "crv_2a3b096c409b32c",
  • "description": "Our 4x6 postcard creative",
  • "from": "adr_210a8d4b0b76d77b",
  • "resource_type": "postcard",
  • "details": { },
  • "metadata": { },
  • "template_preview_urls": { },
  • "template_previews": [ ],
  • "campaigns": [ ],
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "creative"
}

Update

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

Authorizations:
basicAuth
path Parameters
crv_id
required
string (crv_id) ^crv_[a-zA-Z0-9]+$
Example: crv_2a3b096c409b32c

id of the creative

Request Body schema:
adr_id (string) or (address_editable_us (address obj with `name` defined (object) or address obj with `company` defined (object))) (From)

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

description
string or null (resource_description) <= 255 characters

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

@@ -5002,7 +5141,7 @@

Example Create Request using Sen

deleted
required
boolean

Only returned if the resource has been successfully deleted.

Request samples

Content type
{
  • "description": "Test creative"
}

Response samples

Content type
application/json
{
  • "id": "crv_2a3b096c409b32c",
  • "description": "Our 4x6 postcard creative",
  • "from": "adr_210a8d4b0b76d77b",
  • "resource_type": "postcard",
  • "details": { },
  • "metadata": { },
  • "template_preview_urls": { },
  • "template_previews": [ ],
  • "campaigns": [ ],
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "creative"
}

Uploads

The uploads endpoint allows you to upload audience files that are then associated with a given campaign. +

https://api.lob.com/v1/creatives/{crv_id}

Request samples

Content type
{
  • "description": "Test creative"
}

Response samples

Content type
application/json
{
  • "id": "crv_2a3b096c409b32c",
  • "description": "Our 4x6 postcard creative",
  • "from": "adr_210a8d4b0b76d77b",
  • "resource_type": "postcard",
  • "details": { },
  • "metadata": { },
  • "template_preview_urls": { },
  • "template_previews": [ ],
  • "campaigns": [ ],
  • "date_created": "2017-09-05T17:47:53.767Z",
  • "date_modified": "2017-09-05T17:47:53.767Z",
  • "object": "creative"
}

Uploads

The uploads endpoint allows you to upload audience files that are then associated with a given campaign. At this time, only CSV files are allowed. The API provides endpoints for creating uploads, uploading audience files, and marking uploaded files as ready for processing. The API also provides endpoints for downloading files that describe the results, both successful and not, of the processing.

@@ -5027,9 +5166,9 @@

Example Create Request using Sen

failuresUrl
string (Failures URL)

Url where your campaign mailpiece failures can be retrieved

originalFilename
string (Original Filename)

Filename of the upload

Request samples 

curl https://api.lob.com/v1/uploads \
+
https://api.lob.com/v1/uploads

Request samples 

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

Response samples

Content type
application/json
[
  • {
    • "id": "upl_71be866e430b11e9",
    • "accountId": "fa9ea650fc7b31a89f92",
    • "campaignId": "cmp_1933ad629bae1408",
    • "mode": "test",
    • "failuresUrl": "https://www.example.com",
    • "originalFilename": "my_audience.csv",
    • "state": "Draft",
    • "totalMailpieces": 100,
    • "failedMailpieces": 5,
    • "validatedMailpieces": 95,
    • "bytesProcessed": 17268,
    • "dateCreated": "2017-09-05T17:47:53.767Z",
    • "dateModified": "2017-09-05T17:47:53.767Z",
    • "requiredAddressColumnMapping": {
      },
    • "optionalAddressColumnMapping": {
      },
    • "mergeVariableColumnMapping": {
      },
    • "metadata": {
      }
    }
]

Create

Creates a new upload with the provided properties.

+

Response samples

Content type
application/json
[
  • {
    • "id": "upl_71be866e430b11e9",
    • "accountId": "fa9ea650fc7b31a89f92",
    • "campaignId": "cmp_1933ad629bae1408",
    • "mode": "test",
    • "failuresUrl": "https://www.example.com",
    • "originalFilename": "my_audience.csv",
    • "state": "Draft",
    • "totalMailpieces": 100,
    • "failedMailpieces": 5,
    • "validatedMailpieces": 95,
    • "bytesProcessed": 17268,
    • "dateCreated": "2017-09-05T17:47:53.767Z",
    • "dateModified": "2017-09-05T17:47:53.767Z",
    • "requiredAddressColumnMapping": {
      },
    • "optionalAddressColumnMapping": {
      },
    • "mergeVariableColumnMapping": {
      },
    • "metadata": {
      }
    }
]

Create

Creates a new upload with the provided properties.

Authorizations:
basicAuth
Request Body schema: application/json
campaignId
required
string (Campaign id) ^cmp_[a-zA-Z0-9]+$

Unique identifier prefixed with cmp_.

object (Required Address Columns)

The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details.

object (Optional Address Columns)

The mapping of column headers in your file to Lob-optional fields for the resource created. See our Campaign Audience Guide for additional details.

@@ -5055,7 +5194,7 @@

Example Create Request using Sen

originalFilename
string (Original Filename)

Filename of the upload

Request samples

Content type
application/json
{
  • "campaignId": "cmp_1933ad629bae1408",
  • "requiredAddressColumnMapping": {
    • "name": "recipient_name",
    • "address_line1": "primary_line",
    • "address_city": "city",
    • "address_state": "state",
    • "address_zip": "zip_code"
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": "secondary_line",
    • "company": "company",
    • "address_country": "country,"
    },
  • "metadata": {
    • "columns": [
      ]
    },
  • "mergeVariableColumnMapping": {
    • "name": "recipient_name",
    • "gift_code": "code",
    • "qr_code_redirect_url": "redirect_url"
    }
}

Response samples

Content type
application/json
{
  • "id": "upl_71be866e430b11e9",
  • "accountId": "fa9ea650fc7b31a89f92",
  • "campaignId": "cmp_1933ad629bae1408",
  • "mode": "live",
  • "failuresUrl": "http://www.example.com",
  • "originalFilename": "my_audience.csv",
  • "state": "Draft",
  • "totalMailpieces": 100,
  • "failedMailpieces": 5,
  • "validatedMailpieces": 95,
  • "bytesProcessed": 17628,
  • "dateCreated": "2017-09-05T17:47:53.767Z",
  • "dateModified": "2017-09-05T17:47:53.767Z",
  • "requiredAddressColumnMapping": {
    • "name": null,
    • "address_line1": null,
    • "address_city": null,
    • "address_state": null,
    • "address_zip": null
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": null,
    • "company": null,
    • "address_country": null
    },
  • "mergeVariableColumnMapping": null,
  • "metadata": {
    • "columns": [ ]
    }
}

Retrieve

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

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

Request samples

Content type
application/json
{
  • "campaignId": "cmp_1933ad629bae1408",
  • "requiredAddressColumnMapping": {
    • "name": "recipient_name",
    • "address_line1": "primary_line",
    • "address_city": "city",
    • "address_state": "state",
    • "address_zip": "zip_code"
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": "secondary_line",
    • "company": "company",
    • "address_country": "country,"
    },
  • "metadata": {
    • "columns": [
      ]
    },
  • "mergeVariableColumnMapping": {
    • "name": "recipient_name",
    • "gift_code": "code",
    • "qr_code_redirect_url": "redirect_url"
    }
}

Response samples

Content type
application/json
{
  • "id": "upl_71be866e430b11e9",
  • "accountId": "fa9ea650fc7b31a89f92",
  • "campaignId": "cmp_1933ad629bae1408",
  • "mode": "live",
  • "failuresUrl": "http://www.example.com",
  • "originalFilename": "my_audience.csv",
  • "state": "Draft",
  • "totalMailpieces": 100,
  • "failedMailpieces": 5,
  • "validatedMailpieces": 95,
  • "bytesProcessed": 17628,
  • "dateCreated": "2017-09-05T17:47:53.767Z",
  • "dateModified": "2017-09-05T17:47:53.767Z",
  • "requiredAddressColumnMapping": {
    • "name": null,
    • "address_line1": null,
    • "address_city": null,
    • "address_state": null,
    • "address_zip": null
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": null,
    • "company": null,
    • "address_country": null
    },
  • "mergeVariableColumnMapping": null,
  • "metadata": {
    • "columns": [ ]
    }
}

Retrieve

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

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

id of the upload

Responses

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

Unique identifier prefixed with cmp_.

@@ -5078,9 +5217,9 @@

Example Create Request using Sen

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9 \
+
https://api.lob.com/v1/uploads/{upl_id}

Request samples 

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

Response samples

Content type
application/json
{
  • "id": "upl_71be866e430b11e9",
  • "accountId": "fa9ea650fc7b31a89f92",
  • "campaignId": "cmp_1933ad629bae1408",
  • "mode": "live",
  • "failuresUrl": "http://www.example.com",
  • "originalFilename": "my_audience.csv",
  • "state": "Draft",
  • "totalMailpieces": 100,
  • "failedMailpieces": 5,
  • "validatedMailpieces": 95,
  • "bytesProcessed": 17628,
  • "dateCreated": "2017-09-05T17:47:53.767Z",
  • "dateModified": "2017-09-05T17:47:53.767Z",
  • "requiredAddressColumnMapping": {
    • "name": null,
    • "address_line1": null,
    • "address_city": null,
    • "address_state": null,
    • "address_zip": null
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": null,
    • "company": null,
    • "address_country": null
    },
  • "mergeVariableColumnMapping": null,
  • "metadata": {
    • "columns": [ ]
    }
}

Update

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

+

Response samples

Content type
application/json
{
  • "id": "upl_71be866e430b11e9",
  • "accountId": "fa9ea650fc7b31a89f92",
  • "campaignId": "cmp_1933ad629bae1408",
  • "mode": "live",
  • "failuresUrl": "http://www.example.com",
  • "originalFilename": "my_audience.csv",
  • "state": "Draft",
  • "totalMailpieces": 100,
  • "failedMailpieces": 5,
  • "validatedMailpieces": 95,
  • "bytesProcessed": 17628,
  • "dateCreated": "2017-09-05T17:47:53.767Z",
  • "dateModified": "2017-09-05T17:47:53.767Z",
  • "requiredAddressColumnMapping": {
    • "name": null,
    • "address_line1": null,
    • "address_city": null,
    • "address_state": null,
    • "address_zip": null
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": null,
    • "company": null,
    • "address_country": null
    },
  • "mergeVariableColumnMapping": null,
  • "metadata": {
    • "columns": [ ]
    }
}

Update

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

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

id of the upload

Request Body schema: application/json
originalFilename
string (Original Filename)

Original filename provided when the upload is created.

object (Required Address Columns)

The mapping of column headers in your file to Lob-required fields for the resource created. See our Campaign Audience Guide for additional details.

@@ -5108,27 +5247,27 @@

Example Create Request using Sen

Request samples

Content type
application/json
{
  • "originalFilename": "string",
  • "requiredAddressColumnMapping": {
    • "name": "recipient_name",
    • "address_line1": "primary_line",
    • "address_city": "city",
    • "address_state": "state",
    • "address_zip": "zip_code"
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": "secondary_line",
    • "company": "company",
    • "address_country": "country,"
    },
  • "metadata": {
    • "columns": [
      ]
    },
  • "mergeVariableColumnMapping": {
    • "name": "recipient_name",
    • "gift_code": "code",
    • "qr_code_redirect_url": "redirect_url"
    }
}

Response samples

Content type
application/json
{
  • "id": "upl_71be866e430b11e9",
  • "accountId": "fa9ea650fc7b31a89f92",
  • "campaignId": "cmp_1933ad629bae1408",
  • "mode": "live",
  • "failuresUrl": "http://www.example.com",
  • "originalFilename": "my_audience.csv",
  • "state": "Draft",
  • "totalMailpieces": 100,
  • "failedMailpieces": 5,
  • "validatedMailpieces": 95,
  • "bytesProcessed": 17628,
  • "dateCreated": "2017-09-05T17:47:53.767Z",
  • "dateModified": "2017-09-05T17:47:53.767Z",
  • "requiredAddressColumnMapping": {
    • "name": null,
    • "address_line1": null,
    • "address_city": null,
    • "address_state": null,
    • "address_zip": null
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": null,
    • "company": null,
    • "address_country": null
    },
  • "mergeVariableColumnMapping": null,
  • "metadata": {
    • "columns": [ ]
    }
}

Delete

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

+
https://api.lob.com/v1/uploads/{upl_id}

Request samples

Content type
application/json
{
  • "originalFilename": "string",
  • "requiredAddressColumnMapping": {
    • "name": "recipient_name",
    • "address_line1": "primary_line",
    • "address_city": "city",
    • "address_state": "state",
    • "address_zip": "zip_code"
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": "secondary_line",
    • "company": "company",
    • "address_country": "country,"
    },
  • "metadata": {
    • "columns": [
      ]
    },
  • "mergeVariableColumnMapping": {
    • "name": "recipient_name",
    • "gift_code": "code",
    • "qr_code_redirect_url": "redirect_url"
    }
}

Response samples

Content type
application/json
{
  • "id": "upl_71be866e430b11e9",
  • "accountId": "fa9ea650fc7b31a89f92",
  • "campaignId": "cmp_1933ad629bae1408",
  • "mode": "live",
  • "failuresUrl": "http://www.example.com",
  • "originalFilename": "my_audience.csv",
  • "state": "Draft",
  • "totalMailpieces": 100,
  • "failedMailpieces": 5,
  • "validatedMailpieces": 95,
  • "bytesProcessed": 17628,
  • "dateCreated": "2017-09-05T17:47:53.767Z",
  • "dateModified": "2017-09-05T17:47:53.767Z",
  • "requiredAddressColumnMapping": {
    • "name": null,
    • "address_line1": null,
    • "address_city": null,
    • "address_state": null,
    • "address_zip": null
    },
  • "optionalAddressColumnMapping": {
    • "address_line2": null,
    • "company": null,
    • "address_country": null
    },
  • "mergeVariableColumnMapping": null,
  • "metadata": {
    • "columns": [ ]
    }
}

Delete

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

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

id of the upload

Responses

Request samples 

curl -X DELETE https://api.lob.com/v1/uploads/upl_71be866e430b11e9 \
+
https://api.lob.com/v1/uploads/{upl_id}

Request samples 

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

Upload file

Upload an audience file and associate it with an upload.

+

Upload file

Upload an audience file and associate it with an upload.

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

ID of the upload

Request Body schema: multipart/form-data
file
string <binary>

Responses

Request samples 

curl -X POST https://api.lob.com/v1/uploads/upl_71be866e430b11e9/file \
+
https://api.lob.com/v1/uploads/{upl_id}/file

Request samples 

curl -X POST https://api.lob.com/v1/uploads/upl_71be866e430b11e9/file \
   -u <YOUR API KEY>: \
   -F file=@<YOUR FILE NAME HERE>
-

Response samples

Content type
application/json
{
  • "message": "File uploaded successfully",
  • "filename": "string"
}

Create Export

Campaign Exports can help you understand exactly which records in a campaign could not be created. By initiating and retrieving an export, you will get row-by-row errors for your campaign. For a step-by-step walkthrough of creating a campaign and exporting failures, see our Campaigns Guide.

+

Response samples

Content type
application/json
{
  • "message": "File uploaded successfully",
  • "filename": "string"
}

Create Export

Campaign Exports can help you understand exactly which records in a campaign could not be created. By initiating and retrieving an export, you will get row-by-row errors for your campaign. For a step-by-step walkthrough of creating a campaign and exporting failures, see our Campaigns Guide.

Create an export file associated with an upload.

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

ID of the upload

Request Body schema: application/json
type
string
Enum: "all" "failures" "successes"

Responses

Response Schema: application/json
message
required
string (Message)
Default: "Export is processing"
Value: "Export is processing"
exportId
required
string (Export ID)

Request samples

Content type
application/json
{
  • "type": "all"
}

Response samples

Content type
application/json
{
  • "message": "Export is processing",
  • "exportId": "ex_2dafd758ed3da9c43"
}

Retrieve Line Item Report

Retrieves the line item data for each row from the csv file associated with the upload id record. NOTE: This endpoint is currently feature flagged. Please reach out to Lob's support team if you would like access to this API endpoint.

+
https://api.lob.com/v1/uploads/{upl_id}/exports

Request samples

Content type
application/json
{
  • "type": "all"
}

Response samples

Content type
application/json
{
  • "message": "Export is processing",
  • "exportId": "ex_2dafd758ed3da9c43"
}

Retrieve Line Item Report

Retrieves the line item data for each row from the csv file associated with the upload id record. NOTE: This endpoint is currently feature flagged. Please reach out to Lob's support team if you would like access to this API endpoint.

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

ID of the upload

query Parameters
status
string
Enum: "Validated" "Failed" "Processing"

The status of line items to filter and retrieve. By default all line items are returned.

limit
integer [ 1 .. 100 ]
Default: 100
Example: limit=10

How many results to return.

@@ -5141,9 +5280,9 @@

Example Create Request using Sen

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/report \
+
https://api.lob.com/v1/uploads/{upl_id}/report

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/report \
   -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"
}

Retrieve Export

Retrieves the details of an existing export. You need only supply the unique export identifier that was returned upon export creation. If you try retrieving an export immediately after creating one (i.e., before we're done processing the export), you will get back an export object with state = in_progress.

+

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"
}

Retrieve Export

Retrieves the details of an existing export. You need only supply the unique export identifier that was returned upon export creation. If you try retrieving an export immediately after creating one (i.e., before we're done processing the export), you will get back an export object with state = in_progress.

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

ID of the upload

ex_id
required
string (ex_id) ^ex_[a-zA-Z0-9]+$

ID of the export

Responses

type
required
string
Enum: "all" "failures" "successes"

The export file type, which can be all, failures or successes.

uploadId
required
string (upl_id) ^upl_[a-zA-Z0-9]+$

Unique identifier prefixed with upl_.

Request samples 

curl https://api.lob.com/v1/uploads/upl_71be866e430b11e9/exports/ex_6a94fe68fd151e0f8 \
+
https://api.lob.com/v1/uploads/{upl_id}/exports/{ex_id}

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"
}

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
@@ -5260,7 +5399,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.

@@ -5326,7 +5465,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]

@@ -5531,7 +5670,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.

@@ -5545,7 +5684,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.

@@ -5621,7 +5760,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:

@@ -5657,7 +5796,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
@@ -5703,7 +5842,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
    • @@ -5768,7 +5907,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 @@ -6224,7 +6363,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 @@ -6449,7 +6588,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
@@ -6464,9 +6603,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.

@@ -6482,7 +6621,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"].

@@ -6498,9 +6637,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.

@@ -6531,9 +6670,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

@@ -6561,7 +6700,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.

@@ -6586,9 +6725,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

@@ -6616,16 +6755,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.

@@ -6641,9 +6780,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.

@@ -6678,9 +6817,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

@@ -6705,7 +6844,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.

@@ -6727,9 +6866,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

@@ -6754,16 +6893,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.

@@ -6779,9 +6918,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
@@ -6818,9 +6957,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
@@ -6832,9 +6971,9 @@

Certified Tracking Event Details

account_id
string

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

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",
  • "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.

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.

@@ -6842,7 +6981,7 @@

Certified Tracking Event Details

account_id
string

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

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.

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

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.

Responses

Response Schema: application/json
id
string

Unique identifier for a domain.

@@ -6850,20 +6989,20 @@

Certified Tracking Event Details

account_id
string

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

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",
  • "account_id": "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" \
+
https://api.lob.com/v1/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": [
    • {
      }
    ]
}

Request samples 

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

Request samples 

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

Response samples

Content type
application/json
{
  • "count": 0,
  • "limit": 0,
  • "offset": 0,
  • "data": [
    • {
      }
    ]
}

Request samples

Content type
Example
{
  • "resource_id": "ltr_133"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "campaign_id": "string",
  • "domain_id": "string",
  • "resource_id": "string",
  • "redirect_link": "string",
  • "short_link": "string",
  • "metadata_tag": {
    • "property1": "string",
    • "property2": "string"
    },
  • "billing_group_id": "string"
}

Request samples

Content type
Example
{}

Response samples

Content type
application/json
{
  • "id": "string",
  • "campaign_id": "string",
  • "domain_id": "string",
  • "resource_id": "string",
  • "redirect_link": "string",
  • "short_link": "string",
  • "metadata_tag": {
    • "property1": "string",
    • "property2": "string"
    },
  • "billing_group_id": "string"
}

Beta Program

At Lob, we pride ourselves on building high quality platform capabilities rapidly +

https://api.lob.com/v1/links/shorten/bulk

Request samples

Content type
{}

Response samples

Content type
application/json
{
  • "count": 0,
  • "limit": 0,
  • "offset": 0,
  • "data": [
    • {
      }
    ]
}

Beta Program

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

Typically, something in Beta means that the feature is early in its lifecycle here at @@ -7540,7 +7679,7 @@

Changelog

View our Changelog here.