Endpoints // Fetch

Profile status

Updated

Check if a company profile exists in the database before requesting enrichment.

POST/v2/fetch/companies/check

Introduction

The Company Profile Status endpoint verifies whether a company profile exists in our database and returns freshness information. Use it to check data availability before spending credits on a full fetch or a live pull.

When to use

A typical cost-optimized workflow looks like this:

Call Profile Status: get existence status, last update date, and specialty count.
If the company exists and is recent: use Profile (cached, 1 credit) to retrieve the full company profile.
If the company is stale or missing: use Profile live (fresh from Social, 2 credits) for an up-to-date result.

This simple check → fetch/live decision can save significant credits at scale.

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

Availability and freshness information (null on error responses)

Show child attributes

Field	Type	Description
`exists`	boolean	`true` if the company exists in the database
`lastUpdate`	string \| null	When ReverseContact last fetched this company from the source (ISO 8601). `null` when `exists` is `false`
`specialityCount`	number	Number of company specialties. Only present when `exists` is `true`

quotasobject

Credits and rate limit usage after this request

Show child attributes

Field	Type	Description
`creditsConsumed`	number	Credits consumed by this request. Always `0` for Profile Status

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

Code examples

Code Examples

curl -X POST https://api.reversecontact.com/v2/fetch/companies/check \
  -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/check", {
  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();
if (data.data.exists) {
  console.log(`Company exists, last updated ${data.data.lastUpdate}`);
} else {
  console.log("Company not in database yet");
}

import requests

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

data = response.json()
if data["data"]["exists"]:
    print(f"Company exists, last updated {data['data']['lastUpdate']}")
else:
    print("Company not in database yet")

Example response

Example Response

{
  "success": true,
  "data": {
    "exists": true,
    "lastUpdate": "2025-01-10T14:22:00.000Z",
    "specialityCount": 8
  },
  "error": null,
  "metadata": {
    "requestId": "req_e5f6g7h8i9j0",
    "executionTimeMs": 95
  },
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4521,
        "left": 5479
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 14,
        "left": 46,
        "nextReset": "2025-01-15T09:31:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 14,
        "left": 46,
        "nextReset": "2025-01-15T09:31:00.000Z"
      }
    }
  }
}

{
  "success": true,
  "data": {
    "exists": false,
    "lastUpdate": null
  },
  "error": null,
  "metadata": {
    "requestId": "req_f6g7h8i9j0k1",
    "executionTimeMs": 78
  },
  "quotas": {
    "creditsConsumed": 0,
    "workspace": {
      "id": "ws_abc123",
      "credits": {
        "total": 10000,
        "used": 4521,
        "left": 5479
      },
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 15,
        "left": 45,
        "nextReset": "2025-01-15T09:31:00.000Z"
      },
      "hasUnlimitedCredits": false,
      "allowDailyOvercost": false
    },
    "key": {
      "id": "key_abc123",
      "dailyLimit": null,
      "minuteRateLimit": {
        "limit": 60,
        "used": 15,
        "left": 45,
        "nextReset": "2025-01-15T09:31:00.000Z"
      }
    }
  }
}