Endpoints // Fetch

Profile

Updated

Retrieve a complete company profile from a Social company URL.

POST/v2/fetch/companies

Introduction

The Company Profile endpoint retrieves a complete company profile from a Social company URL. It returns structured data including basic information, metrics, headquarters, specialties, and more.

Authorization

Name	Type	Required	Description
`apikey`	string	Yes	Your API key from the developer dashboard. Pass it via `Authorization: Bearer YOUR_API_KEY` header.

Request body

Provide either url or id. If both are supplied, id takes precedence.

Name	Type	Required	Description
`url`	string	Conditional	Public Social company URL (e.g. `https://social.com/company/acme-corp`). Required unless `id` is given.
`id`	string	Conditional	ReverseContact company id from a previous response (e.g. `com_01jbd5vewyenebxgaz869ffe5t`). Required unless `url` is given.

Response structure

Field	Type	Description
`success`	boolean	`true` if the request was processed successfully
`error`	`null`	Always `null` on success

dataobject

The enriched company profile (null on error responses)

Show child attributes

Field	Type	Description
`id`	string	ReverseContact company id (`com_...`). Pass it back as the `id` request parameter 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
`locations`	Location	All office locations registered on the profile (can be empty)
`foundedOn`	FoundedOn \| null	Founding year wrapper
`phone`	string \| null	Phone number

headquarterobject

Headquarter location (null if unknown)

Show child attributes

Field	Type	Description
`street1`	string \| null	Primary street address line
`street2`	string \| null	Secondary street address line
`city`	string \| null	City
`country`	string \| null	Country (ISO code or name)
`geographicArea`	string \| null	State or region
`postalCode`	string \| null	Postal code

locationsobject[]

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

Show child attributes

Field	Type	Description
`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 employeesCount for the exact headcount when available.

Show child attributes

Field	Type	Description
`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 attributes

Field	Type	Description
`year`	number	Four-digit year

quotasobject

Credits and rate limit usage after this request

Show child attributes

Field	Type	Description
`creditsConsumed`	number	Credits consumed by this request

workspaceobject

Workspace-level limits

Show child attributes

Field	Type	Description
`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 attributes

Field	Type	Description
`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 attributes

Field	Type	Description
`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 attributes

Field	Type	Description
`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 attributes

Field	Type	Description
`id`	string	API key identifier

dailyLimitobject

Daily limit for this key (null if not configured)

Show child attributes

Field	Type	Description
`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 attributes

Field	Type	Description
`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 attributes

Field	Type	Description
`requestId`	string	Unique identifier for this request
`executionTimeMs`	number	Total execution time in milliseconds
`updatedAt`	string	Last upstream update timestamp (ISO 8601). Only present when data is from cache.

Code examples

Code Examples

curl -X POST https://api.reversecontact.com/v2/fetch/companies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://social.com/company/acme-corp"}'

const response = await fetch("https://api.reversecontact.com/v2/fetch/companies", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://social.com/company/acme-corp"
  })
});

const data = await response.json();
console.log(data.data.companyName, data.data.industry);

import requests

response = requests.post(
    "https://api.reversecontact.com/v2/fetch/companies",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={"url": "https://social.com/company/acme-corp"}
)

data = response.json()
print(data["data"]["companyName"], data["data"]["industry"])

Example response

200 - Success

Example Response

{
  "success": true,
  "data": {
    "id": "com_01jbd5vewyenebxgaz869ffe5t",
    "companyName": "Acme Corp",
    "linkedinId": "12345678",
    "publicId": "acme-corp",
    "linkedinUrl": "https://www.social.com/company/acme-corp",
    "websiteUrl": "https://www.acmecorp.com",
    "industry": "Software Development",
    "description": "Acme Corp is a leading provider of innovative SaaS solutions for enterprise teams. Founded in 2015, we serve over 10,000 customers worldwide.",
    "tagline": "Building the future of work",
    "logoUrl": "https://media.licdn.com/dms/image/v2/C4D0BAQ.../logo.jpg",
    "backgroundUrl": "https://media.licdn.com/dms/image/v2/D5616AQ.../background.jpg",
    "employeesCount": 450,
    "employeeCountRange": {
      "start": 201,
      "end": 500
    },
    "followersCount": 28500,
    "headquarter": {
      "street1": "1 Market Street",
      "street2": "Suite 400",
      "city": "San Francisco",
      "country": "US",
      "geographicArea": "California",
      "postalCode": "94105"
    },
    "specialities": [
      "SaaS",
      "Enterprise Software",
      "Cloud Computing",
      "Data Analytics",
      "API Integration"
    ],
    "locations": [
      {
        "street1": "1 Market Street",
        "street2": "Suite 400",
        "postalCode": "94105",
        "city": "San Francisco",
        "state": "California",
        "country": "US"
      },
      {
        "street1": "10 Queen Street",
        "street2": null,
        "postalCode": "EC4N 1TX",
        "city": "London",
        "state": null,
        "country": "GB"
      }
    ],
    "foundedOn": {
      "year": 2015
    },
    "phone": "+1 (415) 555-0123"
  },
  "error": null,
  "metadata": {
    "requestId": "req_x7y8z9a0b1c2",
    "executionTimeMs": 1850,
    "updatedAt": "2025-01-20T14:15:00.000Z"
  },
  "quotas": {
    "creditsConsumed": 1,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4521,
        "left": 5479
      },
      "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"
      }
    }
  }
}