Skip to content

Endpoints // Fetch

Profile live

Updated

Trigger a live fetch of a Social profile and retrieve results via polling or webhook callback.

POST/v2/fetch/persons/live

Introduction

The Person Profile Live endpoint triggers a real-time fetch of a Social profile. Instead of relying on cached data, it pulls a fresh copy and returns the result asynchronously.

Use this endpoint when you need the most up-to-date profile data and can wait for the async result. Retrieve the result via polling (recommended, no public endpoint required) or via a webhook callback (advanced, push delivery).

Authorization

NameTypeRequiredDescription
apikeystringYesYour API key from the developer dashboard. Pass it via Authorization: Bearer YOUR_API_KEY header.

Request body

NameTypeRequiredDescription
urlstringConditionalPublic Social profile URL (e.g. https://social.com/in/janedoe). Provide exactly one of url or id.
idstringConditionalReverseContact person id (prs_…). The gateway resolves it to the current Social public slug before starting the scrape.
webhookUrlstringOptionalHTTPS push URL for webhook delivery. Omit this field to retrieve the result via polling (recommended). See the Webhooks guide when you need push delivery.

Response structure

This endpoint replies immediately with a webhookId. You then have two ways to retrieve the actual result:

  1. Polling (recommended). Call GET /v2/webhooks/:webhookId until the status is succeeded. No webhook URL needed. See the Polling guide.
  2. Webhook callback (advanced). If you provided a webhookUrl (or a workspace default is configured), the gateway POSTs the person data to that URL once the fetch completes. See Webhook callback payload (advanced) below.
FieldTypeDescription
successbooleantrue if the job was created successfully
dataobject

Initial job acknowledgement. Save the webhookId to retrieve the result via polling (GET /v2/webhooks/:webhookId) or to correlate an upcoming webhook callback (null on error responses).

Show child attributes
FieldTypeDescription
statusstringJob status, always "created" for the initial response
webhookIdstringUnique identifier (UUID). Save it. Use it to poll the result at GET /v2/webhooks/:webhookId, or to correlate an incoming webhook callback.
pollUrlstringConvenience hint pointing to the polling endpoint for this job (e.g. /v2/webhooks/{webhookId}).
FieldTypeDescription
errornullAlways null on success
quotasobject

Credits and rate limit usage after this request

Show child attributes
FieldTypeDescription
creditsConsumednumberCredits consumed by this request
workspaceobject

Workspace-level limits

Show child attributes
FieldTypeDescription
idstringYour workspace identifier
hasUnlimitedCreditsbooleanWhether workspace credits are unlimited
allowDailyOvercostbooleanWhether the workspace may exceed its daily cap
creditsobject

Credit balance

Show child attributes
FieldTypeDescription
totalnumberTotal credits in your plan
usednumberCredits consumed so far
leftnumberRemaining credits
dailyLimitobject

Daily request limit (null if not configured)

Show child attributes
FieldTypeDescription
limitnumberMaximum requests per day
usednumberRequests made today
leftnumberRemaining requests today
nextResetstringWhen the daily window resets (ISO 8601)
minuteRateLimitobject

Per-minute rate limit

Show child attributes
FieldTypeDescription
limitnumberMaximum requests per minute
usednumberRequests made in the current minute
leftnumberRemaining requests in the current minute
nextResetstringWhen the minute window resets (ISO 8601)
keyobject

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

Show child attributes
FieldTypeDescription
idstringAPI key identifier
dailyLimitobject

Daily limit for this key (null if not configured)

Show child attributes
FieldTypeDescription
limitnumberMaximum requests per day
usednumberRequests made today
leftnumberRemaining requests today
nextResetstringWhen the daily window resets (ISO 8601)
minuteRateLimitobject

Minute rate limit for this key

Show child attributes
FieldTypeDescription
limitnumberMaximum requests per minute
usednumberRequests made in the current minute
leftnumberRemaining requests in the current minute
nextResetstringWhen the minute window resets (ISO 8601)
metadataobject

Request tracking information

Show child attributes
FieldTypeDescription
requestIdstringUnique identifier for this request
executionTimeMsnumberTotal execution time in milliseconds

Webhook callback payload (advanced)

Once the live fetch completes, the gateway POSTs a JSON payload to your webhookUrl. Use the webhookId from the initial response to correlate the callback with your original request.

The payload is not wrapped in an envelope (no success, error, metadata, or quotas keys at the top level, unlike the synchronous response).

FieldTypeDescription
webhookIdstringAlways present. The same identifier returned in the initial response. Use it to correlate the callback with the original request.
dataobject

Always present. On success: the enriched person profile (fields below). On failure: see Webhook callback errors (advanced).

Show child attributes
FieldTypeDescription
idstringReverseContact person id (prs_...). Use it as the id parameter of the Person Profile endpoint to re-fetch this profile
publicIdstringSocial public identifier (the /in/xxx slug)
memberIdstringSocial internal member ID
linkedinUrlstringFull Social profile URL
firstNamestring | nullFirst name
lastNamestring | nullLast name
headlinestring | nullProfile headline
summarystring | nullAbout / summary section
pronounstring | nullPreferred pronoun (e.g. "she/her", "he/him")
isOpenToWorkbooleanWhether the person is open to work
hasPremiumbooleanWhether the person has Social Premium
hasVerificationBadgebooleanWhether the profile is verified
isInRemembrancebooleanWhether the profile is memorialised
photoUrlstring | nullProfile photo URL
backgroundUrlstring | nullBackground / banner image URL
creationDatestring | nullAccount creation date (ISO 8601)
followersCountnumber | nullNumber of followers
connectionsCountnumber | nullNumber of connections
skillsstringList of skill names
locationobject

Geographic location

Show child attributes
FieldTypeDescription
citystring | nullCity name
statestring | nullState or region
countrystring | nullCountry name
countryCodestring | nullISO country code (e.g. "US")
rawLocationstring | nullRaw, unparsed location label
currentPositionobject

Current job position

Show child attributes
FieldTypeDescription
titlestring | nullJob title
descriptionstring | nullRole description
contractTypestring | nullContract type (e.g. "Permanent", "Contract")
companyNamestring | nullCompany name
companyLinkedinIdstring | nullCompany Social identifier
companyUrlstring | nullCompany Social profile URL
companyLocationstring | nullCompany location (city, region, country)
companyLogoUrlstring | nullCompany logo URL
startEndDateDateRange | nullPosition duration
startEndDateobject

Period boundaries

Show child attributes
FieldTypeDescription
startstring | nullStart date (ISO 8601)
endstring | nullEnd date (ISO 8601, null if ongoing)
experienceobject[]

Professional experiences

Show child attributes
FieldTypeDescription
titlestring | nullJob title
descriptionstring | nullRole description
contractTypestring | nullContract type (e.g. "Permanent", "Contract")
companyNamestring | nullCompany name
companyLinkedinIdstring | nullCompany Social identifier
companyUrlstring | nullCompany Social profile URL
companyLocationstring | nullCompany location (city, region, country)
companyLogoUrlstring | nullCompany logo URL
startEndDateDateRange | nullPosition duration
startEndDateobject

Period boundaries

Show child attributes
FieldTypeDescription
startstring | nullStart date (ISO 8601)
endstring | nullEnd date (ISO 8601, null if ongoing)
educationobject[]

Education history

Show child attributes
FieldTypeDescription
degreeNamestring | nullDegree name (e.g. "B.S.", "MBA")
fieldOfStudystring | nullField of study
descriptionstring | nullAdditional description
gradestring | nullGrade or honors
schoolNamestring | nullSchool name
schoolUrlstring | nullSchool Social profile URL
schoolLogoUrlstring | nullSchool logo URL
startEndDateDateRange | nullEducation period
startEndDateobject

Period boundaries

Show child attributes
FieldTypeDescription
startstring | nullStart date (ISO 8601)
endstring | nullEnd date (ISO 8601, null if ongoing)
languagesobject[]

Spoken languages

Show child attributes
FieldTypeDescription
languagestring | nullLanguage name
proficiencystring | nullProficiency level (e.g. "Native or bilingual", "Full professional")
recommendationsobject[]

Received recommendations

Show child attributes
FieldTypeDescription
captionstring | nullShort caption / role of the recommender
descriptionstring | nullRecommendation text
authorFullnamestring | nullFull name of the recommender
authorUrlstring | nullRecommender Social profile URL
certificationsobject[]

Professional certifications

Show child attributes
FieldTypeDescription
namestring | nullCertification name
organizationNamestring | nullIssuing organization name
organizationUrlstring | nullIssuing organization profile URL
issuedDatestring | nullIssue date (ISO 8601, may be null if unknown)
testScoresobject[]

Standardized test scores

Show child attributes
FieldTypeDescription
testTitlestring | nullTest name
scorestring | nullScore value
datestring | nullDate taken (ISO 8601)

Webhook callback errors (advanced)

When the live fetch fails, data does not contain the profile fields. Instead, it contains the original input echoed back together with an errorCode identifying the failure reason:

Webhook callback (error)

Error payload

{
  "webhookId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "data": {
    "url": "https://www.social.com/in/janedoe",
    "errorCode": "data-not-found"
  }
}

data.errorCode will be one of the following values:

CodeBilledDescription
person-not-foundYesThe person profile doesn't exist or could not be scraped
invalid-dataNoThe fetched data failed quality validation
fetch-data-errorNoThe API failed while fetching data. Safe to retry
result-unavailableNoThe enrichment completed but the result was lost on our side. Retry the job. If the request was charged, contact support to get the credit back.

Code examples

Code Examples

const KEY = "YOUR_API_KEY";
const BASE = "https://api.reversecontact.com";

const trigger = await fetch(`${BASE}/v2/fetch/persons/live`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ url: "https://social.com/in/janedoe" })
});
const { data: { webhookId } } = await trigger.json();

async function pollUntilDone(id) {
  while (true) {
    const res = await fetch(`${BASE}/v2/webhooks/${id}`, {
      headers: { "Authorization": `Bearer ${KEY}` }
    });
    const { data } = await res.json();
    if (data.status === "succeeded") return data.result;
    if (data.status === "errored")   throw new Error(data.errorCode ?? "Job failed");
    await new Promise(r => setTimeout(r, 2000));
  }
}

const result = await pollUntilDone(webhookId);
console.log(result);

Example response

Example Response

{
  "success": true,
  "data": {
    "status": "created",
    "webhookId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
    "pollUrl": "/v2/webhooks/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
  },
  "error": null,
  "metadata": {
    "requestId": "req_a1b2c3d4e5f6",
    "executionTimeMs": 120
  },
  "quotas": {
    "creditsConsumed": 2,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4523,
        "left": 5477
      },
      "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"
      }
    }
  }
}