Skip to main content

​
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

​
Company Enrichment

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

FieldTypeDescription
emailstringThe validated email address
resultstringOne of: valid, valid_role_based, risky, invalid, unknown
reasonstringHuman-readable explanation of the result
is_role_basedbooleanWhether the email is a generic business inbox
is_free_providerbooleanWhether the domain is a free email provider (Gmail, Yahoo, etc.)
is_catch_allbooleanWhether the domain accepts all emails
catch_all_confidencestringConfidence level: high, medium, or low (only if catch-all)
b2b_outbound_qualitystringB2B value: high, low, or none
credits_chargedintegerCredits charged (0 or 1)
charge_reasonstringExplanation of credit charge
validation_layerstringLayer where validation stopped: syntax, dns, smtp, catchall
smtp_responsestringRaw 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
}

​
Next Steps

Validate Single Email

Learn how to validate one email at a time

Validate Bulk Emails

Process up to 100 emails per request