Reverse Contact Reverse Contact
Sign Up

Profile live

9 min read

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

POST
Sign up to try

Introduction

The Company Profile Live endpoint triggers a real-time fetch of a Social company 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 company 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 company URL (e.g. https://social.com/company/acme-corp)
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 company 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 company profile (fields below). On failure: see Webhook callback errors (advanced).
Show child attributesHide child attributes
id string
ReverseContact company id (com_...). Use it as the id parameter of the Company Profile endpoint to re-fetch this company
companyName string
Company name
linkedinId string
Social company identifier
publicId string
Universal name / slug (the /company/xxx part of the URL)
linkedinUrl string | null
Full Social company URL
websiteUrl string | null
Official company website URL
industry string | null
Industry (e.g. "Software Development")
description string | null
Full company description
tagline string | null
Tagline / slogan
logoUrl string | null
Logo image URL
backgroundUrl string | null
Background / banner image URL
employeesCount number | null
Exact number of employees
employeeCountRange EmployeeCountRange | null
Employee count range bracket
followersCount number | null
Number of Social followers
specialities string[]
List of company specialties. Empty array if none
foundedOn FoundedOn | null
Founding year wrapper
phone string | null
Phone number
headquarterobject
Primary headquarter location (null if unknown)
Show child attributesHide child attributes
street1 string | null
Street address line 1
street2 string | null
Street address line 2
postalCode string | null
Postal / ZIP code
city string | null
City
geographicArea string | null
State or region
country string | null
Country ISO 3166 code (e.g. "US", "FR")
locationsobject[]
All office locations registered on the profile (can be empty)
Show child attributesHide child attributes
street1 string | null
Street address line 1
street2 string | null
Street address line 2
postalCode string | null
Postal / ZIP code
city string | null
City
state string | null
State or region (named state here, not geographicArea as in headquarter)
country string | null
Country ISO 3166 code (e.g. "US", "FR")
employeeCountRangeobject
Employee count bracket (null if unknown). Buckets mirror LinkedIn’s native staffCountRange: 1, 2–10, 11–50, 51–200, 201–500, 501–1,000, 1,001–5,000, 5,001–10,000, 10,001+. For the top bucket (10,001+), LinkedIn has no upper bound and returns end: 1 as a sentinel — interpret any range where end < start as start+ (unbounded). Use employeeCount for the exact headcount when available.
Show child attributesHide child attributes
start number
Lower bound of the range
end number
Upper bound of the range. If end < start, the bucket is unbounded (start+, i.e. 10,001+)

Example (10,001+ bucket): { "start": 10001, "end": 1 }. Since end (1) < start (10001), this means the company has 10,001 or more employees. No upper bound is available for this bucket.

foundedOnobject
Founding year (null if unknown)
Show child attributesHide child attributes
year number
Four-digit year

Webhook callback errors (advanced)

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

Error payload
Webhook callback (error)
{
  "webhookId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "data": {
    "url": "https://www.social.com/company/acme-corp",
    "errorCode": "company-not-found"
  }
}

data.errorCode will be one of the following values:

Code Billed Description
company-not-found Yes The company 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