openapi.city
Sign in

Lob

Print and mail APIs for direct mail

lob.com/docs ↗
Version
1.19.28
OpenAPI
3.0.3
Endpoints
94
Schemas
303
85
Quality
Updated
3 days ago
Documents documents mail printing
Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://api.lob.com/v1

Endpoints

Clear filters
GET POST PUT PATCH DELETE

Addresses 1 endpoints

POST /addresses

Creates a new address given information

operationId: address_create

Request Body

required
application/json
schema address_editable
multipart/form-data
schema address_editable
application/x-www-form-urlencoded
schema address_editable

Responses

default

Error
200

Echos the writable fields of a newly created address object.
POST /addresses

Bankaccounts 2 endpoints

POST /bank_accounts

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

operationId: BankAccounts_createNewBankAccount

Request Body

required
application/json
schema bank_account_base
Property Type Required
city string optional
state string optional
zipcode string optional
metadata object optional
signatory string required
description string optional
account_type string required
account_number string required
check_template string optional
routing_number string required
fractional_routing_number string optional
multipart/form-data
schema bank_account_base
Property Type Required
city string optional
state string optional
zipcode string optional
metadata object optional
signatory string required
description string optional
account_type string required
account_number string required
check_template string optional
routing_number string required
fractional_routing_number string optional
application/x-www-form-urlencoded
schema bank_account_base
Property Type Required
city string optional
state string optional
zipcode string optional
metadata object optional
signatory string required
description string optional
account_type string required
account_number string required
check_template string optional
routing_number string required
fractional_routing_number string optional

Responses

default

Error
200

Returns a bank_account object
POST /bank_accounts
POST /bank_accounts/{bank_id}/verify

Verify a bank account in order to create a check.

operationId: BankAccounts_verifyBankAccount

Parameters

Name In Required Type Description
bank_id path required

id of the bank account to be verified

Request Body

required
application/json
schema bank_account_verify
Property Type Required
amounts array required
multipart/form-data
schema bank_account_verify
Property Type Required
amounts array required
application/x-www-form-urlencoded
schema bank_account_verify
Property Type Required
amounts array required

Responses

default

Error
200

Returns a bank_account object
POST /bank_accounts/{bank_id}/verify

Billinggroups 2 endpoints

POST /billing_groups

Creates a new billing_group with the provided properties.

operationId: BillingGroups_createNewGroup

Request Body

required
application/json
schema billing_group_editable
Property Type Required
name string required
description string optional
multipart/form-data
schema billing_group_editable
Property Type Required
name string required
description string optional
application/x-www-form-urlencoded
schema billing_group_editable
Property Type Required
name string required
description string optional

Responses

default

Error
200

Returns a billing group object
POST /billing_groups
POST /billing_groups/{bg_id}

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

operationId: BillingGroups_updateAttributes

Parameters

Name In Required Type Description
bg_id path required

id of the billing_group

Request Body

required
application/json
schema billing_group_base
Property Type Required
name string optional
description string optional
multipart/form-data
schema billing_group_base
Property Type Required
name string optional
description string optional
application/x-www-form-urlencoded
schema billing_group_base
Property Type Required
name string optional
description string optional

Responses

default

Error
200

Returns a billing group object
POST /billing_groups/{bg_id}

Bucksliporders 1 endpoints

POST /buckslips/{buckslip_id}/orders

Creates a new buckslip order given information

operationId: BuckslipOrders_createNewOrder

Parameters

Name In Required Type Description
buckslip_id path required

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

Request Body

required
application/json
schema buckslip_order_editable
Property Type Required
quantity integer required
multipart/form-data
schema buckslip_order_editable
Property Type Required
quantity integer required
application/x-www-form-urlencoded
schema buckslip_order_editable
Property Type Required
quantity integer required

Responses

default

Error
200

Buckslip order created successfully
POST /buckslips/{buckslip_id}/orders

Buckslips 1 endpoints

POST /buckslips

Creates a new buckslip given information

operationId: buckslip_create

Request Body

required
application/json
schema buckslip_editable
Property Type Required
size string optional
description string optional
back object optional
front object required
multipart/form-data
schema buckslip_editable
Property Type Required
size string optional
description string optional
back object optional
front object required
application/x-www-form-urlencoded
schema buckslip_editable
Property Type Required
size string optional
description string optional
back object optional
front object required

Responses

default

Error
200

Buckslip created successfully
POST /buckslips

Campaigns 2 endpoints

POST /campaigns

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

operationId: campaign_create

Parameters

Name In Required Type Description
x-lang-output header optional string
  • native - Translate response to the native language of the country in the request
  • match - match the response to the language in the request

Default response is in English.

Request Body

required
application/json
schema campaign_writable
Property Type Required
name string required
metadata object optional
use_type string required
send_date string optional
description string optional
schedule_type string required
billing_group_id string optional
auto_cancel_if_ncoa boolean optional
target_delivery_date string optional
cancel_window_campaign_minutes integer optional
multipart/form-data
schema campaign_writable
Property Type Required
name string required
metadata object optional
use_type string required
send_date string optional
description string optional
schedule_type string required
billing_group_id string optional
auto_cancel_if_ncoa boolean optional
target_delivery_date string optional
cancel_window_campaign_minutes integer optional
application/x-www-form-urlencoded
schema campaign_writable
Property Type Required
name string required
metadata object optional
use_type string required
send_date string optional
description string optional
schedule_type string required
billing_group_id string optional
auto_cancel_if_ncoa boolean optional
target_delivery_date string optional
cancel_window_campaign_minutes integer optional

Responses

default

Error
200

Campaign created successfully
POST /campaigns
POST /campaigns/{cmp_id}/send

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

operationId: campaign_send

Parameters

Name In Required Type Description
cmp_id path required

id of the campaign

Responses

default

Error
200

Returns a campaign object
POST /campaigns/{cmp_id}/send

Cardorders 1 endpoints

POST /cards/{card_id}/orders

Creates a new card order given information

operationId: CardOrders_createNewOrder

Parameters

Name In Required Type Description
card_id path required

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

Request Body

required
application/json
schema card_order_editable
Property Type Required
quantity integer required
multipart/form-data
schema card_order_editable
Property Type Required
quantity integer required
application/x-www-form-urlencoded
schema card_order_editable
Property Type Required
quantity integer required

Responses

default

Error
200

Card order created successfully
POST /cards/{card_id}/orders

Cards 2 endpoints

POST /cards

Creates a new card given information

operationId: card_create

Request Body

required
application/json
schema card_editable
Property Type Required
size string optional
description string optional
back object optional
front object required
multipart/form-data
schema card_editable
Property Type Required
size string optional
description string optional
back object optional
front object required
application/x-www-form-urlencoded
schema card_editable
Property Type Required
size string optional
description string optional
back object optional
front object required

Responses

default

Error
200

Card created successfully
POST /cards
POST /cards/{card_id}

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

operationId: card_update

Parameters

Name In Required Type Description
card_id path required

id of the card

Request Body

required
application/json
schema card_updatable
Property Type Required
description string optional
auto_reorder boolean optional
reorder_quantity number optional
multipart/form-data
schema card_updatable
Property Type Required
description string optional
auto_reorder boolean optional
reorder_quantity number optional
application/x-www-form-urlencoded
schema card_updatable
Property Type Required
description string optional
auto_reorder boolean optional
reorder_quantity number optional

Responses

default

Error
200

Returns a card object
POST /cards/{card_id}

Checks 1 endpoints

POST /checks

Creates a new check with the provided properties.

operationId: check_create

Parameters

Name In Required Type Description
Idempotency-Key header optional string

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

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

required
application/json
schema check_editable
multipart/form-data
schema check_editable
application/x-www-form-urlencoded
schema check_editable

Responses

default

Error
200

Returns a check object
POST /checks

Creatives 1 endpoints

POST /creatives

Creates a new creative with the provided properties

operationId: creative_create

Parameters

Name In Required Type Description
x-lang-output header optional string
  • native - Translate response to the native language of the country in the request
  • match - match the response to the language in the request

Default response is in English.

Request Body

required
application/json
schema creative_writable
multipart/form-data
schema creative_writable
application/x-www-form-urlencoded
schema creative_writable

Responses

default

Error
200

Creative created successfully
POST /creatives

Identityvalidation 1 endpoints

POST /identity_validation

Validates whether a given name is associated with an address.

operationId: identity_validation

Request Body

required
application/json
schema identity_validation_writable
multipart/form-data
schema identity_validation_writable
application/x-www-form-urlencoded
schema identity_validation_writable

Responses

default

Error
200

Returns the likelihood a given name is associated with an address.
POST /identity_validation

Intlautocompletions 1 endpoints

POST /intl_autocompletions

Given an address prefix consisting of a partial primary line and country, as well as optional input of city, state, and zip code, this functionality returns up to 10 full International address suggestions. Not all of them will turn out to be valid addresses; they’ll need to be verified.

operationId: intl_autocompletions

Parameters

Name In Required Type Description
x-lang-output header optional string
  • native - Translate response to the native language of the country in the request
  • match - match the response to the language in the request

Default response is in English.

Request Body

required
application/json
schema intl_autocompletions_writable
Property Type Required
city string optional
state string optional
country string required
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required
multipart/form-data
schema intl_autocompletions_writable
Property Type Required
city string optional
state string optional
country string required
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required
application/x-www-form-urlencoded
schema intl_autocompletions_writable
Property Type Required
city string optional
state string optional
country string required
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required

Responses

default

Error
200

Returns an international autocompletions object.
POST /intl_autocompletions

Intlverifications 2 endpoints

POST /intl_verifications

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.

operationId: intl_verification

Parameters

Name In Required Type Description
x-lang-output header optional string
  • native - Translate response to the native language of the country in the request
  • match - match the response to the language in the request

Default response is in English.

Request Body

required
application/json
schema intl_verification_writable
multipart/form-data
schema intl_verification_writable
application/x-www-form-urlencoded
schema intl_verification_writable

Responses

default

Error
200

Returns an international verification object.
POST /intl_verifications
POST /bulk/intl_verifications

Verify a list of international (except US or US territories) address with a live API key. Requests to this endpoint with a test API key will return a dummy response based on the primary line you input.

operationId: IntlVerifications_verifyBulkAddresses

Request Body

required
application/json
schema intl_verifications_payload
Property Type Required
addresses array required
└ recipient string optional
└ primary_line string required
└ secondary_line string optional
└ city string optional
└ state string optional
└ country string required
└ postal_code string optional
multipart/form-data
schema intl_verifications_payload
Property Type Required
addresses array required
└ recipient string optional
└ primary_line string required
└ secondary_line string optional
└ city string optional
└ state string optional
└ country string required
└ postal_code string optional

Responses

default

Error
200

Returns an array of international verification objects.
POST /bulk/intl_verifications

Letters 1 endpoints

POST /letters

Creates a new letter given information

operationId: letter_create

Parameters

Name In Required Type Description
Idempotency-Key header optional string

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

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

A string representing the version of the API being used. For more information on versioning, refer to our Versioning and Changelog documentation.

Request Body

required
application/json
schema letter_editable
Property Type Required
to object required
from object required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
fsc boolean optional
file object required
size string optional
cards array optional
color boolean required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
double_sided boolean optional
extra_service string optional
custom_envelope string optional
perforated_page integer optional
return_envelope object optional
billing_group_id string optional
…1 more object optional
multipart/form-data
schema letter_editable
Property Type Required
to object required
from object required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
fsc boolean optional
file object required
size string optional
cards array optional
color boolean required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
double_sided boolean optional
extra_service string optional
custom_envelope string optional
perforated_page integer optional
return_envelope object optional
billing_group_id string optional
…1 more object optional
application/x-www-form-urlencoded
schema letter_editable
Property Type Required
to object required
from object required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
fsc boolean optional
file object required
size string optional
cards array optional
color boolean required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
double_sided boolean optional
extra_service string optional
custom_envelope string optional
perforated_page integer optional
return_envelope object optional
billing_group_id string optional
…1 more object optional

Responses

default

Error
200

Returns a letter object
POST /letters

Postcards 1 endpoints

POST /postcards

Creates a new postcard given information

operationId: postcard_create

Parameters

Name In Required Type Description
Idempotency-Key header optional string

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

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

required
application/json
schema postcard_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
back object required
front object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
multipart/form-data
schema postcard_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
back object required
front object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
application/x-www-form-urlencoded
schema postcard_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
back object required
front object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional

Responses

default

Error
200

Returns a postcard object
POST /postcards

Reversegeocodelookups 1 endpoints

POST /us_reverse_geocode_lookups

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

operationId: ReverseGeocodeLookups_usLocationWithLiveApiKey

Parameters

Name In Required Type Description
size query optional integer

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

required
application/json
schema location
Property Type Required
latitude number required
longitude number required
multipart/form-data
schema location
Property Type Required
latitude number required
longitude number required
application/x-www-form-urlencoded
schema location
Property Type Required
latitude number required
longitude number required

Responses

default

Error
200

Returns a zip lookup object if a valid zip was provided.
POST /us_reverse_geocode_lookups

Selfmailers 1 endpoints

POST /self_mailers

Creates a new self_mailer given information

operationId: SelfMailers_createNewSelfMailer

Parameters

Name In Required Type Description
Idempotency-Key header optional string

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

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

required
application/json
schema self_mailer_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
inside object required
outside object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
multipart/form-data
schema self_mailer_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
inside object required
outside object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional
application/x-www-form-urlencoded
schema self_mailer_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
fsc boolean optional
inside object required
outside object required
qr_code object optional
└ top string optional
└ left string optional
└ pages string optional
└ right string optional
└ width string required
└ bottom string optional
└ position string required
└ redirect_url string required
use_type string required
billing_group_id string optional

Responses

default

Error
200

Returns a self_mailer object
POST /self_mailers

Snappacks 1 endpoints

POST /snap_packs

Creates a new snap_pack given information

operationId: SnapPacks_createNewSnapPack

Parameters

Name In Required Type Description
Idempotency-Key header optional string

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

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

required
application/json
schema snap_pack_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
color boolean optional
inside object required
outside object required
use_type string required
billing_group_id string optional
multipart/form-data
schema snap_pack_editable
Property Type Required
metadata object optional
mail_type string optional
send_date string optional
description string optional
merge_variables object optional
size string optional
to object required
from object optional
color boolean optional
inside object required
outside object required
use_type string required
billing_group_id string optional

Responses

default

Error
200

Returns a snap_pack object
POST /snap_packs

Templateversions 2 endpoints

POST /templates/{tmpl_id}/versions

Creates a new template version attached to the specified template.

operationId: TemplateVersions_createNewVersion

Parameters

Name In Required Type Description
tmpl_id path required

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

Request Body

required
application/json
schema template_version_writable
Property Type Required
html string required
engine string optional
description string optional
required_vars array optional
multipart/form-data
schema template_version_writable
Property Type Required
html string required
engine string optional
description string optional
required_vars array optional
application/x-www-form-urlencoded
schema template_version_writable
Property Type Required
html string required
engine string optional
description string optional
required_vars array optional

Responses

default

Error
200

Returns the template version with the given template and version ids.
POST /templates/{tmpl_id}/versions
POST /templates/{tmpl_id}/versions/{vrsn_id}

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

operationId: TemplateVersions_updateTemplateVersion

Parameters

Name In Required Type Description
tmpl_id path required

The ID of the template to which the version belongs.
vrsn_id path required

id of the template_version

Request Body

required
application/json
schema template_version_updatable
Property Type Required
engine string optional
description string optional
required_vars array optional
multipart/form-data
schema template_version_updatable
Property Type Required
engine string optional
description string optional
required_vars array optional
application/x-www-form-urlencoded
schema template_version_updatable
Property Type Required
engine string optional
description string optional
required_vars array optional

Responses

default

Error
200

Returns the template version with the given template and version ids.
POST /templates/{tmpl_id}/versions/{vrsn_id}

Templates 2 endpoints

POST /templates

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.

operationId: create_template

Request Body

required
application/json
schema template_writable
Property Type Required
html string required
engine string optional
metadata object optional
description string optional
required_vars array optional
multipart/form-data
schema template_writable
Property Type Required
html string required
engine string optional
metadata object optional
description string optional
required_vars array optional
application/x-www-form-urlencoded
schema template_writable
Property Type Required
html string required
engine string optional
metadata object optional
description string optional
required_vars array optional

Responses

default

Error
200

Returns a template object
POST /templates
POST /templates/{tmpl_id}

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.

operationId: template_update

Parameters

Name In Required Type Description
tmpl_id path required

id of the template

Request Body

required
application/json
schema template_update
Property Type Required
description string optional
published_version string optional
multipart/form-data
schema template_update
Property Type Required
description string optional
published_version string optional
application/x-www-form-urlencoded
schema template_update
Property Type Required
description string optional
published_version string optional

Responses

default

Error
200

Returns the updated template object
POST /templates/{tmpl_id}

Urlshortener 3 endpoints

POST /domains

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

operationId: domain_create

Request Body

required
application/json
schema domains
Property Type Required
domain string required
multipart/form-data
schema domains
Property Type Required
domain string required
application/x-www-form-urlencoded
schema domains
Property Type Required
domain string required

Responses

default

Error
200

Returns a domain object with details.
POST /domains
POST /links/shorten

Given a long URL, shorten your URL either by using a custom domain or Lob’s own short domain.

operationId: link_create

Request Body

required
application/json
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
multipart/form-data
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
application/x-www-form-urlencoded
schema link_single
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional

Responses

default

Error
200

Returns a successfully created link.
POST /links/shorten
POST /links/shorten/bulk

Shortens a list of links in a single request.

operationId: UrlShortener_bulkShortenLinks

Request Body

required
application/json
schema link_list
array of object
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
multipart/form-data
schema link_list
array of object
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional
application/x-www-form-urlencoded
schema link_list
array of object
Property Type Required
slug string optional
domain string optional
metadata_tag object optional
redirect_link string required
billing_group_id string optional

Responses

default

Error
200

Returns all successfully created links
POST /links/shorten/bulk

Usautocompletions 1 endpoints

POST /us_autocompletions

Given an address prefix consisting of a partial primary line, as well as optional input of city, state, and zip code, this functionality returns up to 10 full US address suggestions. Not all of them will turn out to be valid addresses; they’ll need to be verified.

operationId: UsAutocompletions_getSuggestions

Parameters

Name In Required Type Description
case query optional string

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 primary_line, city, and state. Default casing is upper.
valid_addresses query optional boolean

Possible values are true and false. If false, not all of the suggestions in the response will be valid addresses; they’ll need to be verified in order to determine the deliverability. The valid_addresses flag will greatly reduce the number of keystrokes needed before reaching an intended address.

Request Body

required
application/json
schema us_autocompletions_writable
Property Type Required
city string optional
state string optional
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required
multipart/form-data
schema us_autocompletions_writable
Property Type Required
city string optional
state string optional
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required
application/x-www-form-urlencoded
schema us_autocompletions_writable
Property Type Required
city string optional
state string optional
zip_code string optional
geo_ip_sort boolean optional
address_prefix string required

Responses

default

Error
200

Returns a US autocompletion object.
POST /us_autocompletions

Usverifications 2 endpoints

POST /us_verifications

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.

operationId: us_verification

Parameters

Name In Required Type Description
case query optional string

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

required
application/json
schema us_verifications_writable
multipart/form-data
schema us_verifications_writable
application/x-www-form-urlencoded
schema us_verifications_writable

Responses

default

Error
200

Returns a US verification object.
POST /us_verifications
POST /bulk/us_verifications

Verify a list of US or US territory addresses with a live API key. Requests to this endpoint with a test API key will return a dummy response based on the primary line you input.

operationId: UsVerifications_bulkVerifyAddresses

Parameters

Name In Required Type Description
case query optional string

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

required
application/json
schema multiple_components_list
Property Type Required
addresses array required
└ city string optional
└ state string optional
└ zip_code string optional
└ recipient string optional
└ primary_line string required
└ urbanization string optional
└ secondary_line string optional
multipart/form-data
schema multiple_components_list
Property Type Required
addresses array required
└ city string optional
└ state string optional
└ zip_code string optional
└ recipient string optional
└ primary_line string required
└ urbanization string optional
└ secondary_line string optional
application/x-www-form-urlencoded
schema multiple_components_list
Property Type Required
addresses array required
└ city string optional
└ state string optional
└ zip_code string optional
└ recipient string optional
└ primary_line string required
└ urbanization string optional
└ secondary_line string optional

Responses

default

Error
200

Returns a list of US verification objects.
POST /bulk/us_verifications

Uploads 3 endpoints

POST /uploads

Creates a new upload with the provided properties.

operationId: upload_create

Request Body

required
application/json
schema upload_writable
Property Type Required
metadata object optional
└ columns array required
campaignId string required
mergeVariableColumnMapping object optional
optionalAddressColumnMapping object optional
└ company string required
└ address_line2 string required
└ address_country string required
requiredAddressColumnMapping object optional
└ name string required
└ address_zip string required
└ address_city string required
└ address_line1 string required
└ address_state string required

Responses

201

Upload created successfully
422

Validation Error
POST /uploads
POST /uploads/{upl_id}/exports

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.

operationId: Uploads_createExportFile

Parameters

Name In Required Type Description
upl_id path required

ID of the upload

Request Body

required
application/json
schema UploadsCreateExportFileRequest
Property Type Required
type string optional

Responses

4XX

Create Export Error
200

Successful Response
POST /uploads/{upl_id}/exports
POST /uploads/{upl_id}/file

Upload an audience file and associate it with an upload.

operationId: upload_file

Parameters

Name In Required Type Description
upl_id path required

ID of the upload

Request Body

required
multipart/form-data
schema UploadFileRequest
Property Type Required
file string optional

Responses

202

Successful Response
422

Validation Error
POST /uploads/{upl_id}/file

Ziplookups 1 endpoints

POST /us_zip_lookups

Returns information about a ZIP code

operationId: zip_lookup

Request Body

required
application/json
schema zip5
Property Type Required
zip_code string required
multipart/form-data
schema zip5
Property Type Required
zip_code string required
application/x-www-form-urlencoded
schema zip5
Property Type Required
zip_code string required

Responses

default

Error
200

Returns a zip lookup object if a valid zip was provided.
POST /us_zip_lookups
Load more endpoints

Schemas

object AddressesListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/address"
          },
          "description": "list of addresses"
        }
      }
    }
  ]
}
object BankAccountsGetListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/bank_account"
          },
          "description": "list of bank_accounts"
        }
      }
    }
  ]
}
object BillingGroupsListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/billing_group"
          },
          "description": "list of billing_groups"
        }
      }
    }
  ]
}
object BuckslipOrdersGetByBuckslipIdResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/buckslip_order"
          },
          "description": "List of buckslip orders"
        }
      }
    }
  ]
}
object BuckslipsListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/buckslip"
          },
          "description": "list of buckslips"
        }
      }
    }
  ]
}
object CampaignDeleteResponse 
{
  "properties": {
    "id": {
      "$ref": "#/components/schemas/cmp_id"
    },
    "deleted": {
      "type": "boolean",
      "description": "True if the resource has been successfully deleted."
    }
  },
  "description": "Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end."
}
object CampaignsListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/campaign"
          },
          "description": "list of campaigns"
        }
      }
    }
  ]
}
object CardOrdersGetResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/card_order"
          },
          "description": "List of card orders"
        }
      }
    }
  ]
}
object CardsListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/card"
          },
          "description": "list of cards"
        }
      }
    }
  ]
}
object ChecksListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/check"
          },
          "description": "list of checks"
        }
      }
    }
  ]
}
object ExportRetrieveResponse 
{
  "type": "object",
  "required": [
    "id",
    "dateCreated",
    "dateModified",
    "deleted",
    "s3Url",
    "state",
    "type",
    "uploadId"
  ],
  "properties": {
    "id": {
      "$ref": "#/components/schemas/ex_id"
    },
    "type": {
      "enum": [
        "all",
        "failures",
        "successes"
      ],
      "type": "string",
      "description": "The export file type, which can be `all`, `failures` or `successes`."
    },
    "s3Url": {
      "type": "string",
      "description": "The URL for the generated export file."
    },
    "state": {
      "enum": [
        "in_progress",
        "failed",
        "succeeded"
      ],
      "type": "string",
      "description": "The state of the export file, which can be `in_progress`, `failed` or `succeeded`."
    },
    "deleted": {
      "type": "boolean",
      "description": "Returns as `true` if the resource has been successfully deleted."
    },
    "uploadId": {
      "$ref": "#/components/schemas/upl_id"
    },
    "dateCreated": {
      "type": "string",
      "format": "date-time",
      "description": "A timestamp in ISO 8601 format of the date the export was created"
    },
    "dateModified": {
      "type": "string",
      "format": "date-time",
      "description": "A timestamp in ISO 8601 format of the date the export was last modified"
    }
  }
}
object LettersListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/letter"
          },
          "description": "list of letters"
        }
      }
    }
  ]
}
object PostcardsListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/postcard"
          },
          "description": "list of postcards"
        }
      }
    }
  ]
}
object QrCodesGetSortedQrCodesResponse 
{
  "allOf": [
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/qr_code_scans"
          },
          "description": "List of QR code analytics"
        },
        "count": {
          "$ref": "#/components/schemas/count"
        },
        "object": {
          "$ref": "#/components/schemas/object"
        },
        "total_count": {
          "type": "integer",
          "description": "Indicates the total number of records. Provided when the request specifies an \"include\" query parameter"
        },
        "scanned_count": {
          "type": "integer",
          "description": "Indicates the number of QR Codes out of `count` that were scanned atleast once."
        }
      }
    }
  ]
}
object ReportRetrieve403Response 
{
  "type": "object",
  "properties": {
    "code": {
      "type": "number",
      "description": "The error code"
    },
    "message": {
      "type": "string",
      "description": "Details of the error message with the feature flagged mentioned."
    }
  }
}
object ReportRetrieveResponse 
{
  "type": "object",
  "required": [
    "data",
    "count",
    "offset",
    "total_count"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "properties": {
          "status": {
            "enum": [
              "Validated",
              "Failed",
              "Processing"
            ],
            "type": "string",
            "description": "The processing status of line item."
          },
          "rowNumber": {
            "type": "number",
            "title": "Row Number",
            "description": "The row number of the csv file containing this data."
          },
          "mailpieceId": {
            "type": "string",
            "nullable": true,
            "description": "The mailpiece id created from the line item when it was validated."
          },
          "errorMessage": {
            "type": "string",
            "nullable": true,
            "description": "The error message detailing the reason why processing the line item failed."
          },
          "originalData": {
            "type": "object",
            "description": "Key-value pairs where each key is the column header and each value is the value of the column for the row."
          }
        }
      }
    },
    "count": {
      "$ref": "#/components/schemas/count"
    },
    "next_url": {
      "type": "string",
      "nullable": true,
      "description": "Url of next page of items in list."
    },
    "prev_url": {
      "type": "string",
      "nullable": true,
      "description": "Url of previous page of items in list."
    },
    "total_count": {
      "type": "integer",
      "description": "Indicates the total number of records. Provided when the request specifies an \"include\" query parameter"
    }
  }
}
object SelfMailersGetListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/self_mailer"
          },
          "description": "list of self_mailers"
        }
      }
    }
  ]
}
object TemplateVersionsGetListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/template_version"
          },
          "description": "list of template versions"
        }
      }
    }
  ]
}
object TemplatesListResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/list"
    },
    {
      "type": "object",
      "properties": {
        "data": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/template"
          },
          "description": "list of templates"
        }
      }
    }
  ]
}
object UploadCreateResponse 
{
  "type": "object",
  "title": "HTTPValidationError",
  "properties": {
    "detail": {
      "type": "array",
      "items": {
        "type": "object",
        "title": "ValidationError",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "properties": {
          "loc": {
            "type": "array",
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        }
      },
      "title": "Detail"
    }
  }
}
object UploadFileRequest 
{
  "type": "object",
  "properties": {
    "file": {
      "type": "string",
      "format": "binary"
    }
  }
}
object UploadsCreateExportFileRequest 
{
  "type": "object",
  "properties": {
    "type": {
      "enum": [
        "all",
        "failures",
        "successes"
      ],
      "type": "string"
    }
  }
}
object UploadsCreateExportFileResponse 
{
  "type": "object",
  "example": {
    "code": 400,
    "errors": [
      "type must be a string"
    ],
    "message": "Invalid body, check 'errors' property for more info."
  },
  "required": [
    "code",
    "message",
    "errors"
  ],
  "properties": {
    "code": {
      "enum": [
        400,
        404
      ],
      "type": "number",
      "description": "A conventional HTTP status code"
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "An array of pre-defined strings that identify an error"
    },
    "message": {
      "type": "string",
      "description": "A human-readable message with more details about the error"
    }
  }
}
array UploadsListResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/upload"
  }
}
object address 
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/address_us"
    },
    {
      "$ref": "#/components/schemas/address_intl"
    }
  ]
}
object address_deletion 
{
  "properties": {
    "id": {
      "$ref": "#/components/schemas/adr_id"
    },
    "deleted": {
      "$ref": "#/components/schemas/deleted"
    }
  },
  "description": "Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end."
}
object address_editable 
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/address_editable_us"
    },
    {
      "$ref": "#/components/schemas/address_editable_intl"
    }
  ]
}
object address_editable_intl 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/address_fields_intl"
    },
    {
      "type": "object",
      "anyOf": [
        {
          "title": "address obj with `name` defined",
          "required": [
            "name"
          ]
        },
        {
          "title": "address obj with `company` defined",
          "required": [
            "company"
          ]
        }
      ],
      "properties": {
        "name": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address.\n"
        },
        "email": {
          "type": "string",
          "nullable": true,
          "maxLength": 100,
          "description": "Must be no longer than 100 characters."
        },
        "phone": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Must be no longer than 40 characters."
        },
        "company": {
          "$ref": "#/components/schemas/company"
        },
        "metadata": {
          "$ref": "#/components/schemas/metadata"
        },
        "description": {
          "$ref": "#/components/schemas/resource_description"
        },
        "address_country": {
          "$ref": "#/components/schemas/country_extended"
        }
      }
    }
  ]
}
object address_editable_us 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/address_fields_us"
    },
    {
      "type": "object",
      "anyOf": [
        {
          "title": "address obj with `name` defined",
          "required": [
            "name"
          ]
        },
        {
          "title": "address obj with `company` defined",
          "required": [
            "company"
          ]
        }
      ],
      "properties": {
        "name": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address.\n"
        },
        "email": {
          "type": "string",
          "nullable": true,
          "maxLength": 100,
          "description": "Must be no longer than 100 characters."
        },
        "phone": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Must be no longer than 40 characters."
        },
        "company": {
          "$ref": "#/components/schemas/company"
        },
        "metadata": {
          "$ref": "#/components/schemas/metadata"
        },
        "description": {
          "$ref": "#/components/schemas/resource_description"
        },
        "address_country": {
          "enum": [
            "US"
          ],
          "type": "string",
          "default": "US"
        }
      }
    }
  ]
}
object address_fields_intl 
{
  "type": "object",
  "required": [
    "address_line1",
    "address_country"
  ],
  "properties": {
    "address_zip": {
      "type": "string",
      "nullable": true,
      "maxLength": 40,
      "description": "Optional postal code."
    },
    "address_city": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    },
    "address_line1": {
      "type": "string",
      "maxLength": 200,
      "description": "The primary number, street name, and directional information."
    },
    "address_line2": {
      "type": "string",
      "nullable": true,
      "maxLength": 200,
      "description": "An optional field containing any information which can't fit into line 1."
    },
    "address_state": {
      "type": "string",
      "nullable": true,
      "maxLength": 200
    }
  }
}
object address_fields_us 
{
  "type": "object",
  "required": [
    "address_line1",
    "address_city",
    "address_state",
    "address_zip"
  ],
  "properties": {
    "address_zip": {
      "type": "string",
      "pattern": "^\\d{5}(-\\d{4})?$",
      "description": "Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`.\n"
    },
    "address_city": {
      "type": "string",
      "maxLength": 200
    },
    "address_line1": {
      "type": "string",
      "maxLength": 64,
      "description": "The primary number, street name, and directional information."
    },
    "address_line2": {
      "type": "string",
      "nullable": true,
      "maxLength": 64,
      "description": "An optional field containing any information which can't fit into line 1."
    },
    "address_state": {
      "type": "string",
      "pattern": "^[a-zA-Z]{2}$",
      "description": "2 letter state short-name code"
    }
  }
}
object address_intl 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/lob_base"
    },
    {
      "type": "object",
      "anyOf": [
        {
          "title": "address obj with `name` defined",
          "required": [
            "name"
          ]
        },
        {
          "title": "address obj with `company` defined",
          "required": [
            "company"
          ]
        }
      ],
      "example": {
        "id": "adr_e68217bd744d65c8X",
        "name": "Harry Zhang",
        "email": "harry@lob.com",
        "phone": "5555555555",
        "company": "Lob",
        "metadata": {},
        "address_zip": "C1N 1C4",
        "description": "Harry - Office",
        "address_city": "SUMMERSIDE",
        "address_line1": "370 WATER ST",
        "address_line2": "",
        "address_state": "PRINCE EDWARD ISLAND",
        "address_country": "CANADA"
      },
      "required": [
        "id",
        "address_line1",
        "address_country"
      ],
      "properties": {
        "id": {
          "$ref": "#/components/schemas/adr_id"
        },
        "name": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address.\n"
        },
        "email": {
          "type": "string",
          "nullable": true,
          "maxLength": 100,
          "description": "Must be no longer than 100 characters."
        },
        "phone": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Must be no longer than 40 characters."
        },
        "object": {
          "enum": [
            "address"
          ],
          "type": "string",
          "default": "address",
          "description": "Value is resource type."
        },
        "company": {
          "$ref": "#/components/schemas/company"
        },
        "metadata": {
          "$ref": "#/components/schemas/metadata"
        },
        "address_zip": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Optional postal code."
        },
        "description": {
          "$ref": "#/components/schemas/resource_description"
        },
        "address_city": {
          "type": "string",
          "nullable": true,
          "maxLength": 200
        },
        "address_line1": {
          "type": "string",
          "maxLength": 200
        },
        "address_line2": {
          "type": "string",
          "nullable": true,
          "maxLength": 200
        },
        "address_state": {
          "type": "string",
          "nullable": true,
          "maxLength": 200,
          "description": "Will be returned as a full string"
        },
        "address_country": {
          "enum": [
            "AFGHANISTAN",
            "ALBANIA",
            "ALGERIA",
            "AMERICAN SAMOA",
            "ANDORRA",
            "ANGOLA",
            "ANGUILLA",
            "ANTARCTICA",
            "ANTIGUA AND BARBUDA",
            "ARGENTINA",
            "ARUBA",
            "AUSTRALIA",
            "AUSTRIA",
            "AZERBAIJAN",
            "BAHRAIN",
            "BANGLADESH",
            "BARBADOS",
            "BELARUS",
            "BELGIUM",
            "BELIZE",
            "BENIN",
            "BERMUDA",
            "BHUTAN",
            "BOLIVIA (PLURINATIONAL STATE OF)",
            "BONAIRE, SAINT EUSTATIUS AND SABA",
            "BOSNIA AND HERZEGOVINA",
            "BOTSWANA",
            "BRAZIL",
            "BRITISH INDIAN OCEAN TERRITORY",
            "BRITISH VIRGIN ISLANDS",
            "BRUNEI DARUSSALAM",
            "BULGARIA",
            "BURKINA FASO",
            "BURUNDI",
            "CABO VERDE",
            "CAMBODIA",
            "CAMEROON",
            "CANADA",
            "CAYMAN ISLANDS",
            "CENTRAL AFRICAN REPUBLIC",
            "CHAD",
            "CHILE",
            "CHINA",
            "COLOMBIA",
            "COMOROS",
            "CONGO",
            "CONGO, DEMOCRATIC REPUBLIC OF THE",
            "COOK ISLANDS",
            "COSTA RICA",
            "CÔTE D'IVOIRE",
            "CROATIA",
            "CUBA",
            "CURAÇAO",
            "CYPRUS",
            "CZECH REPUBLIC",
            "DENMARK",
            "DJIBOUTI",
            "DOMINICA",
            "DOMINICAN REPUBLIC",
            "ECUADOR",
            "EGYPT",
            "EL SALVADOR",
            "EQUATORIAL GUINEA",
            "ERITREA",
            "ESTONIA",
            "ESWATINI",
            "ETHIOPIA",
            "FALKLAND ISLANDS (MALVINAS)",
            "FAROE ISLANDS",
            "FIJI",
            "FINLAND",
            "FRANCE",
            "GABON",
            "GAMBIA",
            "GEORGIA",
            "GERMANY",
            "GHANA",
            "GIBRALTAR",
            "GREECE",
            "GREENLAND",
            "GRENADA",
            "GUATEMALA",
            "GUINEA",
            "GUINEA-BISSAU",
            "GUYANA",
            "HAITI",
            "HOLY SEE",
            "HONDURAS",
            "HONG KONG",
            "HUNGARY",
            "ICELAND",
            "INDIA",
            "INDONESIA",
            "IRAN (ISLAMIC REPUBLIC OF)",
            "IRAQ",
            "IRELAND",
            "ISRAEL",
            "ITALY",
            "JAMAICA",
            "JAPAN",
            "JORDAN",
            "KAZAKHSTAN",
            "KENYA",
            "KIRIBATI",
            "KOREA (DEMOCRATIC PEOPLE’S REPUBLIC OF)",
            "KOREA, REPUBLIC OF",
            "KUWAIT",
            "KYRGYZSTAN",
            "LAO PEOPLE’S DEMOCRATIC REPUBLIC",
            "LATVIA",
            "LEBANON",
            "LESOTHO",
            "LIBERIA",
            "LIBYA",
            "LIECHTENSTEIN",
            "LITHUANIA",
            "LUXEMBOURG",
            "MACAO",
            "MACEDONIA",
            "MADAGASCAR",
            "MALAWI",
            "MALAYSIA",
            "MALDIVES",
            "MALI",
            "MALTA",
            "MAURITANIA",
            "MAURITIUS",
            "MEXICO",
            "MOLDOVA, REPUBLIC OF",
            "MONACO",
            "MONGOLIA",
            "MONTENEGRO",
            "MONTSERRAT",
            "MOROCCO",
            "MOZAMBIQUE",
            "MYANMAR",
            "NAMIBIA",
            "NAURU",
            "NEPAL",
            "NETHERLAND ANTILLES",
            "NETHERLANDS",
            "NEW ZEALAND",
            "NICARAGUA",
            "NIGER",
            "NIGERIA",
            "NIUE",
            "NORFOLK ISLAND",
            "NORWAY",
            "OMAN",
            "PAKISTAN",
            "PANAMA",
            "PAPUA NEW GUINEA",
            "PARAGUAY",
            "PERU",
            "PHILIPPINES",
            "PITCAIRN",
            "POLAND",
            "PORTUGAL",
            "QATAR",
            "ROMANIA",
            "RUSSIAN FEDERATION",
            "RWANDA",
            "SAINT HELENA",
            "SAINT KITTS AND NEVIS",
            "SAINT LUCIA",
            "SAINT VINCENT AND THE GRENADINES",
            "SAMOA",
            "SAN MARINO",
            "SAO TOME AND PRINCIPE",
            "SAUDI ARABIA",
            "SENEGAL",
            "SERBIA",
            "SEYCHELLES",
            "SIERRA LEONE",
            "SINGAPORE",
            "SINT MAARTEN",
            "SLOVAKIA",
            "SLOVENIA",
            "SOLOMON ISLANDS",
            "SOMALIA",
            "SOUTH AFRICA",
            "SOUTH GEORGIA AND THE SOUTH SANDWICH ISLANDS",
            "SOUTH SUDAN",
            "SPAIN",
            "SRI LANKA",
            "SUDAN",
            "SURINAME",
            "SWEDEN",
            "SWITZERLAND",
            "SYRIAN ARAB REPUBLIC",
            "TAIWAN",
            "TAJIKISTAN",
            "TANZANIA",
            "THAILAND",
            "THE BAHAMAS",
            "TIMOR-LESTE",
            "TOGO",
            "TOKELAU",
            "TONGA",
            "TRINIDAD AND TOBAGO",
            "TUNISIA",
            "TURKEY",
            "TURKMENISTAN",
            "TURKS AND CAICOS ISLANDS",
            "TUVALU",
            "UGANDA",
            "UKRAINE",
            "UNITED ARAB EMIRATES",
            "UNITED KINGDOM",
            "URUGUAY",
            "UZBEKISTAN",
            "VANUATU",
            "VENEZUELA",
            "VIET NAM",
            "WESTERN SAHARA",
            "YEMEN",
            "ZAMBIA",
            "ZIMBABWE"
          ],
          "type": "string",
          "maxLength": 200,
          "description": "Full name of country"
        }
      }
    }
  ]
}
string address_placement 
{
  "enum": [
    "top_first_page",
    "insert_blank_page",
    "bottom_first_page_center",
    "bottom_first_page"
  ],
  "type": "string",
  "default": "top_first_page",
  "description": "Specifies the location of the address information that will show through the double-window envelope. To see how this will impact your letter design, view our letter template.\nSome values are exclusive to certain customers. Upgrade to the appropriate <a href=\"https://dashboard.lob.com/#/settings/editions\" target=\"_blank\">Print & Mail Edition</a> to gain access.\n  * `top_first_page` - (default) print address information at the top of your provided first page\n  * `insert_blank_page` - insert a blank address page at the beginning of your file (you will be charged for the extra page)\n  * `bottom_first_page_center` - **(exclusive, deprecation planned within a few months)** print address information at the bottom center of your provided first page\n  * `bottom_first_page` - **(exclusive)** print address information at the bottom of your provided first page\n"
}
string address_types 
{
  "enum": [
    "address.created",
    "address.deleted"
  ],
  "type": "string",
  "description": "Unique identifier referring to status of address"
}
object address_us 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/lob_base"
    },
    {
      "type": "object",
      "anyOf": [
        {
          "title": "address obj with `name` defined",
          "required": [
            "name"
          ]
        },
        {
          "title": "address obj with `company` defined",
          "required": [
            "company"
          ]
        }
      ],
      "example": {
        "id": "adr_e68217bd744d65c8",
        "name": "HARRY ZHANG",
        "email": "harry@lob.com",
        "phone": "5555555555",
        "object": "address",
        "company": "LOB",
        "metadata": {},
        "address_zip": "94107-1741",
        "description": "Harry - Office",
        "address_city": "SAN FRANCISCO",
        "date_created": "2019-08-12T00:16:00.361Z",
        "address_line1": "210 KING ST STE 6100",
        "address_line2": null,
        "address_state": "CA",
        "date_modified": "2019-08-12T00:16:00.361Z",
        "address_country": "UNITED STATES",
        "recipient_moved": false
      },
      "required": [
        "id",
        "address_line1",
        "address_city",
        "address_state",
        "address_zip"
      ],
      "properties": {
        "id": {
          "$ref": "#/components/schemas/adr_id"
        },
        "name": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address.\n"
        },
        "email": {
          "type": "string",
          "nullable": true,
          "maxLength": 100,
          "description": "Must be no longer than 100 characters."
        },
        "phone": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Must be no longer than 40 characters."
        },
        "object": {
          "enum": [
            "address"
          ],
          "type": "string",
          "default": "address",
          "description": "Value is resource type."
        },
        "company": {
          "type": "string",
          "nullable": true,
          "maxLength": 40,
          "description": "Either `name` or `company` is required, you may also add both. Must be no longer than 40 characters. If both `name` and `company` are provided, they will be printed on two separate lines above the rest of the address. This field can be used for any secondary recipient information which is not part of the actual mailing address (Company Name, Department, Attention Line, etc).\n"
        },
        "metadata": {
          "$ref": "#/components/schemas/metadata"
        },
        "address_zip": {
          "type": "string",
          "pattern": "^\\d{5}(-\\d{4})?$",
          "description": "Must follow the ZIP format of `12345` or ZIP+4 format of `12345-1234`.\n"
        },
        "description": {
          "$ref": "#/components/schemas/resource_description"
        },
        "address_city": {
          "type": "string",
          "maxLength": 200
        },
        "address_line1": {
          "type": "string",
          "maxLength": 64,
          "description": "The primary number, street name, and directional information."
        },
        "address_line2": {
          "type": "string",
          "nullable": true,
          "maxLength": 64,
          "description": "An optional field containing any information which can't fit into line 1."
        },
        "address_state": {
          "type": "string",
          "pattern": "^[a-zA-Z]{2}$",
          "description": "2 letter state short-name code"
        },
        "address_country": {
          "enum": [
            "UNITED STATES"
          ],
          "type": "string",
          "maxLength": 13,
          "minLength": 13,
          "description": "Full name of country"
        },
        "recipient_moved": {
          "type": "boolean",
          "nullable": true,
          "description": "Only returned for accounts on certain <a href=\"https://dashboard.lob.com/#/settings/editions\" target=\"_blank\">Print &amp; Mail Editions</a>. Value is `true` if the address was altered because the recipient filed for a <a href=\"#tag/National-Change-of-Address\">National Change of Address Linkage (NCOALink)</a>, `false` if the NCOALink check was run but no altered address was found, and `null` if the NCOALink check was not run. The NCOALink check does not happen for non-US addresses, for non-deliverable US addresses, or for addresses created before the NCOALink feature was added to your account.\n"
        }
      }
    }
  ]
}
object addresses 
{
  "type": "object",
  "properties": {
    "components": {
      "$ref": "#/components/schemas/components"
    },
    "location_analysis": {
      "$ref": "#/components/schemas/location_analysis"
    }
  }
}
string adr_id 
{
  "type": "string",
  "pattern": "^adr_[a-zA-Z0-9]+$",
  "description": "Unique identifier prefixed with `adr_`."
}
object bank_account 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/bank_account_base"
    },
    {
      "$ref": "#/components/schemas/lob_base"
    },
    {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "$ref": "#/components/schemas/bank_id"
        },
        "object": {
          "enum": [
            "bank_account"
          ],
          "type": "string",
          "default": "bank_account",
          "description": "Value is resource type."
        },
        "verified": {
          "type": "boolean",
          "default": false,
          "description": "A bank account must be verified before a check can be created. More info [here](#operation/bank_account_verify)."
        },
        "bank_name": {
          "type": "string",
          "description": "The name of the bank based on the provided routing number, e.g. `JPMORGAN CHASE BANK`."
        },
        "signature_url": {
          "allOf": [
            {
              "type": "string",
              "nullable": true,
              "description": "A [signed link](#section/Asset-URLs) to the signature image."
            },
            {
              "$ref": "#/components/schemas/signed_link"
            }
          ]
        }
      }
    }
  ],
  "example": {
    "id": "bank_a",
    "object": "bank_account",
    "metadat": {
      "spiffy": "true"
    },
    "verified": true,
    "bank_name": "JPMORGAN CHASE BANK",
    "signatory": "Jane Doe",
    "description": "Test Bank Account",
    "account_type": "individual",
    "date_created": "2019-08-08T19:34:47.571Z",
    "date_modified": "2019-08-08T19:34:47.571Z",
    "signature_url": "https://lob-assets.com/bank-accounts/asd_asdfghjkqwertyui.pdf?expires=1234567890&signature=aksdf",
    "account_number": "123456789",
    "routing_number": "322271627"
  }
}
object bank_account_base 
{
  "type": "object",
  "required": [
    "routing_number",
    "account_number",
    "account_type",
    "signatory"
  ],
  "properties": {
    "city": {
      "type": "string",
      "description": "The city associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the city associated with your home bank institution."
    },
    "state": {
      "type": "string",
      "description": "The state associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the state associated with your home bank institution."
    },
    "zipcode": {
      "type": "string",
      "description": "The zipcode associated with your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the zipcode associated with your home bank institution."
    },
    "metadata": {
      "$ref": "#/components/schemas/metadata"
    },
    "signatory": {
      "type": "string",
      "maxLength": 30,
      "description": "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 <a href=\"https://dashboard.lob.com/#/login\" target=\"_blank\">Dashboard</a>."
    },
    "description": {
      "$ref": "#/components/schemas/resource_description"
    },
    "account_type": {
      "enum": [
        "company",
        "individual"
      ],
      "type": "string",
      "description": "The type of entity that holds the account."
    },
    "account_number": {
      "type": "string",
      "maxLength": 17
    },
    "check_template": {
      "enum": [
        "common",
        "jpm"
      ],
      "type": "string",
      "description": "The check template used for printing. The defualt value is `common`. If you bank with JP Morgan Chase and wish to use Positive Pay use the `jpm` template. `jpm` requires additional information to be provided."
    },
    "routing_number": {
      "type": "string",
      "maxLength": 9,
      "minLength": 9,
      "description": "Must be a <a href=\"https://www.frbservices.org/index.html\" target=\"_blank\">valid US routing number</a>."
    },
    "fractional_routing_number": {
      "type": "string",
      "description": "The fractional routing number for your home bank account. Required for the `jpm` check template only. Please contact a bank representative if you do not know the fractional routing number associated with your home bank institution."
    }
  }
}
string bank_account_types 
{
  "enum": [
    "bank_account.created",
    "bank_account.deleted",
    "bank_account.verified"
  ],
  "type": "string",
  "description": "Unique identifier referring to status of bank account"
}
object bank_account_verify 
{
  "type": "object",
  "required": [
    "amounts"
  ],
  "properties": {
    "amounts": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/cents"
      },
      "maxItems": 2,
      "minItems": 2,
      "description": "In live mode, an array containing the two micro deposits (in cents) placed in the bank account. In test mode, no micro deposits will be placed, so any two integers between `1` and `100` will work."
    }
  }
}
object bank_deletion 
{
  "properties": {
    "id": {
      "$ref": "#/components/schemas/bank_id"
    },
    "deleted": {
      "$ref": "#/components/schemas/deleted"
    }
  },
  "description": "Lob uses RESTful HTTP response codes to indicate success or failure of an API request. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end."
}
object bank_id 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/bank_id_no_description"
    },
    {
      "type": "string",
      "description": "Unique identifier prefixed with `bank_`."
    }
  ]
}
string bank_id_no_description 
{
  "type": "string",
  "pattern": "^bank_[a-zA-Z0-9]+$"
}
string bg_description 
{
  "type": "string",
  "maxLength": 255,
  "description": "Description of the billing group."
}
string bg_id 
{
  "type": "string",
  "pattern": "^bg_[a-zA-Z0-9]+$",
  "description": "Unique identifier prefixed with `bg_`."
}
object billing_group 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/billing_group_base"
    },
    {
      "type": "object",
      "properties": {
        "id": {
          "$ref": "#/components/schemas/bg_id"
        },
        "object": {
          "enum": [
            "billing_group"
          ],
          "type": "string",
          "default": "billing_group",
          "description": "Value is resource type."
        },
        "date_created": {
          "$ref": "#/components/schemas/date_created"
        },
        "date_modified": {
          "$ref": "#/components/schemas/date_modified"
        }
      }
    }
  ]
}
object billing_group_base 
{
  "type": "object",
  "properties": {
    "name": {
      "$ref": "#/components/schemas/name"
    },
    "description": {
      "$ref": "#/components/schemas/bg_description"
    }
  }
}
object billing_group_editable 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/billing_group_base"
    },
    {
      "required": [
        "name"
      ]
    }
  ]
}
string billing_group_id 
{
  "type": "string",
  "description": "An optional string with the billing group ID to tag your usage with. Is used for billing purposes. Requires special activation to use. See <a href=\"#tag/Billing-Groups\">Billing Group API</a> for more information."
}
Load more schemas

Versions

Version Endpoints Schemas Ingested Status
1.19.28 94 303 2026-05-11 current
1.19.28 94 303 2026-04-20
1.19.28 94 303 2026-04-16