RegistryScouts API Documentation

Start here

Overview

The API mirrors the dashboard: the same records, the same filters, the same lookback window your membership unlocks. Requests are read-only, stateless and authenticated with a bearer token. Every call is logged to your usage history so you can audit volume and troubleshoot integrations.

Base URL

https://registryscouts.com/api/public/v1/companies

Method

GET (OPTIONS supported for CORS)

Auth

Authorization: Bearer rsk_…

Three steps

Quick Start

1
Subscribe
Add API access from your billing page — monthly or annual.
2
Create a key
Name it, copy it once. Up to 5 active keys per account.
3
Call the endpoint
Send the key as a bearer token and read JSON or CSV.

your first call

curl -H "Authorization: Bearer rsk_your_key_here" \
  "https://registryscouts.com/api/public/v1/companies?limit=5"

Bearer tokens

Authentication

Keys start with rsk_, are shown exactly once at creation, and are stored only as a hash. Rotate freely — revoking a key blocks it immediately. Requests without an active API subscription return 402; bad or revoked keys return 401.

header

Authorization: Bearer rsk_your_key_here

Keep keys server-side. Load them from an environment variable. A key in browser JavaScript is a public key — anyone can read it from the network tab.

Interactive

Request Builder

Set your filters and copy working code in the language you use. Nothing is sent from this page — it generates the request for you.

States

From

Limit (250)

Format

Only rows that have…

GEThttps://registryscouts.com/api/public/v1/companies?state=NY%2CCO&email=true&limit=250

cURL

curl -sS -H "Authorization: Bearer rsk_your_key_here" \
  "https://registryscouts.com/api/public/v1/companies?state=NY%2CCO&email=true&limit=250"

Filtering

Query Parameters

Parameter	Example	Description
state	NY,CO	Comma-separated two-letter state codes (or full names).
from	2026-08-01	Earliest filing date, inclusive.
to	2026-08-26	Latest filing date, inclusive.
email	true	Only rows that have an email address.
phone	true	Only rows that have a phone number.
address	true	Only rows that have a street address.
search	roofing	Matches business name, city or registry id.
limit	100	Rows per page, 1–1000. Defaults to 100.
offset	0	Rows to skip, for paging.
format	json	json (default) or csv.

Shape

Response

200 application/json

{
  "plan": "prospector",
  "lookbackDays": 30,
  "lookbackFrom": "2026-07-27T00:00:00.000Z",
  "count": 1,
  "totalMatching": 4821,
  "limit": 100,
  "offset": 0,
  "records": [
    {
      "entity_name": "Cascade Roofing LLC",
      "entity_id": "604123456",
      "entity_type": "LLC",
      "state": "Washington",
      "filing_date": "2026-08-24",
      "status": "Active",
      "address": "412 Pine St",
      "city": "Seattle",
      "state_code": "WA",
      "zip": "98101",
      "email": "hello@cascaderoofing.com",
      "phone": "(206) 555-0142",
      "website": "https://cascaderoofing.com",
      "retrieved_at": "2026-08-25T07:02:11.884Z"
    }
  ]
}

200 text/csv

entity_name,entity_id,entity_type,state,filing_date,status,address,city,state_code,zip,email,phone,website,retrieved_at
Cascade Roofing LLC,604123456,LLC,Washington,2026-08-24,Active,412 Pine St,Seattle,WA,98101,hello@cascaderoofing.com,(206) 555-0142,https://cascaderoofing.com,2026-08-25T07:02:11.884Z

Schema

Fields

Field	Type	Description
entity_name	string	Registered business name
entity_id	string	Registry identifier issued by the state
entity_type	string	Entity form (LLC, corporation, etc.)
state	string	Full state name
filing_date	date	Date the business was registered (YYYY-MM-DD)
status	string	Registration status reported by the state
address	string \| null	Street address on file
city	string \| null	City
state_code	string	Two-letter state code
zip	string \| null	Postal code
email	string \| null	Contact email, when discovered
phone	string \| null	Contact phone, when discovered
website	string \| null	Business website, when discovered
retrieved_at	timestamp	When RegistryScouts captured the record

Entitlements

Lookback Windows

Results are automatically clamped to the window your membership unlocks — the API never returns records older than your plan allows.

Scout

Latest daily drop

Newest records only

Tracker

7 days

Rolling week of filings

Prospector

30 days

Rolling month of filings

Pathfinder

90 days

Deepest lookback available

Recipes

Paging & Bulk CSV

Use totalMatching to know how many pages to walk. Keep limit at or below 1,000.

Python — page through everything

import os, requests

KEY = os.environ["REGISTRYSCOUTS_API_KEY"]
rows, offset = [], 0

while True:
    r = requests.get(
        "https://registryscouts.com/api/public/v1/companies",
        headers={"Authorization": f"Bearer {KEY}"},
        params={"state": "NY,CO", "limit": 1000, "offset": offset},
        timeout=120,
    )
    r.raise_for_status()
    page = r.json()
    rows.extend(page["records"])
    offset += page["limit"]
    if offset >= page["totalMatching"]:
        break

print(len(rows), "records")

bash — nightly CSV drop to disk

#!/usr/bin/env bash
set -euo pipefail
DAY=$(date -u +%F)
curl -fsS -H "Authorization: Bearer $REGISTRYSCOUTS_API_KEY" \
  "https://registryscouts.com/api/public/v1/companies?format=csv&limit=1000" \
  -o "registryscouts-$DAY.csv"
echo "saved registryscouts-$DAY.csv"

SQL warehouse load (DuckDB)

INSTALL httpfs; LOAD httpfs;
CREATE OR REPLACE TABLE leads AS
SELECT * FROM read_csv_auto(
  'https://registryscouts.com/api/public/v1/companies?format=csv&limit=1000'
);

Reliability

Errors & Limits

Status	Meaning	What to do
200	OK	Request succeeded — JSON body or CSV attachment.
401	Unauthorized	Missing, malformed, revoked or unknown API key.
402	Payment Required	No active API subscription on the account.
400	Bad Request	Invalid parameter value (bad date, unknown state, limit out of range).
429	Too Many Requests	Over 120 requests per minute for one key — see the Retry-After header.
500	Server Error	Unexpected error — retry with backoff.

Maximum 1,000 rows per request — page with limit and offset.
Up to 5 active keys per account; every call is logged to your usage history.
Retry 5xx responses with exponential backoff (1s, 2s, 4s).

Rate Limiting

120 requests per minute, per API key, on a rolling 60-second window.
Over the limit returns 429 with a Retry-After: 60 header — wait, then retry.
Limits are per key, so heavy jobs can run on a separate key from live traffic.
Batch with larger limit values rather than firing many small requests.

Parameter Validation

state accepts up to 20 values: two-letter USPS codes (50 states + DC) or full state names. Anything unrecognised returns 400 listing the rejected values.
search is restricted to letters, numbers, spaces and . & ' -, trimmed to 80 characters. Other characters are replaced with spaces.
from and to must be YYYY-MM-DD; other formats are ignored.
limit is clamped to 1–1000 and offset to 0 or greater.
Unknown query parameters are ignored and never logged.

Common questions

FAQ

+Do I need a membership as well as the API add-on?

Yes. The API returns the lookback window your membership unlocks, so the add-on sits on top of Scout, Tracker, Prospector or Pathfinder.

+How fresh is the data?

Records land nightly after each state's daily drop, and stale feeds are backfilled automatically as soon as they publish.

+Can I call the API from the browser?

Technically yes (CORS is enabled), but don't — it would expose your key. Proxy through your own server.

+What happens if I cancel?

Keys stop authenticating at the end of the paid period and return 402. Re-subscribing reactivates existing keys.

Ready to plug in?

$9.99/month or $100/year on top of any membership.

Add API Access

The RegistryScouts API