1. [    Home ](/)
2. [Guides](/guides)
3. [Migration](/guides?category=16)
4. Migrating from API v1 to v2
 
 Advanced Migration      120 min       12 steps      20 min read  

# Migrating from API v1 to v2

  A  admin  February 25, 2026   (Updated April 22, 2026)  

 

 

       

 

 

Image

   ![Migrating from API v1 to v2](/sites/default/files/styles/16_9_512x288_focal_point_webp/public/guide-images/migrating-from-api-v1-to-v2.png.webp?itok=CzArU5Je "Migrating from API v1 to v2") 

 





 

 

 ##     Prerequisites 

Prerequisites



 

 

 

 

 

 ## On this page

  
  12 steps total 

 [    Back to top ](#main-content) 

 This guide covers everything you need to migrate your existing v1 integration to the new v2 API. We recommend a phased approach with dual-running to minimize risk.

## Step 1: Audit Your Current Integration

Identify all v1 endpoints your application uses and map them to v2 equivalents. Use our migration mapping table in the API reference.

## Step 2: Update Authentication

v2 requires Bearer token authentication. If you are using query parameter auth (?api\_key=xxx), migrate to the Authorization header.

## Step 3: Update Request Formats

Several request body schemas have changed. Key differences:

- Snake\_case field names (v1) → camelCase (v2)
- Pagination: offset/limit → page\[after\]/page\[limit\]
- Filters: query params → structured filter syntax

## Step 4: Update Response Handling

v2 uses a new envelope format: { "data": {...}, "meta": {...}, "links": {...} }

## Step 5: Implement Dual-Running

Run both v1 and v2 in parallel with a feature flag. Compare responses to catch discrepancies.

## Step 6: Test in Sandbox

Run your full test suite against the v2 sandbox. The sandbox mirrors production data with 15-minute delay.

## Step 7: Gradual Rollout

Switch traffic from v1 to v2 gradually: 10% → 25% → 50% → 100%. Monitor error rates at each stage.

## Step 8: Decommission v1

Once fully migrated, remove v1 code paths and update documentation. v1 sunsets December 2026.



 

 

 

 ### Tags

 

 

  [     Previous API Error Handling Best Practices  ](/guides/api-error-handling-best-practices) [  Next Batch Address Validation Pipeline     ](/guides/batch-address-validation-pipeline)