Build on Rodeo Recruiting

Authentication

Every request to /api/v1/* requires an API key passed as a bearer token in the Authorization header.

Authorization: Bearer rk_live_…

Generate a key in Settings → API & webhooks. Keys are workspace-scoped — they can search, export, and reveal agents for your workspace. They cannot change workspace settings.

Base URL

https://app.rodeorecruiting.com/api/v1

All endpoints are versioned under /api/v1. The spec is available as a machine-readable OpenAPI 3.1 document.

GET /agents/search

Search the licensed-agent database with filters. Returns up to 25 agents per page. The total is capped at 10,000 (anti-scrape ceiling). Contact fields (phone, email) are masked unless your workspace has revealed the agent.

Example

curl -s \
  -H "Authorization: Bearer rk_live_…" \
  "https://app.rodeorecruiting.com/api/v1/agents/search?state=FL&state=TX&category=life&recency=30"

Query parameters

Response

{
  "ok": true,
  "data": {
    "data": [ ...AgentRow ],
    "page": 1,
    "pageSize": 25,
    "total": 142,       // capped at 10,000
    "hasMore": true
  }
}

AgentRow shape

Each row in data is an AgentRow. Contact fields are masked teaser strings (not null) until your workspace reveals the agent. The masked phone keeps the last 4 digits; the masked email keeps the domain.

// Un-revealed example (revealed: false)
{
  "id": "cm1abc123",
  "name": "Jane Smith",
  "licenseNumber": "L-1234567",
  "licenseDesc": "Life Agent",
  "state": "FL",
  "licensedDate": "Feb 7, 2022",
  "isCell": true,
  "isNew": false,
  "phone": "(•••) •••-0100",   // masked — last 4 kept
  "email": "•••••@example.com", // masked — domain kept
  "revealed": false
}

// After reveal (revealed: true)
{
  "id": "cm1abc123",
  "name": "Jane Smith",
  "licenseNumber": "L-1234567",
  "licenseDesc": "Life Agent",
  "state": "FL",
  "licensedDate": "Feb 7, 2022",
  "isCell": true,
  "isNew": false,
  "phone": "(305) 555-0100",
  "email": "jane.smith@example.com",
  "revealed": true
}

Returns an empty result when your subscription is paused or the query is outside your covered states — not an error code, to avoid org-state disclosure.

GET /agents/export

Export agents in bulk — up to 200 agents per page (default 200). Identical filtering to search; the same masking and 10k ceiling apply. Use for bulk data pulls to your own systems.

Example

curl -s \
  -H "Authorization: Bearer rk_live_…" \
  "https://app.rodeorecruiting.com/api/v1/agents/export?state=FL&category=life&pageSize=200"

Additional parameters

All search parameters are also accepted. See Search agents for the full list.

Response

{
  "ok": true,
  "data": {
    "data": [ ...AgentRow ],
    "page": 1,
    "pageSize": 200,
    "total": 1432,
    "hasMore": true
  }
}

POST /agents/{id}/reveal

Unlock the full contact details (phone, email) for an agent. Spends one reveal credit from your workspace balance on the first reveal. Re-revealing an already-unlocked agent spends no credit (creditsSpent: 0).

Example

curl -s -X POST \
  -H "Authorization: Bearer rk_live_…" \
  "https://app.rodeorecruiting.com/api/v1/agents/cm1abc123/reveal"

Response

{
  "ok": true,
  "data": {
    "revealed": true,
    "phone": "(305) 555-0100",
    "email": "jane.smith@example.com",
    "credits": {
      "used": 51,
      "total": 300,
      "topUp": 0
    },
    "creditsSpent": 1
  }
}

revealed is always true on success. phone and email are the real unmasked values. The credits meter reflects your workspace balance after this reveal: total is null for unlimited (National) plans. creditsSpent is 0 when the agent was already unlocked by your workspace (a no-cost re-view) or when your plan is unlimited.

Rate limits

All /api/v1/* responses carry IETF draft rate-limit headers so you can adapt your request pace without hitting a 429:

Limits per endpoint

Limits are per workspace (keyed on your API key's org).

Response format

Every response is JSON. Successful responses:

{ "ok": true, "data": { ... } }

Error responses:

{
  "ok": false,
  "error": {
    "code": "UNAUTHENTICATED",       // machine-readable code
    "message": "Invalid or missing API key — pass Authorization: Bearer rk_live_…",
    "fields": { ... },              // only on VALIDATION (400)
    "retryAfterSec": 42             // only on RATE_LIMITED (429)
  }
}

Error codes

Webhooks

Register an HTTPS endpoint in Settings → API & webhooks to receive signed POST deliveries when events occur in your workspace (e.g. agent revealed, pipeline stage changed).

Request headers

Verifying a delivery

Compute HMAC-SHA256 over the pre-image ${X-RR-Webhook-Timestamp}.${rawBody} using your endpoint's signing secret. The timestamp is inside the MAC so a replayed (body, signature) pair under a different timestamp will not match.

1. Read X-RR-Webhook-Timestamp from the request headers.
2. Concatenate: "${X-RR-Webhook-Timestamp}." + rawBody
3. Compute HMAC-SHA256(secret, preImage) and hex-encode the digest.
4. Compare to the value after sha256= in X-RR-Signature.
5. During key rotation, also accept X-RR-Signature-Previous.

Node.js example

const crypto = require('node:crypto')

function verify(secret, timestamp, rawBody, signature) {
  const preImage = `${timestamp}.${rawBody}`
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(preImage)
    .digest('hex')
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  )
}

// In your webhook handler:
const ts  = req.headers['x-rr-webhook-timestamp']
const sig = req.headers['x-rr-signature']
if (!verify(SIGNING_SECRET, ts, req.rawBody, sig)) {
  return res.status(401).send('Invalid signature')
}

OpenAPI spec

The full machine-readable OpenAPI 3.1 spec is available at:

https://app.rodeorecruiting.com/api/v1/openapi.json

curl -s "https://app.rodeorecruiting.com/api/v1/openapi.json" | jq '.openapi, (.paths | keys)'

No authentication required — the spec is public. Import it into Postman, Insomnia, or any OpenAPI-compatible client to get auto-complete and inline docs for every endpoint.