API

Workfows API

Introduction

Welcome to the HeyReach API. Let' get started with a quick setup on how to use the API!

Finding your API key

The first step when using the HeyReach API is authenticating your requests with an API key. The API key is used to authenticate the incoming requests and map them to your organization. API keys never expire, however they can be deleted/deactivated.

Authentication

After you have your API key, you will need to provide it in every request that you make to the HeyReach API. You will need to use add the X-API-KEY request header to every request and set you API key as the value.

Test your API key

Once you have your API key, you can check if it's working by sending the following request. If everything is working properly, you should get a 200 HTTP status code.

Plain Text

POST file:///validate-bulk \
 Content-Type: application/json \
 ["google.com", "github.com", "stackoverflow.com"]

Rate Limits

Reach allows a maximum of 300 requests per minute. All requests are attributed to the same limit. Going above the limit will return a 429 HTTP status code and an error.

API Endpoints Backend analysis

Check if your API token is set up properly

postDomain Validator

What it does:

Takes a domain (e.g., 'google.com')
Checks if it actually exists on the internet (DNS lookup)
Tries to connect to it via HTTP
Detects if it redirects to another URL

Business Logic:

Clean input (remove extra spaces, add https:// if missing)
Parse the domain to extract hostname
DNS Check: Query DNS servers - does this domain exist?
HTTP Request: Try to visit the website
Redirect Detection: If the response has history (301/302 redirects), capture final destination
Fallback: If HTTPS fails, try HTTP

Use case:

Clean lead lists, verify scraped domains still exist, find parent companies via redirects

HEADERS

X-API-KEY:<string>(required)

Content-Type:application/json

Accept:text/plain

Body raw (json)

json

{
  "domain": "google.com"
}

postCompany Name Normalizer

What it does:

Takes messy company name (e.g., "THE APPLE INC.")
Standardizes it for matching/deduplication

Business Logic:

Remove "The" prefix at the beginning
Identify and remove legal suffixes (Inc, LLC, Ltd, Corp, Company, GmbH, SA, etc.)
Remove commas and extra punctuation
Convert to Title Case (First Letter Uppercase, rest lowercase)
Fix common acronyms (IBM, AWS, API, SaaS stay uppercase)

Examples:

THE MICROSOFT CORPORATION → Microsoft
Amazon, LLC → Amazon

Use case:

Dedupe company lists, match companies across data sources, clean scraped data

HEADERS

X-API-KEY:<string>(required)

Content-Type:application/json

Accept:text/plain

Body raw (json)

json

{
  "company_name": "Apple Inc."
}

Example Request

json

{
  "domain": "google.com"
}

Example Response

Valid domain

{
  "status": "Valid domain",
  "redirect_url": null,
  "final_domain": null
}

getFirst Name Normalizer

What it does:

Takes full name or messy name input
Extracts clean first name only

Business Logic:

Detect 'Last, First' format — flip it
Remove prefixes (Mr, Mrs, Ms, Dr, Prof)
Take ONLY first word (ignore middle/last names)
Remove numbers and special characters
Capitalize first letter ONLY, rest lowercase

Examples:

Mr. John Doe → John
Smith, Sarah → Sarah
john123 → John

Use case:

Email personalization, clean scraped names for CRM, standardize contact data

HEADERS

X-API-KEY:<string>(required)

Content-Type:application/json

Accept:text/plain

Body raw (json)

json

{
  "domain": "google.com"
}

Example Request

json

{
  "domain": "google.com"
}

Example Response

Valid domain

{
  "original": "JOHN SMITH",
  "normalized": "John",
  "first_name": "John",
  "issues_found": [
    "Fixed ALL CAPS",
    "Extracted first name only (removed 1 additional names)"
  ]
}

getAmount Normalizer

What it does:

Takes text amounts with K/M/B abbreviations
Converts to actual numeric values

Business Logic:

Remove currency symbols ($, €, £, ¥) and commas
Extract number and magnitude letter (K/M/B/T)
Apply multiplier:
K = × 1,000
M = × 1,000,000
B = × 1,000,000,000
T = × 1,000,000,000,000
Format output in both numeric and readable format

Examples:

10M → 10,000,000 (numeric) + $10.00M (formatted)
$5.5K → 5,500
1.2B → 1,200,000,000
€500 → 500

Use case:

Normalize revenue data, convert funding amounts, sort companies by size, clean financial data

HEADERS

X-API-KEY:<string>(required)

Content-Type:application/json

Accept:text/plain

Body raw (json)

json

{
  "amount": "10M"
}

getJob Title Normalizer

What it does:

Takes messy job title
Extracts seniority level, department, and standardizes title

Business Logic:

Seniority Detection (scored 1-6):
Scan for C-Level keywords (CEO, CFO, CTO, President, Founder) → Level 6
Scan for VP keywords (VP, Vice President, SVP, EVP) → Level 5
Scan for Director keywords (Director, Head of) → Level 4
Scan for Senior keywords (Senior, Sr., Principal, Staff, Lead) → Level 3
Default to Mid-Level if no keywords → Level 2
Scan for Entry keywords (Junior, Associate, Assistant, Coordinator, Intern) → Level 1

Department Detection:

Searches for keywords in predefined categories:
Sales: 'sales', 'BDR', 'SDR', 'business development'
Marketing: 'marketing', 'CMO', 'brand'
Engineering: 'engineer', 'developer', 'CTO'
Product: 'product', 'PM'
Finance: 'finance', 'CFO', 'accounting'
Operations: 'operations', 'COO', 'ops'
HR: 'HR', 'talent', 'recruiting'

Title Standardization:

Expands acronyms, e.g., 'VP' → 'Vice President', 'CEO' → 'Chief Executive Officer'

Examples:

Senior VP of Sales → Seniority: VP (Level 5), Department: Sales, Executive: Yes
Junior Marketing Coordinator → Seniority: Entry (Level 1), Department: Marketing, Executive: No
Head of Engineering → Seniority: Director (Level 4), Department: Engineering, Executive: No

Use case:

Filter for decision-makers (VP+), segment by seniority, target specific departments, score leads by title

HEADERS

X-API-KEY:<string>(required)

Content-Type:application/json

Accept:text/plain

Body raw (json)

json

{
  "job_title": "VP of Sales"
}

Example Request

json

{
  "job_title": "VP of Sales"
}

Example Response

Valid domain

{
  "original": "VP of Sales",
  "standardized": "Vice President of Sales",
  "department": "Sales",
  "seniority": "Vice President",
  "seniority_level": 5,
  "is_executive": true
}

putCountry Time

What it does:

Takes country name or timezone
Returns current time in that location

Business Logic:

Check if input matches known country name
If yes, map to timezone ID (Greece → Europe/Athens)
If no, try input as timezone directly
Use pytz library to get current time in that timezone
Format time as 12-hour with AM/PM
Include date and UTC offset

Examples:

input: "Greece" → "03:45:30" PM, Europe/Athens, +0200
input: "America/New_York" → "08:45:30" AM, -0500
"Head of Engineering" → Seniority: Director (Level 4), Department: Engineering, Executive: No

Use case:

Check if it's business hours before sending emails, log contact time in recipient's timezone, schedule follow-ups

HEADERS

X-API-KEY:<string>(required)

Content-Type:application/json

Accept:text/plain

Body raw (json)

json

{
  "country": "Greece"
}

Example Request

json

{
  "country": "Greece"
}

Example Response

Valid domain

{
  "country": "Greece",
  "timezone": "Europe/Athens",
  "current_time": "03:45:30 PM",
  "date": "2025-01-15",
  "utc_offset": "+0200"
}

putDelay

What it does:

Pauses execution for X seconds
Returns success after delay

Business Logic:

Validate input (must be 1-60 seconds)
Use async sleep to pause without blocking
Return success with completion timestamp

HEADERS

X-API-KEY:<string>(required)

Content-Type:application/json

Accept:text/plain

Body raw (json)

json

{
  "domain": "google.com"
}