Fetch Person Details

Learn and practice how to fetch the basic details of a person using Clearbit's person API.

We'll cover the following

If a consumer is interested in what our company offers, we’ll probably have a new sign-up. However, this sign-up will be helpful only if an authenticated user signs up, not a fake one. How would we know this? One way is to spend a lot of time investigating the user. The other approach is to use Clearbit’s Enrichment API. Enrichment API provides three APIs:

  1. Person API
  2. Company API
  3. Combined API

The person API

We can use Clearbit's person endpoint to get the basic details of a person, such as their name, location, employment status, Twitter handle, Facebook handle, and more. This endpoint takes a required parameter — email — and returns all the information in a single JSON response. We can also pass optional parameters, like the name and IP address of a person, to get more accurate and reliable results.

The base URL for this endpoint is as follows:

https://person.clearbit.com/v2/people/find?email={email_of_person}

Request parameters

This endpoint supports the following request parameters:

Name

Type

Category

Description

email

string

required

This is the email address used to look up the person’s information.

given_name

string

optional

This is the first name of the person.

family_name

string

optional

This is the last name of the person—giving it as a parameter ensures more reliable and stronger match rates and, thus, results.

ip_address

string

optional

This is the IP address of the person whose details we are looking for—giving it as a parameter ensures more reliable and stronger match rates and, thus, results.

location

string

optional

This is the city or the country where the person lives.

company

string

optional

This is the name of the employer (mostly company name) for whom the person serves. For example, Google.

company_domain

string

optional

This is the domain of the employer (mostly company domain) for whom the person serves. For example, google.com.

linkedin

string

optional

This is the URL of the person's LinkedIn profile.

twitter

string

optional

This is the Twitter handle associated with the person.

facebook

string

optional

This is the URL of the person's Facebook profile.

webhook_url

string

optional

This is the webhook URL on which we can request the results that might face delays otherwise.

webhook_id

string

optional

This is the custom identifier for the webhook request, if any.

subscribe

boolean

optional

We can get notified about any updates or changes made to the person's details by passing this parameter with its value set to True.

suppression

string

optional

This is used to exclude some country's data from the results. For example, if set to us, it will eliminate results with country data in the US (United States), and if set to us_strict, it will eliminate results with country data in the US or with null country data.

Fetch the person's data

Let's make an actual call to this endpoint using the code widget below. Enter the email address of the person in place of {{EMAIL}} in line 13. For this example, you can use emails of your choice or any of the following values:

Email Address

andrew@airbnb.com

sundar@google.com

marc@salesforce.com

fahim@educative.io

Note: When we run the code, we'll be asked to save the ID of the person. Click "Save" to do so. We'll use this ID later in the lesson.

Now, click "Run" to get the details of the person whose email address we provided.

Press + to interact
import fetch from 'node-fetch';
const API_KEY = 'Bearer {{API_KEY}}';
const endpointUrl = new URL('https://person.clearbit.com/v2/people/find');
const headerParameters = {
  authorization: API_KEY,
  contentType: 'application/json',
};
const queryParameters = new URLSearchParams({
  email: '{{EMAIL}}'
});
const options = {
  method: 'GET',
  headers: headerParameters,
};
async function fetchData() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    
    // Custom function for printing the error message
    printError(error);
  }
}
// Calling function to make API call
fetchData();

In the code above:

  • Line 1: We import the node-fetch library.

  • Line 5: We define the URL for the person endpoint.

  • Lines 7–10: We define the header parameters for the request, including the required API key parameter.

  • Lines 12–14: We define the query parameters for the request.

  • Lines 16–19: We set the options for the API call, specifying the HTTP request type as GET.

  • Lines 21–33: We define a function called fetchData to make the API call.

  • Lines 22–27: Within a try block, we make a call to the API, printing the response to the console.

  • Lines 28–32: We catch all errors and exceptions within a catch block and print them to the console.

  • Line 36: We invoke the fetchData function.

Response parameters

As we know, the output of the person endpoint is a JSON response; the table below explains some attributes of this response. If you want details for all the objects in the output response, then check this lesson.

Name

Type

Description

id

string

This is the internal ID associated with the person on Clearbit.

name

object

This is the object that contains information about the name of the person, including their, first name, last name, or any other names associated with them.

location

string

This is the most accurate location of the person Clearbit could get.

geo

object

This is the object that contains the person's geographical information, such as latitude, longitude, city, state, street number, and so on.

bio

string

This is the most accurate biography of the person Clearbit could get.

site

string

This is the website of the person if they have one.

avatar

string

This is the URL for the avatar of the person, the best Clearbit could get.

employment

object

This is the object that contains the employment details of the person.

Clearbit’s person lookup is a vague match instead of an exact one. Therefore, we may get some incorrect results. Clearbit allows us to help them fix these issues. We can use its flag the person endpoint to label a person’s information as incorrect. We can also pass the correct set of attributes so they can fix it. Once received, Clearbit looks into the request and incorporates the fixes if required. Flagging a person is a POST method.

The base URL for this endpoint is as follows:

https://person.clearbit.com/v1/people/{id_of_person}/flag

Request parameters

The optional versions of attributes we can send to suggest correct information to Clearbit are as follows:

Name

Type

Category

Description

given_name

string

optional

This is the first name of the person.

family_name

string

optional

This is the last name of the person.

employment_title

string

optional

This is the title of the person at the company.

facebook_handle

string

optional

This is the person's Facebook ID or screen name.

github_handle

string

optional

This is the person's GitHub handle.

twitter_handle

string

optional

This is the person's screen name on Twitter.

linkedin_handle

string

optional

This is the LinkedIn URL of this person.

googleplus_handle

string

optional

This is the person's Google Plus handle.

Flag a person

Let's practice flagging someone. This endpoint requires the ID of the person, which we saved earlier in the lesson. Now, click "Run" to use that ID to flag the "xyz" person on Clearbit.

Note: For this example, we can use the ID against any fake email address, such as bill.gates@microsoft.com. To use the ID against this email, go back to the previous code widget and then run and save the ID value.

Press + to interact
import fetch from 'node-fetch';
const API_KEY = 'Bearer {{API_KEY}}';
const endpointUrl = new URL('https://person.clearbit.com/v1/people/{{ID}}/flag');
const headerParameters = {
  authorization: API_KEY,
  contentType: 'application/json',
};
const options = {
  method: 'POST',
  headers: headerParameters,
};
async function fetchData() {
  try {
    const response = await fetch(endpointUrl, options);
    // Custom function for printing the API response
    printResponse(response);
  } catch (error) {
    
    // Custom function for printing the error message
    printError(error);
  }
}
// Calling function to make API call
fetchData();

If we’ve successfully flagged, Clearbit sends the status code 200. Otherwise, it sends 404, which means the person is not found.