Upgrading from Legacy Validation APIs

BriteVerify's Legacy APIs will no longer be supported as of October 1, 2022. The following guide is meant to quickly orient you to the work involved in migration. 

Why is this API being deprecated?

We’ve got big plans for BriteVerify— from quality and speed improvements to new tools and features that help you better manage your data hygiene. Ending support for these legacy APIs means that we can bring that innovation to you faster.  

What improvements are in the new API? 

Moving your team to our current API versions offers many advantages, including:

• Support for email, phone, and mailing address validations in a single call
• Access to the new credits endpoint, allowing you to programmatically check your credit balance
• Support for Public Keys
• Improved phone validation results
• Improved security features

Customers using the Validity Verify (which currently uses the legacy API) plugin in Salesforce don’t need to worry—we will update the plugin for you. However, any other implementations of the legacy API you may have will require your attention.

APIs being deprecated

• Legacy Real-time Single-transaction API
• Legacy Bulk API

APIs not being deprecated

• Real-time Single-transaction API V1
• Bulk API V2
• Bulk API V3

Confirming your use of Legacy APIs

Identifying whether you are using a legacy API is easy:

• Single-transaction API: the GET URL contains one or all of the following:
  • emails.json/xml
  • phones.json/xml
  • names.json/xml
  • the email address being validated
  • your API key
• Legacy Bulk API: the GET and POST URLs start with ‘app.briteverify.com’.

Migrating from Legacy Single-Transaction API to
Real-time Single-transaction API V1

Go to our API documentation ↗︎ for detailed information on endpoints and examples.

If using a client-side API, we strongly encourage you to generate a new public API key. Find out more about public keys here. If you are using a server-side API, you can continue using the same API key with the upgraded V1. Navigate to the API Key page in your account to find the type of API key you are currently using.

V1 changes

Endpoints and Requests changes

• Many of the calls that were Get with Legacy APIs become POST with v1
• A new credits endpoint is available, which returns total credit and reserve credit balances
• Support for external_id third party identifier was added

Status Responses changes

• Email validation
  • No notable changes
• Phone validation
  • The phone response in v1 has been greatly simplified to provide more privacy for data subjects. The new response delivers back the following keys
    • number
    • service_type
    • phone_location (new)
      • residential
      • business
      • small_office
    • status
    • errors
  • Values returned for the service_type key have been updated with new labels. Below is the mapping, old to new.
    
    • pots → land
    • mobile → mobile
    • digital → voip
• Address Validation
  • The address response has also been simplified to eliminate superfluous information and improve privacy, however most of the valuable keys remain unchanged.

Breaking changes

• Support for passing information via URL parameters is no longer provided. A request body MUST be used.
• Support for validating names is no longer provided
• Support for XML requests/responses are no longer provided
• BODY and responses will be in a nested JSON format, necessary for the support of multiple validation types

Migrating from Legacy Bulk API to Bulk API V3

It is highly recommended to skip past V2 and go straight to V3. It has distinct advantages over V2 that are mentioned below. As this is the recommendation, the migration info for Bulk API will only cover V3. Go to our API documentation ↗︎ for detailed information on endpoints and examples.

V3 changes

Endpoints and Requests changes

• POST BODY and responses will be in a nested JSON format
• V3: A new credits endpoint is available, which returns total credit and reserve credit balances
• V3: Mailing address validation support has been added
• V3: Paging is now supported
• V3: Support for making page appends in parallel (as opposed to having to wait for one append request to finish before starting another) has been added
• V3: Support for external_id third party identifier was added

Status Responses changes

• Email validation
  • There is no longer a need to apply a csv name when POSTing a list
  • Much of the metadata returned in the response has been moved to a new endpoint called List State
• Phone validation
  • Phone support was added
• Address Validation
  • Mailing address support was added