Can I fetch a company from a Social company page URL?

Send url to POST /v2/fetch/companies for the cached profile. Company profile costs 1 credit when found and returns the company directly in data.

Use cases // Find & enrich

Find a company from a domain or a page URL

Q: How do I find a company profile from a domain with the API?

Send domain to POST /v2/enrich/companies. Enrich company returns the profile in data.company and costs 2 credits when a company is found. An unmatched lookup is free.

Q: Is a company live lookup free when the company is not found?

No. A company-not-found failure from Company profile live remains billed at 2 credits. A 404 from cached Company profile or Enrich company is free.

New

Last verified November 4, 2026

Find a company profile from a domain or Social company page URL with the API. Compare cached and live data, credit costs and SDK examples.

You have

acme.comcompany domain for Enrich

Company page URL or idfor Fetch

The API

Enrich company
POST /v2/enrich/companies
sync response
Company profile
POST /v2/fetch/companies
sync response
Company profile live
POST /v2/fetch/companies/live
async job

You get

Acme CorpIndustry · size · location

credits when Enrich finds a company: 2
credit when Fetch finds a cached company: 1
credits per live request, at job creation: 2

Find a company profile from a domain or Social company page URL, including industry and employee information. Enrich and cached Fetch return the profile immediately. Use Live to retrieve a fresh profile in the background.

Build it with an AI coding agent

Paste this prompt into Claude Code, Codex or Cursor.

Implement this in my project with the Reverse Contact API: find a company from a domain or a page URL.

Read these pages first and follow them over what you remember about the API:
- The guide for this use case: https://docs.reversecontact.com/use-cases/find-a-company.md
- Enrich company: https://docs.reversecontact.com/endpoints/enrich-company.md
- Company profile: https://docs.reversecontact.com/endpoints/fetch-company.md
- Company profile live: https://docs.reversecontact.com/endpoints/fetch-company-live.md
- Errors and retries: https://docs.reversecontact.com/guides/errors-retries.md
- Async results (polling): https://docs.reversecontact.com/guides/polling.md
The index of the whole documentation is https://docs.reversecontact.com/llms.txt.

Requirements:
- Use the official SDK if this project is in TypeScript, JavaScript or Python (https://docs.reversecontact.com/sdk/javascript.md, https://docs.reversecontact.com/sdk/python.md). Otherwise call the REST API.
- Read the API key from the RC_API_KEY environment variable. Keep it server-side. Never hard-code or log it.
- Company profile live is asynchronous: it returns a job. Poll the job or receive a webhook, as the polling guide explains.
- Credits:
  - Enrich company: 2 credits when a company is found, full profile included. A 404 is free.
  - Company profile: 1 credit when the company is found in the cache. A 404 is free.
  - Company profile live: 2 credits per request, consumed when the job is created.
- Write tests that mock the API with the example responses of the reference pages. Tests must not spend credits.

When you are done, list the endpoints the code calls, what each call costs, and how to run it.

Which endpoint

Input you have	Endpoint	Cost	Mode
Company domain	Enrich company	2 credits when found. A 404 is free	Synchronous
Company page URL or company id	Company profile	1 credit when found in the cache. A 404 is free	Synchronous
Company page URL or company id, with a stale or missing cache	Company profile live	2 credits when the job is created	Asynchronous

How it works

Set RC_API_KEY to your API key. Install the TypeScript SDK, Python SDK or CLI for your chosen example. The cURL live example also uses jq. Choose either the domain lookup or the page URL fetch, depending on your input.

Find the company behind a domain

Send a bare domain or a full website URL as domain to Enrich company. Read the profile from data.company before saving the result. If no company matches, handle the HTTP 404 response, or null / None in the SDKs.

Remembered on every page

Code Examples

curl --fail-with-body -sS -X POST https://api.reversecontact.com/v2/enrich/companies \
  -H "Authorization: Bearer $RC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "acme.com"}'

import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

const result = await client.enrich.company({ domain: "acme.com" });
if (result === null) {
  console.log("No company found: nothing was charged");
} else {
  console.log(result.data.company?.name, result.data.company?.industry);
}

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    result = client.enrich.company(domain="acme.com")
    if result is None:
        print("No company found: nothing was charged")
    elif result.data is not None and result.data.company is not None:
        print(result.data.company.name, result.data.company.industry)

rc enrich company --domain acme.com

Fetch a company page you already know

When you have the company page URL, fetch the cached profile and read data.companyName, data.industry and data.employeesCount. You can send the company id from an earlier response instead of url.

Remembered on every page

Code Examples

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

import ReverseContact from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

const result = await client.fetch.company({ url: "https://www.social.com/company/acme-corp" });
if (result === null) {
  console.log("Company not found: nothing was charged");
} else {
  console.log(result.data.companyName, result.data.industry);
}

import os

from reversecontact import ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    result = client.fetch.company(url="https://www.social.com/company/acme-corp")
    if result is None:
        print("Company not found: nothing was charged")
    elif result.data is not None:
        print(result.data.company_name, result.data.industry)

rc fetch company --url https://www.social.com/company/acme-corp

Refresh the company when the cache is too old

You can use Live for a stale or missing company profile. To decide based on the profile's age, check freshness first. Save the job id, then poll for the company profile in data.result.

Remembered on every page

Code Examples

curl --fail-with-body -sS -X POST https://api.reversecontact.com/v2/fetch/companies/live \
  -H "Authorization: Bearer $RC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.social.com/company/acme-corp"}' > live-job.json
WEBHOOK_ID=$(jq -er .data.webhookId live-job.json)
printf 'Save this job id: %s\n' "$WEBHOOK_ID"

while :; do
  result=$(curl --fail-with-body -sS --max-time 30 \
    "https://api.reversecontact.com/v2/webhooks/$WEBHOOK_ID?wait=20" \
    -H "Authorization: Bearer $RC_API_KEY") || break
  case "$(printf '%s' "$result" | jq -r '.data.status')" in
    succeeded) printf '%s' "$result" | jq '.data.result'; break ;;
    errored) printf '%s' "$result" | jq '.data | {errorCode, creditsConsumed}'; break ;;
    created|in_progress) sleep 2 ;;
    *) printf '%s\n' "$result"; break ;;
  esac
done

import ReverseContact, { JobFailedError } from "@reverse-contact/sdk";

const client = new ReverseContact({ apiKey: process.env.RC_API_KEY });

const job = await client.fetch.companyLive({ url: "https://www.social.com/company/acme-corp" });
console.log("Save this job id:", job.id); // resume after a restart with client.jobs.wait(id)

try {
  // Long polls until the job ends, 30 minutes at most by default.
  const done = await job.wait();
  console.log(done.data.result?.companyName, done.data.result?.industry);
} catch (error) {
  if (error instanceof JobFailedError) console.log("Job failed:", error.errorCode, "credits:", error.creditsConsumed);
  else throw error;
}

import os

from reversecontact import JobFailedError, ReverseContact

with ReverseContact(api_key=os.environ["RC_API_KEY"]) as client:
    job = client.fetch.company_live(url="https://www.social.com/company/acme-corp")
    print("Save this job id:", job.id)  # resume after a restart with client.jobs.wait(id)

    try:
        # Long polls until the job ends, 30 minutes at most by default.
        done = job.wait()
        company = done.data.result if done.data else None
        if company is not None:
            print(company.company_name, company.industry)
    except JobFailedError as error:
        print("Job failed:", error.error_code)

rc fetch company --url https://www.social.com/company/acme-corp --live --wait --timeout 300

What it costs

Enrich company costs 2 credits when a company is found, with the full profile included. Company profile costs 1 credit when the company is found in the cache. A 404 from either synchronous lookup is free.

Company profile live consumes 2 credits per request when the job is created. A company-not-found failure remains billed. Failures with invalid-data or fetch-data-error are refunded. The live failure rules describe the other outcomes. Polling costs nothing.

Good to know

Enrich returns data.company and data.isFullProfile. Cached Fetch returns the company directly in data. If Enrich returns a light profile, data.isFullProfile is false and the request still costs 2 credits. A separate cached fetch can complete the profile for 1 additional credit when found.

Use employeesCount for the exact headcount when available. The employeeCountRange field gives a size bracket. Treat missing values as unknown, as described in Missing and empty profile fields.

Live jobs can take tens of minutes. Use polling, or pass webhookUrl for optional webhook delivery. Resume a saved job with client.jobs.wait(jobId) or rc task after a timeout instead of starting a new paid refresh.

FAQ

How do I find a company profile from a domain with the API?

Send domain to POST /v2/enrich/companies. Enrich company returns the profile in data.company and costs 2 credits when a company is found. An unmatched lookup is free.

When should I use Company profile live?

Use Company profile live when the cached profile is stale or missing. A live refresh consumes 2 credits when the job is created and returns the fresh company asynchronously through polling or a webhook.

Is a company live lookup free when the company is not found?

No. A company-not-found failure from Company profile live remains billed at 2 credits. A 404 from cached Company profile or Enrich company is free.