Enrich a person

This endpoint allows you to enrich a person with its complete accurate B2B profile data, email address and mobile.

Important note: When possible, it is recommended to use our Bulk Enrich Person endpoint instead for faster response time. It allows you to enrich up to 50 persons at once, instead of performing 50 individual requests.

How are credits spent?

Enriching a person record cost 1 credit per match (person data + company data + free email).
Enriching a person record with a mobile cost 10 credit per match.
You can control when you spend credits: only for verified email, only for record with a mobile, etc…
You won’t be charged if no results are found.
You won’t be charged if you enrich the same record twice in the lifetime of your account.

Endpoint

URL: https://api.prospeo.io/enrich-person
Method: POST
Headers:
- X-KEY: your_api_key
- Content-Type: application/json

Parameters

Parameter	Example value	Description
`only_verified_email` ^optional	`true`	Chose if you only want records with a verified email to be returned. Default is `false`.
`enrich_mobile` ^optional	`true`	Chose if you want to enrich the mobile (if it exists).
`only_verified_mobile` ^optional	`true`	Chose if you only want records with a mobile to be returned. Default is `false`. If `true`, `enrich_mobile` will automatically be `true`.
`data` ^required	`See below`	The person to enrich. See below for complete details.

Data parameter

The data parameter contains the datapoints you have for us to identify the person. We offer the following matching datapoints:

Datapoint	Example value	Description
`first_name` ^optional	`Roger`	The first name of the person
`last_name` ^optional	`Sterling`	The last name of the person
`full_name` ^optional	`Roger Sterling`	The full name of the person
`linkedin_url` ^optional	`https://www.linkedin.com/in/roger-sterling`	The person’s LinkedIn URL
`email` ^optional	`roger.sterling@deloitte.com`	The work email of the person
`company_name` ^optional	`Deloitte`	The company name
`company_website` ^optional	`deloitte.com`	The company website
`company_linkedin_url` ^optional	`https://linkedin.com/company/deloitte`	The company’s LinkedIn URL
`person_id` ^optional	`6f745841665155f554e5f`	If enriching from search: the ID of the person from the `Search Person API endpoint`

Minimum requirements for matching

We require at a minimum the below datapoints together in one request (allowing us to accurately identify the person):

first_name + last_name + any of (company_name/company_website/company_linkedin_url)
full_name + any of (company_name/company_website/company_linkedin_url)
linkedin_url
email
person_id (enrich from Search Person API)

Important note #1: We advise strongly against using only the company_name for matching. Many company have the same name, and this can result in mismatch/inaccurate results. Whenever possible, try to use at least the company_website.

Important note #2: the more datapoints you submit, the better, so whenever possible, submit everything you have for greater accuracy. For example, it is better to submit company_website and company_linkedin_url together rather than just one of them.

Enrich records from our search API

Another way to enrich records is to use the person_id you get from the search results (Search Person API) to this endpoint. This will identify the person and enrich as per your option (only_verified_email, only_verified_mobile, enrich_mobile).

Example requests

Always enrich

Simple request that always returns a result if a person is matched but does not reveal the mobile (use enrich_mobile:true).

In this example, we used the first_name + last_name to identify the person, and submitted all the company datapoints possible for better accuracy. This request will perform better than a request with only the company_name.


 
POST "https://api.prospeo.io/enrich-person"
X-KEY: "your_api_key"
Content-Type: "application/json"
 
{
   "data": {
       "first_name": "Eva",
       "last_name": "Kiegler",
       "company_name": "Intercom",
       "company_website": "intercom.com",
       "company_linkedin_url": "https://www.linkedin.com/company/intercom"
   }
}

With verified email only

Request that only returns a result if the email status is VERIFIED.

In this example, we used the full_name, and we could only submit the company_website to identify the company.


POST "https://api.prospeo.io/enrich-person"
X-KEY: "your_api_key"
Content-Type: "application/json"
 
{
    "only_verified_email": true,
    "data": {
        "full_name": "Eva Kiegler",
        "company_website": "intercom.com"
    }
}

Only if there is a mobile

Request that only returns a result if the record has a VERIFIED mobile.

This request automatically reveals the mobile (cost is 10 credits).

In this example, we used the linkedin_url of the person.


POST "https://api.prospeo.io/enrich-person"
X-KEY: "your_api_key"
Content-Type: "application/json"
 
{
   "only_verified_mobile": true,
   "data": {
       "linkedin_url": "https://www.linkedin.com/in/eva-kiegler"
   }
}

Always enrich mobile

This request will always return a result if there is a match and will reveal the mobile if one is present.

This request automatically reveals the mobile (cost is 10 credits).

In this example, we used the full_name, and we could only submit the company_name to identify the company.

Important: we advise against using only the company_name for matching. Many companies have the same name, and this can result in mismatch/inaccurate results. Whenever possible, try to use at least the company_website.


POST "https://api.prospeo.io/enrich-person"
X-KEY: "your_api_key"
Content-Type: "application/json"
 
{
   "enrich_mobile": true,
   "data": {
       "full_name": "Eva Kiegler",
       "company_name": "Intercom"
   }
}

With mobile + email

Request that only returns a result if the record has a VERIFIED mobile and VERIFIED email.

This request automatically reveal the mobile (cost is 10 credits).

Using the mobile and email parameter at the same time is very restrictive and might result in low match rate, and should be used only if mobiles are essential to your workflow. If not, we advise using the enrich_mobile parameter instead.


POST "https://api.prospeo.io/enrich-person"
X-KEY: "your_api_key"
Content-Type: "application/json"
 
{
   "only_verified_email": true,
   "only_verified_mobile": true,
   "data": {
       "first_name": "Eva",
       "last_name": "Kiegler",
       "company_name": "Intercom",
       "company_website": "intercom.com",
       "company_linkedin_url": "https://www.linkedin.com/company/intercom"
   }
}

Response

Complete response

This response contains all the possible fields and their example value. When a field is unavailable, it will be null.

Each response contains an person and company object. The company object contains the detail of the current company the lead work at. If the lead has no current job, this field can be null.

You can find the details of every person field here.
You can find the details of every company field here.

For error handling, see the error codes at the bottom of the page here.


{
	"error": false,
	"free_enrichment": false,
	"person": {
		"person_id": "681d3b5efb651de6f7ffdecb",
		"first_name": "Roger",
		"last_name": "Sterling",
		"full_name": "Roger Sterling",
		"linkedin_url": "https://www.linkedin.com/in/roger-sterling",
		"current_job_title": "Head of Ads",
		"current_job_key": "66d9e67b86199f0001b24246",
		"headline": "Head of Ads @ Prospeo.io | GTM pro",
		"linkedin_member_id": "161379400",
		"last_job_change_detected_at": "2024-08-27T21:18:29.577Z",
		"job_history": [
			{
				"title": "Head of Ads",
				"company_name": "Prospeo.io",
				"current": true,
				"start_year": 2024,
				"start_month": 12,
				"end_year": null,
				"end_month": null,
				"duration_in_months": 10,
				"logo_url": "25544e91-4fda-46ab-910a-2a2018c02870.jpg",
				"departments": [
					"Online marketing",
					"Communication"
				],
				"seniority": "Head",
				"company_id": "63f53afe4ceeca00016bdd2f",
				"job_key": "66d9e67b86199f0001b24246"
			},
			{
				"title": "Managing Partner",
				"company_name": "Sterling-Cooper",
				"current": false,
				"start_year": 2014,
				"start_month": 7,
				"end_year": 2024,
				"end_month": 7,
				"duration_in_months": 120,
				"logo_url": "25544e91-4fda-46ab-910a-2a2018c02870.jpg",
				"departments": [
					"Advertising"
				],
				"seniority": "Partner",
				"company_id": "50f53afe4ceeca00016bdd2f",
				"job_key": "60d9e67b16199f1001b24246"
			}
		],
		"mobile": {
			"status": "VERIFIED",
			"revealed": true,
			"mobile": "+1 234 567 8900",
			"mobile_national": "234 567 8900",
			"mobile_international": "+12345678900",
			"mobile_country": "United States",
			"mobile_country_code": "US"
		},
		"email": {
			"status": "VERIFIED",
			"revealed": true,
			"email": "roger@prospeo.io",
			"email_mx_provider": "Mimecast",
			"email_catch_all_domain": false
		},
		"location": {
			"country": "United States",
			"country_code": "US",
			"state": "California",
			"city": "Los Angeles",
			"time_zone": "America/Los_Angeles",
			"time_zone_offset": -8
		},
		"skills": [
			"Google Ads",
			"Paid media",
			"Marketing"
		]
	},
	"company": {
		"company_id": "63f53afe4ceeca00016bdd2f",
		"name": "Prospeo.io",
		"website": "https://prospeo.io",
		"domain": "prospeo.io",
		"other_websites": [],
		"description": "Say stop to bad quality data - find leads that respond.",
		"description_seo": "Prospeo is the most accurate email finder. Find emails from everywhere with our free tools.",
		"description_ai": "Prospeo is a searchable database of leads, offering quality data through verified emails and mobiles of B2B contacts.",
		"type": "Public",
		"industry": "Environmental Services",
		"employee_count": 4631,
		"employee_range": "1000-5000",
		"location": {
			"country": "Canada",
			"country_code": "CA",
			"state": "Ontario",
			"city": "Toronto",
			"raw_address": "Suite 1102, 20 Eglinton Ave W, M4R 1K8, Toronto, Canada"
		},
		"sic_codes": [
			"5045"
		],
		"naics_codes": [],
		"email_tech": {
			"domain": "prospeo.io",
			"mx_provider": "GOOGLE",
			"catch_all_domain": false
		},
		"linkedin_url": "http://www.linkedin.com/company/prospeoio",
		"twitter_url": "https://x.com/prospeoio/",
		"facebook_url": "https://www.facebook.com/prospeoio",
		"crunchbase_url": "https://www.crunchbase.com/organization/venture-capital",
		"instagram_url": "https://instagram.com/prospeoio/",
		"youtube_url": "https://youtuce.com/prospeoio/",
		"phone_hq": {
			"phone_hq": "+1 234 567 8900",
			"phone_hq_national": "234 567 8900",
			"phone_hq_international": "+12345678900",
			"phone_hq_country": "United States",
			"phone_hq_country_code": "US"
		},
		"linkedin_id": "18511550",
		"founded": 2015,
		"revenue_range": {
			"min": 5000000000,
			"max": 10000000000
		},
		"revenue_range_printed": "$ 5B-10B+",
		"keywords": [
			"Data quality",
			"B2B data",
			"Leads list"
		],
		"logo_url": "https://prospeoassets.s3.us-east-1.amazonaws.com/company_logo/GF45H5U785G18.jpg",
		"attributes": {
			"has_demo": false,
			"has_free_trial": true,
			"has_downloadable": false,
			"has_mobile_apps": null,
			"has_online_reviews": true,
			"has_pricing": true
		},
		"funding": {
			"count": 1,
			"total_funding": 1000000,
			"total_funding_printed": "$1M",
			"latest_funding_date": "2025-05-11",
			"latest_funding_stage": "Series A",
			"funding_events": [
				{
					"amount": 1000000,
					"amount_printed": "$1M",
					"raised_at": "2025-05-11",
					"stage": "Series A",
					"link": "https://www.crunchbase.com/funding_round/iq-business-south-africa-private-equity--6b34a99a"
				}
			]
		},
		"technology": {
			"count": 3,
			"technology_names": [
				"Google Analytics",
				"Mailchimp",
				"Outlook"
			],
			"technology_list": [
				{
					"name": "Google Analytics",
					"category": "Analytics"
				},
				{
					"name": "Mailchimp",
					"category": "Webmail"
				},
				{
					"name": "Outlook",
					"category": "Webmail"
				}
			]
		},
		"job_postings": {
			"active_count": 1,
			"active_titles": [
				"Rust engineer"
			]
		}
	}
}

Without email / mobile

This is another example of a response where there is less information available about the person, and the person also does not have an email nor a mobile.

In this case, if the property only_verified_email was set to true OR the only_verified_mobile was set to true, this request would have responded with a NO_MATCH error as the lead does not meet the criteria, and request would have not been charged.

As this person also does not have a current job, the company object is completely null.

Many properties are partial or null: skills (no skills available), partial location (only country is known), start_month and end_month were not reported…

You can find the details of every person field here.
You can find the details of every company field here.

For error handling, see the error codes at the bottom of the page here.


{
	"error": false,
	"free_enrichment": false,
	"person": {
		"person_id": "681d3b5efb651de6f7ffdecb",
		"first_name": "Roger",
		"last_name": "Sterling",
		"full_name": "Roger Sterling",
		"linkedin_url": "https://www.linkedin.com/in/roger-sterling",
		"current_job_title": null,
		"current_job_key": null,
		"headline": "Looking for work...",
		"linkedin_member_id": "161379400",
		"last_job_change_detected_at": "2024-08-27T21:18:29.577Z",
		"job_history": [
			{
				"title": "Head of Ads",
				"company_name": "Prospeo.io",
				"current": false,
				"start_year": 2024,
				"start_month": null,
				"end_year": 2025,
				"end_month": null,
				"duration_in_months": null,
				"logo_url": "25544e91-4fda-46ab-910a-2a2018c02870.jpg",
				"departments": [
					"Online marketing",
					"Communication"
				],
				"seniority": "Head",
				"company_id": "63f53afe4ceeca00016bdd2f",
				"job_key": "66d9e67b86199f0001b24246"
			}
		],
		"mobile": {
			"status": "UNAVAILABLE",
			"revealed": null,
			"mobile": null
		},
		"email": {
			"status": "UNAVAILABLE",
			"revealed": null,
			"email": null
		},
		"location": {
			"country": "United States",
			"country_code": "US",
			"state": null,
			"city": null,
			"time_zone": "America/New_York",
			"time_zone_offset": -5
		},
		"skills": null
	},
	"company": null
}

With mobile but not revealed

This is the response if the option enrich_mobile was not used or false. The mobile is revealed:false, and a snippet is showed.

You can find the details of every person field here.
You can find the details of every company field here.

For error handling, see the error codes at the bottom of the page here.


{
	"error": false,
	"free_enrichment": false,
	"person": {
		"person_id": "681d3b5efb651de6f7ffdecb",
		"first_name": "Roger",
		"last_name": "Sterling",
		"full_name": "Roger Sterling",
		"linkedin_url": "https://www.linkedin.com/in/roger-sterling",
		"current_job_title": "Head of Ads",
		"current_job_key": "66d9e67b86199f0001b24246",
		"headline": "Head of Ads @ Prospeo.io | GTM pro",
		"linkedin_member_id": "161379400",
		"last_job_change_detected_at": "2024-08-27T21:18:29.577Z",
		"job_history": [
			{
				"title": "Head of Ads",
				"company_name": "Prospeo.io",
				"current": true,
				"start_year": 2024,
				"start_month": 12,
				"end_year": null,
				"end_month": null,
				"duration_in_months": 10,
				"logo_url": "25544e91-4fda-46ab-910a-2a2018c02870.jpg",
				"departments": [
					"Online marketing",
					"Communication"
				],
				"seniority": "Head",
				"company_id": "63f53afe4ceeca00016bdd2f",
				"job_key": "66d9e67b86199f0001b24246"
			}
		],
		"mobile": {
			"status": "VERIFIED",
			"revealed": false,
			"mobile": "+1 (234) *** ****"
		},
		"email": {
			"status": "VERIFIED",
			"revealed": true,
			"email": "roger@prospeo.io",
			"email_mx_provider": "Proofpoint",
			"email_catch_all_domain": false
		},
		"location": {
			"country": "United States",
			"country_code": "US",
			"state": "California",
			"city": "Los Angeles",
			"time_zone": "America/Los_Angeles",
			"time_zone_offset": -8
		},
		"skills": [
			"Google Ads",
			"Paid media",
			"Marketing"
		]
	},
	"company": {
		"company_id": "63f53afe4ceeca00016bdd2f",
		"name": "Prospeo.io",
		"website": "https://prospeo.io",
		"domain": "prospeo.io",
		"other_websites": [],
		"description": "Say stop to bad quality data - find leads that respond.",
		"description_seo": "Prospeo is the most accurate email finder. Find emails from everywhere with our free tools.",
		"description_ai": "Prospeo is a searchable database of leads, offering quality data through verified emails and mobiles of B2B contacts.",
		"type": "Public",
		"industry": "Environmental Services",
		"employee_count": 4631,
		"employee_range": "1000-5000",
		"location": {
			"country": "Canada",
			"country_code": "CA",
			"state": "Ontario",
			"city": "Toronto",
			"raw_address": "Suite 1102, 20 Eglinton Ave W, M4R 1K8, Toronto, Canada"
		},
		"sic_codes": [
			"5045"
		],
		"naics_codes": [],
		"email_tech": {
			"domain": "prospeo.io",
			"mx_provider": "Microsoft",
			"catch_all_domain": false
		},
		"linkedin_url": "http://www.linkedin.com/company/prospeoio",
		"twitter_url": "https://x.com/prospeoio/",
		"facebook_url": "https://www.facebook.com/prospeoio",
		"crunchbase_url": "https://www.crunchbase.com/organization/venture-capital",
		"instagram_url": "https://instagram.com/prospeoio/",
		"youtube_url": "https://youtuce.com/prospeoio/",
		"phone_hq": {
			"phone_hq": "+1 234 567 8900",
			"phone_hq_national": "234 567 8900",
			"phone_hq_international": "+12345678900",
			"phone_hq_country": "United States",
			"phone_hq_country_code": "US"
		},
		"linkedin_id": "18511550",
		"founded": 2015,
		"revenue_range": {
			"min": 5000000000,
			"max": 10000000000
		},
		"revenue_range_printed": "$ 5B-10B+",
		"keywords": [
			"Data quality",
			"B2B data",
			"Leads list"
		],
		"logo_url": "https://prospeoassets.s3.us-east-1.amazonaws.com/company_logo/GF45H5U785G18.jpg",
		"attributes": {
			"has_demo": false,
			"has_free_trial": true,
			"has_downloadable": false,
			"has_mobile_apps": null,
			"has_online_reviews": true,
			"has_pricing": true
		},
		"funding": {
			"count": 1,
			"total_funding": 1000000,
			"total_funding_printed": "$1M",
			"latest_funding_date": "2025-05-11",
			"latest_funding_stage": "Series A",
			"funding_events": [
				{
					"amount": 1000000,
					"amount_printed": "$1M",
					"raised_at": "2025-05-11",
					"stage": "Series A",
					"link": "https://www.crunchbase.com/funding_round/iq-business-south-africa-private-equity--6b34a99a"
				}
			]
		},
		"technology": {
			"count": 3,
			"technology_names": [
				"Google Analytics",
				"Mailchimp",
				"Outlook"
			],
			"technology_list": [
				{
					"name": "Google Analytics",
					"category": "Analytics"
				},
				{
					"name": "Mailchimp",
					"category": "Webmail"
				},
				{
					"name": "Outlook",
					"category": "Webmail"
				}
			]
		},
		"job_postings": {
			"active_count": 1,
			"active_titles": [
				"Rust engineer"
			]
		}
	}
}

Error

An error occured, the error property is true and the HTTP status code is 400. You should always parse this before anything else to see if the request executed properly.

When error is true, read the error_code to understand what went wrong.

See and implement handling for the error codes here.


{
	"error": true,
	"error_code": "NO_MATCH"
}

Response details

Property	Type	Description
`error`	boolean	Indicates if an error has occurred. If `false`, the request was successful. If `true`, an error has occurred and a `error_code` property will be present. See below.
`free_enrichment`	boolean	Indicates whether you were charged. This will be `true` if you enriched the record in the past. If you enriched the record in the past, but chose to enrich the mobile this time (with `enrich_mobile`), it will be `false`.
`person`	object	The person that was matched. See our up-to-date person fields in details here.
`company`	object	The current company of the person that was matched. See our up-to-date company fields in details here.

Error codes

HTTP code	`error_code` property	Meaning
`400`	`NO_MATCH`	We couldn’t match the data you provided with a person record. This will also be returned if you used `only_verified_email`, but the lead didn’t have a verified email, or if you used `only_verified_mobile`, but the lead didn’t have a mobile.
`400`	`INVALID_DATAPOINTS`	The datapoints you submitted to identify the person are meeting the minimum requirements for matching. See this section.
`400`	`INSUFFICIENT_CREDITS`	You do not have enough credit to perform the request.
`401`	`INVALID_API_KEY`	Invalid API key, check your `X-KEY` header.
`429`	`RATE_LIMITED`	You hit the rate limit for your current plan.
`400`	`INVALID_REQUEST`	The request your submitted is invalid.
`400`	`INTERNAL_ERROR`	An error occurred on our side, please contact the support.

Rate limit

See our rate limits page.