API Access

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.

What you can do

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:

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 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"

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

{
  "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

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

{
  "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:

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.

Manage Sequences

Use the API to create sequences, update their settings, add prospects, and review steps and prospect tasks.

Sequence permissions still apply. Owners control the sequence’s name and tags. Collaborators can change their own sending priority and autosend settings. Updating a sequence does not regenerate its content.

When adding prospects, provide a Rox person ID, Rox lead ID, or person data containing at least an email address or LinkedIn slug. Content generation runs in the background after the request returns. Check the individual prospect endpoint for status. Prospects already in the sequence are reported under duplicates.

Review autosend settings before adding prospects. See the API Reference for request schemas and configuration options.

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.

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.