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.

Base URL

All endpoints below are relative to this base URL.

https://api.reachstream.com

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

02 Quickstart

The full request cycle in four calls: check your credit balance, size a search with Counts, submit a Data Filter request, then poll for the results. Grab an API key from Authentication first — every call below expects it in the X-API-Key header.

Step 1 — Check your credit balance

Confirms your key works and shows how much credit you have before spending any of it.

curl --location 'https://api.reachstream.com/api/v2/retrive/users/active/credits' \
  --request POST \
  --header 'X-API-Key: your-api-key-here'

Full reference →

Step 2 — Size your search with Counts

Try a filter and see how many records match — this doesn't spend download credits.

curl --location 'https://api.reachstream.com/api/v2/request/records/count' \
  --request POST \
  --header 'X-API-Key: your-api-key-here' \
  --header 'Content-Type: application/json' \
  --data '{
  "filter": {
    "company_address_state": { "0": "California" }
  }
}'

See Filter Property for the full set of filterable fields. Full reference →

Step 3 — Submit a Data Filter request

Once the filter looks right, submit it with a fetchCount to start processing. This returns a batch_process_id — it doesn't return records yet.

curl --location 'https://api.reachstream.com/api/v2/async/records/filter/data' \
  --request POST \
  --header 'X-API-Key: your-api-key-here' \
  --header 'Content-Type: application/json' \
  --data '{
  "fetchCount": 50,
  "filter": {
    "company_address_state": { "0": "California" }
  }
}'

Full reference →

Step 4 — Poll for the results

Poll with the batch_process_id from Step 3 until it stops returning "still being processed" — then the validated records are in the response.

curl --location 'https://api.reachstream.com/api/v2/records/batch-process?batch_process_id=31' \
  --header 'X-API-Key: your-api-key-here'

Full reference →

03 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.

04 Credit Insights API

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

05 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.

06 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 — this header is validated against the secret key on file for your account: omit it and you get 400, send the wrong value and you get 401.

fetchCount is capped per plan — see Record Limits.

07 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

08 Filter Value Reference

Use this endpoint to retrieve the supported values available for ReachAPI filters, including job titles, locations, industries, company types, technologies, employee sizes, revenue ranges, and other searchable attributes. These values can be used when building filter requests across the Counts API and Data Access APIs, helping ensure your queries use recognized filter inputs.

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

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

Matching related job titles

The job_title field accepts an optional matchRelatedTitles boolean, keyed alongside the field's own indexed values (not nested inside exclude). Set it to false to match only the exact title(s) supplied. Set it to true — or omit it — to also match titles ReachStream considers related to the ones supplied.

{
  "filter": {
    "job_title": {
      "0": "Hr manager",
      "1": "Project manager",
      "exclude": {
        "0": "Business Manager and HR",
        "1": "HR Manager and Accounting Supervisor"
      },
      "matchRelatedTitles": false
    }
  }
}

10 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"
    }
  ]
}

Delivery headers

Every delivery POST to your Webhook URL carries these headers, in addition to the JSON body above:

Handling incoming requests

Retry policy

A delivery only counts as successful when your endpoint returns 200 (or a JSON body containing "status": 200). Anything else — a non‑200 status, a timeout, or an unparseable response — is logged as a failed attempt and retried on ReachStream's next delivery pass.

Each failed attempt triggers a notification email to your account with the error status and reason. If a batch exhausts its retries or its 7‑day window without a successful delivery, it's marked dormant, a final "try limit exceeded" email is sent, and no further attempts are made — check the Batch List API or your inbox if you suspect a delivery was missed.

Security

Every delivery includes your Webhook Secret Key in the webhook-secret-key header — before trusting a request, compare that header's value against the secret key stored in your own systems (from Account Details → API) using a constant‑time comparison, and reject anything that doesn't match. Also 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, confirm your endpoint truly returns 200, and check for a retry‑failure email — see Retry policy.

11 HTTP Return Codes

12 Rate Limitations