Guides & TutorialsAPI ReferenceOpen SourceSDKVersium for Sheets™
Versium REACH

Find Consumer Contact Information in cURL Walkthrough

Find contact information from a consumer name and postal code

Suggest Edits

This walkthrough shows you how to use a name and postal code (zip) to get back the contact details for a consumer.

Before you Start

To complete this walkthrough, you'll need:

Call the API

  1. Find the API Call -- Let's start with the API service that you need to get this information - which is the Consumer Contact API. Here's the URL for the service: https://api.versium.com/v2/contact

You add the service name in cURL with the -s option, with a question mark at the end, which indicates to the API service that options follow.:

curl \
-s https://api.versium.com/v2/contact? \
  1. Add your API key -- Adding your API key lets the API service confirm that the call is authorized. You add your API key using -H. In the call below, replace "api key" with the Versium REACH API key. For help, see Find your API key.
curl \
-s https://api.versium.com/v2/contact? \
-H "x-versium-api-key: <api key>" \
  1. Add your inputs -- Add the inputs that you want to search for using -d, each on its own line. See the The Versium REACH API and Common API Inputs and Options. For example, this API call uses the first, last, and zip inputs to specify the name and postal code for the consumer we want contact information for.

📘

Note

The name used in this walkthrough is fictitious. Replace the name with a name from your records to get real results.

curl \
-s https://api.versium.com/v2/contact? \
-H "x-versium-api-key: <api key>" \
-d first=veronica \
-d last=quek \
-d zip=92117 \
  1. Add API Output Type -- Add the output type for the API call. In this example, we're using the Output Type address and email to specify the type of information we want returned. See Common Option for details. Here's the full API call in cURL:
curl \
-s https://api.versium.com/v2/contact? \
-H "x-versium-api-key: <api key>" \
-d first=veronica \
-d last=quek \
-d zip=92117 \
-d output[]=email
-d output[]=address

var fetch = require('node-fetch');

fetch('https://api.versium.com/v2/contact?', {
    method: 'POST',
    headers: {
        'x-versium-api-key': '<api key>'
    },
    body: 'first=veronica&last=quek&zip=92117&output[]=email&output[]=address'
});

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.versium.com/v2/contact?');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, "first=veronica&last=quek&zip=92117&output[]=email&output[]=address");
$headers = array();
$headers[] = 'x-versium-api-key: <api key>';
$headers[] = 'Content-Type: application/x-www-form-urlencoded';
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$result = curl_exec($ch);
if (curl_errno($ch)) {
    echo 'Error:' . curl_error($ch);
}
curl_close($ch);

import requests

headers = {
    'x-versium-api-key': '<api key>',
}

data = [
  ('first', 'veronica'),
  ('last', 'quek'),
  ('zip', '92117'),
  ('output[]', 'email'),
  ('output[]', 'address'),
]

response = requests.post('https://api.versium.com/v2/contact', headers=headers, data=data)
  1. Call the API service over a secure connection -- When you're done adding inputs and options, you're ready to call the API. Run the cURL command over a secure internet connection.

Interpret the Response

Your response will look something like the following. It's the API giving you the data you requested in JSON format. There are three parts to the response:

  • API Information -- Response starts with information on the API version used, the time it took the API to return your response, and a unique query ID you can use if you need to troubleshoot something with us.
  • Results -- This section contains the information you requested. Our sample below has been truncated to help you see what it looks like. You'll likely see more information when you try it.
  • Input Query -- The last section shows you the options used to make the call. It should match the inputs and options you entered when you created your API call, plus any defaults used by the API service. 
{
  "versium": {
    "version":"2.0",
    "match_counts":{
      "address":1,
      "email":1
     },
      "num_matches":1,
       "num_results":1,
        "query_id":"48f9238a-ba98-4c45-97df-74f405c97527",
        "query_time":7.340619087219238,
        "results":[
          {
             "First Name":"Veronica",
             "Last Name":"Queck",
             "Address":"18804 10TH PL W",
             "City":"Kirklan",
             "State":"WA",
             "Zip":"98033",
             "Country":"US",  
             "Email Address":"[email protected]"
      } 
    ], 
    "input_query":{ 
      "first":"veronica"
       "last":"queck"
       "zip":"98117"
    }
  }
}

What's Next

Now that you've built your own API call, you're ready to dive in:

If you'd like to keep exploring, see:

Updated 5 months ago