Postal Address Verification API

Quick Start: Ruby

There are three steps to integrating the Postal Address Verification API into your Ruby project.

1. Create an account.

Sign up for an Esendex account. When you register you will receive a license key. You will need this to use the API.

2. Install Ruby.

Install Ruby if it is not on your computer already. To check, run this command in your terminal: ruby --version

PS C:\> ruby --version
ruby 3.2.2 (2023-03-30 revision e51014f9c0) [x64-mingw-ucrt]

3. Verify an address.

Create a new Ruby file. Let’s call it demo.rb.

You can use the VerifyAddressAdvanced method to verify an address. Add the displayed code to your new file.

Replace the LicenseKey value with your account’s license key.

require 'json'
require 'net/http'

headers = { Accept: 'application/json', 'Content-Type': 'application/json' }
uri = URI('')

data = {
  'FirmOrRecipient': 'City Manager's Office',
  'PrimaryAddressLine': '306 Cedar Road',
  'SecondaryAddressLine': '6th Floor',
  'CityName': 'Chesapeake',
  'State': 'VA',
  'ZipCode': '23322',
  'LicenseKey': '00000000-0000-0000-0000-000000000000'

response =, data, headers)
raise response.message if response.is_a?(Net::HTTPClientError) || response.is_a?(Net::HTTPServerError)
response = JSON.parse(response.body)

return_code_description = case response['ReturnCode']
  when 1 then 'Invalid input'
  when 2 then 'Invalid license key'
  when 10 then 'Input address is not found'
  when 100 then 'Input address is DPV-confirmed for all components'
  when 101 then 'Input address is found, but not DPV-confirmed'
  when 102 then 'Input address primary number is DPV-confirmed, secondary number is present but not DPV-confirmed'
  when 103 then 'Input address primary number is DPV-confirmed, secondary number is missing'
  when 200 then 'Canadian address on input, verified on city level only'
  else 'Unknown return code'

puts "Return code: #{response['ReturnCode']} - #{return_code_description}"
puts response['FirmOrRecipient']
puts response['PrimaryDeliveryLine']
puts "#{response['CityName']}, #{response['StateAbbreviation']} #{response['ZipCode']}"

Run the project in your terminal with this command: ruby demo.rb. The program will display the results of the address verification.

PS C:\RubyDemo> ruby demo.rb
Return code: 100 - Input address is DPV-confirmed for all components
CHESAPEAKE, VA 23322-5514

Let’s start sending, together.