Addresses4
To add an address to your address book, you create a new address object. You can retrieve and delete individual
addresses as well as get a list of addresses. Addresses are identified by a unique random ID.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/addressesList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/addressesCreate
Request bodyapplication/json — address_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/addresses/{adr_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
adr_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
DELETE/addresses/{adr_id}Delete
Parameters| Name | In | Required | Type |
|---|
adr_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Bank Accounts5
Bank Accounts allow you to store your bank account securely in our system. The API provides
endpoints for creating bank accounts, deleting bank accounts, verifying bank accounts,
retrieving individual bank accounts, and retrieving a list of bank accounts.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/bank_accountsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/bank_accountsCreate
Request bodyapplication/json — bank_account_base (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/bank_accounts/{bank_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
bank_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a bank account object | — |
default | — | — |
DELETE/bank_accounts/{bank_id}Delete
Parameters| Name | In | Required | Type |
|---|
bank_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/bank_accounts/{bank_id}/verifyVerify
Parameters| Name | In | Required | Type |
|---|
bank_id | path | yes | — |
Request bodyapplication/json — bank_account_verify (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Billing Groups4
The Billing Groups API allows you to create and view labels that can be attached to certain consumption-based
usages of Letters, Checks, Postcards and Self-Mailers to customize your bill. Please check each
resource API section to learn more about how to access the Billing Groups API.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/billing_groupsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
offset | query | no | integer |
include | query | no | array |
date_created | query | no | — |
date_modified | query | no | — |
sort_by | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a list of billing_groups. | — |
default | — | — |
POST/billing_groupsCreate
Request bodyapplication/json — billing_group_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/billing_groups/{bg_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
bg_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a billing_group object. | — |
default | — | — |
POST/billing_groups/{bg_id}Update
Parameters| Name | In | Required | Type |
|---|
bg_id | path | yes | — |
Request bodyapplication/json — billing_group_base (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Buckslip Orders2
The Buckslip Orders endpoint allows you to easily create buckslip orders for existing buckslips.
The API provides endpoints for creating buckslip orders and listing buckslip orders for a given buckslip.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/buckslips/{buckslip_id}/ordersRetrieve
Parameters| Name | In | Required | Type |
|---|
buckslip_id | path | yes | — |
limit | query | no | integer |
offset | query | no | integer |
Responses| Status | Description | Schema |
|---|
200 | Returns the buckslip orders associated with the given buckslip id | — |
default | — | — |
POST/buckslips/{buckslip_id}/ordersCreate
Parameters| Name | In | Required | Type |
|---|
buckslip_id | path | yes | — |
Request bodyapplication/json — buckslip_order_editable (required)
Responses| Status | Description | Schema |
|---|
200 | Buckslip order created successfully | — |
default | — | — |
Buckslips5
The Buckslips endpoint allows you to easily create buckslips that can later be used as add-ons for Letters Campaigns. Note that a Letter Campaign with Buckslip add-on requires a minimum send quantity of 5,000 letters.
The API provides endpoints for creating buckslips, retrieving individual buckslips, creating buckslip orders, and retrieving a list of buckslips.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/buckslipsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
Responses| Status | Description | Schema |
|---|
200 | Returns a list of buckslip objects | — |
default | — | — |
POST/buckslipsCreate
Request bodyapplication/json — buckslip_editable (required)
Responses| Status | Description | Schema |
|---|
200 | Buckslip created successfully | — |
default | — | — |
GET/buckslips/{buckslip_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
buckslip_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a buckslip object | — |
default | — | — |
PATCH/buckslips/{buckslip_id}Update
Parameters| Name | In | Required | Type |
|---|
buckslip_id | path | yes | — |
Request bodyapplication/json — buckslip_updatable (required)
Responses| Status | Description | Schema |
|---|
200 | Returns a buckslip object | — |
default | — | — |
DELETE/buckslips/{buckslip_id}Delete
Parameters| Name | In | Required | Type |
|---|
buckslip_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Campaigns6
The campaigns endpoint allows you to create and view campaigns that can be used to send multiple letters or postcards.
The API provides endpoints for creating campaigns, updating campaigns, retrieving individual campaigns, listing campaigns, and deleting
campaigns.
GET/campaignsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
include | query | no | array |
before/after | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
POST/campaignsCreate
Parameters| Name | In | Required | Type |
|---|
x-lang-output | header | no | string |
Request bodyapplication/json — campaign_writable (required)
Responses| Status | Description | Schema |
|---|
200 | Campaign created successfully | — |
default | — | — |
GET/campaigns/{cmp_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
cmp_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a campaign object | — |
default | — | — |
PATCH/campaigns/{cmp_id}Update
Parameters| Name | In | Required | Type |
|---|
cmp_id | path | yes | — |
Request bodyapplication/json — campaign_updatable (required)
Responses| Status | Description | Schema |
|---|
200 | Returns a campaign object | — |
default | — | — |
DELETE/campaigns/{cmp_id}Delete
Parameters| Name | In | Required | Type |
|---|
cmp_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/campaigns/{cmp_id}/sendSend Campaign
Parameters| Name | In | Required | Type |
|---|
cmp_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a campaign object | — |
default | — | — |
Card Orders2
The card orders endpoint allows you to easily create card orders for existing cards.
The API provides endpoints for creating card orders and listing card orders for a given card.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/cards/{card_id}/ordersRetrieve
Parameters| Name | In | Required | Type |
|---|
card_id | path | yes | — |
limit | query | no | integer |
offset | query | no | integer |
Responses| Status | Description | Schema |
|---|
200 | Returns the card orders associated with the given card id | — |
default | — | — |
POST/cards/{card_id}/ordersCreate
Parameters| Name | In | Required | Type |
|---|
card_id | path | yes | — |
Request bodyapplication/json — card_order_editable (required)
Responses| Status | Description | Schema |
|---|
200 | Card order created successfully | — |
default | — | — |
Cards5
The cards endpoint allows you to easily create cards that can later be affixed to Letters.
The API provides endpoints for creating cards, retrieving individual cards, creating card orders, and retrieving a list of cards.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/cardsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
Responses| Status | Description | Schema |
|---|
200 | Returns a list of card objects | — |
default | — | — |
POST/cardsCreate
Request bodyapplication/json — card_editable (required)
Responses| Status | Description | Schema |
|---|
200 | Card created successfully | — |
default | — | — |
GET/cards/{card_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
card_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a card object | — |
default | — | — |
POST/cards/{card_id}Update
Parameters| Name | In | Required | Type |
|---|
card_id | path | yes | — |
Request bodyapplication/json — card_updatable (required)
Responses| Status | Description | Schema |
|---|
200 | Returns a card object | — |
default | — | — |
DELETE/cards/{card_id}Delete
Parameters| Name | In | Required | Type |
|---|
card_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Checks4
Checks allow you to send payments via physical checks. The API provides endpoints
for creating checks, retrieving individual checks, canceling checks, and retrieving a list of checks.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/checksList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
scheduled | query | no | boolean |
send_date | query | no | — |
mail_type | query | no | — |
sort_by | query | no | — |
status | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/checksCreate
Parameters| Name | In | Required | Type |
|---|
Idempotency-Key | header | no | string |
idempotency_key | query | no | string |
Request bodyapplication/json — check_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/checks/{chk_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
chk_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a check object | — |
default | — | — |
DELETE/checks/{chk_id}Cancel
Parameters| Name | In | Required | Type |
|---|
chk_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Creatives3
The creatives endpoint allows you to create and view creatives. Creatives are used to create
reusable letter and postcard templates. The API provides endpoints for creating creatives, updating creatives,
retrieving individual creatives, and deleting creatives.
POST/creativesCreate
Parameters| Name | In | Required | Type |
|---|
x-lang-output | header | no | string |
Request bodyapplication/json — creative_writable (required)
Responses| Status | Description | Schema |
|---|
200 | Creative created successfully | — |
default | — | — |
GET/creatives/{crv_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
crv_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a creative object | — |
default | — | — |
PATCH/creatives/{crv_id}Update
Parameters| Name | In | Required | Type |
|---|
crv_id | path | yes | — |
Request bodyapplication/json — creative_base (required)
Responses| Status | Description | Schema |
|---|
200 | Returns a creative object | — |
default | — | — |
Identity Validation1
Validates whether a given name is associated with an address.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
POST/identity_validationIdentity Validation
Request bodyapplication/json — identity_validation_writable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Informed Delivery Campaign4
The Informed Delivery campaigns API allows you to create and view Informed Delivery campaigns.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/informed_delivery_campaignsList
Responses| Status | Description | Schema |
|---|
200 | — | — |
POST/informed_delivery_campaignsCreate
Request bodymultipart/form-data — create (required)
Responses| Status | Description | Schema |
|---|
200 | Creative created successfully | — |
422 | — | — |
GET/informed_delivery_campaigns/{usps_campaign_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
usps_campaign_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a informed delivery campaign object | — |
404 | — | — |
PATCH/informed_delivery_campaigns/{usps_campaign_id}Update
Parameters| Name | In | Required | Type |
|---|
usps_campaign_id | path | yes | — |
Request bodymultipart/form-data — update (required)
Responses| Status | Description | Schema |
|---|
200 | Returns an Informed Delivery campaign object | — |
404 | — | — |
422 | — | — |
Intl Verifications2
Address verification for non-US addresses
<br>
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
## Intl Verifications Test Env
When verifying international addresses, you'll likely want to test against
a wide array of addresses to ensure you're handling responses correctly.
With your test API key, requests that use specific values for `primary_line`
let you explore the responses to many types of addresses:
<table>
<tr>
<th style="white-space: nowrap">DELIVERABILITY OF SAMPLE RESPONSE</th>
<th style="white-space: nowrap">SET <code>primary_line</code> TO</th>
</tr>
<tr>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap">deliverable</td>
</tr>
<tr>
<td style="white-space: nowrap"><code>deliverable_missing_info</code></td>
<td style="white-space: nowrap">deliverable missing info</td>
</tr>
<tr>
<td style="white-space: nowrap"><code>undeliverable</code></td>
<td style="white-space: nowrap">undeliverable</td>
</tr>
<tr>
<td style="white-space: nowrap"><code>no_match</code></td>
<td style="white-space: nowrap">no match</td>
</tr>
</table>
See the `test` request & response examples under [Intl Verification Examples](#operation/intl_verification) within the
"Verify an international address section" in Intl Verifications.
You can rely on the response from these examples generally matching the response
you'd see in the live environment with an address of that type (excluding the `recipient` field).
The test API key does not perform any verification, automatic correction, or standardization
for addresses. If you wish to try these features out, use our <a href="https://lob.com/address-verification" target="_blank">live demo</a>
or the free plan (see <a href="https://lob.com/pricing/address-verification" target="_blank">our pricing</a> for details).
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
POST/bulk/intl_verificationsBulk Verify
Request bodyapplication/json — intl_verifications_payload (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/intl_verificationsSingle Verify
Parameters| Name | In | Required | Type |
|---|
x-lang-output | header | no | string |
Request bodyapplication/json — intl_verification_writable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Letters4
The letters endpoint allows you to easily print and mail letters. The API provides endpoints for
creating letters, retrieving individual letters, canceling letters, and retrieving a list of letters.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/lettersList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
campaign_id | query | no | — |
status | query | no | — |
color | query | no | boolean |
scheduled | query | no | boolean |
send_date | query | no | — |
mail_type | query | no | — |
sort_by | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/lettersCreate
Parameters| Name | In | Required | Type |
|---|
Idempotency-Key | header | no | string |
idempotency_key | query | no | string |
Lob-Version | header | no | string |
Request bodyapplication/json — letter_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/letters/{ltr_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
ltr_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a letter object | — |
default | — | — |
DELETE/letters/{ltr_id}Cancel
Parameters| Name | In | Required | Type |
|---|
ltr_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Postcards4
The postcards endpoint allows you to easily print and mail postcards. The API provides endpoints for creating postcards,
retrieving individual postcards, canceling postcards, and retrieving a list of postcards.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/postcardsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
campaign_id | query | no | — |
status | query | no | — |
size | query | no | array |
scheduled | query | no | boolean |
send_date | query | no | — |
mail_type | query | no | — |
sort_by | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/postcardsCreate
Parameters| Name | In | Required | Type |
|---|
Idempotency-Key | header | no | string |
idempotency_key | query | no | string |
Request bodyapplication/json — postcard_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/postcards/{psc_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
psc_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a postcard object | — |
default | — | — |
DELETE/postcards/{psc_id}Cancel
Parameters| Name | In | Required | Type |
|---|
psc_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
QR Codes1
Lob QR codes allow you to generate a QR code that is unique to each mailpiece, thereby allowing each and every customers to receive a personalized link. See the Create endpoint for <a href="#tag/Letters/operation/letter_create">Letters</a>, <a href="#tag/Postcards/operation/postcard_create">Postcards</a> or <a href="#tag/Self-Mailers/operation/self_mailer_create">Self Mailers</a> to learn how to embed a QR code into your mail piece.
Webhooks can be used to integrate Lob QR code scans into your omni channel marketing strategy. See the <a href="#tag/Webhooks">Webhooks</a> section of our documentation to learn how to enable the `letter.viewed`, `postcard.viewed` and `self_mailer.viewed` event notifications for your mail pieces.
Furthermore, our QR code Analytics endpoint can be used to track the impact and engagement rate of your mail sends. Lob can tell you exactly which recipients opened your mailpiece. Our Analytics endpoint allows you to see exactly which recipient scanned a mailpiece, when they scanned it, and more!
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/qr_code_analyticsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
offset | query | no | integer |
include | query | no | array |
date_created | query | no | — |
scanned | query | no | boolean |
resource_ids | query | no | array |
Responses| Status | Description | Schema |
|---|
200 | Returns a list of QR Codes and their analytics. | — |
Resource Proofs3
The resource proofs endpoint allows you to create a final rendering of any template. This is best practice to ensure that you are visually validating your creative before any mail pieces use the template. The API provides endpoints for creating, updating, and retrieving template proofs.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
POST/resource_proofsCreate
Request bodyapplication/json — resource_proof_editable (required)
Responses| Status | Description | Schema |
|---|
201 | — | — |
default | — | — |
GET/resource_proofs/{res_prf_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
res_prf_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a resource proof object | — |
default | — | — |
PATCH/resource_proofs/{res_prf_id}Update
Parameters| Name | In | Required | Type |
|---|
res_prf_id | path | yes | — |
Request bodyapplication/json — resource_proof_updatable (required)
Responses| Status | Description | Schema |
|---|
200 | Returns an updated resource proof object | — |
default | — | — |
Reverse Geocode Lookups1
Find a list of zip codes associated with a valid US location via latitude and longitude. <br> <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
POST/us_reverse_geocode_lookupsReverse Geocode Lookup
Parameters| Name | In | Required | Type |
|---|
size | query | no | integer |
Request bodyapplication/json — location (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Self Mailers4
The self mailer endpoint allows you to easily print and mail self mailers. The API provides endpoints
for creating self mailers, retrieving individual self mailers, canceling self mailers, and retrieving a list of self mailers.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/self_mailersList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
size | query | no | array |
scheduled | query | no | boolean |
send_date | query | no | — |
mail_type | query | no | — |
sort_by | query | no | — |
campaign_id | query | no | — |
status | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/self_mailersCreate
Parameters| Name | In | Required | Type |
|---|
Idempotency-Key | header | no | string |
idempotency_key | query | no | string |
Request bodyapplication/json — self_mailer_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/self_mailers/{sfm_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
sfm_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a self_mailer object | — |
default | — | — |
DELETE/self_mailers/{sfm_id}Delete
Parameters| Name | In | Required | Type |
|---|
sfm_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Template Versions5
These API endpoints allow you to create, retrieve, update and delete versions of reusable HTML templates for use with the Print & Mail API.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/templates/{tmpl_id}/versionsList
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/templates/{tmpl_id}/versionsCreate
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
Request bodyapplication/json — template_version_writable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/templates/{tmpl_id}/versions/{vrsn_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
vrsn_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns the template version with the given template and version ids. | — |
default | — | — |
POST/templates/{tmpl_id}/versions/{vrsn_id}Update
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
vrsn_id | path | yes | — |
Request bodyapplication/json — template_version_updatable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
DELETE/templates/{tmpl_id}/versions/{vrsn_id}Delete
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
vrsn_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Templates5
These API endpoints allow you to create, retrieve, update and delete reusable HTML templates for use with the Print & Mail API.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/templatesList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/templatesCreate
Request bodyapplication/json — template_writable (required)
Responses| Status | Description | Schema |
|---|
200 | Returns a template object | — |
default | — | — |
GET/templates/{tmpl_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a template object | — |
default | — | — |
POST/templates/{tmpl_id}Update
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
Request bodyapplication/json — template_update (required)
Responses| Status | Description | Schema |
|---|
200 | Returns the updated template object | — |
default | — | — |
DELETE/templates/{tmpl_id}Delete
Parameters| Name | In | Required | Type |
|---|
tmpl_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Uploads9
The uploads endpoint allows you to upload audience files that are then associated with a given campaign.
At this time, only CSV files are allowed. The API provides endpoints for creating uploads, uploading audience files,
and marking uploaded files as ready for processing. The API also provides endpoints for downloading files that
describe the results, both successful and not, of the processing.
GET/uploadsList
Parameters| Name | In | Required | Type |
|---|
campaignId | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
POST/uploadsCreate
Request bodyapplication/json — upload_writable (required)
Responses| Status | Description | Schema |
|---|
201 | Upload created successfully | — |
422 | — | — |
GET/uploads/{upl_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
upl_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns an upload object | — |
404 | — | — |
422 | — | — |
PATCH/uploads/{upl_id}Update
Parameters| Name | In | Required | Type |
|---|
upl_id | path | yes | — |
Request bodyapplication/json — upload_updatable (required)
Responses| Status | Description | Schema |
|---|
200 | Returns an upload object | — |
404 | — | — |
422 | — | — |
DELETE/uploads/{upl_id}Delete
Parameters| Name | In | Required | Type |
|---|
upl_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
204 | Successful Response | — |
POST/uploads/{upl_id}/exportsCreate Export
Parameters| Name | In | Required | Type |
|---|
upl_id | path | yes | — |
Request bodyapplication/json (required)
Responses| Status | Description | Schema |
|---|
200 | Successful Response | upload_create_export |
4XX | — | — |
GET/uploads/{upl_id}/exports/{ex_id}Retrieve Export
Parameters| Name | In | Required | Type |
|---|
upl_id | path | yes | — |
ex_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns an export object | — |
POST/uploads/{upl_id}/fileUpload file
Parameters| Name | In | Required | Type |
|---|
upl_id | path | yes | — |
Request bodymultipart/form-data (required)
Responses| Status | Description | Schema |
|---|
202 | Successful Response | upload_file |
422 | — | — |
GET/uploads/{upl_id}/reportRetrieve Line Item Report
Parameters| Name | In | Required | Type |
|---|
upl_id | path | yes | — |
status | query | no | string |
limit | query | no | integer |
offset | query | no | integer |
Responses| Status | Description | Schema |
|---|
200 | Returns an report object | — |
404 | — | — |
URL Shortener9
Lob's URL shortener allows you to generate unique short links, either with Lob's own domain or your own custom domains. Each custom link enables Lob to track mail individually and provide customers the relevant tracking data in their dashboard.
Webhooks can be used to integrate Lob's URL Shortener scans into your omni channel marketing stratergy. See the <a href="#tag/Webhooks">Webhooks</a> section of our documentation to learn how to enable the `letter.viewed`, `postcard.viewed` and `self_mailer.viewed` event notifications for your mail pieces.
Furthermore, you can use our Retrieve endpoints to track the impact and engagement rate of links created.
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
GET/domainsList all domains
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
status | query | no | string |
Responses| Status | Description | Schema |
|---|
200 | Returns a list of all domains. | domains_response |
default | Error | error |
POST/domainsCreate Domain
Request bodyapplication/json — domains (required)
Responses| Status | Description | Schema |
|---|
200 | Returns a domain object with details. | domain_response |
default | Error | error |
GET/domains/{domain_id}Retrieve a domain
Parameters| Name | In | Required | Type |
|---|
domain_id | path | yes | string |
Responses| Status | Description | Schema |
|---|
200 | Returns domain related details. | domain_response |
default | Error | error |
DELETE/domains/{domain_id}Delete a Domain
Parameters| Name | In | Required | Type |
|---|
domain_id | path | yes | string |
Responses| Status | Description | Schema |
|---|
200 | Returns the deleted link object. | domain_delete |
default | Error | error |
GET/linksList all links
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
campaign_id | query | no | — |
domain_id | query | no | string |
Responses| Status | Description | Schema |
|---|
200 | Returns the deleted link object. | links_response |
default | Error | error |
POST/linksCreate Link
Request bodyapplication/json — link_single (required)
Responses| Status | Description | Schema |
|---|
200 | Returns a successfully created link. | link_response |
default | Error | error |
GET/links/{link_id}Retrieve a link
Parameters| Name | In | Required | Type |
|---|
link_id | path | yes | string |
Responses| Status | Description | Schema |
|---|
200 | Returns a single link. | link_response |
default | Error | error |
PATCH/links/{link_id}Update a Link
Parameters| Name | In | Required | Type |
|---|
link_id | path | yes | string |
Request bodyapplication/json — link_update (required)
Responses| Status | Description | Schema |
|---|
200 | Returns the updated link. | link_response |
default | Error | error |
DELETE/links/{link_id}Delete Link
Parameters| Name | In | Required | Type |
|---|
link_id | path | yes | string |
Responses| Status | Description | Schema |
|---|
200 | Returns the deleted short link object | link_delete_response |
default | Error | error |
US Autocompletions1
Given partial address information, this endpoint returns up to 10 address suggestions. <br> <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
## Autocompletion Test Env
Your test API key does not autocomplete US addresses and is used to simulate behavior. With your test API key, requests with specific values for `address_prefix` return predetermined values. When `address_prefix` is set to:
- `0 suggestions` - Returns no suggestions - `[PRIMARY NUMBER] s[uggestion]` - Returns a maximum of ten predefined suggested addresses.
`[PRIMARY NUMBER]` does not have to be a valid primary number when sending a test request.
Each additional letter in `suggestion` reduces the number of suggestions by one (e.g.
`1 su` returns 9 suggested addresses). `[PRIMARY NUMBER]` does not affect the number of
suggestions returned.
City and state filters work as expected and filter the list of predetermined suggested addresses.
See the `test` request & response examples under [Autocomplete Examples](#operation/autocompletion) within the "Autocomplete a partial address" section in US Autocompletions. <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
POST/us_autocompletionsAutocomplete
Parameters| Name | In | Required | Type |
|---|
case | query | no | string |
valid_addresses | query | no | boolean |
Request bodyapplication/json — us_autocompletions_writable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
US Verifications2
Validate, automatically correct, and standardize the addresses in your
address book based on USPS's <a href="https://postalpro.usps.com/certifications/cass" target="_blank">Coding Accuracy Support System (CASS)</a>.
<br>
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
## US Verifications Test Env
When verifying US addresses, you'll likely want to test against a wide array of addresses to
ensure you're handling responses correctly. With your test API key, requests that use specific
values for `address` or `primary_line` and (if using `primary_line`) an arbitrary five digit
number for `zip_code` (e.g. "11111") let you explore the responses to many types of addresses:
<table>
<tr>
<th style="white-space: nowrap">ADDRESS TYPE FOR SAMPLE RESPONSE</th>
<th style="white-space: nowrap">DELIVERABILITY</th>
<th style="white-space: nowrap">SET <code>primary_line</code> OR <code>address</code> TO</th>
</tr>
<tr>
<td style="white-space: nowrap">Commercial highrise</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>commercial highrise</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Residential highrise</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>residential highrise</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Residential house</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>residential house</code></td>
</tr>
<tr>
<td style="white-space: nowrap">PO Box</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>po box</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Rural route</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>rural route</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Puerty Rico address w/ urbanization</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>puerto rico</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Military address</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>military</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Department of state</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>department of state</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Generic deliverable</td>
<td style="white-space: nowrap"><code>deliverable</code></td>
<td style="white-space: nowrap"><code>deliverable</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Missing a suite number</td>
<td style="white-space: nowrap"><code>deliverable_missing_unit</code></td>
<td style="white-space: nowrap"><code>missing unit</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Suite number doesn't exist</td>
<td style="white-space: nowrap"><code>deliverable_incorrect_unit</code></td>
<td style="white-space: nowrap"><code>incorrect unit</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Residential house with unnecessary suite number</td>
<td style="white-space: nowrap"><code>deliverable_unnecessary_unit</code></td>
<td style="white-space: nowrap"><code>unnecessary unit</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Undeliverable and block matched</td>
<td style="white-space: nowrap"><code>undeliverable</code></td>
<td style="white-space: nowrap"><code>undeliverable block match</code></td>
</tr>
<tr>
<td style="white-space: nowrap">Undeliverable and no block matched</td>
<td style="white-space: nowrap"><code>undeliverable</code></td>
<td style="white-space: nowrap"><code>undeliverable no match</code></td>
</tr>
</table>
See the `test` request & response examples under [US Verification Examples](#operation/us_verification) within the
"Verify a US or US territory address" section in US Verifications.
You can rely on the response from these examples generally matching the response you'd see in the live environment with an
address of that type (excluding the `recipient` field).
The test API key does not perform any verification, automatic correction, or standardization for addresses. If you wish to
try these features out, use our <a href="https://lob.com/address-verification" target="_blank">live demo</a> or the free plan (see <a href="https://lob.com/pricing/address-verification" target="_blank">our pricing</a> for details).
<div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
POST/bulk/us_verificationsBulk Verify
Parameters| Name | In | Required | Type |
|---|
case | query | no | string |
Request bodyapplication/json — multiple_components_list (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/us_verificationsSingle Verify
Parameters| Name | In | Required | Type |
|---|
case | query | no | string |
Request bodyapplication/json — us_verifications_writable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Zip Lookups1
Find a list of cities, states and associated information about a US ZIP code. <div class="back-to-top" ><a href="#" onclick="toTopLink()">back to top</a></div>
POST/us_zip_lookupsLookups
Request bodyapplication/json — zip5 (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Accounts1
GET/accountsGet Lob Credits Balance
Responses| Status | Description | Schema |
|---|
200 | Returns a lob_credits_balance object. | — |
Booklets4
GET/bookletsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
send_date | query | no | — |
mail_type | query | no | — |
sort_by | query | no | — |
campaign_id | query | no | — |
status | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/bookletsCreate
Parameters| Name | In | Required | Type |
|---|
Idempotency-Key | header | no | string |
idempotency_key | query | no | string |
Request bodyapplication/json — booklet_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/booklets/{booklet_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
booklet_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a booklet object | — |
default | — | — |
DELETE/booklets/{booklet_id}Delete
Parameters| Name | In | Required | Type |
|---|
booklet_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
Snap Packs4
GET/snap_packsList
Parameters| Name | In | Required | Type |
|---|
limit | query | no | integer |
before/after | query | no | — |
include | query | no | array |
date_created | query | no | — |
metadata | query | no | — |
send_date | query | no | — |
mail_type | query | no | — |
sort_by | query | no | — |
campaign_id | query | no | — |
status | query | no | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
POST/snap_packsCreate
Parameters| Name | In | Required | Type |
|---|
Idempotency-Key | header | no | string |
idempotency_key | query | no | string |
Request bodyapplication/json — snap_pack_editable (required)
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
GET/snap_packs/{snap_pack_id}Retrieve
Parameters| Name | In | Required | Type |
|---|
snap_pack_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | Returns a snap_pack object | — |
default | — | — |
DELETE/snap_packs/{snap_pack_id}Delete
Parameters| Name | In | Required | Type |
|---|
snap_pack_id | path | yes | — |
Responses| Status | Description | Schema |
|---|
200 | — | — |
default | — | — |
