Our API can process the following real-time services:
| Consumer Phone Append | As low as $0.08 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/consumerphoneappend Fields To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
FirstName
First name of the person associated with the phone number.
MiddleInitial
Middle initial of the person associated with the phone number.
LastName
Last name of the person associated with the phone number.
FullName
Full name of the person associated with the phone number.
Address1
Primary address associated with the phone number.
Address2
Secondary address associated with the phone number.
City
City associated with the phone number.
State
State associated with the phone number.
ZipCode
Zip associated with the phone number.
AreaCode
3 digit Area Code (if verification flag selected).
Phone
7 digit Phone (if verification flag selected).
AreaCodePlusPhone
10 Digit Phone Number (if verification flag selected).
|
|
| Business Phone Append | As low as $0.08 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/businessphoneappend Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
FirstName
First name of the person associated with the phone number.
MiddleInitial
Middle initial of the person associated with the phone number.
LastName
Last name of the person associated with the phone number.
FullName
Full name of the person associated with the phone number.
Firm
Company name of the person associated with the phone number.
Address1
Primary address associated with the phone number.
Address2
Secondary address associated with the phone number.
City
City associated with the phone number.
State
State associated with the phone number.
ZipCode
Zip associated with the phone number.
AreaCode
3 digit Area Code (if verification flag selected).
Phone
7 digit Phone (if verification flag selected).
AreaCodePlusPhone
10 Digit Phone Number (if verification flag selected).
|
|
| Reverse Phone Append | As low as $0.08 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/reversephoneappend Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
AreaCode
3 Digit Area Code.
Phone
7 Digit Phone Number.
AreaCodePlusPhone
10 Digit Phone Number.
|
|
| Email Append | As low as $0.12 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/emailappend Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
FirstName
First name of the person for the associated record.
MiddleInitial
Middle initial of the person for the associated record.
LastName
Last name of the person for the associated record.
FullName
Full name of the person for the associated record.
Address1
Primary address for the associated record.
Address2
Secondary address for the associated record.
City
City for the associated record.
State
State for the associated record.
ZipCode
Zip for the associated record.
Email
Email address (if verification flag selected).
|
|
| Reverse Email Append | As low as $0.08 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/reverseemailappend Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
Email
Email address.
|
|
| Email Validation | $0.02 per validation |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/emailvalidation Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
Email
Email address.
|
|
| Reverse Address Append | As low as $0.08 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/reverseaddressappend Fields To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
Address1
Primary address associated with the phone number.
Address2
Secondary address associated with the phone number.
City
City associated with the phone number.
State
State associated with the phone number.
ZipCode
Zip associated with the phone number.
AreaCode
3 digit Area Code (if verification flag selected).
Phone
7 digit Phone (if verification flag selected).
AreaCodePlusPhone
10 Digit Phone Number (if verification flag selected).
|
|
| VIN Append | As low as $0.09 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/vinappend Fields To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
FirstName
First name of the person associated with the phone number.
MiddleInitial
Middle initial of the person associated with the phone number.
LastName
Last name of the person associated with the phone number.
FullName
Full name of the person associated with the phone number.
Address1
Primary address associated with the phone number.
Address2
Secondary address associated with the phone number.
City
City associated with the phone number.
State
State associated with the phone number.
ZipCode
Zip associated with the phone number.
|
|
| Reverse VIN Append | As low as $0.09 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/reversevinappend Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
VIN
17 digit Vehicle Identification Number.
|
|
| Address Cleanse | $0.02 per query |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/standardizeaddress NOTE: Addresses must contain City/State, City/State/Zip Code, Zip Code, or Last Line. NOTE: Alternatively multiline addresses can be submitted as shown below, and must have at least 2 address lines. Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
companyname
If the associated record is a business address, the name of the company at the address.
address1
Street address portion of the address (example: 111 Main St.).
address2
Secondary address, usually containing the suite or apartment number (example: Suite 200).
city
The city name, not used when LastLine is used (example: Atlanta).
state
The state name, not used when LastLine is used (example: Georgia).
zipcode
The zip code, not used when LastLine is used (example: 30301).
lastline
Use this when the city, state, and zip are on one line (example: Atlanta, Georgia 30301).
Parameters
Description
line1
First line of the address.
line2
Second line of the address.
line3
Third line of the address.
line4
Fourth line of the address.
line5
Fifth line of the address.
line6
Sixth line of the address.
line7
Seventh line of the address.
line8
Eighth line of the address.
|
|
| Area Code Verification | $0.02 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/areacodeverification Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
AreaCode
3 Digit Area Code.
Phone
7 Digit Phone Number.
AreaCodePlusPhone
10 Digit Phone Number.
ZipCode
Zip code associated with the phone number.
|
|
| Cell Phone Verification | $0.02 per append |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/cellphoneverification Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
AreaCode
3 Digit Area Code.
Phone
7 Digit Phone Number.
AreaCodePlusPhone
10 Digit Phone Number.
|
|
| Disconnected Phone Verification | As low as $0.03 per query |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/disconnectverification Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
AreaCode
3 Digit Area Code.
Phone
7 Digit Phone Number.
AreaCodePlusPhone
10 Digit Phone Number.
|
|
| Do Not Call (DNC) Flagging | As low as $0.02 per query |
|
WebAPI: https://api.updateyourlist.com/realtime/v1/dnc Field To Submit
Description
account_id
Your DIY Portal Account #.
profilename
Your custom profile name for this service.
AreaCode
3 Digit Area Code.
Phone
7 Digit Phone Number.
AreaCodePlusPhone
10 Digit Phone Number.
|
|
How It Works...
You will use your Account # and API Key (acquired after creating a DIY Portal account and requesting your key) to connect to our WebAPI using HMAC authentication with a custom AMX Authorization Header which will be used to secure access to the WebAPI.
First...
Each WebAPI appending service will have it's own custom profile which you will create and save in the DIY Portal. A "profile" is basically the custom options you select and save for each of the WebAPI appending services. In otherwords, when you submit the "required fields" (i.e. name, address, city, state, zip etc..) to the WebAPI, we'll use your custom profiles to retrieve instructions on how to process your WebAPI request. In the example screenshot(s) below, we're going to request Time Zone flag, Parsed Names, and Parsed Address output fields for our Reverse Phone Append service which we saved under profile name, "mycustomprofile".
Next...
You will create a LIST of "DIYFields" you want to submit to the WebAPI which will include your account_id, profile name, and the required fields for the WebAPI service you are consuming.
Next...
You will hash the "signature" string (highlighted in green) below with your secret API Key using HMACSHA256..
Finally...
You will create a custom "AMX" Authentication header by combining the items highlighted in red (separated by colon symbols).
That's it!
Our server will use the same logic to authenticate your WebAPI request and return the output data in JSON using the same format ---> LIST of "DIYFields"
Sample source code available in ASP.Net, VB.Net, C#, JAVA, PHP, Python, Node.js, Perl, and/or Ruby On Rails.
What is HMAC API Key Authentication
It is a mechanism for calculating a message authentication code using a hash function in combination with a shared secret key between the two parties involved in sending and receiving the data (Front-end client and Back-end HTTP service) . The main use for HMAC is to verify the integrity, authenticity, and the identity of the message sender.
Once the server revives the request along with the hash from the client, it tries to reconstruct the hash by using the received request data from the client along with the API Key, once the hash is generated on the server, the server will be responsible to compare the hash sent by the client with the regenerated one, if they match then the server considers this request authentic and will process your WebAPI request(s).
Flow of Using API Key – HMAC Authentication
Flow on the client side:
- Client should build a string by combining all the data that will be sent. This "signature" string contains the following parameters (Your DIY Portal Account#, Http Method, Request WebAPI Url, Request Time Stamp, Random Nonce, and the Base 64 string representation of the request body content (MD5 hash the request body content). *Note: Request Time Stamp is calculated using UNIX time (number of seconds since Jan. 1st 1970) to overcome any issues related to a different timezone between client and server. A Random Nonce is an arbitrary number/string used only once.
- Client will hash this large "signature" string built in the first step using a hash algorithm such as (SHA256) and the API Key assigned to it. The result for this hash is a unique signature for this WebAPI request.
- The signature will be sent in the Authorization header using a custom scheme such as”amx” . The data in the Authorization header will contain your DIY Portal Account#, Request Time Stamp, and Random Nonce separated by colon ":" symbol. The format for the Authorization header will be like: [Authorization: amx AccountId:Signature:Nonce:Timestamp].
- Client will send the request as usual along with the data generated in step 3 in the Authorization header.
Flow on the server side:
- Server receives all the data included in the request along with the Authorization header.
- Server extracts the values (Account#, Signature, Nonce, and Request Time stamp) from the Authorization header.
- Servers looks for the Account# in a certain secure repository (DB, Conguration File, etc…) to get the API Key for this client.
- Assuming the server was able to look up this Account# from the repository, it will be responsible to validate if this request is a replay request and reject it, so it will prevent the API from any replay attacks. This is why we’ve used a Request Time Stamp along with a Random Nonce generated at the client, and both values have been included into HMAC signature generation. The server will depend on the Random Nonce to check if it was used before within certain acceptable bounds, i.e. 5 minutes.
- Server will rebuild a string containing the same data received in the request by adhering to the same parameter orders and encoding followed in the client application.
- Server will hash the string generated in previous step using the same hashing algorithm used by the client (SHA256) and the same API Key obtained from the secure repository for this client.
- Once the hash is generated on the server, the server will be responsible to compare the hash sent by the client with the regenerated one, if they match then the server considers this request authentic and will process your WebAPI request(s) and return your output results in JSON format.
Sample Results & Code (Click To Enlarge)
First...
Create and activate your free DIY Portal account
Next...
After logging into the DIY Portal click on 'Developer API' in the left hand navigation pane
Next...
Click on 'Request Developer API Key'
Finally...
Complete the form and click 'Request API Key'
This Developer API landing page content was last updated on: 7/10/2019