openapi: 3.0.3 info: title: Lob version: "1.5.0" description: > The Lob API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and uses HTTP response codes to indicate any API errors.

Looking for our [previous documentation](https://lob.github.io/legacy-docs/)? license: name: MIT url: https://mit-license.org/ contact: name: Lob Developer Experience url: https://support.lob.com/ email: lob-openapi@lob.com termsOfService: https://www.lob.com/legal servers: - url: https://api.lob.com/v1 description: production tags: - name: Addresses description: | 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. - name: Authentication x-traitTag: true description: | Requests made to the API are protected with [HTTP Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). In order to properly authenticate with the API you must use your API key as the username while leaving the password blank. Requests not properly authenticated will return a `401` [error code](#tag/Errors). You can find your account's API keys in your [Dashboard Settings](https://dashboard.lob.com/#/settings/keys). ### Example Request curl uses the -u flag to pass basic auth credentials (adding a colon after your API key will prevent it from asking you for a password). One of our test API keys has been filled into all the examples on the page, so you can test out any example right away. ```bash curl https://api.lob.com/v1/addresses \ -u test_0dc8dXXXXXXXXXXXXXXXXXXXXXX5b0cc: ``` ## API Keys Lob authenticates your API requests using your account's API keys. If you do not include your key when making an API request, or use one that is incorrect or outdated, Lob returns an error with a `401` HTTP response code. You can find all API keys in your dashboard under [Settings](https://dashboard.lob.com/#/settings/keys). There are two types of API keys: *secret* and *publishable*. - **Secret API keys** should be kept confidential and only stored on your own servers. Your account's secret API key can perform any API request to Lob without restriction. - **Publishable API keys** are limited to US verifications, international verifications, and US autocomplete requests. While we encourage you to use a secret key for maximum security, you can publish these keys to JavaScript code or in an Android or iPhone app without exposing print and mail services or your secret key. Publishable keys are always prefixed with `[environment]_pub`. Every type comes with a pair of keys: one for the testing environment and one for the live environment. We recommend reading [Test and Live Environments](#tag/Test-and-Live-Environments) for more information. - name: Bank Accounts description: | 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. - name: Beta Program x-traitTag: true description: | At Lob, we pride ourselves on building high quality platform capabilities rapidly and iteratively, so we can constantly be delivering additional value to our customers. When evaluating a new product or feature from Lob, you may see that it has been released in Beta. Typically, something in Beta means that the feature is early in its lifecycle here at Lob. While we fully stand behind the quality of everything we release in Beta, we do anticipate receiving a higher level of customer feedback on Beta features, as well as a faster pace of changes from our engineering team in response to that feedback. By participating in a Lob Beta program, you will have the opportunity to get early access to a new product capability, as well as having a unique opportunity to influence the product's direction with your feedback. You should also anticipate that features in Beta may have functional or design limitations, and might change rapidly as we receive customer feedback and make improvements. In particular, new APIs in Beta may also go through more frequent versioning and version deprecation cycles than our more mature APIs. If you are participating in a Beta program and want to provide feedback, please feel free to [contact us](https://lob.com/support#contact)! - name: Billing Groups description: | 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. - name: Bulk Intl Verifications description: Verify a list of non-US addresses. - name: Bulk US Verifications description: Verify a list of US addresses. - name: Card Orders description: | 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. - name: Cards description: | 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. - name: Checks description: | 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. - name: Errors x-traitTag: true description: | Lob uses RESTful HTTP response codes to indicate success or failure of an API request - read below for more information. In general, 2xx indicates success, 4xx indicate an input error, and 5xx indicates an error on Lob's end.
ATTRIBUTE DESCRIPTION
code A consistent machine-keyable string identifying the error
status_code A conventional HTTP status code
message A human-readable, subject-to-change message with more details about the error
### HTTP Status Code Summary
CODE STATUS_CODE MESSAGE
200 SUCCESS Successful API request
401 UNAUTHORIZED Authorization error with your API key or account
403 FORBIDDEN Forbidden error with your API key or account
404 NOT FOUND The requested item does not exist
422 BAD REQUEST The query or body parameters did not pass validation
429 TOO MANY REQUESTS Too many requests have been sent with an API key in a given amount of time
500 SERVER ERROR An internal server error occurred, please contact support@lob.com
### Error Codes - Generic
CODE STATUS_CODE MESSAGE
422 BAD_REQUEST An invalid request was made. See error message for details.
409/422 CONFLICT This operation would leave data in a conflicted state.
403 FEATURE_LIMIT_REACHED The account has reached its resource limit and requires upgrading to add more.
500 INTERNAL_SERVER_ERROR An error has occured on Lob's servers. Please try request again.
422 INVALID An invalid request was made. See error message for details.
422 NOT_DELETABLE An attempt was made to delete a resource, but the resource cannot be deleted.
404 NOT_FOUND The requested resource was not found.
408 REQUEST_TIMEOUT The request took too long. Please try again.
503 SERVICE_UNAVAILABLE The Lob servers are temporarily unavailable. Please try again.
404 UNRECOGNIZED_ENDPOINT The requested endpoint doesn't exist.
422 UNSUPPORTED_LOB_VERSION An unsupported Lob API version was requested.
### Error Codes - Authentication
CODE STATUS_CODE MESSAGE
401 EMAIL_REQUIRED Account must have a verified email address before creating live resources.
401 UNAUTHORIZED The request isn't authorized.
401 UNAUTHORIZED_TOKEN Token isn't authorized.
401/403 INVALID_API_KEY The API key is invalid.
403 PUBLISHABLE_KEY_NOT_ALLOWED The requested operation needs a secret key, not a publishable key. See [API Keys](#tag/API-Keys) for more information.
429 RATE_LIMIT_EXCEEDED Requests were sent too quickly and must be slowed down.
### Error Codes - Advanced
CODE STATUS_CODE MESSAGE
401 PAYMENT_METHOD_UNVERIFIED You must have a verified bank account or credit card to submit live requests.
404 DELETED_BANK_ACCOUNT Checks cannot be created with a deleted bank account.
422 ADDRESS_LENGTH_EXCEEDS_LIMIT The sum of to.address_line1 and to.address_line2 cannot surpass 50 characters.
422 BANK_ACCOUNT_ALREADY_VERIFIED The bank account has already been verified.
422 BANK_ERROR There's an issue with the bank account.
422 CUSTOM_ENVELOPE_INVENTORY_DEPLETED Custom envelope inventory is depleted, and more will need to be ordered.
422 FAILED_DELIVERABILITY_STRICTNESS The to address doesn't meet strictness requirements. See [Account Settings](https://dashboard.lob.com/#/settings/account) to configure strictness.
422 FILE_PAGES_BELOW_MIN Not enough pages.
422 FILE_PAGES_EXCEED_MAX Too many pages.
422 FILE_SIZE_EXCEEDS_LIMIT The file size is too large. See description for details.
422 FOREIGN_RETURN_ADDRESS The 'from' address must be a US address.
422 INCONSISTENT_PAGE_DIMENSIONS All pages of the input file must have the same dimensions.
422 INVALID_BANK_ACCOUNT The provided bank routing number is invalid.
422 INVALID_BANK_ACCOUNT_VERIFICATION Verification amounts do not match.
422 INVALID_CHECK_INTERNATIONAL Checks cannot be sent internationally.
422 INVALID_COUNTRY_COVID The postal service in the specified country is currently unable to process the request due to COVID-19 restrictions.
422 INVALID_FILE The file is invalid.
422 INVALID_FILE_DIMENSIONS File dimensions are incorrect for the selected mail type.
422 INVALID_FILE_DOWNLOAD_TIME File download from remote server took too long.
422 INVALID_FILE_URL The file URL when creating a resource is invalid.
422 INVALID_IMAGE_DPI DPI must be at least 300.
422 INVALID_INTERNATIONAL_FEATURE The specified product cannot be sent to the destination.
422 INVALID_PERFORATION_RETURN_ENVELOPE Both `return_envelope` and `perforation` must be used together.
422 INVALID_TEMPLATE_HTML The provided HTML is invalid.
422 MERGE_VARIABLE_REQUIRED A required merge variable is missing.
422 MERGE_VARIABLE_WHITESPACE Merge variable names cannot contain whitespace.
422 PDF_ENCRYPTED An encrypted PDF was provided.
422 SPECIAL_CHARACTERS_RESTRICTED Cannot use special characters for merge variable names.
422 UNEMBEDDED_FONTS The provided PDF contains non-standard unembedded fonts. See description for details.
- name: Events description: | When various notable things happen within the Lob architecture, Events will be created. To get these events sent to your server automatically when they occur, you can set up [Webhooks](#tag/Webhooks).

Postcards

EVENT TYPE LIVE-ONLY WHEN EVENT TYPE OCCURS
postcard.created false A postcard is successfully created (Lob returns a 200 status code).
postcard.rendered_pdf false A postcard's PDF proof is successfully rendered.
postcard.rendered_thumbnails false A postcard's thumbnails are successfully rendered.
postcard.deleted false A postcard is successfully canceled.
postcard.mailed true A postcard receives a "Mailed" tracking event. Only enabled for certain Print & Mail Editions.
postcard.in_transit true A postcard receives an "In Transit" tracking event.
postcard.in_local_area true A postcard receives an "In Local Area" tracking event.
postcard.processed_for_delivery true A postcard receives a "Processed for Delivery" tracking event.
postcard.re-routed true A postcard receives a "Re-Routed" tracking event.
postcard.returned_to_sender true A postcard receives a "Returned to Sender" tracking event.

Self Mailers

EVENT TYPE LIVE-ONLY WHEN EVENT TYPE OCCURS
self_mailer.created false A self_mailer is successfully created (Lob returns a 200 status code).
self_mailer.rendered_pdf false A self_mailer's PDF proof is successfully rendered.
self_mailer.rendered_thumbnails false A self_mailer's thumbnails are successfully rendered.
self_mailer.deleted false A self_mailer is successfully canceled.
self_mailer.mailed true A self_mailer receives a "Mailed" tracking event. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions).
self_mailer.in_transit true A self_mailer receives an "In Transit" tracking event.
self_mailer.in_local_area true A self_mailer receives an "In Local Area" tracking event.
self_mailer.processed_for_delivery true A self_mailer receives a "Processed for Delivery" tracking event.
self_mailer.re-routed true A self_mailer receives a "Re-Routed" tracking event.
self_mailer.returned_to_sender true A self_mailer receives a "Returned to Sender" tracking event.

Letters

EVENT TYPE LIVE-ONLY WHEN EVENT TYPE OCCURS
letter.created false A letter is successfully created (Lob returns a 200 status code).
letter.rendered_pdf false A letter's PDF proof is successfully rendered.
letter.rendered_thumbnails false A letter's thumbnails are successfully rendered.
letter.deleted false A letter is successfully canceled.
letter.mailed true A letter receives a "Mailed" tracking event. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions).
letter.in_transit true A letter receives an "In Transit" tracking event.
letter.in_local_area true A letter receives an "In Local Area" tracking event.
letter.processed_for_delivery true A letter receives a "Processed for Delivery" tracking event.
letter.re-routed true A letter receives a "Re-Routed" tracking event.
letter.returned_to_sender true A letter receives a "Returned to Sender" tracking event.
letter.certified.mailed true A certified letter receives a "Mailed" tracking event. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions).
letter.certified.in_transit true A certified letter receives an "In Transit" tracking event.
letter.certified.in_local_area true A certified letter receives an "In Transit" tracking event.
letter.certified.in_local_area true A certified letter receives an "In Local Area" tracking event.
letter.certified.processed_for_delivery true A certified letter receives a "Processed for Delivery" tracking event.
letter.certified.re-routed true A certified letter receives a "Re-Routed" tracking event.
letter.certified.returned_to_sender true A certified letter receives a "Returned to Sender" tracking event.
letter.certified.delivered true A certified letter receives a "Delivered" tracking event.
letter.certified.pickup_available true A certified letter receives a "Pickup Available" tracking event.
letter.certified.issue true A certified letter receives an "Issue" tracking event.
letter.return_envelope.created false A return envelope is created (occurs simultaneously with letter creation).
letter.return_envelope.in_transit true A return envelope receives an "In Transit" tracking event.
letter.return_envelope.in_local_area true A return envelope receives an "In Local Area" tracking event.
letter.return_envelope.processed_for_delivery true A return envelope receives a "Processed for Delivery" tracking event.
letter.return_envelope.re-routed true A return envelope receives a "Re-Routed" tracking event.
letter.return_envelope.returned_to_senders true A return envelope receives a "Returned to Sender" tracking event.

Checks

EVENT TYPE LIVE-ONLY WHEN EVENT TYPE OCCURS
check.created false A check is successfully created (Lob returns a 200 status code).
check.rendered_pdf false A check's PDF proof is successfully rendered.
check.rendered_thumbnails false A check's thumbnails are successfully rendered.
check.deleted false A check is successfully canceled.
check.mailed true A check receives a "Mailed" tracking event. Only enabled for certain [Print & Mail Editions](https://dashboard.lob.com/#/settings/editions).
check.in_transit true A check receives an "In Transit" tracking event.
check.in_local_area true A check receives an "In Local Area" tracking event.
check.processed_for_delivery true A check receives a "Processed for Delivery" tracking event.
check.re-routed true A check receives a "Re-Routed" tracking event.
check.returned_to_sender true A check receives a "Returned to Sender" tracking event.

Addresses

EVENT TYPE LIVE-ONLY WHEN EVENT TYPE OCCURS
address.created false An address is successfully created (Lob returns a 200 status code).
address.deleted false An address is successfully deleted.

Bank Accounts

EVENT TYPE LIVE-ONLY WHEN EVENT TYPE OCCURS
bank_account.created false A bank account is successfully created (Lob returns a 200 status code).
bank_account.deleted false A bank account is successfully deleted.
bank_account.verified false A bank account is successfully verified.
- name: Getting Started x-traitTag: true description: | ### 1. Get Setup * Create an account at Lob.com * Obtain your API keys in the Lob dashboard settings * You'll use the format, `test_*.` for your Test API key and `live_*.` for your Live API key. ### 2. Explore * Try out in Postman:
Run in Postman
* Launch your terminal and copy/paste a CURL command. ```bash curl https://api.lob.com/v1/addresses \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: ``` * Download a [Lob SDK](#tag/SDKs-and-Tools) into your favorite IDE (integrated development environment) ### 3. Learn more Review our "Getting Started" guides for more details on use cases: * [Postcards](https://www.lob.com/guides#getting_started) * [Self-Mailers](https://www.lob.com/guides#getting_started_selfmailers) * [Letters](https://www.lob.com/guides#getting_started_letters) * [Checks](https://www.lob.com/guides#getting_started_checks) * [Address Verification Elements](https://www.lob.com/guides#av-elements-quickstart) - name: Intl Verifications description: | Address verification for non-US addresses ## 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:
DELIVERABILITY OF SAMPLE RESPONSE SET primary_line TO
deliverable deliverable
deliverable_missing_info deliverable missing info
undeliverable undeliverable
no_match no match
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 [live demo](https://lob.com/address-verification) or the free plan (see [our pricing](https://lob.com/pricing/address-verification) for details). - name: Introduction x-traitTag: true description: | Lob’s Print & Mail and Address Verification APIs help companies transform outdated, manual print-and-mail processes; save 1,000s of hours in processing time by sending mail much more quickly; and increase ROI on offline communications. Automate direct mail by triggering on-demand postcards, letters, and checks directly from your CRM or customer data systems. Address Verification corrects, standardizes, and cleanses address data for assured delivery with instant verification across 240+ countries and territories. Lob's print delivery network eliminates the hassle of vendor management with automated production and postage across a global network of vetted commercial printers. Tracking & Analytics gives you complete visibility of production and delivery for each piece of mail you send to meet compliance requirements and measure campaign performance. - name: Letters description: | 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. - name: Manage Mail x-traitTag: true description: | ## Cancellation Windows By default, all new accounts have a 5 minute cancellation window for postcards, self mailers, letters, and checks. Within that timeframe, you can cancel mailings from production, free of charge. Once the window has passed for a postcard, self mailer, letter, or check, the mailing is no longer cancelable. In addition, certain customers can customize their cancellation windows by product in their [Dashboard Settings](https://dashboard.lob.com/#). Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions) to automatically gain access to this ability. For more details on this feature, check out our [Cancellation Guide](https://lob.com/guides#cancellation_windows). If you schedule a postcard, self mailer, letter, or check for up to 180 days in the future by supplying the `send_date` parameter, that will override any cancellation window you may have for that product. ## Scheduled Mailings Postcards, self mailers, letters, and checks can be scheduled to be sent up to 180 days in advance. You can use this feature to: - Create automated drip campaigns (e.g. send a postcard at 15, 30, and 60 days) - Schedule recurring sends - Plan your mailing schedule ahead of time Up until the time a mailing is scheduled for, it can also be canceled. If you use this feature in conjunction with [a cancellation window]( index.html#section/Cancellation-Windows), the `send_date` parameter will always take precedence. For implementation details, see documentation below for each respective endpoint. For more help, see our [Scheduled Mailings Guide](https://lob.com/guides#scheduled_mailing). This feature is exclusive to certain customers. Upgrade to the appropriate [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions) to gain access. ### Example Create Request using Send Date ```bash curl https://api.lob.com/v1/postcards \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \ -d "description=Demo Future Postcard" \ -d "to=adr_bae820679f3f536b" \ -d "from=adr_210a8d4b0b76d77b" \ -d "front=tmpl_b846a20859ae11a" \ -d "back=tmpl_01b0d396a10c268" \ -d "merge_variables[name]=Harry" \ -d "send_date=2021-07-26" ``` - name: National Change of Address x-traitTag: true description: | National Change of Address (NCOA) is a service offered by the USPS, which allows individuals or businesses who have recently moved to have any mail forwarded from their previous address to their new address. As a CASS-certified Address Verification Provider, Lob also offers NCOA functionality to our Print & Mail customers. With the Lob NCOA feature enabled, Postcards, Letters, Checks and Addresses can automatically be corrected to reflect an individual's or business's new address in the case that they have moved (only if they have registered for NCOA with the USPS). Due to privacy concerns and USPS constraints, for customers with NCOA enabled, our API responses for a limited set of endpoints differ slightly in the case when an address has been changed through NCOA. **NOTE**: This feature is exclusive to certain customers. Upgrade to the appropriate Print & Mail Editions to gain access. For more information, see our [NCOA guide](https://lob.com/guides#national_change). ## NCOA Live Environment Though there are no changes to API requests, there are significant changes to our API responses, but only in the event that an address has been changed through NCOA. If an address has not been changed through NCOA, the response would be identical to our standard responses, except the addition of a `recipient_moved` field, which is `false` for unchanged addresses. If an address has been changed through NCOA, we are required to suppress the following response fields for that address: - `address_line1` - `address_line2` - The +4 portion of the ZIP+4 (5-digit ZIP code will still be present) See the `ncoa_us_live` example under [Response samples](#operation/address_create) within the "Create an Address" section in Addresses ## NCOA Test Environment In addition to sending live requests, you may also want to simulate what an NCOA response might look like so that you can ensure your application behaves as expected. The behavior of NCOA in Lob's Test Environment is very similar to our [US Verifications Test Mode](#section/US-Verifications-Test-Env). To simulate an NCOA request, send a POST request to any of the four endpoints below with an `address_line1` field equal to `NCOA`: - `POST /v1/addresses` - `POST /v1/checks` - `POST /v1/letters` - `POST /v1/postcards` - `POST /v1/self_mailers` A static address will always be returned, as documented in the `ncoa_us_test` example under [Response samples](#operation/address_create) within the "Create an Address" section in Addresses (along with the corresponding request under "Request samples"). - name: Postcards description: | 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. - name: Rate Limiting x-traitTag: true description: >- To prevent misuse, we enforce a rate limit on an API Key and endpoint basis, similar to the way many other APIs enforce rate limits. By default, all accounts and their corresponding Test and Live API Keys have a rate limit of 150 requests per 5 seconds per endpoint. The `POST /v1/us_verifications` and `POST /v1/us_autocompletions` endpoints have a limit of 300 requests per 5 seconds for all accounts. When your application exceeds the rate limit for a given API endpoint, the Lob API will return an HTTP 429 "Too Many Requests" response code instead of the variety of codes you would find across the other API endpoints. **HTTP Headers** HTTP headers are returned on each request to a rate limited endpoint. Ensure that you inspect these headers during your requests as they provide relevant data on how many more requests your application is allowed to make for the endpoint you just utilized. While the headers are documented here in titlecase, HTTP headers are case insensitive and certain libraries may transform them to lowercase. Please inspect your headers carefully to see how they will be represented in your chosen development scenario.
X-Rate-Limit-Limit: the rate limit ceiling for a given request
X-Rate-Limit-Remaining: the number of requests remaining in this window
X-Rate-Limit-Reset: the time at which the rate limit window resets (in UTC epoch seconds)
### Example HTTP Headers ```bash X-Rate-Limit-Limit:150 X-Rate-Limit-Remaining:100 X-Rate-Limit-Reset:1528749846 ``` ### Example Response If you hit the rate limit on a given endpoint, this is the body of the HTTP 429 message that you will see: ```javascript { "error": { "message": "Rate limit exceeded. Please wait 5 seconds and try your request again.", "code": "rate_limit_exceeded", "status_code": 429 } } ``` - name: Requests and Responses x-traitTag: true description: | ## Asset URLs All asset URLs returned by the Lob API (postcards, letters, thumbnails, etc) are signed links served over HTTPS. All links returned will expire in 30 days to prevent mis-sharing. Each time a GET request is initiated, a new signed URL will be generated. ## Idempotent Requests Lob supports idempotency for safely retrying `POST` requests to create postcards, self mailers, letters, and checks without accidentally creating duplicates. For example, if a request to create a check fails due to a network error, you can safely retry the same request with the same idempotency key and guarantee that only one check will ultimately be created and sent. When a request is sent with an idempotency key for an already created resource, the response object for the existing resource will be returned. To perform an idempotent `POST` request to one of the mailpiece product endpoints, provide an additional `Idempotency-Key` header or an `idempotency_key` query parameter to the request. If multiple idempotency keys are provided, the request will fail. How you create unique keys is up to you, but we suggest using random values, such as V4 UUIDs. Idempotency keys are intended to prevent issues over a short periods of time, therefore keys expire after 24 hours. Keys are unique by mode (Test vs. Live) as well as by resource (postcard vs. letter, etc.). By default, all `GET` and `DELETE` requests are idempotent by nature, so they do not require an additional idempotency key. For more help integrating idempotency keys, refer to our [implementation guide](https://lob.com/guides#idempotent_request). **Headers**
Idempotency-Key: optional

A string of no longer than 256 characters that uniquely identifies this resource.

**Query Parameters**
idempotency-key: optional

A string of no longer than 256 characters that uniquely identifies this resource.

### Example Request ```bash curl https://api.lob.com/v1/postcards \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \ -H "Idempotency-Key: 026e7634-24d7-486c-a0bb-4a17fd0eebc5" \ -d "to=adr_bae820679f3f536b" \ -d "from=adr_210a8d4b0b76d77b" \ --data-urlencode "front=Front HTML for {{name}}" \ --data-urlencode "back=Back HTML" \ -d "merge_variables[name]=Harry" ``` ## Metadata When creating any Lob object, you can include a metadata object with up to 20 key-value pairs of custom data. You can use metadata to store information like `metadata[customer_id] = "987654"` or `metadata[campaign] = "NEWYORK2015"`. This is especially useful for filtering and matching to internal systems. Each metadata key must be less than 40 characters long and values must be less than 500 characters. Metadata does not support nested objects. ### Example Create Request with Metadata ```bash curl https://api.lob.com/v1/postcards \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \ -d "description=Demo Postcard job" \ -d "metadata[campaign]=NEWYORK2015" \ -d "to=adr_bae820679f3f536b" \ -d "from=adr_210a8d4b0b76d77b" \ --data-urlencode "front=Front HTML for {{name}}" \ --data-urlencode "back=Back HTML" \ -d "merge_variables[name]=Harry" ``` ### Example List Request with Metadata Filter ```bash curl -g "https://api.lob.com/v1/postcards?metadata[campaign]=NEWYORK2015&limit=2" \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: ``` ## Request Body When manually sending a POST HTTP request directly to the Lob API, without the use of a library, you may represent the body as either a Form URL Encoded request, a JSON document, or a Multipart Form Data request. However, if you're using one of our [SDKs](#tag/SDKs-and-Tools), the generation of the request bodies is done for you automatically and you don't need to worry about the format. ### Form URL Encoded This request body encoding is accompanied with the `Content-Type: application/x-www-form-urlencoded` header. The content is an example of what the [Verify a US address](index.html#operation/us_verification) endpoint accepts. An example of a request body encoded in this format follows. ```javascript primary_line=210 King Street&city=San Francisco&state=CA&zip_code=94107 ``` ### JSON This request body encoding is accompanied with the `Content-Type: application/json` header. The content is an example of what the [Verify a US address endpoint](index.html#operation/us_verification) accepts. An example of a request body encoded in this format follows. ```javascript { "primary_line": "210 King Street", "city": "San Francisco", "state": "CA", "zip_code": "94107" } ``` ### Multipart Form Data This request body encoding is accompanied with the `Content-Type: multipart/form-data` header. This is the only format that can be used for uploading a file to the API. The content is an example of what the [Create a check](index.html#operation/check_create) endpoint accepts. An example of a request body encoded in this format follows. ```javascript --------------------------7015ebe79c0a5f8c Content-Disposition: form-data; name="description" Demo Letter --------------------------7015ebe79c0a5f8c Content-Disposition: form-data; name="to" adr_bae820679f3f536b --------------------------7015ebe79c0a5f8c Content-Disposition: form-data; name="from" adr_210a8d4b0b76d77b --------------------------7015ebe79c0a5f8c Content-Disposition: form-data; name="file"; filename="file.pdf" Content-Type: application/pdf --------------------------7015ebe79c0a5f8c Content-Disposition: form-data; name="color" true --------------------------7015ebe79c0a5f8c-- ``` - name: Reverse Geocode Lookups description: > Find a list of zip codes associated with a valid US location via latitude and longitude. - name: SDKs and Tools x-traitTag: true description: | Please visit our [Github](https://www.github.com/lob) for a list of our supported libraries. - [Ruby](https://github.com/lob/lob-ruby) - [PHP](https://github.com/lob/lob-php) - [Node.js](https://github.com/lob/lob-node) - [Python](https://github.com/lob/lob-python) - [Java](https://github.com/lob/lob-java) - [Elixir](https://github.com/lob/lob-elixir) - name: Self Mailers description: | 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. - name: Template Design x-traitTag: true description: | ## HTML Templates You can save commonly used HTML as templates within Lob to more easily manage them. You can reference your saved templates in postcard, letter, and check requests instead of having to pass a long HTML string on each request. Additionally, you can make changes to your HTML templates and update them independently, without having to touch your API integration. Templates can be created, edited, and viewed on your [Dashboard](https://dashboard.lob.com/#/templates). To use a template in a postcard, letter, or check, see the documentation for each endpoint below. For help using templates, check out our [HTML Templates Guide](https://lob.com/guides#html_templates) or get started with a [pre-designed template from our gallery](https://lob.com/template-gallery). In Live mode, you can only have as many templates as allotted in your current [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions). There is no limit in Test mode. If you'd like to interact with templates programmatically, check out our Beta Program for API access to the [HTML Templates Endpoints](#tag/Templates). ### Example Create Request using HTML Templates ```bash curl https://api.lob.com/v1/postcards \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \ -d "description=Demo Postcard job" \ -d "to=adr_78c304d54912c502" \ -d "from=adr_61a0865c8c573139" \ -d "front=tmpl_b846a20859ae11a" \ -d "back=tmpl_01b0d396a10c268" \ -d "merge_variables[name]=Harry" ``` ## HTML Examples Use a pre-designed template from our [gallery](https://lob.com/resources/template-gallery) or follow these basic [guidelines](https://github.com/lob/examples) as starting points for creating custom Postcards, Self Mailers, Letters, and Checks. Please follow the standards used in these templates, such as: - For any linked assets, you must use a performant file hosting provider with no rate limits such as Amazon S3. - Use inline styles or an internal stylesheet, do not link to external stylesheets. - Link to images that are 300DPI and sized at the final desired size on the physical mailing. For example, for a photo that is desired to be 1in x 1in on the final postcard, the image asset should be sized at 1in x 1in at 300DPI (which equates to 300px by 300px). - The sum of all linked assets should not exceed 5MB in file size. - Use `-webkit` prefixes for CSS properties when recommended [here](http://shouldiprefix.com/). Because different browsers have varying user-agent styles, the HTML you see in your browser will not always look identical to what is produced through the API. It is **strongly** recommended that you test all HTML requests by reviewing the final PDF files in your Test Environment, as these are the files that will be printed. ## Image Prepping Currently we support the following file types for all endpoints: - PDF - PNG - JPEG **Templates** You can find pre-made templates that already adhere to all of these guidelines here: - [Postcards](#tag/Postcards) - [Letters](#tag/Letters) - [Checks](#tag/Checks) - [Self Mailers](#tag/Self-Mailers) **Prepping All Images** The following guidelines apply to image types: - Images should be 300 dpi or higher - PNG/JPEG files with less than 300 dpi will be rejected. - Your artwork should include a 1/8" border around the final trim size. This means your final file size will be a total of 0.25" larger than your expected printed piece (ie, a 4"x6" postcard should be submitted as 4.25"x6.25"). There is no need to include crop marks in your submitted content. - Include a safe zone – make sure no critical elements are within 1/8" from the edge of the final size. - Do not include any additional postage marks or indicia. - File sizes should be no larger than 5MB. **Prepping PDFs** To ensure that you are producing PDF's correctly please follow the guidelines below: - [Make sure all non-standard fonts are embedded.](#section/Standard-PDF-Fonts) - Generated PDF's need to be be PDF/A compliant. **Prepping PNGs/JPEGs** To ensure that you are producing PNG's/JPEG's correctly please follow the guidelines below: - Minimum 300 dpi. The dpi is calculated as (width of image in pixels) / (width of product in inches) and (length of image in pixels) / (length of product in inches). For Example: 1275px x 1875px image used to create a 4.25" x 6.25" postcard has a dpi of 300. - Submitted images must have the same length to width ratio as the chosen product. Images will not be cropped or stretched by the API. ## Standard PDF Fonts Ideally, all fonts in provided PDFs should be embedded. Embedding a font in a PDF ensures that the final printed product will look as it was designed. Fonts can vary greatly in size and shape, even within the same family. If the exact font that was used to design the artwork is not used to print, the look and placement of the text is not guaranteed to be the same. In general, requests that provide PDFs with un-embedded fonts will be rejected. We make an exception for "standard fonts", a set of fonts that we have identified as being common. PDFs that contain un-embedded fonts that are found in the list, and match the accepted [font type](https://en.wikipedia.org/wiki/Category:Font_formats) will be accepted. Otherwise, the request will be rejected. Font embedding is an essential part of standard PDF workflows. Fonts should be embedded automatically by PDF editing software that are compliant with PDF standards.
FONT NAME TYPES
Arial Type 1, TrueType, CID TrueType
Arial,Bold Type 1, TrueType, CID TrueType
Arial,BoldItalic Type 1, TrueType, CID TrueType
Arial,Italic TrueType, CID TrueType
ArialMT TrueType, CID TrueType
Arial-BoldMT TrueType
Arial-BoldItalicMT TrueType
Arial-ItalicMT TrueType
ArialNarrow TrueType
ArialNarrow-Bold TrueType
Calibri TrueType
Calibri-Bold TrueType
Calibri-Italic TrueType
Candara-Bold TrueType
Courier Type 1
Courier-Oblique Type 1
Courier-Bold Type 1
Courier-BoldOblique Type 1
CourierNewPSMT TrueType
CourierNewPS-ItalicMT TrueType
CourierNewPS-BoldMT TrueType
Helvetica Type 1
Helvetica-Bold Type 1
Helvetica-BoldOblique Type 1
Helvetica-Oblique Type 1
LucidaConsole TrueType
MsSansSerif TrueType
MsSansSerif,Bold TrueType
Symbol Type 1, TrueType
Tahoma TrueType
Tahoma-Bold TrueType
Times-Bold Type 1
Times-BoldItalic Type 1
Times-Italic Type 1
Times-Roman Type 1
TimesNewRomanPS-BoldItalicMT TrueType
TimesNewRomanPS-BoldMT TrueType
TimesNewRomanPS-ItalicMT TrueType
TimesNewRomanPSMT TrueType, CID TrueType
TimesNewRomanPSMT,Bold TrueType
TrebuchetMS TrueType
Verdana TrueType
Verdana-Bold TrueType
Verdana,Bold TrueType
Verdana,Italic TrueType
ZapfDingbats Type 1
- name: Template Versions description: | These API endpoints allow you to create, retrieve, update and delete versions of reusable HTML templates for use with the Print & Mail API. - name: Templates description: | These API endpoints allow you to create, retrieve, update and delete reusable HTML templates for use with the Print & Mail API. - name: Test and Live Environments x-traitTag: true description: | To make the API as explorable as possible, accounts have test and live environment API keys. You're not charged any fees in the test environment, so we encourage you to use it to try out services, perform quality assurance, and run automated testing. Objects―addresses, letters, checks, etc―in one environment cannot be manipulated by objects in the other. In general, a payment method (either credit card or ACH account) must be added to your account to make live API requests. However, a payment method is not required for the first 300 live requests per month to the `/v1/us_verifications` endpoint. After the first 300 requests, you will begin receiving errors with status code `403`. Requests made in the test environment always validate request arguments, simulate live environment behavior, and enforce rate limits. _They never print, mail nor, for verification services, verify addresses._ The US & International verification services trigger behavior with specific argument values, and, if you plan on using those, we recommend reading [US Verification Test Environment](#tag/US-Verifications-Test-Environment) and [Intl Verification Test Environment](#tag/Intl-Verifications-Test-Environment). To switch between environments, use the appropriate key for that environment when performing a request. You can find each environment's API key in your dashboard under Settings; test API keys are always prefixed with `test_` and production API keys with `live_`. - name: Tracking Events description: | As mailpieces travel through the mail stream, USPS scans their unique barcodes, and Lob processes these mail scans to generate tracking events.

Certified Tracking Event Details

Letters sent with USPS Certified Mail are fully tracked by USPS, and therefore their [tracking events](#operation/tracking_event) have an additional `details` object with more detailed information about the tracking event. The following table shows the potential values for the fields in the `details` object mapped to the tracking event `name`.
NAME EVENT DESCRIPTION ACTION REQUIRED
Mailed package_accepted Package has been accepted into the carrier network for delivery. false
In Transit package_arrived Package has arrived at an intermediate location in the carrier network. false
In Transit package_departed Package has departed from an intermediate location in the carrier network. false
In Transit package_processing Package is processing at an intermediate location in the carrier network. false
In Transit package_processed Package has been processed at an intermediate location. false
In Local Area package_in_local_area Package is at a location near the end destination. false
Processed For Delivery delivery_scheduled Package is scheduled for delivery. false
Processed For Delivery out_for_delivery Package is out for delivery. false
Pickup Available pickup_available Package is available for pickup at carrier location. true
Delivered delivered Package has been delivered. false
Re-Routed package_forwarded Package has been forwarded. false
Returned to Sender returned_to_sender Package is to be returned to sender. false
Issue address_issue Address information is incorrect. Contact carrier to ensure delivery. true
Issue contact_carrier Contact the carrier for more information. true
Issue delayed Delivery of package is delayed. false
Issue delivery_attempted Delivery of package has been attempted. Contact carrier to ensure delivery. true
Issue delivery_rescheduled Delivery of package has been rescheduled. false
Issue location_inaccessible Delivery location inaccessible to carrier. Contact carrier to ensure delivery. true
Issue notice_left Carrier left notice during attempted delivery. Follow carrier instructions on notice. true
Issue package_damaged Package has been damaged. Contact carrier for more details. true
Issue package_disposed Package has been disposed. false
Issue package_held Package held at carrier location. Contact carrier for more details. true
Issue package_lost Package has been lost. Contact carrier for more details. true
Issue package_unclaimed Package is unclaimed. true
Issue package_undeliverable Package is not able to be delivered. true
Issue reschedule_delivery Contact carrier to reschedule delivery. true
Issue other Unrecognized carrier status. false
- name: US Autocompletions description: > Given partial address information, this endpoint returns up to 10 address suggestions. ## 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. - name: US Verification Types x-traitTag: true description: | These are detailed definitions for various fields in the [US verification object](#operation/us_verification).

ZIP Code Types - components[zip_code_type]

standard The default ZIP code type. Used when none of the other types apply.
po_box The ZIP code contains only PO Boxes.
unique The ZIP code is uniquely assigned to a single organization (such as a government agency) that receives a large volume of mail.
military The ZIP code contains military addresses.
empty string A match could not be made with the provided inputs.

Record Types - components[record_type]

street The default address type.
highrise The address is a commercial building, apartment complex, highrise, etc.
firm The address is of an organizational entity which receives a minimum number of mailpieces per day.
po_box The address is a PO Box.
rural_route The address exists on a Rural Route. This is an older system of mail delivery which is still used in some parts of the country.
general_delivery The address is part of the USPS General Delivery service, which allows individuals without permanent addresses to receive mail.
empty string A match could not be made with the provided inputs.

Carrier Route Types - components[carrier_route_type]

city_delivery The default carrier route type. Used when none of the other types apply.
rural_route The carrier route is a Rural Route. This is an older system of mail delivery which is still used in some parts of the country.
highway_contract The carrier route is a Highway Contract Route. This is an older system of mail delivery which is still used in some parts of the country.
po_box The carrier route consists of PO Boxes.
general_delivery The carrier route is part of the USPS General Delivery service, which allows individuals without permanent addresses to receive mail.
empty string A match could not be made with the provided inputs.

DPV Footnotes - deliverability_analysis[dpv_footnotes]

AA Some parts of the address (such as the street and ZIP code) are valid.
A1 The address is invalid based on given inputs.
BB The address is deliverable.
CC The address is deliverable by removing the provided secondary unit designator.
N1 The address is deliverable but is missing a secondary information (apartment, unit, etc).
F1 The address is a deliverable military address.
G1 The address is a deliverable General Delivery address. General Delivery is a USPS service which allows individuals without permanent addresses to receive mail.
U1 The address is a deliverable unique address. A unique ZIP code is assigned to a single organization (such as a government agency) that receives a large volume of mail.
M1 The primary number is missing.
M3 The primary number is invalid.
P1 PO Box, Rural Route, or Highway Contract box number is missing.
P3 PO Box, Rural Route, or Highway Contract box number is invalid.
R1 The address matched to a CMRA and private mailbox information is not present.
R7 The address matched to a Phantom Carrier Route (carrier_route of R777), which corresponds to physical addresses that are not eligible for delivery.
RR The address matched to a CMRA and private mailbox information is present.
- name: US Verifications description: | Validate, automatically correct, and standardize the addresses in your address book based on USPS's [Coding Accuracy Support System (CASS)](https://postalpro.usps.com/certifications/cass). ## 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:
ADDRESS TYPE FOR SAMPLE RESPONSE DELIVERABILITY SET primary_line OR address TO
Commercial highrise deliverable commercial highrise
Residential highrise deliverable residential highrise
Residential house deliverable residential house
PO Box deliverable po box
Rural route deliverable rural route
Puerty Rico address w/ urbanization deliverable puerto rico
Military address deliverable military
Department of state deliverable department of state
Generic deliverable deliverable deliverable
Missing a suite number deliverable_missing_unit missing unit
Suite number doesn't exist deliverable_incorrect_unit incorrect unit
Residential house with unnecessary suite number deliverable_unnecessary_unit unnecessary unit
Undeliverable and block matched undeliverable undeliverable block match
Undeliverable and no block matched undeliverable undeliverable no match
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 [live demo](https://lob.com/address-verification) or the free plan (see [our pricing](https://lob.com/pricing/address-verification) for details). - name: Versioning and Changelog x-traitTag: true description: | ### API Versioning When backwards-incompatible changes are made to the API, a new dated version is released. The latest version of the API is version **2020-02-11**. You can view your version and upgrade to the latest version in your [Dashboard Settings](https://dashboard.lob.com/#/settings/keys). You will only need to specify a version if you would like to test a newer version of the API without doing a full upgrade. The API will return an error if a version older than your current one is passed in. See [API Changelog](#tag/Versioning-and-Changelog) for a full list of breaking changes. ### Example Request ```bash curl https://api.lob.com/v1/addresses \ -u test_0dc8d51e0acffcb1880e0f19c79b2f5b0cc: \ -H "Lob-Version: 2020-02-11" ``` ### Specification Versioning You might be wondering why our API and specification use different versioning schemes. Lob's API predates our specification and follows the [Stripe versioning](https://stripe.com/blog/api-versioning) approach. This works well to manage backwards-incompatible changes to our API. For our API specification (used to create this documentation), we've chosen [semantic versioning](https://semver.org/). This versioning reflects the backward-compatible changes that do not require a versioning of Lob's API. Lob's API specification will be used to generate artifacts like documentation, client SDKs, and other developer tooling. Semantic versioning of our specification will inform how we version those artifacts like SDKs. It is helpful to know the version of a specification used to produce an artifact in order reference the specification release notes. ### Changelog **2020-02-11** - renders merge_variables into HTML with syntax that supports objects, conditionals, and loops **2019-06-01** - changed pagination model of GET endpoints for postcards, letters, checks, addresses, bank accounts, templates, and template versions to a cursor-based model - offset parameter on these endpoints has been removed - previous_url and next_url response fields have been added **2018-06-05** - remove rate-limit headers **2018-03-30** - updated letter template which includes a white box behind the address block area to ensure deliverability **2018-03-01** - US verification deliverability value no_match deprecated and merged into undeliverable - US verification deliverability value deliverable_extra_secondary is split into deliverable_unnecessary_unit and deliverable_incorrect_unit - US verification deliverability value deliverable_missing_secondary renamed to deliverable_missing_unit - US verifications zip_code special values deprecated in favor of more comprehensive primary_line special values **2018-02-08** - enforce 50 character limit on the sum of address_line1 and address_line2 for check recipients **2017-11-08** - split extra_secondary_information into extra_secondary_designator and extra_secondary_number for /v1/us_verifications **2017-10-17** - remove support for the /v1/states endpoint - remove support for the /v1/countries endpoint - remove support for the message field from the POST /v1/postcards endpoint **2017-09-08** - renames input parameters and restructures response object for /v1/intl_verifications **2017-08-14** - automatically standardizes and corrects US addresses created via POST /v1/addresses. non-US addresses will be standardized into uppercase only. - automatically standardizes and corrects inline US addresses used in POST /v1/postcards, POST /v1/letters, and POST /v1/checks. non-US addresses will be standardized into uppercase only. - enforce 40 character limit on name and company for all addresses - enforce 64 character limit on address_line1 and address_line2 for US addresses **2017-06-16** - enforce 10,000 character limit on HTML strings - rename data parameter for all products to merge_variables **2017-05-17** - discontinues the /v1/verify endpoint - please use /v1/us_verifications or /v1/intl_verifications instead **2016-06-30** Sunsetted - unnest tracking object from postcard, letter, and check response objects **2016-05-02** Sunsetted - adds address_placement parameter to letters that defaults to top_first_page, template is no longer allowed **2016-03-21** Sunsetted - removes tracking numbers that do not provide any consumer-facing tracking information - removes link from tracking responses - requires account_type when creating a bank account **2016-01-19** Sunsetted - renames the count parameter to limit for all list endpoints - removes the next_url and previous_url from list responses **2015-12-22** Sunsetted - adds size parameter to postcards that defaults to 4x6, setting is no longer allowed **2015-11-23** Sunsetted - remove price from letters - remove pages from letters - remove price from postcards - renamed file parameter to check_bottom for checks **2015-11-06** Sunsetted - remove bank_address from bank_accounts - remove account_address from bank_accounts and add from to checks - remove price from checks **2015-10-21** Sunsetted - use the new HTML renderer for all products **2015-06-25** Sunsetted - remove the status field from all endpoints **2015-04-11** Sunsetted - errors on all endpoints are now single objects instead of arrays - full_bleed is no longer allowed for postcards, objects, and area mails - all products are now full_bleed by default - template is no longer allowed for postcards - all postcards must adhere to the template - name is no longer allowed for area mails, bank accounts, checks, jobs, objects, and postcards - it has been replaced by description - setting ID's 100 and 101 are no longer supported for objects - please use the Simple Letter Service instead - service is no longer supported for jobs - all boolean parameters now return true/false instead of 1/0 - double_sided is no longer allowed for objects - all products are default double sided if more than one page is allowed - template is no longer allowed for objects **2014-12-18** Sunsetted - removed concept of packaging - signatory is now a required field when creating a bank account - bank_code is no longer an allowed field when creating a bank account - service_id parameter replaced by service parameter in /jobs - setting_id parameter replaced by setting parameter in /objects - name: Webhooks x-traitTag: true description: | Webhooks are an easy way to get notifications on events happening asynchronously within Lob's architecture. For example, when a postcard gets a "Processed For Delivery" tracking event, an event object of type `postcard.processed_for_delivery` will be created. If you are subscribed to that event type in that Environment (Test vs. Live), Lob will send that event to any URLs you've specified via an HTTP POST request. In Live mode, you can only have as many webhooks as allotted in your current [Print & Mail Edition](https://dashboard.lob.com/#/settings/editions). There is no limit in Test mode. You can view and create [webhooks](https://dashboard.lob.com/#/webhooks) on the Lob Dashboard, as well as view your [events](https://dashboard.lob.com/#/events). See our [Webhooks Integration Guide](https://lob.com/guides#webhooks_block) for more details on how to integrate. Please see the full list of event types available for subscription here. - name: Zip Lookups description: > Find a list of cities, states and associated information about a US ZIP code. x-tagGroups: - name: Overview tags: - Introduction - Authentication - Getting Started - SDKs and Tools - name: Address Book tags: - Addresses - National Change of Address - name: Print and Mail API tags: - Postcards - Self Mailers - Letters - Checks - Bank Accounts - Templates - Template Versions - Template Design - Manage Mail - name: Address Verification API tags: - US Verifications - US Verification Types - US Autocompletions - Reverse Geocode Lookups - Zip Lookups - Intl Verifications - name: Webhooks tags: - Webhooks - Events - Tracking Events - name: Special Features tags: - Billing Groups - Cards - Card Orders - name: Appendix tags: - Beta Program - Errors - Rate Limiting - Requests and Responses - Test and Live Environments - Versioning and Changelog components: securitySchemes: basicAuth: type: http scheme: basic security: - basicAuth: [] x-webhooks: events: post: summary: Events description: Information about an event operationId: event tags: - Events responses: "200": $ref: resources/events/responses/events.yml tracking_events: post: summary: Tracking Events description: Information about tracking events operationId: tracking_event tags: - Tracking Events responses: "200": $ref: shared/resources/tracking_events/responses/tracking_events.yml paths: /addresses: $ref: resources/addresses/addresses.yml /addresses/{adr_id}: $ref: resources/addresses/address.yml /bank_accounts/{bank_id}/verify: $ref: resources/bank_accounts/bank_account_verify.yml /bank_accounts/{bank_id}: $ref: resources/bank_accounts/bank_account.yml /bank_accounts: $ref: resources/bank_accounts/bank_accounts.yml /billing_groups/{bg_id}: $ref: resources/billing_groups/billing_group.yml /billing_groups: $ref: resources/billing_groups/billing_groups.yml /bulk/us_verifications: $ref: resources/bulk_us_verifications/bulk_us_verifications.yml /bulk/intl_verifications: $ref: resources/bulk_intl_verifications/bulk_intl_verifications.yml /cards: $ref: resources/cards/cards.yml /cards/{card_id}: $ref: resources/cards/card.yml /cards/{card_id}/orders: $ref: resources/cards/card_orders/card_orders.yml /checks/{chk_id}: $ref: resources/checks/check.yml /checks: $ref: resources/checks/checks.yml /intl_verifications: $ref: resources/intl_verifications/intl_verifications.yml /letters/{ltr_id}: $ref: resources/letters/letter.yml /letters: $ref: resources/letters/letters.yml /postcards/{psc_id}: $ref: resources/postcards/postcard.yml /postcards: $ref: resources/postcards/postcards.yml /self_mailers/{sfm_id}: $ref: resources/self_mailers/self_mailer.yml /self_mailers: $ref: resources/self_mailers/self_mailers.yml /templates/{tmpl_id}/versions/{vrsn_id}: $ref: resources/templates/template_versions/template_version.yml /templates/{tmpl_id}/versions: $ref: resources/templates/template_versions/template_versions.yml /templates/{tmpl_id}: $ref: resources/templates/template.yml /templates: $ref: resources/templates/templates.yml /us_autocompletions: $ref: resources/us_autocompletions/us_autocompletions.yml /us_reverse_geocode_lookups: $ref: resources/reverse_geocode_lookups/reverse_geocode_lookups.yml /us_verifications: $ref: resources/us_verifications/us_verifications.yml /us_zip_lookups: $ref: resources/zip_lookups/zip_lookups.yml