# orbitreach API

The public API is scoped to the workspace that owns the API key. Workspace
admins can create and revoke keys in **Settings → API**. The secret is
displayed only once; store it in a password manager or environment variable.

Machine-readable spec: [https://orbitreach.io/openapi.json](https://orbitreach.io/openapi.json).
Interactive reference: [https://orbitreach.io/docs/api](https://orbitreach.io/docs/api).

## Authentication

Pass the key using a bearer token (recommended), or the `X-API-Key` header.

```bash
curl https://orbitreach.io/api/v1/tables \
  -H "Authorization: Bearer orb_your_api_key"
```

All endpoints return `401` for a missing, invalid, or revoked key. The API
never accepts browser sessions as authentication.

## Endpoints

| Method  | Path                        | Description                                                               |
| ------- | --------------------------- | ------------------------------------------------------------------------- |
| `GET`   | `/api/v1/tables`            | List active lead tables.                                                  |
| `POST`  | `/api/v1/tables`            | Create a lead table with `{ "name": "Prospects" }`.                       |
| `PATCH` | `/api/v1/tables/:id`        | Show or hide standard fields and add custom fields with a `fields` array. |
| `GET`   | `/api/v1/leads?tableId=123` | List workspace leads; `tableId` is optional.                              |
| `POST`  | `/api/v1/leads`             | Create or update leads by email.                                          |
| `POST`  | `/api/v1/local-leads`       | Preview or import local businesses from Google Places.                    |
| `POST`  | `/api/v1/email/verify`      | Verify one email address or an `emails` array.                            |
| `POST`  | `/api/v1/email/find`        | Find a person's business email from their name and company website.       |

## Leads

To import leads, send either one lead or `{ "tableId": 123, "leads": [...] }`.
An email address is required. `firstName`, `lastName`, `name`, `company`,
`role`, `website`, `linkedin`, `phone`, `address`, `rating`,
`customFields`, and `status` are optional. Custom values use the stable
field IDs returned by the tables endpoint, for example
`"customFields": { "custom_owner_email": "owner@example.com" }`. Valid
statuses are `new`, `ready`, `contacted`, `bounced`, `replied`,
`interested`, `not_interested`, and `meeting_booked`.

```bash
curl -X POST https://orbitreach.io/api/v1/leads \
  -H "Authorization: Bearer orb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"tableId":123,"leads":[{"email":"ada@example.com","firstName":"Ada","company":"Example Co"}]}'
```

Creating a lead with an email already in the same table updates that lead. Do
not put API keys in client-side code or source control; revoke a key
immediately if it may have been exposed.

## Local lead finder

Send a natural-language prompt to `/api/v1/local-leads`. Use
`mode: "search"` to preview results without changing a list:

```bash
curl -X POST https://orbitreach.io/api/v1/local-leads \
  -H "Authorization: Bearer orb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mode":"search","prompt":"5 restaurants in Lisbon with a rating 4+"}'
```

Omit `mode` to import. Supply either an existing `tableId` or a
`newTableName`:

```bash
curl -X POST https://orbitreach.io/api/v1/local-leads \
  -H "Authorization: Bearer orb_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"10 dentists in Austin rated 4.5+","newTableName":"Austin dentists"}'
```

The response includes the interpreted query and constraints, returned places,
import count, duplicate count, and destination list. Google Places returns
public business data, not email addresses or private employee contacts;
unavailable fields remain empty instead of being guessed.

When a result has a website, orbitreach may inspect its homepage, sitemap, and
a bounded set of public same-origin founder, team, legal, contact, and about
pages. The response can include `websiteResearch` with published emails,
phone links, social URLs, explicitly named people and roles, legal
identifiers, verbatim evidence, and source URLs. UK results can include
`registryResearch` from the official Companies House API; Serbian results
can include APR registry matches. No person, role, email, or phone number is
guessed.

## Errors and limits

- `400` — invalid input (the response `error` explains what to fix).
- `401` — missing, invalid, or revoked API key.
- `402` — the workspace has used all credits for the current month.
- `404` — the referenced resource (for example a lead table) was not found.

## More

- [MCP setup guide](https://orbitreach.io/docs/mcp.md)
- [Developer portal](https://orbitreach.io/developers)
- Support: support@orbitreach.io