Monitoring API sandbox & test keys

Monitoring API test keys: create one in the dashboard

The monitoring sandbox is the Monitoring API on a separate server: create, list, read and cancel person and location monitors, read their alerts, and receive them at your webhook, with the same paths and payloads as live. It matches against a fixed set of made-up people, and nothing you send is billed.

1. In the dashboard, open Developers → API keys.
2. Choose Create test key. Test keys are for business accounts and need no subscription.
3. Copy the key. Test keys begin os_test_. Like a live key, the full secret is shown once, so put it in your secrets store straight away.

One test key works on every API’s sandbox. Each key in the list is labelled Test · Sandbox or Live, with the base URL it works on. Send it in the same X-API-Key header the live API uses. An account holds up to 3 active test keys and can create 10 a day. A revoked test key stops working on the sandbox within a few minutes.

Monitoring API sandbox base URL vs live

Each key works on its own server only, so a mixed-up configuration is caught on the first request rather than after a release. A test key sent to the live API, or a live key sent to the sandbox, is refused with 401 and a detail message that says so:

{
  "detail": "This is a test key (os_test_…). Test keys work only on the sandbox at https://sandbox.offendersearch.app, which answers with sample data. To search real records, send a live key (os_live_…) to https://api.offendersearch.app."
}

{
  "detail": "This is a live key. The sandbox at https://sandbox.offendersearch.app accepts test keys (os_test_…) only — create one in the dashboard under Developers → API keys. Send live keys to https://api.offendersearch.app."
}

A revoked test key gets 401 with: “This test key has been revoked. Create a new test key in the dashboard under Developers → API keys.”

Each test key can send 60 requests a minute and 2,000 a day, and one IP address 120 a minute, across every API on the sandbox. Past a limit the sandbox answers 429 with a Retry-After header. See Sandbox rate limits.

Monitoring API sandbox: person and location monitors

POST /v1/monitors and the rest of the Monitoring API run on the sandbox. A sandbox monitor is checked once, when you create it, against the test people: each match is filed at once as a new alert and sent to channels.webhookUrl one time, in the production payload. The sandbox sends no email. Nothing is billed.

curl -X POST "https://sandbox.offendersearch.app/v1/monitors" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "product": "sex-offender",
      "type": "person",
      "person": {
        "firstName": "Exact",
        "lastName": "Match",
        "dob": "1980-01-01"
      },
      "channels": {
        "webhookUrl": "https://your-app.example.com/hooks/offendersearch"
      }
    }'

Monitoring webhook test event in the sandbox

To test your webhook handler again without creating a new monitor, ask the sandbox for one more alert on a monitor you created. This endpoint exists only on the sandbox. The alert arrives in the same payload a live alert uses, so your handler can check the secret token in your webhookUrl and read monitorId exactly as it will in production. See Delivery.

curl -X POST "https://sandbox.offendersearch.app/v1/sandbox/monitors/{monitorId}/test-event" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY"

Monitoring API sandbox examples in cURL, Node and Python

Person monitor, date of birth verified: the monitor is checked once at creation, and its alert is sent to your webhook. Export your test key as OFFENDERSEARCH_TEST_KEY first.

curl -X POST "https://sandbox.offendersearch.app/v1/monitors" \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "product": "sex-offender",
      "type": "person",
      "person": {
        "firstName": "Exact",
        "lastName": "Match",
        "dob": "1980-01-01"
      },
      "channels": {
        "webhookUrl": "https://your-app.example.com/hooks/offendersearch"
      }
    }'

Postman collection for the monitoring API sandbox

One collection covers every API’s sandbox, with a folder per API, ready to import into Postman or Insomnia. The Monitoring API folder has one request for every scenario on this page. Set {{apiKey}} to your test key; {{baseUrl}} is preset to the sandbox. A request that needs an id from an earlier response uses a variable for it: {{monitorId}}.

Download the sandbox collection (JSON)

Postman: Import, then drop the file. Insomnia: Import, then From file.

Move monitoring from the sandbox to production

The sandbox and the live API differ only in the base URL and the key. Keep both in configuration, not in code, and going live is a configuration change:

# Sandbox
OFFENDERSEARCH_BASE=https://sandbox.offendersearch.app
OFFENDERSEARCH_KEY=os_test_…

# Production — change these two values and nothing else
OFFENDERSEARCH_BASE=https://api.offendersearch.app
OFFENDERSEARCH_KEY=os_live_…

• Create a live key on the same Developers → API keys page.
• Remove any branch that reads sandbox. The field does not exist on live.
• Remove the sandbox-only test-event call. It does not exist on live.
• Live monitors are billed monthly, each dataset separately; see Billing.