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

GET POST PUT PATCH DELETE

Accounts 1 endpoints

GET /accounts

Returns the account’s current balance of Lob Credits.

operationId: Accounts_getCreditsBalance

Responses

200

Returns a lob_credits_balance object.
GET /accounts

Addresses 4 endpoints

GET /addresses

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

operationId: addresses_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

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

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

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 ≤.
metadata query optional

Filter by metadata key-value pair`.

Responses

default

Error
200

A dictionary with a data property that contains an array of up to limit addresses. Each entry in the array is a separate address object. The previous and next page of address entries can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more addresses are available beyond the current set of returned results, the next_url field will be empty.
GET /addresses
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
DELETE /addresses/{adr_id}

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

operationId: address_delete

Parameters

Name In Required Type Description
adr_id path required

id of the address

Responses

default

Error
200

Deleted
DELETE /addresses/{adr_id}
GET /addresses/{adr_id}

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

operationId: address_retrieve

Parameters

Name In Required Type Description
adr_id path required

id of the address

Responses

default

Error
200

Returns an address object if a valid identifier was provided.
GET /addresses/{adr_id}

Bankaccounts 5 endpoints

GET /bank_accounts

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.

operationId: BankAccounts_getList

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

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

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

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 ≤.
metadata query optional

Filter by metadata key-value pair`.

Responses

default

Error
200

A dictionary with a data property that contains an array of up to limit bank_accounts. Each entry in the array is a separate bank_account. The previous and next page of bank_accounts can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more bank_accounts are available beyond the current set of returned results, the next_url field will be empty.
GET /bank_accounts
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
DELETE /bank_accounts/{bank_id}

Permanently deletes a bank account. It cannot be undone.

operationId: BankAccounts_deleteBankAccount

Parameters

Name In Required Type Description
bank_id path required

id of the bank account

Responses

default

Error
200

Deleted
DELETE /bank_accounts/{bank_id}
GET /bank_accounts/{bank_id}

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

operationId: BankAccounts_getDetails

Parameters

Name In Required Type Description
bank_id path required

id of the bank account

Responses

default

Error
200

Returns a bank account object
GET /bank_accounts/{bank_id}
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 4 endpoints

GET /billing_groups

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.

operationId: BillingGroups_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
offset query optional integer

An integer that designates the offset at which to begin returning results. Defaults to 0.
include query optional array

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

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 ≤.
date_modified query optional

Filter by date modified. 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 ≤.
sort_by query optional

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

Responses

default

Error
200

Returns a list of billing_groups.
GET /billing_groups
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
GET /billing_groups/{bg_id}

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

operationId: BillingGroups_getDetails

Parameters

Name In Required Type Description
bg_id path required

id of the billing_group

Responses

default

Error
200

Returns a billing_group object.
GET /billing_groups/{bg_id}
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 2 endpoints

GET /buckslips/{buckslip_id}/orders

Retrieves the buckslip orders associated with the given buckslip id.

operationId: BuckslipOrders_getByBuckslipId

Parameters

Name In Required Type Description
buckslip_id path required

The ID of the buckslip to which the buckslip orders belong.
limit query optional integer

How many results to return.
offset query optional integer

An integer that designates the offset at which to begin returning results. Defaults to 0.

Responses

default

Error
200

Returns the buckslip orders associated with the given buckslip id
GET /buckslips/{buckslip_id}/orders
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 5 endpoints

GET /buckslips

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

operationId: buckslips_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

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

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

Responses

default

Error
200

Returns a list of buckslip objects
GET /buckslips
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
DELETE /buckslips/{buckslip_id}

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

operationId: buckslip_delete

Parameters

Name In Required Type Description
buckslip_id path required

id of the buckslip

Responses

default

Error
200

Deleted the buckslip
DELETE /buckslips/{buckslip_id}
GET /buckslips/{buckslip_id}

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

operationId: buckslip_retrieve

Parameters

Name In Required Type Description
buckslip_id path required

id of the buckslip

Responses

default

Error
200

Returns a buckslip object
GET /buckslips/{buckslip_id}
PATCH /buckslips/{buckslip_id}

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

operationId: buckslip_update

Parameters

Name In Required Type Description
buckslip_id path required

id of the buckslip

Request Body

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

Responses

default

Error
200

Returns a buckslip object
PATCH /buckslips/{buckslip_id}

Campaigns 6 endpoints

GET /campaigns

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

operationId: campaigns_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
include query optional array

Request that the response include the total count by specifying include=["total_count"].
before/after query optional

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

Responses

200

A dictionary with a data property that contains an array of up to limit campaigns. Each entry in the array is a separate campaign. The previous and next page of campaigns can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more campaigns are available beyond the current set of returned results, the next_url field will be empty.
GET /campaigns
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
DELETE /campaigns/{cmp_id}

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.

operationId: campaign_delete

Parameters

Name In Required Type Description
cmp_id path required

id of the campaign

Responses

default

Error
200

Deleted the campaign.
DELETE /campaigns/{cmp_id}
GET /campaigns/{cmp_id}

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

operationId: campaign_retrieve

Parameters

Name In Required Type Description
cmp_id path required

id of the campaign

Responses

default

Error
200

Returns a campaign object
GET /campaigns/{cmp_id}
PATCH /campaigns/{cmp_id}

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

operationId: campaign_update

Parameters

Name In Required Type Description
cmp_id path required

id of the campaign

Request Body

required
application/json
schema campaign_updatable
Property Type Required
name string optional
is_draft boolean optional
metadata object optional
use_type string optional
send_date string optional
description string optional
schedule_type string optional
auto_cancel_if_ncoa boolean optional
target_delivery_date string optional
cancel_window_campaign_minutes integer optional
multipart/form-data
schema campaign_updatable
Property Type Required
name string optional
is_draft boolean optional
metadata object optional
use_type string optional
send_date string optional
description string optional
schedule_type 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_updatable
Property Type Required
name string optional
is_draft boolean optional
metadata object optional
use_type string optional
send_date string optional
description string optional
schedule_type string optional
auto_cancel_if_ncoa boolean optional
target_delivery_date string optional
cancel_window_campaign_minutes integer optional

Responses

default

Error
200

Returns a campaign object
PATCH /campaigns/{cmp_id}
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 2 endpoints

GET /cards/{card_id}/orders

Retrieves the card orders associated with the given card id.

operationId: CardOrders_get

Parameters

Name In Required Type Description
card_id path required

The ID of the card to which the card orders belong.
limit query optional integer

How many results to return.
offset query optional integer

An integer that designates the offset at which to begin returning results. Defaults to 0.

Responses

default

Error
200

Returns the card orders associated with the given card id
GET /cards/{card_id}/orders
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 5 endpoints

GET /cards

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

operationId: cards_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

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

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

Responses

default

Error
200

Returns a list of card objects
GET /cards
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
DELETE /cards/{card_id}

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

operationId: card_delete

Parameters

Name In Required Type Description
card_id path required

id of the card

Responses

default

Error
200

Deleted the card
DELETE /cards/{card_id}
GET /cards/{card_id}

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

operationId: card_retrieve

Parameters

Name In Required Type Description
card_id path required

id of the card

Responses

default

Error
200

Returns a card object
GET /cards/{card_id}
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 4 endpoints

GET /checks

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

operationId: checks_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

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

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

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 ≤.
metadata query optional

Filter by metadata key-value pair`.
scheduled query optional boolean
  • true - only return orders (past or future) where send_date is
    greater than date_created
  • false - only return orders where send_date is equal to date_created
send_date query optional

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 query optional

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.
sort_by query optional

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

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

default

Error
200

A dictionary with a data property that contains an array of up to limit checks. Each entry in the array is a separate check. The previous and next page of checks can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more checks are available beyond the current set of returned results, the next_url field will be empty.
GET /checks
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
DELETE /checks/{chk_id}

Completely removes a check from production. This can only be done if the check has a send_date and the send_date has not yet passed. If the check is successfully canceled, you will not be charged for it. Read more on cancellation windows and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition to gain access.

operationId: check_cancel

Parameters

Name In Required Type Description
chk_id path required

id of the check

Responses

default

Error
200

Deleted
DELETE /checks/{chk_id}
GET /checks/{chk_id}

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

operationId: check_retrieve

Parameters

Name In Required Type Description
chk_id path required

id of the check

Responses

default

Error
200

Returns a check object
GET /checks/{chk_id}

Creatives 3 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
GET /creatives/{crv_id}

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

operationId: creative_retrieve

Parameters

Name In Required Type Description
crv_id path required

id of the creative

Responses

default

Error
200

Returns a creative object
GET /creatives/{crv_id}
PATCH /creatives/{crv_id}

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

operationId: creative_update

Parameters

Name In Required Type Description
crv_id path required

id of the creative

Request Body

required
application/json
schema creative_base
Property Type Required
from object optional
metadata object optional
description string optional
multipart/form-data
schema creative_base
Property Type Required
from object optional
metadata object optional
description string optional
application/x-www-form-urlencoded
schema creative_base
Property Type Required
from object optional
metadata object optional
description string optional

Responses

default

Error
200

Returns a creative object
PATCH /creatives/{crv_id}

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 /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
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

Letters 4 endpoints

GET /letters

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

operationId: letters_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

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

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

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 ≤.
metadata query optional

Filter by metadata key-value pair`.
campaign_id query optional

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

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.
color query optional boolean

Set to true to return only color letters. Set to false to return only black & white letters.
scheduled query optional boolean
  • true - only return orders (past or future) where send_date is
    greater than date_created
  • false - only return orders where send_date is equal to date_created
send_date query optional

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 query optional

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.
sort_by query optional

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

Responses

default

Error
200

A dictionary with a data property that contains an array of up to limit letters. Each entry in the array is a separate letter. The previous and next page of letters can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively. If no more letters are available beyond the current set of returned results, the next_url field will be empty.
GET /letters
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
DELETE /letters/{ltr_id}

Completely removes a letter from production. This can only be done if the letter has a send_date and the send_date has not yet passed. If the letter is successfully canceled, you will not be charged for it. Read more on cancellation windows and scheduling. Scheduling and cancellation is a premium feature. Upgrade to the appropriate Print & Mail Edition to gain access.

operationId: letter_cancel

Parameters

Name In Required Type Description
ltr_id path required

id of the letter

Responses

default

Error
200

Deleted
DELETE /letters/{ltr_id}
GET /letters/{ltr_id}

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

operationId: letter_retrieve

Parameters

Name In Required Type Description
ltr_id path required

id of the letter

Responses

default

Error
200

Returns a letter object
GET /letters/{ltr_id}

Postcards 1 endpoints

GET /postcards

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

operationId: postcards_list

Parameters

Name In Required Type Description
limit query optional integer

How many results to return.
before/after query optional

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

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

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 ≤.
metadata query optional

Filter by metadata key-value pair`.
campaign_id query optional

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

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.
size query optional array

Specifies the size of the postcard. Only 4x6 postcards can be sent to international destinations.
scheduled query optional boolean
  • true - only return orders (past or future) where send_date is
    greater than date_created
  • false - only return orders where send_date is equal to date_created
send_date query optional

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 query optional

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.
sort_by query optional

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

Responses

default

Error
200

A dictionary with a data property that contains an array of up to limit postcards. Each entry in the array is a separate postcard. The previous and next page of postcards can be retrieved by calling the endpoint contained in the previous_url and next_url fields in the API response respectively.
If no more postcards are available beyond the current set of returned results, the next_url field will be empty.
GET /postcards
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