01 Overview

ReachAPI is a REST‑oriented service suite for embedding contact and company data into applications. It returns structured JSON, and the data‑retrieval endpoints follow an asynchronous, credit‑metered pattern: you submit filter criteria, the server validates and processes matching records in the background, and you either poll for a batch ID or receive a webhook when the batch is ready.

Every endpoint on this page is also described machine‑readably in an OpenAPI 3.0 spec — import it into Postman/Insomnia, feed it to a codegen tool, or point an LLM agent at it directly.

02 Authentication

API Key

Every request (except the webhook receiver on your own server) is authenticated with an X-API-Key header.

Webhook Secret

For the webhook‑based data request flow, generate a Webhook Secret Key from the same Account Details page and set an active Endpoint URL that accepts POST requests.

03 Credit Insights API

Check the available credit balance on your account before running a large batch.

04 Counts API

Get a total match count and a small sample of records for a given filter, without spending download credits — useful for sizing a request before committing to it.

05 Data Access API

Data can be retrieved two ways: API Query (poll for results using a Batch Process ID) or Webhook (ReachStream pushes the result to your endpoint when ready). Only validated records are returned and billed — this includes both valid and catch‑all email addresses; if 99 of 100 requested contacts come back valid or catch‑all, you receive and are charged for 99.

Step 1 — Data Filter API

Submits filter criteria and a fetchCount. Processing happens asynchronously; the response gives you a Batch Process ID to poll.

Step 2 — Retrieve Data API

Poll with the Batch Process ID from step 1 until status is ready, then read the validated records.

Batch List API

Paginated audit log of every batch you've created via the Filter API — status, record counts, credits used, and the original filter.

Webhook‑based Request

Same filter/fetchCount payload, but instead of polling, ReachStream pushes the validated batch to your Webhook URL once ready. Requires an active webhook and its secret key in the webhook_secret_key header.

06 Data Enrichment APIs

Send partial contact or company records in, get enriched records back — also processed asynchronously in two steps.

Initiate Enrichment

Each object in data is validated individually before processing — a failing row returns 400 and rejects the whole batch.

Retrieve Enrichment Results

07 Predefined Values

Look up valid, predefined values (job titles, SIC codes, cities, etc.) to use as filter inputs elsewhere in the API.

Predefined value lists (the full valid vocabulary for each field) are also published as an SDK on GitHub.

08 Filter Property

The filter object is the shared search payload used by the Counts, Data Access, and Data Enrichment endpoints. Every field takes an object keyed by index ("0", "1", …) so you can pass multiple values per criterion.

{
  "filter": {
    "job_title": { "0": "Business Manager" },
    "job_title_level": { "0": "Manager" },
    "company_address_country": { "0": "United States" },
    "company_address_state": { "0": "California" },
    "sic_code": { "0": "111", "1": "112" },
    "company_employee_size": { "0": "10 to 20" }
  }
}

Excluding values from a field

Any field in the filter object accepts a nested exclude object, keyed by index the same way as the field itself. It removes matching records from that field's results — combine it with the field's own indexed values to include a broad match while excluding specific values.

{
  "filter": {
    "job_title": {
      "0": "Software",
      "exclude": {
        "0": "Software Developer"
      }
    }
  }
}

Here, records matching "Software" are included, except those matching "Software Developer".

09 Webhook

Once configured and active, ReachStream POSTs a JSON payload to your endpoint as soon as a batch is validated, instead of you polling for it.

Payload shape

{
  "unique_processing_id": 1300,
  "event": "data_notification",
  "data": [
    {
      "id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "naics_code": [
        "541330"
      ],
      "sic_code": [
        "8711"
      ],
      "company_company_name": "xxxxx",
      "company_domain": "xxxxx.com",
      "company_type": "Private",
      "company_employee_size": "100 to 250",
      "company_annual_revenue_amount": "$10M to $25M",
      "company_address_city": "xxxxx",
      "company_address_state": "xxxxx",
      "company_address_country": "Switzerland",
      "company_phone": "xxxxx",
      "company_industry_categories_list": [
        "Engineering Services"
      ],
      "company_tech_keywords_list": [
        "Aws",
        "Abacus",
        "Azure",
        "Google analytics",
        "Director",
        "Compliance",
        "Continuous improvement",
        "Financial",
        "Infrastructure"
      ],
      "company_buzzwords_list": [
        "Railway Engineering",
        "Power Supply",
        "Rolling Stock",
        "Traction Systems",
        "Infrastructure"
      ],
      "contact_name": "xxxxx",
      "contact_first_name": "xxxxx",
      "contact_last_name": "xxxxx",
      "contact_job_title": "xxxxx",
      "contact_job_title_level": "C-Suite",
      "contact_job_dept_name": "C-Suite",
      "contact_job_function_name": "Executive",
      "contact_email": "xxxxx@xxxxx.com",
      "contact_email_verified_status": "valid"
    }
  ]
}

Handling incoming requests

Security

Verify each request using your shared webhook secret key, serve the endpoint over HTTPS only, and consider IP‑whitelisting ReachStream's outbound addresses.

Testing & troubleshooting

Use Postman or ngrok to simulate deliveries locally. If deliveries seem to fail, check your server logs, confirm the payload shape matches what's above, and confirm your endpoint truly returns 200.

10 HTTP Return Codes

11 Rate Limitations