An Overview
ReachAPI is a REST-oriented service suite designed for seamless application data access. Built on REST principles, ReachAPI facilitates efficient data retrieval through HTTP requests, delivering structured JSON responses.
The API’s well-defined JSON schemas ensure data clarity and consistency, making integration straightforward. With ReachAPI, real-time data can be seamlessly embedded into development workflows, eliminating the need for manual updates.
Authentication
ReachAPI provides secure access to data for authorized applications. API Key authentication restricts access to approved users, ensuring secure data retrieval and integration.
Steps to Generate API Key1. Log In: Visit the ReachStream Login page and enter your credentials to sign in.
2. Access Profile: Click on your Profile icon located in the top-right corner of the page.
3. Account Details: Navigate to the Account Details section from the Profile menu.
4. Generate API Key: Locate the "Generate API Key" option and click it to create your unique API Key.
5. Secure Key: Secure Key: Copy the newly generated API key and store it securely, as required for API access.
Webhook IntegrationWebhooks integrate with ReachAPI to enable real-time data delivery. Webhooks automatically push data to the designated endpoint upon availability (e.g., after email verification), eliminating the need for repeated API requests and ensuring uninterrupted data flow.
Setting Up Webhook1. Access Webhook Setup:
a. Go to the Account Details section where the API Key was generated.
b. Click on "Add Webhook" to open the configuration window.
2. Generate Webhook Secret Key:
a. Select "Generate Webhook Secret" to create a unique secret key for secure authentication.
b. If needed, use the "Re-generate" option to create a new key.
3. Configure Webhook Settings:
a. Enter the Endpoint URL where the data will be delivered. Ensure the URL supports POST requests.
b. Set the Webhook Status to "Active" to enable real-time data delivery.
4. Finalize Configuration:
a. Once configured and activated, the webhook automatically transmits data to the endpoint upon processing completion. The webhook uses the secret key to authenticate and ensure secure communication.
Predefined Values:
This API endpoint allows you to query predefined records using various parameters, such as job titles, SIC codes, and company names. It can also retrieve specific datasets, including employee sizes and other relevant attributes.
API EndpointGET /api/v2/predefined/records/preset-values
Base URLhttps://api-prd.reachstream.com/api/v2/predefined/records/preset-values
AuthenticationThe API requires an X-API-Key header for authentication. You need to provide your API key in the request header to access the endpoint. Replace 'your-api-key-here' with your actual API key.
Request Format
- HTTP Method: GET
- URL: /api/v2/predefined/records/preset-values
- Query Parameters:
- job_title (optional) - Filters results by job title.
- sic_code (optional) - Filters results by the SIC code.
- address_zipcode (optional) - Filters results by address zip code.
- address_city (optional) - Filters results by address city.
- address_state (optional) - Filters results by address state.
- address_country (optional) - Filters results by address country.
- company_name (optional) - Filters results by company name.
- website (optional) - Filters results by website.
- tech_keywords (optional) - Filters results by technology keywords.
- job_title_level (optional) - Filters results by job title level.
- job_dept_name (optional) - Filters results by job department name.
- job_function_name (optional) - Filters results by job function name.
- company_type (optional) - Filters results by company type.
- company_industry_categories_list (optional) - Filters results by company industry categories.
- employee_size (optional) - Filters results by employee size.
- annual_revenue_amount (optional) - Filters results by annual revenue amount.
This command will fetch predefined job titles based on the query parameter job_title=dev. You can replace 'dev' with any other job title or value.
This command will fetch predefined SIC codes based on the query parameter sic_code=1234. You can replace 1234 with any valid SIC code.
This command will fetch predefined records based on the city "New York."
Response FormatThe response from the API will be in JSON format. A successful response (HTTP Status 200) will contain the data that matches the query parameters. If the request fails, the response will contain an error message with an appropriate status code.
Response Fields
- status: The status of the request, typically "200" or "404."
- data:An array of results that match the query parameters
Error Handling
The API returns HTTP status codes, including:
- 200 OK:The request was successful, and the data is returned.
- 400 Bad Request:The request was malformed or missing required parameters.
- 401 Unauthorized:The API key is missing or invalid.
- 500 Internal Server Error:There was an error processing the request.
List of Query Parameters
| Parameter | Description |
|---|---|
| job_title | Filter results by job title. |
| sic_code | Filter results by SIC code. |
| address_zipcode | Filter results by address zip code. |
| address_city | Filter results by address city. |
| address_state | Filter results by address state. |
| address_country | Filter results by address country. |
| company_name | Filter results by company name. |
| website | Filter results by website. |
| tech_keywords | Filter results by technology keywords. |
| job_title_level | Filter results by job title level |
| job_dept_name | Filter results by job department name. |
| job_function_name | Filter results by job function name. . |
| company_type | Filter results by company type. |
| company_industry_categories_list | Filters results by industry categories. |
| employee_size | Filter results by employee size. |
| annual_revenue_amount | Filter results by annual revenue amount. |
Notes
- 200 OK:The request was successful, and the data is returned.
- 400 Bad Request:The request was malformed or missing required parameters.
- 401 Unauthorized:The API key is missing or invalid.
- 500 Internal Server Error:An error occurred during request processing.
Predefined values for the search criteria can be obtained from the provided SDK on GitHub. GitHub
Example: Query Job Titles
curl --location 'https://api-prd.reachstream.com/api/v2/predefined/records/preset-values?
job_title=dev' \ --header 'X-API-Key: your-api-key-here'
Example: Query SIC Codes
curl --location 'https://api-prd.reachstream.com/api/v2/predefined/records/preset-values?job_title=dev'
\--header 'X-API-Key: your-api-key-here'
Example: Query Address City
curl --location 'https://api-prd.reachstream.com/api/v2/predefined/records/
preset-values?address_city=New York'
\ --header 'X-API-Key: your-api-key-here'
{
"status": 200,
"message": "Success",
"data": [
"Software Engineer",
"DevOps Engineer",
"Frontend Developer",
"Backend Developer"
]
}
{
"status": 401,
"message": "Unauthorized",
"data": null
}
{
"status": 404,
"message": "Not Found",
"data": null
}
{
"status": 500,
"message": "Server Error",
"data": null
}
Filter Property:
The `filter` property enables users to conduct detailed, criteria-driven searches by utilizing a set of additional parameters.
Additional Query ParametersThe following query parameters can be used in conjunction with the `filter` JSON object:
| Parameter | Description |
|---|---|
| filter(Object) | The primary object that contains the search criteria. |
| job_title (Object) | Specifies one or more job titles to search for. For example, you can search for "Business Manager" or "Project Manager" to find candidates or listings with those specific roles. |
| job_title_level (Object) | Defines the level of job titles to filter by, such as "Manager" or "Supervisor." This allows you to narrow searches to specific tiers within an organizatio |
| job_dept_name (Object) | Identifies one or more department names within a company. For instance, you can specify "Marketing" or "Finance" to focus on those areas of expertise. |
| job_function_name (Object) | Specifies the job functions, such as "Engineering" or "Sales." This helps in filtering candidates based on their professional expertise. |
| company_industry_categories_list (Object) | Allows for the specification of one or more industry categories, such as "Information Technology" or "Healthcare," to target specific fields. |
| sic_code (Object) | Enables filtering by one or more Standard Industrial Classification (SIC) codes. For example, you might include "111" for Agriculture and "112" for Forestry, allowing for industry-specific searches. |
| company_employee_size (Object) | Lets you specify ranges for company employee sizes, such as "10 to 50" or "100 to 500." This can help in targeting small startups or larger enterprises. |
| company_annual_revenue_amount (Object) | Specifies ranges for annual revenue, such as "$1M to $5M" or "$5M to $10M." This is useful for filtering companies based on financial size and stability. |
| company_address_country (Object) | Allows you to specify one or more countries where the company operates, such as "United States" or "Germany," ensuring relevant regional results. |
| company_address_zipcode (Object) | Lets you filter by specific zip codes, such as "92111" or "90210," to target businesses in particular areas. |
| company_address_state (Object) | Specifies one or more states where the company is located, such as "California" or "Texas," facilitating localized searches. |
| company_address_city (Object) | Enables filtering by one or more cities, such as "San Francisco" or "New York," to focus on urban markets. |
| company_name (Object) | Allows you to search for specific company names, such as "DataCaptive" or "Spokesly," to find targeted results related to particular organizations. |
| company_website (Object) | Lets you specify one or more company websites, such as "www.datacaptive.com" or "www.spokesly.com," for precise digital presence searches. |
| company_type (Object) | Enables filtering by types of companies, such as "Public Company" or "Non-Profit," which can help in categorizing the search results appropriately. |
| tech_keywords (Object) | Allows for the inclusion of technology-related keywords, such as "Artificial Intelligence" or "Cloud Computing," to filter candidates or organizations with specific tech expertise. |
|
This structured approach to querying enables users to perform highly targeted searches based on a comprehensive set of criteria, ensuring relevant and meaningful results. |
Use this payload request to customize and refine your search by providing multiple values for each search criterion, with the option to reference predefined values from the SDK on GitHub. This flexibility allows you to find related information that aligns with your specific preferences or requirements.
"X-API-Key": "gEqboyoK7JSfMvxxxxxxxxxx",
"Content-Type": "application/json",
"Accept": "application/json",
Code Copied!
Credit Insights API
API Endpoint: POST
/api/v2/retrive/users/active/credits
Base URL: https://api-prd.reachstream.com/api/v2/retrive/users/active/credits
Authentication:
The API requires an X-API-Key header for authentication. To access the
endpoint, provide a valid API key in the request header. Replace
'your-api-key-here' with your
actual API key.
Request:
Headers
"X-API-Key": "gEqboyoK7JSfMvxxxxxxxxxx",
"Content-Type": "application/json",
"Accept": "application/json",
Code Copied!
EXPECTED RESPONSES
{
"status": 200,
"message": "success",
"data": {
"available_credit":720
}
}
{
"status": 401,
"message": "Unauthorized",
"data": null
}
{
"status": 404,
"message": "Page Not Found",
"data": null
}
{
"status": 500,
"message": "Server Error",
"data": null
}
Counts API
API Endpoint: POST
/api/v2/request/records/count
Base URL: https://api-prd.reachstream.com/api/v2/request/records/count
The API requires an X-API-Key header for authentication. You need to provide your API key in the request header to access the endpoint. Replace 'your-api-key-here' with your actual API key.
Request Format:
- HTTP Method: POST
- URL: /api/v2/request/records/count
- Body:
- filter(Object) - As mentioned earlier, this remains the same.
Request:
"X-API-Key":
"gEqboyoK7JSfMvxxxxxxxxxx",
"Content-Type": "application/json",
"Accept": "application/json",
Code Copied!
{
"status": 200,
"message": "success",
"data": {
"counts": 2410893,
"records": [
{
"id": 3451,
"contact_name": "xxxxx",
"contact_first_name": null,
"contact_middle_name": null,
"contact_last_name": null,
"contact_job_title_1": "manager",
"contact_job_title_level_1": null,
"contact_job_dept_name_1": null,
"contact_job_function_name_1": null,
"contact_email_1": null,
"contact_phone_1": null,
"company_company_name": "xxxxx",
"company_website": null,
"company_address_street": null,
"company_address_city": "hayden",
"company_address_state": "California",
"company_address_country": "united states",
"company_address_zipcode": null,
"company_employee_size": null,
"company_annual_revenue_amount": null,
"company_industry_categories_list": null,
"company_tech_keywords_list": null,
"sic_code": null,
"npi_number": null,
"contact_social_linkedin": null,
"contact_social_facebook": null,
"contact_social_twitter": null,
"contact_social_instagram": null
},
{
"id": 3496,
"contact_name": "xxxxx",
"contact_first_name": null,
"contact_middle_name": null,
"contact_last_name": null,
"contact_job_title_1": "manager",
"contact_job_title_level_1": null,
"contact_job_dept_name_1": null,
"contact_job_function_name_1": null,
"contact_email_1": null,
"contact_phone_1": null,
"company_company_name": "xxxxx",
"company_website": null,
"company_address_street": null,
"company_address_city": "burlington",
"company_address_state": "California",
"company_address_country": "united states",
"company_address_zipcode": null,
"company_employee_size": null,
"company_annual_revenue_amount": null,
"company_industry_categories_list": null,
"company_tech_keywords_list": null,
"sic_code": null,
"npi_number": null,
"contact_social_linkedin": null,
"contact_social_facebook": null,
"contact_social_twitter": null,
"contact_social_instagram": null
}
]
}
}
{
"status": 400,
"message": "Missing parameter filter",
"data": null
}
{
"status": 401,
"message": "Unauthorized",
"data": null
}
{
"status": 404,
"message": "Page Not Found",
"data": null
}
{
"status": 500,
"message": "Server Error",
"data": null
}
curl -X POST \
--header 'Content-Type: application/json'
\,
--header 'X-API-Key: gEqboyoK7JSfMvxxxxxxxxxx'
\,
--data-raw '{
"filter": {
"company_address_state": {
}
}
}
Code Copied!
import http.client
import json
import http.client
conn = http.client.HTTPSConnection("https://api-prd.reachstream.com"),
payload = json.dumps,
({
"filter": {
"job_title_level": {
"0" = "C-Suite",
}
}
})
headers = {
'Content-Type': = 'application/json',
'X-API-Key': = 'gEqboyoK7JSfMvxxxxxxxxxx',
}
conn.request ("POST",
"/api/v2/async/records/filter/count", payload, headers),
res = conn.getresponse(),
data = res.read(),
print(data.decode("utf-8"))
Code Copied!
require "uri"
require "json"
require "net/http"
url = URI
("https://api-prd.reachstream.com/api/v2/async/records/filter/count")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["X-API-Key"] =
"gEqboyoK7JSfMvxxxxxxxxxx"
request.body = JSON.dump({
"filter": {
"job_title_level": {
"0" = "C-Suite"
}
}
})
response = http.request(request)
puts response.read_body
Code Copied!
OkHttpClient client = new
OkHttpClient().newBuilder(),
.build();
MediaType mediaType = new
OkHttpClient().newBuilder(),
MediaType mediaType
= MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType,
"{\r\n \n
\"filter\":
{\r\n
\"job_title_level\": {\r\n \"0\": \"C-Suite\"\r\n }\r\n }\r\n}");
,
MediaType mediaType
= MediaType.parse("application/json");
,
Request request
= new Request.Builder()
,
new Request.Builder()
.url("http://stag-apigateway.reachstream.com:
9010/api/v2/async/records/filter/count")
,
.method
= ("POST", body)
,
.addHeader
= ("Content-Type", "application/json")
,
.addHeader
= ("X-API-Key", "gEqboyoK7JSfMvxxxxxxxxxx")
,
.build();
Response response
= client.newCall(request).execute();
,
Code Copied!
<?php
$curl
= curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL =>
'http://stag-apigateway.reachstream.com:
9010/api/v2/async/records/filter/count',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => '10',
CURLOPT_TIMEOUT => '0',
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => {
"filter": {
"job_title_level": {
"0": "C-Suite"
}
}
}',
CURLOPT_HTTPHEADER => array(
'Content-Type: application/json',
'X-API-Key: gEqboyoK7JSfMvxxxxxxxxxx'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Code Copied!
var myHeaders = new Headers();
myHeaders.append("Content-Type",
"application/json");
myHeaders.append("X-API-Key",
"gEqboyoK7JSfMvxxxxxxxxxx");
var raw = JSON.stringify({
"filter": {
"job_title_level": {
"0": "C-Suite"
}
}
});
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("http://stag-apigateway.reachstream.com:
9010/api/v2/async/records/filter/count", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
Code Copied!
Data Access API
Data can be accessed using two methods:
I. API Query – Allows you to request specific data on demand by making API calls. It is ideal for retrieving data as needed.
II. Webhook– Enables automatic data delivery whenever a data-ready event is triggered. It is suitable for real-time updates without manual requests.
I. Data Request via API QueryThe Data Request via API Query process follows a two-step workflow using two distinct APIs: the Data Filter API and the Retrieve Data API . These APIs work together seamlessly to enable asynchronous filtering and retrieval of validated records. This integration ensures efficient data processing, allowing users to automate workflows and reduce manual intervention.
Key Steps in the Data Request Process1. Step 1: Initiate Data Filtering (Data Filter API)
a. Submit a request to the Data Filter API with the desired filter criteria and fetch count.
b. The server processes the request asynchronously and generates a Batch Process ID to track the progress of the request.
2. Step 2: Retrieve Filtered Data (Retrieve Data API)
a. Once the filtering process is complete, use the Batch Process ID to call the Retrieve Data API.
b. Retrieve only the validated and processed records associated with the Batch Process ID.
Example Workflow1. Data Filtering:
a. User submits a request via the Data Filter API, specifying filters like location, industry, and fetch count.
b. The server responds with a Batch Process ID, initiating asynchronous processing of the records.
2. Data Retrieval:
a. Using the Batch Process ID, the user queries the Retrieve Data API.
b. The API returns the filtered and validated records, ensuring accurate results for further use.
Data Filter API
Initiates the filtering process based on user-defined criteria and fetch count. It processes the request asynchronously and returns a unique Batch Process ID, which serves as a reference for the filtered records.
Endpoint
POST /api/v2/async/records/filter/data
Headers
| Header | Value | Required | Description |
|---|---|---|---|
| Accept | application/json | Yes | Indicates that the response should be JSON. |
| Content-Type | application/json | Yes | Specifies that the request body is JSON. |
| X-API -Key | string | Yes | API key for authenticating the request. |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| fetchCount | Integer | Yes | The number of records to fetch. |
| filter | Object | Yes | The filtering criteria for the records. |
Error Responses
| Status Code | Type | Description |
|---|---|---|
| 400 | Required fetchCount and filter | Indicates missing required parameters. |
| 401 | Unauthorized | Indicates invalid or missing API key. |
| 500 | Server Error | Indicates a server-side error occurred. |
Example Request
curl --location ''https://api-prd.reachstream.com/api/v2/async/records/filter/data' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: e8Agjbci9D/qtxxxxxxxx' \
--data '{
"fetchCount": 200,
"filter": {
"company_address_country": {
"0": "India"
}
}
}
Code Copied!
import requests
import json
url = "https://api-prd.reachstream.com/api/v2/async/records/filter/data"
payload = json.dumps({
"fetchCount": 2,
"filter": {
"company_address_country": {
"0": "India"
}
}
})
headers = {
'Accept': 'application/json',
'Content-Type': 'application/json',
'X-API-Key': '••••••'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Code Copied!
require "uri"
require "json"
require "net/http"
url = URI("https://api-prd.reachstream.com/api/v2/async/records/filter/data")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"
request["X-API-Key"] = "••••••"
request.body = JSON.dump({
"fetchCount": 2,
"filter": {
"company_address_country": {
"0": "India"
}
}
})
response = http.request(request)
puts response.read_body
Code Copied!
OkHttpClient client
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \n \"fetchCount\": 2,\r\n \"filter\": {\r\n \"company_address_country\": {\r\n \"0\": \"India\"\r\n }\r\n }\r\n}");
Request request = new Request.Builder()
.url("https://api-prd.reachstream.com/api/v2/async/records/filter/data")
.method("POST", body)
.addHeader("Accept", "application/json")
.addHeader("Content-Type", "application/json")
.addHeader("X-API-Key", "••••••")
.build();
Response response = client.newCall(request).execute();
Code Copied!
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api-prd.reachstream.com/api/v2/async/records/filter/data',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS =>'{
"fetchCount": 2,
"filter": {
"company_address_country": {
"0" : "India"
}
}
}',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'Content-Type: application/json',
'X-API-Key: ••••••' ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Code Copied!
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-API-Key", "••••••");
const raw = JSON.stringify({ "fetchCount": 2, "filter": { "company_address_country": { "0": "India" } } });
const requestOptions = { method: "POST", headers: myHeaders,
body: raw, redirect: "follow" };
fetch("https://api-prd.reachstream.com/api/v2/async/records/filter/data",
requestOptions) .then((response) => response.text()) .then((result) => console.log(result))
.catch((error) => console.error(error));
Code Copied!
Retrieve Data API
Retrieves filtered and validated records using the Batch Process ID generated by the Data Filter API. It ensures only processed and valid records are returned to the user.
Endpoint
GET /api/v2/records/batch-process
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| batch_ process_id | Integer | Yes | The ID of the batch process to retrieve data. |
Headers
| Parameter | Value | Required | Description |
|---|---|---|---|
| Accept | application/json | Yes | Indicates that the response should be JSON. |
| X-API -Key | string | Yes | API key for authenticating the request. |
Example Request
curl --location ''https://api-prd.reachstream.com/api/v2/records/batch-process?batch_process_id=4' \
--header 'Accept: application/json' \
--header 'X-API-Key: e8Agjbci9D/qtxxxxx' \
Code Copied!
import requests url = "https://api-prd.reachstream.com/api/v2/records/batch-process?batch_process_id=4"
payload = {} headers = { 'Accept': 'application/json', 'X-API-Key': 'e8Agjbci9D/qt5MoawKE3Q==' }
response = requests.request("GET",
url,
headers=headers, data=payload) print(response.text)
Code Copied!
require "uri"
require "net/http"
url = URI("https://api-prd.reachstream.com/api/v2/records/batch-process?batch_process_id=4")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["X-API-Key"] = "••••••"
response = http.request(request) puts response.read_body
Code Copied!
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("text/plain");
RequestBody body = RequestBody.create(mediaType, "");
Request request = new Request.Builder()
.url("https://api-prd.reachstream.com/api/v2/records/batch-process?batch_process_id=4")
.method("GET", body)
.addHeader("Accept", "application/json") .addHeader("X-API-Key", "••••••")
.build(); Response response = client.newCall(request).execute();
Code Copied!
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => 'https://api-prd.reachstream.com/api/v2/records/batch-process?
batch_process_id=4',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => '',
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 0,
CURLOPT_FOLLOWLOCATION => true,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => array(
'Accept: application/json',
'X-API-Key: ••••••'
),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Code Copied!
const myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("X-API-Key", "••••••");
const requestOptions = { method: "GET", headers: myHeaders,
redirect: "follow" }; fetch("https://api-prd.reachstream.com/api/v2/records/batch-process?batch_process_id=4",
requestOptions) .then((response) => response.text())
.then((result) => console.log(result)) .catch((error) => console.error(error));
Code Copied!
Error Responses
| Status Code | Message | Description |
|---|---|---|
| 400 | Records are still being processed. | The requested data is not yet available. |
| 400 | Records are not available. | No data is available for the given ID. |
| 400 | Missing parameter | A required parameter is missing. |
| 400 | Provide a valid batch_process_id. | The batch process ID is invalid. |
| 401 | Unauthorized | Indicates invalid or missing API key. |
| 500 | Server Error | Indicates a server-side error occurred. |
Success Responses
{
"status": 200,
"message":"Success" ,
"data":[
{"id": 0,
"contact_first_name":null,
"contact_middle_name":null,
"contact_last_name": null,
"contact_name": null,
"contact_suffix": null ,
"contact_gender": null,
"contact_date_of_birth": null,
"contact_address_street": null,
"contact_address_city": null,
"contact_address_state": null,
"contact_address_zipcode": null,
"contact_address_country": null,
"contact_address_type": null,
"contact_email_1": null,
"contact_email_verified_status_1": null,
"contact_phone_1": null,
"contact_phone_1_ext": null,
"contact_phone_type_1": null,
"contact_job_title_1": null,
"contact_job_title_level_1": null,
"contact_job_start_date_1": null,
"contact_job_end_date_1": null,
"contact_reporting_authority_1": null,
"contact_job_dept_name_1": null,
"contact_job_role_name_1": null,
"contact_job_function_name_1":null,
"contact_social_facebook": null,
"contact_social_instagram": null,
"contact_social_linkedin": null,
"contact_social_twitter": null,
"contact_src_name": null,
"contact_status": null,
"contact_age": null,
"company_company_name": null,
"company_description": null,
"company_website": null,
"company_founded_year": null,
"company_address_street": null,
"company_address_city": null,
"company_address_state": null,
"company_address_zipcode": null,
"company_address_country": null,
"company_address_type": null,
"company_type": null,
"company_email_1": null,
"company_email_verified_status_1": null,
"company_phone_1": null,
"company_phone_1_ext": null,
"company_phone_type_1": null,
"company_fax": null,
"company_public_status": null,
"company_fiscal_year_end_month": null,
"company_projected_revenue_amount": null,
"company_projected_revenue_period_in_years": null,
"company_acquisition_company_name": null,
"company_acquisition_date": null,
"company_acquisition_amount": null,
"company_investment_company_name": null,
"company_inn_description": null,
"company_investment_amount": null,
"company_investment_round": null,
"company_investment_start_date": null,
"company_investment_end_date": null,
"company_tech_keywords_list":null,
"company_buzzwords_list":null,
"company_social_facebook":null,
"company_social_instagram":null,
"company_social_linkedin":null,
"company_social_twitter":null,
"company_youtube": null,
"company_angel_list": null,
"company_crunchbase": null,
"company_blog":null,
"company_products":null,
"company_src_name":null,
"sic_code":null,
"company_sic_code":null,
"naics_code":null,
"duns_code":null,
"npi_number": null,
"cms_number": null,
"company_industry_categories_list":null,
"company_industries":null,
"company_second_level_industry":null,
"company_third_level_industry":null,
"company_employee_size":null,
"company_annual_revenue_amount":null,
"created_at":null,
"updated_at": null,
}
]
}
Code Copied!
Notes
- Ensure that the X-API-Key is valid and included in the headers for authentication.
- Confirm that the batch_process_id exists, before retrieving data.
II. Data Request Process Webhook:
Submit Data Request: The API processes the request with specified filters, generating a unique processing ID for future reference.
-
Email Validation: The requested contact list undergoes an email validity check. A response with valid emails, along with the processing ID and Webhook Secret Key, is sent to the specified webhook endpoint.
-
Credits Deduction: The system deducts download credits based on the number of valid emails.
-
Acknowledge Receipt: To confirm receipt, users must respond with a "200 OK" status. Any other response triggers a retry at specified intervals.
Note: Only valid records are returned. For example, if 99 out of 100 emails are valid, the webhook will only include the 99 valid emails, and credits will be deducted accordingly.
To request data via the API, users must submit a valid webhook URL with an Active status. If the webhook is inactive, the API will return a "Bad Request" response.
When users submit a data request, the API will process the specified filters and generate a unique processing ID for future reference. The requested contact list will undergo email validity check. A response with a list of valid emails will be sent to the specified webhook endpoint. This response will go along with the unique processing Id and Webhook Secret Key. Subsequently, the download credits for all valid emails will be deducted from users’ account.
Users are required to acknowledge receipt of the data by responding with a "200 OK" status. A response other than "200 OK" is considered a failed attempt, prompting the server to retry the request at specified intervals.
Please note that only valid records will be returned to the user/client. For instance, if a request is made to retrieve 100 records and 99 emails are deemed valid, the webhook request will contain only the 99 valid records. Correspondingly, credits will be deducted only for the 99 valid records.
API Endpoint
POST /api/v2/async/records/filter
Base URL
https://api-prd.reachstream.com/api/v2/async/records/filterAuthentication
The API requires an X-API-Key header for authentication. You need to provide your API key in the request header to access the endpoint. Replace 'your-api-key-here' with your actual API key.
Request Format:
- HTTP Method: POST
- URL: /api/v2/async/records/filter
- Body:
- filter (Object) - As mentioned earlier, this remains the same.
- fetchCount (Integer) - Specifies the quantity of data you wish to retrieve.
Request
"X-API-Key": 'gEqboyoK7JSfMvxxxxxxxxxx ',
webhook_secret_key: '34906274bxxxxxxxxxx ',
Content-Type: ‘application/json’
Accept: ‘application/json’
Code Copied!
{
"status": 200,
"message": "Records processing initiated",
"data": {
"unique_processing_id":1300
}
}
{
"status": 400,
"message": "Required fetchCount and filter",
"data": null
}
{
"status": 400,
"message": "Webhook feature is inactive",
"data": null
}
{
"status": 402,
"message": "Insufficient credit balance",
"data": {
"available_credit":720
"requested_fetch_count":2000
}
}
{
"status": 401,
"message": "Unauthorized",
"data": null
}
{
"status": 404,
"message": "Page Not Found",
"data": null
}
{
"status": 500,
"message": "Server Error",
"data": null
}
Webhook
A webhook automates data delivery to a specified endpoint, essential for ReachAPI. Setting up a webhook ensures timely and efficient data delivery to your endpoint URL, integrating it seamlessly into your application or development workflow.
The webhook enhances the ReachAPI experience by automating real-time data flow. Once ReachAPI processes a request, the webhook handles delivery, eliminating the need for customers to poll for updates. A unique webhook secret key verifies the authenticity of incoming data, adding an extra layer of security. Together, the webhook and ReachAPI create a reliable, automated system for accurate, on-time data delivery.
Webhook Payload:The data sent to your webhook URL will be in JSON format.
Handling Incoming RequestsTo handle incoming webhook requests:
1. Set Up Your Server
Ensure your server is configured to accept POST requests at the specified URL
2. Parse the Payload
Extract the relevant data from the JSON payload.
3. Process the Data
Implement your logic based on the event received (e.g., updating a database, notifying a user).
Security Consideration
To secure your webhook:
Verify Signatures
Use the shared secret key to verify the incoming requests from your serviceUse HTTPS
Always use HTTPS to encrypt data in transit.IP Whitelisting
Consider restricting access to your webhook URL to known IP addresses.
Testing Webhooks
To test your webhook integration:
Use tools like [Postman] (https://www.postman.com/) or [ngrok] (https://ngrok.com/) to simulate incoming requests.
Ensure that your endpoint responds with a 200 OK status code for successful processing
If you encounter issues:
- Check Server Logs: Review your server logs for errors.
- Payload Format: Ensure the payload format matches the expected structure.
- Response Codes: Make sure your endpoint returns the correct HTTP response codes.
Request:
{
"unique_processing_id": 1300,
"event": "data_notification",
"data": [
{
"id": 30965,
"contact_name": "xxxx",
"contact_first_name": "xxxx",
"contact_middle_name": "xxxx",
"contact_last_name": "xxxx",
"contact_job_title_1": "manager",
"contact_job_title_level_1": "xxxx",
"contact_job_dept_name_1": "xxxx",
"contact_job_function_name_1": "xxxx",
"contact_email_1": "xxxx",
"contact_phone_1": "xxxx",
"company_company_name": "xxxx",
"company_website": "xxxx",
"company_address_street": "xxxx",
"company_address_city": "xxxx",
"company_address_state": "xxxx",
"company_address_country": "xxxx",
"company_address_zipcode": "xxxx",
"company_employee_size": "xxxx",
"company_annual_revenue_amount": "$5m to $10m",
"company_industry_categories_list": "xxxx",
"company_tech_keywords_list": "xxxx",
"sic_code": "8082",
"npi_number": "xxxx",
"contact_social_linkedin": "xxxx",
"contact_social_facebook": "xxxx",
"contact_social_twitter": "xxxx",
"contact_social_instagram": "xxxx"
}
]
}
curl --location 'https://api-prd.reachstream.com/api/v2/async/records/filter' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: GEqboyoK7JSfMvxxxxxxxxxx' \
--header 'webhook_secret_key: 34906274bexxxxxxxx' \
--data '{
"fetchCount": 5000,
"filter": {
"job_title_level": {
"0": "C-Suite"
}
}
}
Code Copied!
import requests
import json
url = "https://api-prd.reachstream.com/api/v2/async/records/filter"
payload = json.dumps({
"fetchCount": 5000,
"filter": {
"job_title_level": {
"0": "C-Suite"
}
}
})
headers = {
'Content-Type': 'application/json',
'X-API-Key': 'GEqboyoK7JSfMvxxxxxxxxxx'
'webhook_secret_key: '34906274be594xxxxxxx'
}
response = requests.request("POST", url, headers=headers, data=payload)
print(response.text)
Code Copied!
require "uri"
require "json"
require "net/http"
url = URI("https://api-prd.reachstream.com/api/v2/async/records/filter")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["X-API-Key"] = "GEqboyoK7JSfMvxxxxxxxxxx"
request["'webhook_secret_key "] = "34906274be594xxxxxxx "
request.body = JSON.dump({
"fetchCount": 5000,
"filter": {
"job_title_level": {
"0": "C-Suite"
}
}
})
response = http.request(request)
puts response.read_body
Code Copied!
OkHttpClient client
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\r\n \n \"fetchCount\": 5000,\r\n \"filter\": {\r\n \"job_title_level\": {\r\n \"0\": \"C-Suite\"\r\n }\r\n }\r\n}\r\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n");
Request request = new Request.Builder()
.url("https://api-prd.reachstream.com/api/v2/async/records/filter")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("X-API-Key", "GEqboyoK7JSfMvxxxxxxxxxx")
.addHeader("webhook_secret_key", "34906274be594xxxxxxxxxx")
.build();
Response response = client.newCall(request).execute();
Code Copied!
$client = new Client();
$headers = [
'Content-Type' => 'application/json',
'X-API-Key' => 'GEqboyoK7JSfMvxxxxxxxxxx',
'webhook_secret_key’ => '34906274be594xxxxxxx'
];
$body = '{
"fetchCount": 5000,
"filter": {
"job_title_level": {
"0": "C-Suite"
}
}
}';
$request = new Request('POST', 'https://api-prd.reachstream.com/api/v2/async/records/filter', $headers, $body);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
Code Copied!
var myHeaders = new Headers();
myHeaders.append("Content-Type", "application/json");
myHeaders.append("X-API-Key", "GEqboyoK7JSfMvxxxxxxxxxx");
myHeaders.append("webhook_secret_key", "34906274bxxxxxxxxxx");
var raw = JSON.stringify({
"fetchCount": 500,
"filter": {
"job_title_level": {
"0": "C-Suite"
}
}
});
var requestOptions = {
method: 'POST',
headers: myHeaders,
body: raw,
redirect: 'follow'
};
fetch("https://api-prd.reachstream.com/api/v2/async/records/filter", requestOptions)
.then(response => response.text())
.then(result => console.log(result))
.catch(error => console.log('error', error));
Code Copied!
HTTP Return Codes
ReachAPI follows standard HTTP response codes:
- 2xx: Success
- 4xx: Client errors (e.g., missing parameters, invalid input).
- 5xx: Server errors (rare).
ReachAPI uses conventional HTTP response codes to indicate the success or failure of an API request.
Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with ReachAPI servers (these are rare).
200k
Success
400 Bad Request
This error indicates that the user’s request contains incorrect syntax. This could be due to the request URL or it’s payload (if applicable).
401 Unauthorized
This error indicates that the client is not permitted to access the requested resource or perform the requested operation.
402 Payment Required
This error indicates that your account has an insufficient credit balance to complete this operation. Please add more credits to your account.
403 Forbidden
This error indicates that the server will not allow the caller to access the requested API – likely due to an invalid API key. Remember that all API calls must have “X-API-Key” as a header for all requests.
404 Not Found
This error indicates that the server could not find the API endpoint that the caller requested. This commonly occurs when a URL is mistyped.
429 Too many requests
This error indicates that the client has exceeded quota. This could be due to too many requests within the last second (concurrency).
500 Internal Server Error
This error indicates that the server has faced a critical internal error. if this happens, please reach out to us at support@reachstream.com.
Rate Limitations
Our API is designed to provide access to our services while maintaining the quality of service for all users. To achieve this, we have implemented rate limitations to prevent abuse, ensure fair usage, and maintain system stability.
| Rate limit | 10 requests per second (RPS) |
The API allows 10 requests per second; Exceeding this limit triggers an HTTP 429 error