API Reference

The GTMAPIs REST API provides B2B data enrichment including email validation, email finder, LinkedIn company data, and people lookup.

Base URL

https://api.gtmapis.com

Authentication

All API requests require an API key in the X-API-Key header:

X-API-Key: gtm_test_your_key_here

See Authentication for details.

Available Endpoints

Email Validation

Single Validation

POST /v1/validateValidate a single email address with B2B quality scoring

Bulk Validation

POST /v1/validate/bulkValidate up to 100 emails at once

Email Finder

Find Email

POST /v1/findFind professional email from name + company

Bulk Find

POST /v1/find/bulkFind emails for up to 100 contacts

LinkedIn Company Data

Company Profile

POST /v1/linkedin/companyGet company details, size, funding, locations

Employee Data

POST /v1/linkedin/employees/countEmployee count and growth metrics

Recent Hires

POST /v1/linkedin/hiresWho they hired recently (sales signal)

Job Postings

POST /v1/linkedin/jobsCurrent open positions

People Data

Person Lookup

POST /v1/people/lookupFind LinkedIn profile from name + company

Role Lookup

POST /v1/people/roleFind person by job role at a company

Email to LinkedIn

POST /v1/people/email-to-linkedinConvert work email to LinkedIn URL

Mobile Finder

POST /v1/mobile/findFind mobile phone numbers

Profile Enrichment

POST /v1/profile/enrichGet full profile from email or LinkedIn

Employee Search

POST /v1/people/searchSearch employees with filters

Prospecting

Prospect Account

GET /v1/prospect/accountCheck account status and remaining credits

ICP Search

POST /v1/prospect/icpFind people matching your ICP at a company

Employee Search

POST /v1/prospect/employeesSearch employees with job-level and function filters

Email from LinkedIn

POST /v1/prospect/emailGet email from a LinkedIn profile

Phone from LinkedIn

POST /v1/prospect/phoneGet phone from a LinkedIn profile

Email to Person

POST /v1/prospect/email-to-personReverse lookup person from email

Phone to Person

POST /v1/prospect/phone-to-personReverse lookup person from phone

Company Data

Company Search

POST /v1/company/searchSearch companies by industry, size, location, tech

Company Enrich (LinkedIn)

POST /v1/company/enrich-linkedinGet firmographic data from LinkedIn URL

Domain to LinkedIn

POST /v1/company/domain-to-linkedinFind company LinkedIn from domain

LinkedIn to Domain

POST /v1/company/linkedin-to-domainFind company domain from LinkedIn

Company Enrichment

POST /v1/company/enrichGet firmographic data for any company

Bulk Enrichment

POST /v1/company/enrich/bulkEnrich up to 25 companies at once

Subscriptions & Billing

Create Subscription

POST /v1/subscriptions/createStart a new Stripe subscription

Get Current Subscription

GET /v1/subscriptions/currentCheck subscription status and credits

Cancel Subscription

POST /v1/subscriptions/cancelCancel at end of billing period

Reactivate Subscription

POST /v1/subscriptions/reactivateUndo cancellation before period ends

Monitoring

Health Checks

GET /health, /ready, /liveMonitor API health and readiness

Rate Limits

Limit: 1000 requests per minute per API key
Bulk limit: 100 emails per request
Response header: X-RateLimit-Remaining

When you exceed the rate limit:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 1000 requests per minute",
  "retry_after": 60
}

Request Format

All requests must include: Headers:

Content-Type: application/json
X-API-Key: gtm_test_your_key_here

Body: JSON with required fields

Response Format

All successful responses return HTTP 200 with JSON:

{
  "email": "john@company.com",
  "result": "valid",
  "reason": "",
  "is_role_based": false,
  "is_free_provider": false,
  "is_catch_all": false,
  "b2b_outbound_quality": "high",
  "credits_charged": 1,
  "charge_reason": "Valid personal email with high B2B outbound quality"
}

Error Responses

400 Bad Request

Invalid request format or missing required fields:

{
  "error": "Bad Request",
  "message": "Email field is required"
}

401 Unauthorized

Missing or invalid API key:

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded the rate limit of 1000 requests per minute",
  "retry_after": 60
}

500 Internal Server Error

Unexpected server error:

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Response Fields

Field	Type	Description
`email`	string	The validated email address
`result`	string	One of: `valid`, `valid_role_based`, `risky`, `invalid`, `unknown`
`reason`	string	Human-readable explanation of the result
`is_role_based`	boolean	Whether the email is a generic business inbox
`is_free_provider`	boolean	Whether the domain is a free email provider (Gmail, Yahoo, etc.)
`is_catch_all`	boolean	Whether the domain accepts all emails
`catch_all_confidence`	string	Confidence level: `high`, `medium`, or `low` (only if catch-all)
`b2b_outbound_quality`	string	B2B value: `high`, `low`, or `none`
`credits_charged`	integer	Credits charged (0 or 1)
`charge_reason`	string	Explanation of credit charge
`validation_layer`	string	Layer where validation stopped: `syntax`, `dns`, `smtp`, `catchall`
`smtp_response`	string	Raw SMTP server response (if applicable)

Client Libraries

JavaScript/TypeScript

const validateEmail = async (email) => {
  const response = await fetch('https://api.gtmapis.com/v1/validate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': process.env.GTMAPIS_API_KEY
    },
    body: JSON.stringify({ email })
  });

  return await response.json();
};

Python

import requests
import os

def validate_email(email):
    response = requests.post(
        'https://api.gtmapis.com/v1/validate',
        headers={
            'Content-Type': 'application/json',
            'X-API-Key': os.environ.get('GTMAPIS_API_KEY')
        },
        json={'email': email}
    )
    return response.json()

Go

package main

import (
    "bytes"
    "encoding/json"
    "net/http"
    "os"
)

type ValidationRequest struct {
    Email string `json:"email"`
}

type ValidationResponse struct {
    Email              string `json:"email"`
    Result             string `json:"result"`
    B2BOutboundQuality string `json:"b2b_outbound_quality"`
    CreditsCharged     int    `json:"credits_charged"`
}

func validateEmail(email string) (*ValidationResponse, error) {
    body, _ := json.Marshal(ValidationRequest{Email: email})

    req, _ := http.NewRequest("POST", "https://api.gtmapis.com/v1/validate", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", os.Getenv("GTMAPIS_API_KEY"))

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    var result ValidationResponse
    json.NewDecoder(resp.Body).Decode(&result)
    return &result, nil
}

Documentation Index

​API Reference

​Base URL

​Authentication

​Available Endpoints

​Email Validation

Single Validation

Bulk Validation

​Email Finder

Find Email

Bulk Find

​LinkedIn Company Data

Company Profile

Employee Data

Recent Hires

Job Postings

​People Data

Person Lookup

Role Lookup

Email to LinkedIn

Mobile Finder

Profile Enrichment

Employee Search

​Prospecting

Prospect Account

ICP Search

Employee Search

Email from LinkedIn

Phone from LinkedIn

Email to Person

Phone to Person

​Company Data

Company Search

Company Enrich (LinkedIn)

Domain to LinkedIn

LinkedIn to Domain

Company Enrichment

Bulk Enrichment

​Subscriptions & Billing

Create Subscription

Get Current Subscription

Cancel Subscription

Reactivate Subscription

​Monitoring

Health Checks

​Rate Limits

​Request Format

​Response Format

​Error Responses

​400 Bad Request

​401 Unauthorized

​429 Too Many Requests

​500 Internal Server Error

​Response Fields

​Client Libraries

​JavaScript/TypeScript

​Python

​Go

​Next Steps

Validate Single Email

Validate Bulk Emails

API Reference

Base URL

Authentication

Available Endpoints

Email Validation

Email Finder

LinkedIn Company Data

People Data

Prospecting

Company Data

Subscriptions & Billing

Monitoring

Rate Limits

Request Format

Response Format

Error Responses

400 Bad Request

401 Unauthorized

429 Too Many Requests

500 Internal Server Error

Response Fields

Client Libraries

JavaScript/TypeScript

Python

Go

Next Steps