> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Create a key, find a person, and list who they know.

**1. Create an API key**

Open [API keys](https://platform.orbb.com/console/keys) in the console and create one. It starts `orbb_sk_` and is shown **once** — copy it somewhere safe.

```bash theme={"system"}
export ORBB_API_KEY="orbb_sk_..."
```

Your first key also opens your billing account. Every key on the account shares one balance, one set of jobs and one set of [rate limits](https://docs.orbb.com/api/rate-limits.md).

**2. Find the person**

Most of what you hold about a person is an email or a name and a company. [`/v1/resolve`](https://docs.orbb.com/api-reference/resolve) turns that into the id every other call takes.

```bash theme={"system"}
curl https://api.orbb.com/v1/resolve \
  -H "Authorization: Bearer $ORBB_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 60 \
  -d '{"full_name": "Maya Okafor", "company": "Northwind Labs"}'
```

```json theme={"system"}
{
  "resolution": { "status": "RESOLVED", "method": "NAME_COMPANY" },
  "person": {
    "key": "maya-okafor",
    "publicId": "maya-okafor",
    "full_name": "Maya Okafor",
    "role": "VP Engineering",
    "company": "Northwind Labs"
  }
}
```

`person.publicId` is the id. Check `resolution.status` before using it — a person who cannot be identified is a `200` with `UNRESOLVED`, and several matches is `AMBIGUOUS` with `candidates`. Neither is an error. See [People and ids](https://docs.orbb.com/concepts/people.md).

> [!WARNING]
>
> Keep `Content-Type: application/json`. Without it, curl sends the body as a form field and the API answers `400 invalid_body`.

**3. List who they know**

```bash theme={"system"}
curl https://api.orbb.com/v1/circle \
  -H "Authorization: Bearer $ORBB_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 60 \
  -d '{"id": "maya-okafor", "limit": 5}'
```

Each entry in `data` is a person, a **verdict** (`LIKELY_KNOW`, `POSSIBLE`, …), a **strength** from 0 to 1, and the **evidence**: the employer they shared and when, the comment one left on the other's post. The top-level `coverage` says which kinds of evidence were examined and which were not. See [Relationships](https://docs.orbb.com/concepts/relationships.md).

More people than `limit`? Pass `next_cursor` back as `cursor` with the same body.

**4. Handle a 202**

Resolve, circle, edge and paths start a **job**. If the answer is ready within 30 seconds you get it straight back; otherwise you get `202` and a job id:

```json theme={"system"}
{ "job": { "id": "qry_6720f0c2a1b2c3d4e5f60718", "status": "PROCESSING" } }
```

Poll [`/v1/job`](https://docs.orbb.com/api-reference/job) with that id — every 3 seconds for the first 10 polls, then every 10 — until it answers with what the original call would have. Set your client timeout to **at least 60 seconds**: a client that gives up first never sees the id, and sending the call again starts, and pays for, a new job.

> [accordion] A polling loop in Python
>
> ```python theme={"system"}
> import os, random, time, requests
>
> API = "https://api.orbb.com/v1"
> HEADERS = {"Authorization": f"Bearer {os.environ['ORBB_API_KEY']}"}
>
> def post(path, body):
>     # A 429 reserves and charges nothing, so the same request is safe to repeat.
>     while True:
>         res = requests.post(f"{API}/{path}", json=body, headers=HEADERS, timeout=60)
>         if res.status_code != 429:
>             return res
>         time.sleep(int(res.headers["Retry-After"]) + random.random())
>
> def call(path, body):
>     res = post(path, body)
>     polls = 0
>     while res.status_code == 202 or (polls and res.status_code == 503):
>         # A 503 on a poll means the state could not be read, not that the job failed.
>         time.sleep(3 if polls < 10 else 10)
>         polls += 1
>         if res.status_code == 202:
>             job_id = res.json()["job"]["id"]
>         res = post("job", {"id": job_id})
>     res.raise_for_status()
>     answer = res.json()
>     if answer.get("job", {}).get("status") == "FAILED":
>         raise RuntimeError(f"job {answer['job']['id']} failed; send the original call again")
>     return answer
>
> circle = call("circle", {"id": "maya-okafor", "limit": 5})
> for entry in circle["data"]:
>     print(entry["person"]["full_name"], entry["verdict"], entry.get("strength", {}).get("label"))
> ```

The full rules, including what `410` and `503` on a poll mean, are in [Jobs](https://docs.orbb.com/api/jobs.md).

## Next

> [card] [Find an introduction](https://docs.orbb.com/api-reference/paths.md)
>
> `/v1/paths` lists who could introduce you to a person, strongest first.

> [card] [Unknown is not no](https://docs.orbb.com/concepts/unknowns.md)
>
> What `coverage` and `on_miss` mean, and how to ask Orbb to research what it has not examined.

> [!NOTE]
>
> Examples on this site use fictional people and companies.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.