Integration guides

Your first API call

New

Send your first enrichment request and parse the response.

You have your API key ready. Let's make your first profile enrichment call and inspect the result.

1. Send the request

The Person Profile endpoint retrieves a complete professional profile from a Social URL. It costs 1 credit (cached data).

POST /v2/fetch/persons

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

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

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

import os
import requests

response = requests.post(
    "https://api.reversecontact.com/v2/fetch/persons",
    headers={
        "Authorization": f"Bearer {os.environ['RC_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={"url": "https://www.social.com/in/janedoe"}
)

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

2. Read the response

A successful response returns the full profile inside data:

Response

200 OK

{
  "success": true,
  "data": {
    "id": "prs_01jbd5vewyenebxgaz869ffe5t",
    "publicId": "janedoe",
    "firstName": "Jane",
    "lastName": "Doe",
    "headline": "VP of Marketing at Acme Corp",
    "photoUrl": "https://media.licdn.com/dms/image/...",
    "isOpenToWork": false,
    "location": {
      "city": "San Francisco",
      "country": "United States"
    },
    "currentPosition": {
      "title": "VP of Marketing",
      "companyName": "Acme Corp"
    },
    "experience": [
      {
        "title": "VP of Marketing",
        "companyName": "Acme Corp",
        "startEndDate": { "start": "2021-06-01T00:00:00.000Z", "end": null }
      }
    ],
    "skills": ["Marketing Strategy", "B2B SaaS", "Demand Generation"]
  },
  "error": null,
  "quotas": {
    "creditsConsumed": 1,
    "workspace": {
      "credits": { "total": 10000, "used": 1, "left": 9999 }
    }
  },
  "metadata": {
    "requestId": "a1b2c3d4-e5f6-4a90-abcd-ef1234567890",
    "executionTimeMs": 230
  }
}

Start with these key fields:

Field	What it gives you
`data.firstName` / `data.lastName`	Full name
`data.headline`	Current role summary
`data.currentPosition`	Job title + company (how it is chosen)
`data.experience`	Full work history with dates
`data.skills`	List of professional skills
`data.location`	City, state, country

See the Person Profile endpoint for all available fields, and API reference for the full response structure.

3. Handle errors

If the URL is invalid, you get a 422 with zero credits charged:

Invalid URL

422 Validation Error

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_LINKEDIN_URL",
    "message": "Invalid LinkedIn profile URL. Expected format: https://linkedin.com/in/username"
  }
}

Issue	Fix
Invalid LinkedIn URL	Use the full URL: `https://www.linkedin.com/in/username`
`401` Unauthorized	Check your API key. See Authentication
`402` Insufficient credits	Purchase more credits from the dashboard
`404` Not found	The profile doesn't exist or isn't indexed yet. Try the Live endpoint

For all error codes and retry strategies, see Error handling & retries.