Enrich a lead profile

curl --request POST \
  --url https://app.bettercontact.rocks/api/v2/enrich_profile/lead \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "linkedin_url": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373"
}
'

{
  "success": true,
  "data": {
    "contact_id": 98012430,
    "contact_first_name": "Veronick",
    "contact_last_name": "Martinuzzi",
    "contact_full_name": "Veronick Martinuzzi",
    "contact_job_title": "Development solutions sr. principal engineer",
    "contact_seniority": "Senior",
    "contact_industry": "Motor vehicle manufacturing",
    "contact_linkedin_headline": "",
    "contact_linkedin_profile_url": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373",
    "contact_location_continent": "<string>",
    "contact_location_country": "United states",
    "contact_location_state": "Ohio",
    "contact_location_city": "<string>",
    "company_name": "Honda rd americas",
    "company_domain": "hondaresearch.com",
    "company_description": "<string>",
    "company_linkedin_url": "https://www.linkedin.com/company/honda-r&d",
    "company_industry": "Motor vehicle manufacturing",
    "company_type": "<string>",
    "company_founded_year": 123,
    "company_employees_range_start": 10001,
    "company_employees_range_end": 123,
    "company_headquarters_city": "Ohio center; 21001 state route 739; raymond",
    "company_headquarters_country": "United states",
    "company_keywords": [
      "automotive",
      "auto development",
      "design",
      "research",
      "products",
      "honda"
    ]
  }
}

{
  "success": false,
  "error": "Data parameter is required."
}

{
  "success": false,
  "error": "Your are not authorized. Please check your api_key."
}

{
  "success": false,
  "error": "You do not have enough credits to perform a profile search."
}

{
  "success": false,
  "error": "Profile was not found."
}

{
  "success": false,
  "error": "Linkedin url OR First_name, last_name, company and company domain is missing"
}

POST

enrich_profile

lead

curl --request POST \
  --url https://app.bettercontact.rocks/api/v2/enrich_profile/lead \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "linkedin_url": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373"
}
'

{
  "success": true,
  "data": {
    "contact_id": 98012430,
    "contact_first_name": "Veronick",
    "contact_last_name": "Martinuzzi",
    "contact_full_name": "Veronick Martinuzzi",
    "contact_job_title": "Development solutions sr. principal engineer",
    "contact_seniority": "Senior",
    "contact_industry": "Motor vehicle manufacturing",
    "contact_linkedin_headline": "",
    "contact_linkedin_profile_url": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373",
    "contact_location_continent": "<string>",
    "contact_location_country": "United states",
    "contact_location_state": "Ohio",
    "contact_location_city": "<string>",
    "company_name": "Honda rd americas",
    "company_domain": "hondaresearch.com",
    "company_description": "<string>",
    "company_linkedin_url": "https://www.linkedin.com/company/honda-r&d",
    "company_industry": "Motor vehicle manufacturing",
    "company_type": "<string>",
    "company_founded_year": 123,
    "company_employees_range_start": 10001,
    "company_employees_range_end": 123,
    "company_headquarters_city": "Ohio center; 21001 state route 739; raymond",
    "company_headquarters_country": "United states",
    "company_keywords": [
      "automotive",
      "auto development",
      "design",
      "research",
      "products",
      "honda"
    ]
  }
}

{
  "success": false,
  "error": "Data parameter is required."
}

{
  "success": false,
  "error": "Your are not authorized. Please check your api_key."
}

{
  "success": false,
  "error": "You do not have enough credits to perform a profile search."
}

{
  "success": false,
  "error": "Profile was not found."
}

{
  "success": false,
  "error": "Linkedin url OR First_name, last_name, company and company domain is missing"
}

This endpoint is synchronous. It costs 0.1 credit per profile found, and nothing when no profile matches.There is no request_id and nothing to poll: the profile comes back in the same response. Expect a couple of seconds.

This endpoint returns profile data only. It never returns an email address or a phone number. For contact data, use Enrich leads.

Identifying the lead

There are two ways in, and they are not equivalent.

By LinkedIn URL

Send linkedin_url alone. This is the most reliable form and the one to prefer whenever you have the URL.

By name and company

Send first_name, last_name and company_domain together. All three are required.

company_domain is required in the second form, a company name is not enough. Sending first_name + last_name + company without company_domain is rejected with 422. You can send company in addition to company_domain, but never instead of it.

When linkedin_url is present the other attributes are ignored.

curl -X POST https://app.bettercontact.rocks/api/v2/enrich_profile/lead \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "linkedin_url": "https://www.linkedin.com/in/veronick-martinuzzi-a4533373" }'

const res = await fetch(
  "https://app.bettercontact.rocks/api/v2/enrich_profile/lead",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.BETTERCONTACT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      linkedin_url: "https://www.linkedin.com/in/veronick-martinuzzi-a4533373",
    }),
  }
);

const { success, data } = await res.json();
if (!success) throw new Error("Lookup failed");

import os, requests

res = requests.post(
    "https://app.bettercontact.rocks/api/v2/enrich_profile/lead",
    headers={"X-API-Key": os.environ["BETTERCONTACT_API_KEY"]},
    json={"first_name": "Veronick", "last_name": "Martinuzzi", "company_domain": "hondaresearch.com"},
)

body = res.json()
if not body["success"]:
    raise RuntimeError(body["error"])

profile = body["data"]

Authentication

The key goes either in the X-API-Key header, like every other endpoint, or as an api_key attribute in the body. The header is the recommended form: it keeps the key out of your request payloads and out of your logs.

What you get back

25 fields describing the person and their current company. Unlike the enrichment and Lead Finder payloads, there are no extra always-null legacy keys: what you see is the whole response. A few fields deserve a note:

Field	Note
`contact_linkedin_headline`	Often an empty string rather than `null` when the profile has no headline.
`contact_location_continent` / `_city`	Frequently `null` even when country and state are filled. Do not assume the location block is all-or-nothing.
`company_headquarters_city`	Can carry a full street address rather than a bare city name.
`company_employees_range_end`	`null` on open ended ranges: a company in `10001+` has a start and no end.
`company_keywords`	An array of strings, not a comma separated string.
`company_type`, `company_founded_year`	Frequently `null`.

Values are capitalised on the way out, which is why a job title comes back as Development solutions sr. principal engineer rather than in its original casing.

Authorizations

X-API-Key

string

header

required

Body

application/json

Lead to look up

Identify the lead in one of two ways:

By LinkedIn URL: send linkedin_url alone. This is the most reliable form.
By name and company: send first_name, last_name and company_domain.

linkedin_url takes precedence: when it is present the other attributes are ignored.

linkedin_url

string

Public LinkedIn profile URL of the contact. Sufficient on its own.

Example:

"https://www.linkedin.com/in/veronick-martinuzzi-a4533373"

first_name

string

First name. Required when you do not send linkedin_url.

Example:

"Veronick"

last_name

string

Last name. Required when you do not send linkedin_url.

Example:

"Martinuzzi"

company_domain

string

Company domain. Required when you do not send linkedin_url.

Example:

"hondaresearch.com"

company

string

Company name. Complements company_domain, it cannot replace it.

Example:

"Honda R&D Americas"

api_key

string

Your API key. Only needed if you do not send the X-API-Key header.

Response

Profile found.

success

boolean

Example:

true

data

object

The lead profile. These are all the keys returned: unlike the enrichment and Lead Finder payloads there are no extra always-null legacy keys.

Show child attributes

Get Started

Using the API

Lead Finder - Get new leads

Waterfall enrichment - Get phone and email

Enrich Profile

My account

Identifying the lead

By LinkedIn URL

By name and company

Authentication

What you get back

Authorizations

Body

Response

​Identifying the lead

By LinkedIn URL

By name and company

​Authentication

​What you get back

Authorizations

Body

Response

Identifying the lead

Authentication

What you get back