Get a LIFETIME DEAL for $600 $59 forever

Reach API

An Overview

The Reach API is a set of REST oriented web services that provide access to information via HTTP requests. Our API has predictable resource-oriented URLs, accepts standard headers, accepts and returns JSON responses, and uses standard HTTP response codes, authentication, and verbs.

The Reach API also describes it’s JSON payloads using well-formed schema to provide a deterministic programming experience.

Reach API requests or calls are made through properly formed URLs. The URLs are created manually or programmatically. There are several elements to the URL that need to be composed correctly to request to succeed and return data. This article’s remainder provides an overview of the Reach API, onboarding, usage, and other details to get started.

API Key:

Log in with secure credentials to generate and/or view available API Key from

https://app.reachstream.com/account

API to check available credit:

POST https://api-prd.reachstream.com/api/Search/v1/users/active/credits
Headers:

X-API-Key: gEqboyoK7JSfMvxxxxxxxxxx

Content-Type: ‘application/json’

Accept: ‘application/json 

 

EXPECTED RESPONSES
{
        "status": 200,
        "message": "success",
        "data": "{\"available_credit\":23}"
}
 

{
        "status": 401,
        "message": "Unauthorized",
         "data": "null"
}

{
        "status": 404,
        "message": "Page Not Found",
        "data": "null"
}

{
        "status": 500,
        "message": "Server Error",
        "data": "null"
}

Search Pattern Property:

Within the searchPattern property, user can use additional parameters to conduct a more criteria-driven search.

The additional query parameters that can be used in conjunction with searchPattern JSON include:

Parameter Description
searchPattern (Object)
This is the main object that contains the search criteria.
job_title (Object)
Specifies one or more job titles you want to search for. For example, you can provide a list of job titles like "Business Manager," "Project Manager," etc.
job_title_level (Object)
Specifies one or more job title levels or positions, such as "Manager," "Supervisor," etc.
job_dept_name (Object)
Specifies one or more department names within a company or organization, like "Industry Professional," "Marketing," etc.
job_function_name (Object)
Specifies one or more job functions or roles, which can be "Unspecified" or other roles.
industry_categories (Object)
Specifies one or more industry categories, such as "IT System Operations and Maintenance," "Finance," etc.
sic_code (Object)
Specifies one or more Standard Industrial Classification (SIC) codes, which can have multiple values like "111" and "112."
company_employee_size (Object)
Specifies one or more ranges of company employee sizes, e.g., "10 to 20," "100 to 250," etc.
company_annual_revenue_amount (Object)
Specifies one or more ranges of annual revenue, e.g., "$1M to $5M," "$5M to $10M," etc.
company_address_country (Object)
Specifies one or more countries where the company is located, like "United States," "Canada," etc.
company_address_zipcode (Object)
Specifies one or more company zip codes, for example, "92111," "90210," etc.
company_address_state (Object)
Specifies one or more states where the company is located, e.g., "California," "New York," etc.
company_address_city (Object)
Specifies one or more cities where the company is located, like "San Diego," "Los Angeles," etc.

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.

Example:

Headers:

X-API-Key: ‘gEqboyoK7JSfMvxxxxxxxxxx ‘

Content-Type: ‘application/json’

Accept: ‘application/json 

Body:

{

“searchPattern”: {

        “job_title”: {

                “0”: “Business Manager”

        },

        “job_title_level”: {

                “0”: “Manager”

        },

        “job_dept_name”: {

                 “0”: “Industry Professional”

        },

        “job_function_name”: {

                “0”: “Unspecified”

        },

        “industry_categories”: {

                “0”: “IT System Operations and Maintenance”

        },

          “sic_code”: {

                “0”: “111”,

                “1”: “112”

        },

        “company_employee_size”: {

                “0”: “10 to 20”

        },

        “company_annual_revenue_amount”: {

                “0”: “$1M to $5M”

        },

        “company_address_country”: {

                “0”: “United States”

        },

        “company_address_zipcode”: {

                “0”: “92111”

        },

        “company_address_state”: {

                “0”: “California”

         },

        “company_address_city”: {

                “0”: “San Diego”

        }

}

}

Note: Please keep in mind that all the properties mentioned above are not mandatory. If any of these properties are necessary for your query, you can include them in the request body. You can also include multiple values within any of these properties, as demonstrated in the example above for the ‘sic_code’ property. JSON property containing an array of values.

Get Counts and Sample Data for the Search Query

POST https://api-prd.reachstream.com/api/Search/v1/records/search/count

By using the above URL, we can retrieve both counts and sample data corresponding to the search query pattern. This is achieved by providing JSON Raw format for ‘searchPattern’ properties as demonstrated below.
Request :

Headers:

X-API-Key: ‘gEqboyoK7JSfMvxxxxxxxxxx ‘

Content-Type: ‘application/json’

Accept: ‘application/json 

Body: (JSON Raw)

{

        “searchPattern”: {

                “company_address_state”: {

                “0”: “California”

                 }

        }

}

Note: Please be aware that the ‘data’ property holds data in a stringified format, requiring parsing to extract it into JSON format. ‘Records’ represent sample data, while ‘counts’ indicate the quantity of data accessible for the specified search criteria.
EXPECTED RESPONSES
{
        "status": 200,
        "message": "success",
        "data": "{\"records\":\"[{\\\"id\\\":23174,\\\"contact_name\\\":\\\"Ravi Balwada\\\",\\\"first_name\\\":null,\\\"middle_name\\\":null,\\\"last_name\\\":null,\\\"job_title\\\":\\\"Chief Technology Officer\\\",\\\"job_title_level\\\":null,\\\"job_dept_name\\\":null,\\\"job_function_name\\\":null,\\\"email\\\":null,\\\"phone\\\":null,\\\"company_name\\\":\\\"Guitar Center\\\",\\\"company_website\\\":null,\\\"address_street\\\":null,\\\"address_city\\\":\\\"Northridge\\\",\\\"address_state\\\":\\\"CA\\\",\\\"address_country\\\":\\\"United States\\\",\\\"address_zipcode\\\":null,\\\"company_employee_size\\\":null,\\\"company_annual_revenue_amount\\\":null,\\\"industry_categories\\\":null,\\\"tech_keywords_list\\\":null,\\\"sic_code\\\":null,\\\"npi_number\\\":null,\\\"contact_social_linkedin\\\":null,\\\"updatedAt\\\":\\\"2023-07-03 11:52:29.0\\\"}, {\\\"id\\\":23169,\\\"contact_name\\\":\\\"Dave Obrien\\\",\\\"first_name\\\":null,\\\"middle_name\\\":null,\\\"last_name\\\":null,\\\"job_title\\\":\\\"Chief Marketing Officer\\\",\\\"job_title_level\\\":null,\\\"job_dept_name\\\":null,\\\"job_function_name\\\":null,\\\"email\\\":null,\\\"phone\\\":null,\\\"company_name\\\":\\\"Zywave Inc\\\",\\\"company_website\\\":null,\\\"address_street\\\":null,\\\"address_city\\\":\\\"Milwaukee\\\",\\\"address_state\\\":\\\"WI\\\",\\\"address_country\\\":\\\"United States\\\",\\\"address_zipcode\\\":null,\\\"company_employee_size\\\":null,\\\"company_annual_revenue_amount\\\":null,\\\"industry_categories\\\":null,\\\"tech_keywords_list\\\":null,\\\"sic_code\\\":null,\\\"npi_number\\\":null,\\\"contact_social_linkedin\\\":null,\\\"updatedAt\\\":\\\"2023-06-02 10:38:10.0\\\"}]\",\"counts\":4944}"
}

{
       "status": 400,
       "message": "Missing parameter searchPattern",
       "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 \

'https://api-prd.reachstream.com/api/Search/v1/records/search/count' \

--header 'Content-Type: application/json' \

--header 'X-API-Key: gEqboyoK7JSfMvxxxxxxxxxx' \

--data-raw '{

        "searchPattern": {

                   "company_address_state": {

                            "0": "California"

                }

        }

}'

import http.client

import json

conn = http.client.HTTPSConnection("https://api-prd.reachstream.com")

payload = json.dumps({

        "searchPattern": {

                "job_title_level": {

                        "0": "C-Suite"

                }

       }

})

headers = {

'Content-Type': 'application/json',

'X-API-Key': 'gEqboyoK7JSfMvxxxxxxxxxx'

}

conn.request("POST", "/api/Search/v1/records/search/count", payload, headers)

res = conn.getresponse()

data = res.read()

print(data.decode("utf-8"))

require "uri"

require "json"

require "net/http"

url = URI("https://api-prd.reachstream.com/api/Search/v1/records/search/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({

        "searchPattern": {

                "job_title_level": {

                        "0": "C-Suite"

                }

        }

})

response = http.request(request)

puts response.read_body

OkHttpClient client = new OkHttpClient().newBuilder()

.build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\r\n \n \"searchPattern\": {\r\n \"job_title_level\": {\r\n \"0\": \"C-Suite\"\r\n }\r\n }\r\n}");

Request request = new Request.Builder()

.url("https://api-prd.reachstream.com/api/Search/v1/records/search/count")

.method("POST", body)

.addHeader("Content-Type", "application/json")

.addHeader("X-API-Key", "gEqboyoK7JSfMvxxxxxxxxxx")

.build();

Response response = client.newCall(request).execute();

<?php

$curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://api-prd.reachstream.com/api/Search/v1/records/search/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_POSTFIELDS =>'{

        "searchPattern": {

                "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;

var myHeaders = new Headers();

myHeaders.append("Content-Type", "application/json");

myHeaders.append("X-API-Key", "gEqboyoK7JSfMvxxxxxxxxxx");

var raw = JSON.stringify({

        "searchPattern": {

                "job_title_level": {

                        "0": "C-Suite"

                }

        }

});

var requestOptions = {

method: 'POST',

headers: myHeaders,

body: raw,

redirect: 'follow'

};

fetch("https://api-prd.reachstream.com/api/Search/v1/records/search/count", requestOptions)

.then(response => response.text())

.then(result => console.log(result))

.catch(error => console.log('error', error));

Fetch Data Using API:

POST https://api-prd.reachstream.com/api/Search/v1/records/search
Mandatory properties that must be provided within the raw JSON body:
Request:

Headers:

X-API-Key: ‘gEqboyoK7JSfMvxxxxxxxxxx ‘

Content-Type: ‘application/json’

Body: (JSON Raw)

{

    “fetch_count”: 500,

    “searchPattern”: {

            “job_title_level”: {

                    “0”: “C-Suite”

             }

    }

}

Note: Please be aware that the ‘data’ property holds data in a stringified format, requiring parsing to extract it into JSON format.
EXPECTED RESPONSES

{
        "status": 200,
        "message": "success",
        "data": "[{\"id\":4593185,\"contact_name\":\"Tanya Perez\",\"first_name\":\"Tanya\",\"middle_name\":\"--\",\"last_name\":\"Perez\",\"job_title\":\"Real Estate Agent\",\"job_title_level\":\"Entry\",\"job_dept_name\":\"Operations\",\"job_function_name\":\"Real Estate\",\"email\":\"--\",\"phone\":\"--\",\"company_name\":\"Mexican American Council Inc\",\"company_website\":\"--\",\"address_street\":\"401 N Garfield Ave\",\"address_city\":\"Alhambra\",\"address_state\":\"California\",\"address_country\":\"United States\",\"company_employee_size\":\"Over 10,000\",\"company_annual_revenue_amount\":\"Over $5B\",\"industry_categories\":\"Civic and Social Organization\",\"sic_code\":\"8641\",\"npi_number\":null,\"contact_social_linkedin\":\"--\"}]"
}

{
        "status": 400,
        "message": "Missing parameter searchPattern",
        "data": "null"
}

{
        "status": 400,
        "message": "Missing parameter fetch_count",
        "data": "null"
}

{
        "status": 400,
        "message": "Insufficient credit balance",
        "data": "{\"available_credit\":161,\"requested_fetch_count\":50000}"
}

{
        "status": 401,
        "message": "Unauthorized",
        "data": "null"
}

{
        "status": 402,
        "message": "Insufficient credit balance",
        "data": "{\"available_credit\":161,\"requested_fetch_count\":5000}"
}

{
        "status": 404,
        "message": "Page Not Found",
        "data": "null"
}

{
        "status": 500,
        "message": "Server Error",
        "data": "null"
}

Note: Please be aware that the ‘data’ property holds data in a stringified format, requiring parsing to extract it into JSON format.

curl --location 'https://api-prd.reachstream.com/api/Search/v1/records/search' \

--header 'Content-Type: application/json' \

--header 'X-API-Key: GEqboyoK7JSfMvxxxxxxxxxx' \

--data '{

        "fetch_count": 5000,

        "searchPattern": {

               "job_title_level": {

                       "0": "C-Suite"

                }

        }

}

import requests

import json

url = "https://api-prd.reachstream.com/api/Search/v1/records/search"

payload = json.dumps({

        "fetch_count": 5000,

        "searchPattern": {

                "job_title_level": {

                        "0": "C-Suite"

                }

       }

})

headers = {

'Content-Type': 'application/json',

'X-API-Key': 'GEqboyoK7JSfMvxxxxxxxxxx'

}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

require "uri"

require "json"

require "net/http"

url = URI("https://api-prd.reachstream.com/api/Search/v1/records/search")

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({

        "fetch_count": 5000,

        "searchPattern": {

                "job_title_level": {

                        "0": "C-Suite"

                }

        }

})

response = http.request(request)

puts response.read_body

OkHttpClient client = new OkHttpClient().newBuilder()

.build();

MediaType mediaType = MediaType.parse("application/json");

RequestBody body = RequestBody.create(mediaType, "{\r\n \n \"fetch_count\": 5000,\r\n \"searchPattern\": {\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/Search/v1/records/search")

.method("POST", body)

.addHeader("Content-Type", "application/json")

.addHeader("X-API-Key", "GEqboyoK7JSfMvxxxxxxxxxx")

.build();

Response response = client.newCall(request).execute();

<?php

$client = new Client(); $headers = [ 'Content-Type' => 'application/json',

'X-API-Key' => 'GEqboyoK7JSfMvxxxxxxxxxx'

];

$body = '{

        "fetch_count": 5000,

        "searchPattern": {

                "job_title_level": {

                        "0": "C-Suite"

                }

        }

}';

$request = new Request('POST', 'https://api-prd.reachstream.com/api/Search/v1/records/search', $headers, $body);

$res = $client->sendAsync($request)->wait();

echo $res->getBody();

var myHeaders = new Headers();

myHeaders.append("Content-Type", "application/json");

myHeaders.append("X-API-Key", "GEqboyoK7JSfMvxxxxxxxxxx");

var raw = JSON.stringify({

        "fetch_count": 500,

       "searchPattern": {

                "job_title_level": {

                        "0": "C-Suite"

                }

        }

});

var requestOptions = {

method: 'POST',

headers: myHeaders,

body: raw,

redirect: 'follow'

};

fetch("https://api-prd.reachstream.com/api/Search/v1/records/search", requestOptions)

.then(response => response.text())

.then(result => console.log(result))

.catch(error => console.log('error', error));

HTTP Return Codes

Reach API 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 Reach API servers (these are rare).

200 OK
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 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 reach@reachstream.com

Predefined Values

Predefined values for the search criteria can be obtained from the provided SDK on GitHub

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)

A rate limiter on the number of requests received by the API within any given second. Violations will result in HTTP 429 error being returned.