Fetch Combined Person and Company Data

Learn and practice how to fetch data for people and companies simultaneously with the combined API.

We'll cover the following

The person API takes a person’s email address and provides the person’s complete profile. Similarly, the company API takes a company’s domain and returns its associated data. In this lesson, we’ll look at the conjunction of the person and company APIs: the combined API.

The combined API

To avoid users having to make two separate requests if they want data for a person and a company, Clearbit offers the combined API endpoint. Using this endpoint, we can get the data for a person and company simultaneously. The combined endpoint takes in a required parameter—email—along with some optional parameters. It returns the details of the person and their associated company (if any) in a single JSON response.

The base URL for this endpoint is as follows:

https://person.clearbit.com/v2/combined/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 search for someone’s personal and company details.

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 country where the person lives.

company

string

optional

This is the name of the employer (mostly company name) the person works at. For example, Google.

company_domain

string

optional

This is the domain of the employer (mostly company domain) the person works for. 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 this 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 person and company data together

Now, let's make a call to the combined endpoint using the code widget below. Enter the email address of the person in place of {{EMAIL}} in line 13. Now, click "Run" to fetch the details of both the person and company at the same time.

Press + to interact
import fetch from 'node-fetch';
const API_KEY = 'Bearer {{API_KEY}}';
const endpointUrl = new URL('https://person.clearbit.com/v2/combined/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 combined API 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

The output JSON response contains both the person response object parameters and the company response object parameters.