Endpoints // Fetch

Profile

Updated

Retrieve a complete professional profile from a Social URL.

POST/v2/fetch/persons

Introduction

The Person Profile endpoint retrieves a complete professional profile from a Social URL. It returns structured data including work experience, education, skills, certifications, and more.

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

Provide either url or id. If both are supplied, id takes precedence.

Name	Type	Required	Description
`url`	string	Conditional	Public Social profile URL (e.g. `https://social.com/in/janedoe`). Required unless `id` is given.
`id`	string	Conditional	ReverseContact person id from a previous response (e.g. `prs_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given.

Response structure

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

dataobject

The enriched person profile (null on error responses)

Show child attributes

Field	Type	Description
`id`	string	ReverseContact person id (`prs_...`). Pass it back as the `id` request parameter to re-fetch this profile
`publicId`	string	Social public identifier (the `/in/xxx` slug)
`memberId`	string	Social internal member ID
`linkedinUrl`	string	Full Social 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
`skills`	string	List of skill names

locationobject

Geographic location

Show child attributes

Field	Type	Description
`city`	string \| null	City name
`state`	string \| null	State or region
`country`	string \| null	Country name
`countryCode`	string \| null	ISO country code (e.g. `"US"`)
`rawLocation`	string \| null	Raw, unparsed location label

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)

experienceobject[]

Professional experiences

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)

educationobject[]

Education history

Show child attributes

Field	Type	Description
`degreeName`	string \| null	Degree name (e.g. `"B.S."`)
`fieldOfStudy`	string \| null	Field of study
`description`	string \| null	Additional description
`grade`	string \| null	Reported grade
`schoolName`	string \| null	School name
`schoolUrl`	string \| null	School Social profile URL
`schoolLogoUrl`	string \| null	School logo URL
`startEndDate`	DateRange \| null	Education period

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)

languagesobject[]

Spoken languages

Show child attributes

Field	Type	Description
`language`	string \| null	Language name
`proficiency`	string \| null	Proficiency level (e.g. `"Native"`, `"Professional working"`)

certificationsobject[]

Professional certifications

Show child attributes

Field	Type	Description
`name`	string \| null	Certification name
`organizationName`	string \| null	Issuing organization
`organizationUrl`	string \| null	Organization Social profile URL
`issuedDate`	string \| null	Issue date (ISO 8601)

recommendationsobject[]

Received recommendations

Show child attributes

Field	Type	Description
`caption`	string \| null	Short caption / role of the recommender
`description`	string \| null	Recommendation text
`authorFullname`	string \| null	Full name of the recommender
`authorUrl`	string \| null	Recommender Social profile URL

testScoresobject[]

Standardized test scores

Show child attributes

Field	Type	Description
`testTitle`	string \| null	Test name
`score`	string \| null	Score value
`date`	string \| null	Date taken (ISO 8601)

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
`updatedAt`	string	Last upstream update timestamp (ISO 8601). Only present when data is from cache.

Code examples

Code Examples

curl -X POST https://api.reversecontact.com/v2/fetch/persons \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://social.com/in/janedoe"}'

const response = await fetch("https://api.reversecontact.com/v2/fetch/persons", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://social.com/in/janedoe"
  })
});

const data = await response.json();
console.log(data.data.firstName, data.data.lastName);

import requests

response = requests.post(
    "https://api.reversecontact.com/v2/fetch/persons",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={"url": "https://social.com/in/janedoe"}
)

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

Example response

200 - Success

Example Response

{
  "success": true,
  "data": {
    "id": "prs_01jbd5vewyenebxgaz869ffe5t",
    "publicId": "janedoe",
    "memberId": "ACoAAB12345",
    "linkedinUrl": "https://www.social.com/in/janedoe",
    "firstName": "Jane",
    "lastName": "Doe",
    "headline": "VP of Marketing at Acme Corp",
    "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",
    "isOpenToWork": false,
    "hasPremium": true,
    "hasVerificationBadge": true,
    "isInRemembrance": false,
    "photoUrl": "https://media.licdn.com/dms/image/v2/D5603AQ.../profile-photo.jpg",
    "backgroundUrl": "https://media.licdn.com/dms/image/v2/D5616AQ.../background.jpg",
    "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. Drove 140% pipeline growth YoY.",
      "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. Drove 140% pipeline growth YoY.",
        "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": "https://media.licdn.com/dms/image/v2/C560BAQ.../logo.jpg",
        "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",
      "Team Leadership",
      "Data Analytics",
      "Content Marketing",
      "SEO",
      "Account-Based Marketing"
    ],
    "languages": [
      {
        "language": "English",
        "proficiency": "Native or bilingual"
      },
      {
        "language": "French",
        "proficiency": "Professional working"
      }
    ],
    "certifications": [
      {
        "name": "Google Analytics Certified",
        "organizationName": "Google",
        "organizationUrl": "https://www.social.com/company/google",
        "issuedDate": "2023-02-01T00:00:00.000Z"
      }
    ],
    "recommendations": [
      {
        "caption": "CEO at Startup Inc",
        "description": "Jane is one of the most strategic marketers I've worked with. She has an incredible ability to turn data into actionable growth plans.",
        "authorFullname": "John Smith",
        "authorUrl": "https://www.social.com/in/johnsmith"
      }
    ],
    "testScores": []
  },
  "error": null,
  "metadata": {
    "requestId": "req_a1b2c3d4e5f6",
    "executionTimeMs": 2340,
    "updatedAt": "2025-01-15T09:30:00.000Z"
  },
  "quotas": {
    "creditsConsumed": 1,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4521,
        "left": 5479
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 12,
        "left": 48,
        "nextReset": "2025-01-15T09:31:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 12,
        "left": 48,
        "nextReset": "2025-01-15T09:31:00.000Z"
      }
    }
  }
}