Getting started

Before you begin

Create an account. Sign up if you don’t have one yet
Generate an API key. Open Workspace > API Keys, create a new key, copy and keep it secure.
Have a LinkedIn URL ready, e.g. https://www.social.com/in/janedoe

See Authentication for more details on API keys and permissions.

1. Make your first request

All endpoints are served from https://api.reversecontact.com/v2/. Here is a quick example:

POST /v2/fetch/persons

const response = await fetch("https://api.reversecontact.com/v2/fetch/persons", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.RC_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://www.social.com/in/janedoe"
  })
});

const result = await response.json();
console.log(result.data.firstName, result.data.lastName);

curl -X POST https://api.reversecontact.com/v2/fetch/persons \
  -H "Authorization: Bearer ${RC_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.social.com/in/janedoe"}'

import os
import requests

response = requests.post(
    "https://api.reversecontact.com/v2/fetch/persons",
    headers={
        "Authorization": f"Bearer {os.environ['RC_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={"url": "https://www.social.com/in/janedoe"}
)

result = response.json()
print(result["data"]["firstName"], result["data"]["lastName"])

Tip

Want to test without writing code? Try the API Playground to run requests directly from your browser.

2. Read the response

Every API response follows the same structure. Here is what you get back:

Field	Description
`success`	`true` if the request succeeded
`data`	The returned object for this endpoint
`error`	Error details if something went wrong, `null` on success
`metadata`	Request ID and execution time, useful for debugging
`quotas`	Your remaining credits and rate limit status

See API reference for the full response format, metadata, quotas, and shared types.

3. Need real-time data? Use the live endpoints

The live and contact endpoints fetch fresh data asynchronously. They reply immediately with a webhookId, then deliver the actual result once it’s ready, usually within seconds.

Important

Async, not synchronous. We aim to deliver each result in under 15 seconds, but it can take tens of minutes depending on conditions. Live endpoints are built to update databases and feed async pipelines, not to block a synchronous, real-time request a user is waiting on.

The simplest way to retrieve that result is polling: trigger the job, then call GET /v2/webhooks/:webhookId until the status is succeeded. No public endpoint, no receiver to build.

Trigger + poll

const KEY = "YOUR_API_KEY";
const BASE = "https://api.reversecontact.com";

const trigger = await fetch(`${BASE}/v2/fetch/persons/live`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ url: "https://social.com/in/janedoe" })
});
const { data: { webhookId } } = await trigger.json();

while (true) {
  const res = await fetch(`${BASE}/v2/webhooks/${webhookId}`, {
    headers: { "Authorization": `Bearer ${KEY}` }
  });
  const { data } = await res.json();
  if (data.status === "succeeded") { console.log(data.result); break; }
  if (data.status === "errored")   throw new Error(data.errorCode ?? "Job failed");
  await new Promise(r => setTimeout(r, 2000));
}

KEY="YOUR_API_KEY"
ID=$(curl -sX POST https://api.reversecontact.com/v2/fetch/persons/live \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://social.com/in/janedoe"}' | jq -r .data.webhookId)

while :; do
  S=$(curl -s https://api.reversecontact.com/v2/webhooks/$ID \
    -H "Authorization: Bearer $KEY" | jq -r .data.status)
  [ "$S" = "succeeded" ] && break
  [ "$S" = "errored" ] && echo "job failed" && exit 1
  sleep 2
done

curl -s https://api.reversecontact.com/v2/webhooks/$ID \
  -H "Authorization: Bearer $KEY" | jq .data.result

Tip

Polling is the simplest way to use live endpoints. No webhook receiver required, free to call, off the rate-limit clock.

See the Polling guide for the full integration walkthrough, comparison with webhooks, status codes, polling frequency, and retention details.