Lob Help Center

Versioning & changelog

Table of Contents

Upgrading API versionVersioningChangelog

Upgrading API version

It is recommended that when you are ready to upgrade your API version to the current version, you should add in the versioning header to your requests (as described below) and then attempt test requests to ensure your integration will not break upon fully upgrading. 

Once testing is complete, you can go into your dashboard settings and make the full upgrade. After that is complete, you should remove the Lob version header from your requests to ensure all your requests use your global version.


When backwards-incompatible changes are made to the API, a new dated version is released. You have the latest version of the API, version 2020-02-11. You can always view your current version in your Dashboard Settings. 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. 


A full list of breaking changes: 

  • renders merge_variables into HTML with syntax that supports objects, conditionals, and loops

  • 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

  • remove rate-limit headers

  • updated letter template which includes a white box behind the address block area to ensure deliverability

  • 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

  • enforce 50 character limit on the sum of address_line1 and address_line2 for check recipients

  • split extra_secondary_information into extra_secondary_designator and extra_secondary_number for /v1/us_verifications

  • 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

  • renames input parameters and restructures response object for /v1/intl_verifications

  • 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


  • enforce 10,000 character limit on HTML strings

  • rename data parameter for all products to merge_variables

  • discontinues the /v1/verify endpoint - please use /v1/us_verifications or /v1/intl_verifications instead

  • unnest tracking object from postcard, letter, and check response objects

  • adds address_placement parameter to letters that defaults to top_first_page, template is no longer allowed

  • 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

  • renames the count parameter to limit for all list endpoints

  • removes the next_url and previous_url from list responses

  • adds size parameter to postcards that defaults to 4x6, setting is no longer allowed

  • remove price from letters

  • remove pages from letters

  • remove price from postcards

  • renamed file parameter to check_bottom for checks

  • remove bank_address from bank_accounts

  • remove account_address from bank_accounts and add from to checks

  • remove price from checks

  • use the new HTML renderer for all products

  • remove the status field from all endpoints

  • 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

  • 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

Was this article helpful?