Skip to content

Endpoints // Fetch

Profile live

Updated

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

POST/v2/fetch/companies/live

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

Authorization

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

Request body

NameTypeRequiredDescription
urlstringConditionalPublic Social company URL (e.g. https://social.com/company/acme-corp). Provide exactly one of url or id.
idstringConditionalReverseContact company id (com_…). 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 company 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 company profile (fields below). On failure: see Webhook callback errors (advanced).

Show child attributes
FieldTypeDescription
idstringReverseContact company id (com_...). Use it as the id parameter of the Company Profile endpoint to re-fetch this company
companyNamestringCompany name
linkedinIdstringSocial company identifier
publicIdstringUniversal name / slug (the /company/xxx part of the URL)
linkedinUrlstring | nullFull Social company URL
websiteUrlstring | nullOfficial company website URL
industrystring | nullIndustry (e.g. "Software Development")
descriptionstring | nullFull company description
taglinestring | nullTagline / slogan
logoUrlstring | nullLogo image URL
backgroundUrlstring | nullBackground / banner image URL
employeesCountnumber | nullExact number of employees
employeeCountRangeEmployeeCountRange | nullEmployee count range bracket
followersCountnumber | nullNumber of Social followers
specialitiesstringList of company specialties. Empty array if none
foundedOnFoundedOn | nullFounding year wrapper
phonestring | nullPhone number
headquarterobject

Primary headquarter location (null if unknown)

Show child attributes
FieldTypeDescription
street1string | nullStreet address line 1
street2string | nullStreet address line 2
postalCodestring | nullPostal / ZIP code
citystring | nullCity
geographicAreastring | nullState or region
countrystring | nullCountry ISO 3166 code (e.g. "US", "FR")
locationsobject[]

All office locations registered on the profile (can be empty)

Show child attributes
FieldTypeDescription
street1string | nullStreet address line 1
street2string | nullStreet address line 2
postalCodestring | nullPostal / ZIP code
citystring | nullCity
statestring | nullState or region (named state here, not geographicArea as in headquarter)
countrystring | nullCountry 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 attributes
FieldTypeDescription
startnumberLower bound of the range
endnumberUpper 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 attributes
FieldTypeDescription
yearnumberFour-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:

Webhook callback (error)

Error payload

{
  "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:

CodeBilledDescription
company-not-foundYesThe company 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("https://api.reversecontact.com/v2/fetch/companies/live", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://social.com/company/acme-corp"
  })
});
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": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
    "pollUrl": "/v2/webhooks/b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
  },
  "error": null,
  "metadata": {
    "requestId": "req_d4e5f6a7b8c9",
    "executionTimeMs": 95
  },
  "quotas": {
    "creditsConsumed": 2,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4524,
        "left": 5476
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2025-01-20T14:16:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 5,
        "left": 55,
        "nextReset": "2025-01-20T14:16:00.000Z"
      }
    }
  }
}