Reverse Contact Reverse Contact
Sign Up

Profile live

11 min read

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

POST
Sign up to try

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).

Note

Async, not real-time. We aim to deliver each result in under 15 seconds, but it can take tens of minutes depending on conditions. Built to update databases and feed async pipelines, not to back a synchronous request a user is waiting on. See Polling for delivery details.

Important

Not available on the free trial. This endpoint requires an active pay-as-you-go balance or an Enterprise plan. Add credits to your workspace to unlock it, or contact sales to discuss Enterprise pricing.

Authorization

apikey string required
Your API key from the developer dashboard. Pass it via Authorization: Bearer YOUR_API_KEY header.

Request body

url string required
Public Social profile URL (e.g. https://social.com/in/janedoe)
webhookUrl string
HTTPS 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.
success boolean
true 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 attributesHide child attributes
status string
Job status, always "created" for the initial response
webhookId string
Unique identifier (UUID). Save it. Use it to poll the result at GET /v2/webhooks/:webhookId, or to correlate an incoming webhook callback.
pollUrl string
Convenience hint pointing to the polling endpoint for this job (e.g. /v2/webhooks/{webhookId}).
error null
Always null on success
quotasobject
Credits and rate limit usage after this request
Show child attributesHide child attributes
creditsConsumed number
Credits consumed by this request
workspaceobject
Workspace-level limits
Show child attributesHide child attributes
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 attributesHide child attributes
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 attributesHide child attributes
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 attributesHide child attributes
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 attributesHide child attributes
id string
API key identifier
dailyLimitobject
Daily limit for this key (null if not configured)
Show child attributesHide child attributes
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 attributesHide child attributes
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 attributesHide child attributes
requestId string
Unique identifier for this request
executionTimeMs number
Total 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).

webhookId string
Always 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 attributesHide child attributes
id string
ReverseContact person id (prs_...). Use it as the id parameter of the Person Profile endpoint 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 attributesHide child attributes
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

Note

When a profile lists several jobs, the current position is selected — and the experience and education lists are ordered — by fixed, predictable rules. See Current position and work history ordering.

currentPositionobject
Current job position
Show child attributesHide child attributes
title string | null
Job title
description string | null
Role description
contractType string | null
Contract type (e.g. "Permanent", "Contract")
companyName string | null
Company name
companyLinkedinId string | null
Company Social identifier
companyUrl string | null
Company Social profile URL
companyLocation string | null
Company location (city, region, country)
companyLogoUrl string | null
Company logo URL
startEndDate DateRange | null
Position duration
startEndDateobject
Period boundaries
Show child attributesHide child attributes
start string | null
Start date (ISO 8601)
end string | null
End date (ISO 8601, null if ongoing)
experienceobject[]
Professional experiences
Show child attributesHide child attributes
title string | null
Job title
description string | null
Role description
contractType string | null
Contract type (e.g. "Permanent", "Contract")
companyName string | null
Company name
companyLinkedinId string | null
Company Social identifier
companyUrl string | null
Company Social profile URL
companyLocation string | null
Company location (city, region, country)
companyLogoUrl string | null
Company logo URL
startEndDate DateRange | null
Position duration
startEndDateobject
Period boundaries
Show child attributesHide child attributes
start string | null
Start date (ISO 8601)
end string | null
End date (ISO 8601, null if ongoing)
educationobject[]
Education history
Show child attributesHide child attributes
degreeName string | null
Degree name (e.g. "B.S.", "MBA")
fieldOfStudy string | null
Field of study
description string | null
Additional description
grade string | null
Grade or honors
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 attributesHide child attributes
start string | null
Start date (ISO 8601)
end string | null
End date (ISO 8601, null if ongoing)
languagesobject[]
Spoken languages
Show child attributesHide child attributes
language string | null
Language name
proficiency string | null
Proficiency level (e.g. "Native or bilingual", "Full professional")
recommendationsobject[]
Received recommendations
Show child attributesHide child attributes
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
certificationsobject[]
Professional certifications
Show child attributesHide child attributes
name string | null
Certification name
organizationName string | null
Issuing organization name
organizationUrl string | null
Issuing organization profile URL
issuedDate string | null
Issue date (ISO 8601, may be null if unknown)
testScoresobject[]
Standardized test scores
Show child attributesHide child attributes
testTitle string | null
Test name
score string | null
Score value
date string | null
Date 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:

Error payload
Webhook callback (error)
{
  "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:

Code Billed Description
person-not-found Yes The person profile doesn’t exist or could not be scraped
invalid-data No The fetched data failed quality validation
fetch-data-error No The API failed while fetching data. Safe to retry
result-unavailable No The 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.

Note

Billed means the credits consumed at request time are kept. Not billed means the credits are fully refunded to your workspace balance.

Previous

Profile

Next

Profile status