# People Enrich `POST https://api.getprospect.com/v2/people/enrich` Retrieve the full profile of one person you already know - identity, location, work history and contact fields. Look them up by GetProspect id, LinkedIn id or URL, email, or first name + last name + company; when several identifiers are sent the strongest wins (id, then linkedin_id, linkedin_url, email, name + company). A verified business email is found and revealed by default (1 email credit per newly revealed email; set enrich_email to false to skip), and enrich_phone additionally looks up a mobile phone for 1 phone credit. When no one matches it answers 200 with `NOT_FOUND` in `errors` and charges nothing. Uses 1 unit of the enrich rate limit, none when your workspace already owns the person. A first email search can take more than a minute: set the client timeout to at least 95 seconds. Every position is a current one and carries its start_date (YYYY-MM). Authenticate with your API key in the x-api-key header. > **How are credits spent?** > > Matching a person is free. `enrich_email` is on by default and costs 1 > email credit per newly revealed email - re-revealing an email your > workspace already unlocked is free. `enrich_phone` is off by default and > costs 1 phone credit per lookup. ## How matching works Provide any identifiers you have inside `data`. They are tried in order of reliability - `id`, then `linkedin_id`, `linkedin_url`, `email`, and finally `first_name` + `last_name` with `company_domain` or `company_name` - and the first one that finds a person wins. The `id` and LinkedIn lookups are exact; the name + company lookup is the fuzziest, so use it when it is all you have. When nothing matches, the `404` response lists which identifiers were `attempted` and which were `skipped` as invalid, so you can tell a bad input from a genuinely unknown person. ## What you get back A full [Person object](https://getprospect.com/api-docs/person-object.md): identity, location, `primary_position` and `other_positions` with complete company data (unlike [People Search](https://getprospect.com/api-docs/people-search.md), which trims position companies to keep result pages light), plus `email`, `mobile_phone`, and your workspace's `saved` context. ## Authentication Pass your API key in the `x-api-key` header. ## Body parameters - `data` (object, required): How to find the person: at least one identifier; when several are sent the strongest wins. - `id` (string, optional): The GetProspect person `id`, as returned in People Search results. - `linkedin_id` (one of, optional): The LinkedIn member numeric id (accepted as string or number). Example: `1048576` - `linkedin_url` (string, optional): The LinkedIn person URL (e.g. "https://linkedin.com/in/john-doe"). Sales Navigator URN URLs are also accepted. - `email` (string, optional): Reverse-lookup the person by their stored email address. - `first_name` (string, optional): Used together with last_name + company_domain or company_name. - `last_name` (string, optional): Used together with first_name + company_domain or company_name. - `company_domain` (string, optional): Company domain for the name+company composite lookup. - `company_name` (string, optional): Company name for the name+company composite lookup. - `enrich_email` (boolean, optional, default: true): Reveal a verified business email for the matched person; set false to skip. A stored valid email is handed over at once; a person never searched before (email.status not_checked) gets a live search against their primary company, which can take a few seconds. Consumes 1 email credit per newly revealed email (re-revealing the same email for a workspace is free); a search that finds nothing is free and leaves email.status not_found. - `enrich_phone` (boolean, optional, default: false): If true, attempt to find a mobile phone for the matched person. Consumes 1 phone credit. ## Example request ```bash curl --request POST \ --url https://api.getprospect.com/v2/people/enrich \ --header 'Content-Type: application/json' \ --header 'x-api-key: YOUR_API_KEY' \ --data ' { "data": { "email": "emily.carter.sample@intercom.com" }, "enrich_email": true, "enrich_phone": true } ' ``` ## Response 200 The person. When nobody matches, `success` is false, `data` is null and `errors[0].name` is `NOT_FOUND` (not charged). ```json { "success": true, "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "full_name": "Emily Carter", "first_name": "Emily", "last_name": "Carter", "email": { "status": "valid", "address": "emily.carter.sample@intercom.com", "verified_at": "2026-06-18T09:12:44.000Z", "checked_at": "2026-06-18T09:12:44.000Z", "revealed": true }, "mobile_phone": { "status": "found", "number": "+1 555-010-0142", "revealed": true }, "location": { "city": "San Francisco", "state": "California", "state_code": "CA", "country": "United States", "country_code": "US", "time_zone": "America/Los_Angeles", "time_zone_offset": -7 }, "linkedin_url": "https://linkedin.com/in/emily-carter-sample", "primary_position": { "job_title": "Senior Product Marketing Manager", "seniority": "Senior", "departments": [ "Marketing" ], "company": { "id": "64f1a2b3c4d5e6f7a8b9c0d2", "name": "Intercom", "description": "Intercom is a customer service platform that helps businesses talk to customers through live chat, an AI-powered help desk, and proactive support.", "logo": "https://logos.getprospect.com/64f1a2b3c4d5e6f7a8b9c0d2.jpg", "website": "intercom.com", "email": { "domain": "intercom.com", "provider": null }, "linkedin_url": "https://linkedin.com/company/intercom-inc-", "industry": "Software Development", "keywords": [ "customer messaging", "AI customer service", "help desk software" ], "naics_codes": [ 511210 ], "type": "Privately Held", "business_type": "B2B", "revenue_stream": "Subscriptions / Recurring", "founded": 2011, "employee_count": 900, "employee_range": "501-1000", "location": { "city": "San Francisco", "state": "California", "state_code": "CA", "country": "United States", "country_code": "US", "raw_address": "55 2nd St, San Francisco, CA 94105" }, "other_locations": [ { "city": "Chicago", "state": "Illinois", "state_code": "IL", "country": "United States", "country_code": "US", "raw_address": "222 W Merchandise Mart Plaza, Chicago, IL 60654" }, { "city": "Dublin", "state": null, "state_code": null, "country": "Ireland", "country_code": "IE", "raw_address": "2 Dockland Central, Dublin, Ireland" } ] } }, "other_positions": [], "saved": { "id": "64f1a2b3c4d5e6f7a8b9c0e9", "saved_at": "2026-05-02T11:20:00.000Z", "lists": [ { "id": "64f1a2b3c4d5e6f7a8b9c0f1", "name": "SaaS Marketing Leaders", "created_at": "2026-04-01T08:00:00.000Z" } ] } }, "metadata": { "timestamp": "2026-07-25T14:05:12.000Z", "matched_by": "email" } } ``` ## Response 400 Invalid request (`VALIDATION_ERROR`; `payload.code` says which kind of mistake), or no usable identifier. ```json { "success": false, "data": null, "metadata": { "timestamp": "2026-10-08T09:30:00.000Z" }, "errors": [ { "name": "VALIDATION_ERROR", "message": "enrich_mail is not a field of this request - did you mean enrich_email?", "payload": { "field": "enrich_mail", "code": "unknown_field", "received_value": true, "received_type": "boolean", "did_you_mean": "enrich_email", "allowed_fields": [ "data", "enrich_email", "enrich_phone" ] } } ] } ``` ## Response 401 Missing, unknown or inactive credentials (`UNAUTHORIZED`). ## Response 402 Not enough credits for the email or phone reveal asked for (`PAYMENT_REQUIRED`). ## Response 408 The email search or phone lookup is still running (`REQUEST_TIMEOUT`, the older spelling of `TIMEOUT`). Not charged; ask again in a few minutes, when its result is usually stored. ## Response 429 Over the `enrich` rate limit (`RATE_LIMIT`); wait `Retry-After` seconds. Sent only where rate limits are enforced. ## Response 500 Unexpected server error.