> For the complete documentation index, see [llms.txt](https://docs.rox.com/development/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rox.com/development/admin-guide/api-access.md).

# API Access

Use the Rox API to enrich companies and people, find prospects, and validate whether they match your criteria.

The Rox API lets you use enrichment and prospecting in your own applications and workflows. An Organization Admin creates an API key in Rox. Enrichment requests use the authenticated organization's enrichment waterfall, which determines the providers used to find data.

The API is in public alpha. This page covers key creation and the main workflows. For authentication details, complete request and response schemas, and endpoint requirements, see the [API reference](https://public-api.rox.com/v0/redoc).

### What you can do

| Action               | Endpoint                   | What it does                                                             |
| -------------------- | -------------------------- | ------------------------------------------------------------------------ |
| Enrich a company     | `POST /enrich/company`     | Find company information using your organization's enrichment waterfall. |
| Enrich a person      | `POST /enrich/person`      | Find profile information, email addresses, or phone numbers.             |
| Search for prospects | `POST /prospects/search`   | Build a candidate pool from a natural-language description.              |
| Validate prospects   | `POST /prospects/validate` | Check current employment and assess candidates against your criteria.    |

Search returns candidates that still need to be validated. For prospecting, search first, validate the returned candidates, then enrich the people whose verdict is `matched`.

### Create an API key

You need the Admin role in your Rox organization to create a key.

1. Open **Settings → Access → API keys**.
2. Create a new API key.
3. Enter a **Description** that identifies its purpose, such as “Prospect enrichment,” and choose an **Expiration**.
4. Click **Create**.
5. Copy the generated key and store it securely, such as in a password manager.

The key is shown only once after creation. Store it before closing the dialog.

### Connect to the API

The base URL is:

```
<https://public-api.rox.com/v0>
```

Append the endpoint path to this URL. For example, company enrichment uses `https://public-api.rox.com/v0/enrich/company`.

Requests use API key authentication and JSON request bodies. Follow the authentication instructions in the [API reference](https://public-api.rox.com/v0/redoc) when configuring your client.

### Enrich companies and people

Enrichment uses your organization's configured waterfall. To change it, open **Settings → Features → Enrichment**.

For company enrichment, the request supports `company_domain`, `company_name`, and `company_linkedin_url`. For people, supported identifiers include email, LinkedIn URL, name, and current company information. See the API reference for the input requirements for each endpoint.

Person enrichment defaults to profile data. To request email addresses as well, include this `targets` object in the request:

```
{
  "targets": {
    "profile": {},
    "email": {}
  }
}
```

To also request phone numbers, add `"phone": {}` inside `targets`.

If you provide `company_domain` when requesting an email address, the returned address must belong to that company. Otherwise, the email result is `not_found`.

Enrichment responses include `results`, `credits_used`, and failure information. Check the returned data and any failure details before using the result. An HTTP `201` response alone does not establish that the requested enrichment data was found.

### Find and validate prospects

#### 1. Search for candidates

Call `POST /prospects/search` in prompt mode. Describe who you want to find using `prompt`, and set `target_limit` to size the candidate pool.

Example request body:

```
{
  "prompt": "VPs of Engineering currently at Datadog",
  "target_limit": 25
}
```

`target_limit` accepts values from 1 to 50 and defaults to 25. Search can return up to five times that value. A limit of 25 can therefore return up to 125 candidates; it does not mean 25 validated matches.

To restrict the search to specific Rox accounts, provide `rox_company_ids`. These IDs override company names in the prompt. Salesforce IDs are not accepted.

Review the response's `completion` value:

| Value                      | Meaning                                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------------------- |
| `complete`                 | The candidate pool was filled. Narrow constraints, such as a city, may have been relaxed to fill it. |
| `incomplete_agent_stopped` | The prompt's constraints were maintained, but fewer candidates were found.                           |

#### 2. Validate the candidates

Call `POST /prospects/validate` with the `prospects` returned by search. Copy each candidate as returned, including `experience` and `source_updated_at`, and pass the same `prompt` so validation checks the intended criteria.

Each request accepts 1 to 50 prospects, and each prospect must include `subject.linkedin_url`. Split larger candidate pools into batches of no more than 50. Those batches can run in parallel.

If you used `rox_company_ids` in search, send the same list to validation.

Validation checks each candidate's current employer before assessing role, seniority, geography, and other criteria in the prompt. It returns a verdict with a one-sentence explanation. Without a prompt, validation checks current employment only; everyone still employed is treated as matched.

#### 3. Enrich the matches

For each `matched` verdict, send its `subject` to `POST /enrich/person` and include the `targets` you need. Enrichment requests for different people can run in parallel.

### Credits and errors

Search, validation, and enrichment responses report `credits_used`. Review the API reference for credit charges and balance requirements before running larger requests.

| Response                        | What to check                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `402` from search or validation | The available credits do not cover the requested candidate pool or validation batch.                                |
| `422`                           | The request does not meet the endpoint's input requirements. Review the validation details and correct the payload. |
| `503` from search               | Search is temporarily unavailable. Retry later; the request is not billed.                                          |
| `503` from validation           | Every prospect failed validation processing. Retry later; failed prospects are not billed.                          |

For successful requests, inspect individual results as well as the HTTP status. A filled search pool is not a vetted prospect list, and an enrichment response may contain failure information or no data for a requested target.