Endpoints // Enrichment

Enrich profile

Updated

Get a person's full professional profile from any details you have.

POST/v2/enrich/persons

Introduction

The Enrich Profile endpoint returns a person's full professional profile from any combination of identifying details. Every input is optional and independent; you only need to provide at least one, and the more fields you include, the more accurate the match.

This endpoint costs 2 credits, charged only when a person is found. The full profile is included, with no extra credit. A not-found response (404) is always free: no credits are consumed.

Authorization

Name	Type	Required	Description
`apikey`	string	Yes	Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header.

Request body

All fields are optional and independent. Provide at least one of email, firstName, lastName, companyDomain, or companyName. Any combination works, and the more identifying fields you provide, the more accurate the match.

Name	Type	Required	Description
`email`	string	No	Professional email address to look up (e.g. `jane.doe@acme.com`).
`firstName`	string	No	First name of the person to look up.
`lastName`	string	No	Last name of the person to look up.
`companyDomain`	string	No	Company domain to help disambiguate (e.g. `acme.com` or `https://acme.com`).
`companyName`	string	No	Company name to help disambiguate (e.g. `Acme Corp`).
`fullProfile`	boolean	No	Deprecated and ignored. Enrich always returns the full profile, so this field no longer changes the response or the cost. It is still accepted so existing requests keep working, and you can remove it.

Best practices

Every field you add narrows the search. That is a trade-off, not a free win.

Fewer fields mean a higher match rate, but lower confidence. Sending only firstName: "Pierre" and lastName: "Dupont" will almost always return someone, because there are hundreds of Pierre Dupont. Nothing in that response guarantees it is your Pierre Dupont. In any case, whenever more than one person matches your request, the extra candidates are returned in the response under data.alternativePersons (see Response structure below).

More fields mean a lower match rate, but higher confidence. Add companyDomain: "acme.com" and the request only matches if a Pierre Dupont is actually known at Acme. You will get more 404s, and the matches you do get are the right person.

Which side to lean on depends on what a wrong match costs you. For outbound or CRM writes, prefer precision: a wrong profile is worse than no profile. For coverage-oriented work where a human reviews the output, a looser query is fine.

Response structure

The person is returned nested under data.person, other candidates under data.alternativePersons, and data.isFullProfile tells you which shape data.person has.

Full profile

data.person is the full profile: the same person shape as /v2/fetch/persons, with full-profile fields such as summary, photoUrl, currentPosition, experience, education, skills, languages, certifications, and more. It also keeps the enrich fields currentPositionTitle, currentCompanyId, currentCompanyName, currentCompanyLinkedinId and updateDate. Each item of data.alternativePersons is a full profile too, with the same enrich fields, at no extra credit.

The full profile is a superset of the light enrich shape: every light field keeps its name, its place and its type, and the full-profile fields are added next to them. An integration built on the light shape keeps working unchanged.

The complete full-profile field reference, including the items of experience, education, languages, certifications, recommendations and testScores, is documented on the Person Profile endpoint.

Light fallback

In rare cases the full profile cannot be retrieved in time. The response then has data.isFullProfile set to false, and data.person and data.alternativePersons contain only the light shape: the fields listed under alternativePersons below. The request still costs 2 credits.

An alternative candidate can also come back in the light shape on its own, while data.person is full, when its full profile could not be retrieved in time. A full item always carries experience: check for it on each alternative.

To complete a light result, call the Person Profile endpoint (/v2/fetch/persons, 1 credit for a cached profile) with the id or the linkedinUrl returned in data.person:

JSON

{
  "id": "prs_9f8e7d6c5b4a"
}

Field	Type	Description
`success`	boolean	`true` if the request was processed successfully
`error`	`null`	Always `null` on success

dataobject

The response payload (null on error responses)

Show child attributes

Field	Type	Description
`isFullProfile`	boolean	`true` when `person` is the full profile. `false` when only the light shape could be returned in time (see Light fallback)

personobject

The matched person: the full profile, or the light shape when isFullProfile is false

Show child attributes

Field	Type	Description
`id`	string	Internal identifier for the person (`prs_...`). Pass it as `id` to the Person Profile endpoint to fetch this profile again
`publicId`	string	Public profile slug (the `/in/xxx` part of the URL)
`memberId`	string	Social internal member ID
`linkedinUrl`	string	Full profile URL
`firstName`	string \| null	First name
`lastName`	string \| null	Last name
`headline`	string \| null	Profile headline
`summary`	string \| null	About / summary section
`pronoun`	string \| null	Preferred pronoun (e.g. `"she/her"`, `"he/him"`)
`isOpenToWork`	boolean	Whether the person is open to work
`hasPremium`	boolean	Whether the person has Social Premium
`hasVerificationBadge`	boolean	Whether the profile is verified
`isInRemembrance`	boolean	Whether the profile is memorialised
`photoUrl`	string \| null	Profile photo URL
`backgroundUrl`	string \| null	Background / banner image URL
`creationDate`	string \| null	Account creation date (ISO 8601)
`followersCount`	number \| null	Number of followers
`connectionsCount`	number \| null	Number of connections
`experience`	PersonExperience	Professional experiences, same shape as `currentPosition`
`education`	PersonEducation	Education history
`skills`	string	List of skill names
`languages`	PersonLanguage	Spoken languages
`certifications`	PersonCertification	Professional certifications
`recommendations`	PersonRecommendation	Received recommendations
`testScores`	PersonTestScore	Standardized test scores
`currentPositionTitle`	string \| null	Current job title (how it is chosen)
`currentCompanyId`	string \| null	Internal identifier of the current company
`currentCompanyName`	string \| null	Current company name
`currentCompanyLinkedinId`	string \| null	Social identifier of the current company (useful to chain into a company fetch)
`updateDate`	string \| null	When the record was last refreshed (ISO 8601)

locationobject

Geographic location (null if unknown)

Show child attributes

Field	Type	Description
`city`	string	City
`state`	string	State or region
`country`	string	Country name
`countryCode`	string	ISO country code (e.g. `"US"`)
`rawLocation`	string	Raw location string as displayed on the profile (`null` if unavailable)

currentPositionobject

Current job position (null if no current position)

Show child attributes

Field	Type	Description
`title`	string \| null	Job title
`description`	string \| null	Role description
`contractType`	string \| null	Contract type (e.g. `"Permanent"`, `"Internship"`)
`companyName`	string \| null	Company name
`companyLinkedinId`	string \| null	Company Social internal identifier
`companyUrl`	string \| null	Company Social profile URL
`companyLocation`	string \| null	Company location
`companyLogoUrl`	string \| null	Company logo URL
`startEndDate`	DateRange \| null	Position duration

startEndDateobject

Period boundaries

Show child attributes

Field	Type	Description
`start`	string \| null	Start date (ISO 8601)
`end`	string \| null	End date (ISO 8601, `null` if ongoing)

alternativePersonsobject[]

Other candidates that matched your input but scored lower than person, ordered best first (up to 9). Empty when the match is unique. Alternatives mostly show up when resolving by name, where several people can match. Each one is returned with its full profile, the same shape as person; the fields below are always present, including on the rare item that falls back to the light shape.

Show child attributes

Field	Type	Description
`id`	string	Internal identifier for the person
`publicId`	string	Public profile slug (the `/in/xxx` part of the URL)
`linkedinUrl`	string	Full profile URL
`firstName`	string	First name
`lastName`	string	Last name
`headline`	string	Profile headline
`currentPositionTitle`	string	Current job title (how it is chosen)
`currentCompanyId`	string	Always `null` on alternative candidates
`currentCompanyName`	string	Current company name
`currentCompanyLinkedinId`	string	Social identifier of the current company (useful to chain into a company fetch)
`updateDate`	string	When the record was last refreshed (ISO 8601)

locationobject

Geographic location (null if unknown)

Show child attributes

Field	Type	Description
`city`	string	City
`state`	string	State or region
`country`	string	Country name
`countryCode`	string	ISO country code (e.g. `"US"`)
`rawLocation`	string	Raw location string as displayed on the profile (`null` if unavailable)

quotasobject

Credits and rate limit usage after this request

Show child attributes

Field	Type	Description
`creditsConsumed`	number	Credits consumed by this request

workspaceobject

Workspace-level limits

Show child attributes

Field	Type	Description
`id`	string	Your workspace identifier
`hasUnlimitedCredits`	boolean	Whether workspace credits are unlimited
`allowDailyOvercost`	boolean	Whether the workspace may exceed its daily cap

creditsobject

Credit balance

Show child attributes

Field	Type	Description
`total`	number	Total credits in your plan
`used`	number	Credits consumed so far
`left`	number	Remaining credits

dailyLimitobject

Daily request limit (null if not configured)

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per day
`used`	number	Requests made today
`left`	number	Remaining requests today
`nextReset`	string	When the daily window resets (ISO 8601)

minuteRateLimitobject

Per-minute rate limit

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per minute
`used`	number	Requests made in the current minute
`left`	number	Remaining requests in the current minute
`nextReset`	string	When the minute window resets (ISO 8601)

keyobject

API key-level limits (null when request is from dashboard)

Show child attributes

Field	Type	Description
`id`	string	API key identifier

dailyLimitobject

Daily limit for this key (null if not configured)

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per day
`used`	number	Requests made today
`left`	number	Remaining requests today
`nextReset`	string	When the daily window resets (ISO 8601)

minuteRateLimitobject

Minute rate limit for this key

Show child attributes

Field	Type	Description
`limit`	number	Maximum requests per minute
`used`	number	Requests made in the current minute
`left`	number	Remaining requests in the current minute
`nextReset`	string	When the minute window resets (ISO 8601)

metadataobject

Request tracking information

Show child attributes

Field	Type	Description
`requestId`	string	Unique identifier for this request
`executionTimeMs`	number	Total execution time in milliseconds

Code examples

Code Examples

const response = await fetch("https://api.reversecontact.com/v2/enrich/persons", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "jane.doe@acme.com"
  })
});

const { data } = await response.json();
console.log(data.person.firstName, data.person.lastName, data.person.currentCompanyName);

curl -X POST https://api.reversecontact.com/v2/enrich/persons \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane.doe@acme.com"}'

import requests

response = requests.post(
    "https://api.reversecontact.com/v2/enrich/persons",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={"email": "jane.doe@acme.com"}
)

person = response.json()["data"]["person"]
print(person["firstName"], person["lastName"], person["currentCompanyName"])

Example response

200 - Success

Example Response

{
  "success": true,
  "data": {
    "person": {
      "id": "prs_9f8e7d6c5b4a",
      "firstName": "Jane",
      "lastName": "Doe",
      "publicId": "jane-doe",
      "memberId": "ACoAAB12345",
      "linkedinUrl": "https://www.social.com/in/jane-doe",
      "headline": "VP of Marketing @ Acme Corp | Demand Gen & Brand",
      "summary": "Experienced marketing leader with 15+ years driving growth for B2B SaaS companies. Passionate about data-driven strategies and building high-performing teams.",
      "pronoun": "she/her",
      "photoUrl": "https://media.licdn.com/dms/image/v2/D5603AQ.../profile-photo.jpg",
      "backgroundUrl": "https://media.licdn.com/dms/image/v2/D5616AQ.../background.jpg",
      "isOpenToWork": false,
      "hasPremium": true,
      "hasVerificationBadge": true,
      "isInRemembrance": false,
      "creationDate": "2009-03-15T00:00:00.000Z",
      "followersCount": 12480,
      "connectionsCount": 500,
      "location": {
        "city": "San Francisco",
        "state": "California",
        "country": "United States",
        "countryCode": "US",
        "rawLocation": "San Francisco Bay Area"
      },
      "currentPosition": {
        "title": "VP of Marketing",
        "description": "Leading a team of 25 marketers across demand gen, product marketing, and brand.",
        "contractType": "Full-time",
        "companyName": "Acme Corp",
        "companyLinkedinId": "12345678",
        "companyUrl": "https://www.social.com/company/acme-corp",
        "companyLocation": "San Francisco, CA",
        "companyLogoUrl": "https://media.licdn.com/dms/image/v2/C4D0BAQ.../logo.jpg",
        "startEndDate": {
          "start": "2021-06-01T00:00:00.000Z",
          "end": null
        }
      },
      "experience": [
        {
          "title": "VP of Marketing",
          "description": "Leading a team of 25 marketers across demand gen, product marketing, and brand.",
          "contractType": "Full-time",
          "companyName": "Acme Corp",
          "companyLinkedinId": "12345678",
          "companyUrl": "https://www.social.com/company/acme-corp",
          "companyLocation": "San Francisco, CA",
          "companyLogoUrl": "https://media.licdn.com/dms/image/v2/C4D0BAQ.../logo.jpg",
          "startEndDate": {
            "start": "2021-06-01T00:00:00.000Z",
            "end": null
          }
        },
        {
          "title": "Director of Marketing",
          "description": "Built the marketing function from scratch. Scaled from 0 to $5M ARR.",
          "contractType": "Full-time",
          "companyName": "Startup Inc",
          "companyLinkedinId": "98765432",
          "companyUrl": "https://www.social.com/company/startup-inc",
          "companyLocation": "Remote",
          "companyLogoUrl": null,
          "startEndDate": {
            "start": "2018-01-01T00:00:00.000Z",
            "end": "2021-05-31T00:00:00.000Z"
          }
        }
      ],
      "education": [
        {
          "degreeName": "MBA",
          "fieldOfStudy": "Marketing",
          "description": null,
          "grade": null,
          "schoolName": "Stanford Graduate School of Business",
          "schoolUrl": "https://www.social.com/school/stanford-gsb",
          "schoolLogoUrl": "https://media.licdn.com/dms/image/v2/C4D0BAQ.../logo.jpg",
          "startEndDate": {
            "start": "2012-09-01T00:00:00.000Z",
            "end": "2014-06-15T00:00:00.000Z"
          }
        }
      ],
      "skills": ["Marketing Strategy", "B2B SaaS", "Demand Generation", "Product Marketing"],
      "languages": [{ "language": "English", "proficiency": "Native or bilingual" }],
      "certifications": [],
      "recommendations": [],
      "testScores": [],
      "currentPositionTitle": "VP of Marketing",
      "currentCompanyId": "cmp_12345678",
      "currentCompanyName": "Acme Corp",
      "currentCompanyLinkedinId": "12345678",
      "updateDate": "2026-04-07T14:22:17.271Z"
    },
    "alternativePersons": [
      {
        "id": "prs_1a2b3c4d5e6f",
        "publicId": "jane-doe-marketing",
        "linkedinUrl": "https://www.social.com/in/jane-doe-marketing",
        "firstName": "Jane",
        "lastName": "Doe",
        "headline": "Marketing Manager @ Acme Corp Europe",
        "summary": "Brand and demand generation for Acme Corp in Europe.",
        "location": {
          "city": "London",
          "state": null,
          "country": "United Kingdom",
          "countryCode": "GB",
          "rawLocation": "London, England, United Kingdom"
        },
        "currentPosition": {
          "title": "Marketing Manager",
          "companyName": "Acme Corp Europe",
          "companyLinkedinId": "87654321"
        },
        "experience": [
          {
            "title": "Marketing Manager",
            "companyName": "Acme Corp Europe",
            "companyLinkedinId": "87654321"
          }
        ],
        "education": [],
        "skills": ["Demand Generation", "Brand Marketing"],
        "currentPositionTitle": "Marketing Manager",
        "currentCompanyId": null,
        "currentCompanyName": "Acme Corp Europe",
        "currentCompanyLinkedinId": "87654321",
        "updateDate": "2026-03-11T09:04:52.118Z"
      }
    ],
    "isFullProfile": true
  },
  "error": null,
  "metadata": {
    "requestId": "req_e1n2r3i4c5h6",
    "executionTimeMs": 1240
  },
  "quotas": {
    "creditsConsumed": 2,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4535,
        "left": 5465
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 8,
        "left": 52,
        "nextReset": "2025-01-20T14:16:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 8,
        "left": 52,
        "nextReset": "2025-01-20T14:16:00.000Z"
      }
    }
  }
}