API Reference

Everything you need to integrate Third Party API v2. Base URL: https://api.third-party-api.com/v2. All responses are JSON over HTTPS.

Quickstart

Every request needs your API key. The following example verifies an email address and geolocates the caller's IP in two calls:

# 1. Verify an email address
curl -s https://api.third-party-api.com/v2/verify/email \
  -H "X-API-Key: $THIRDPARTY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "ada@lovelace.dev"}'

# 2. Geolocate any public IP
curl -s https://api.third-party-api.com/v2/geo/98.207.254.17 \
  -H "X-API-Key: $THIRDPARTY_KEY"

Authentication

Requests are authenticated with your API key passed in the X-API-Key header. Keys are scoped per environment (test / live) and can be rotated at any time from the dashboard. Live keys are shown only once at creation — store them somewhere safe.

Note: Never put your API key in client-side JavaScript. Route calls through your backend, or use short-lived session tokens issued by POST /tokens.

A missing or invalid key returns 401 with a JSON body:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided X-API-Key is invalid or has been revoked.",
    "request_id": "req_7f2b0d1c"
  }
}

Rate limits

Limits depend on your plan and are returned in every response via the X-RateLimit-* headers. When you exceed a limit you'll receive 429 and a Retry-After header in seconds.

Plan	Requests / second	Burst
Free	1	10
Pro	25	100
Enterprise	negotiated (default 200)	negotiated

Pagination

List endpoints use cursor pagination. Pass ?cursor= from the next_cursor field of the previous response. Cursors expire after 24 hours.

Endpoints

Method	Path	Description
POST	/verify/email	Verify a single email address
POST	/verify/email/bulk	Verify up to 10,000 addresses
GET	/geo/{ip}	Geolocate an IPv4 or IPv6 address
GET	/geo/me	Geolocate the requesting IP
POST	/enrich/contact	Enrich a person by email or domain
POST	/enrich/company	Enrich a company by domain
POST	/batch	Create an async batch job
GET	/batch/{id}	Poll a batch job's status

POST /verify/email

POST /v2/verify/email

Checks syntax, MX records, disposable domains, catch-all mail servers and performs mailbox probing where the remote server allows it.

Request

{
  "email": "ada@lovelace.dev",
  "options": {
    "probe_mailbox": true,
    "check_disposable": true
  }
}

Response 200 OK

{
  "email": "ada@lovelace.dev",
  "deliverable": true,
  "state": "deliverable",
  "quality_score": 0.97,
  "reasons": [],
  "is_disposable": false,
  "is_catch_all": false,
  "mx": { "accepts_mail": true, "records": ["mx1.lovelace.dev"] },
  "checked_at": "2026-02-11T09:12:44Z",
  "request_id": "req_a91c00ef"
}

Possible state values: deliverable, undeliverable, risky, unknown.

GET /geo/{ip}

GET /v2/geo/98.207.254.17

Returns city-level geolocation plus network metadata. Private/reserved ranges return 400 invalid_ip.

Response 200 OK

{
  "ip": "98.207.254.17",
  "continent": "North America",
  "country": "US",
  "country_name": "United States",
  "region": "California",
  "city": "San Francisco",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "timezone": "America/Los_Angeles",
  "asn": 7922,
  "org": "Comcast Cable Communications",
  "is_proxy": false,
  "is_vpn": false
}

POST /enrich/contact

POST /v2/enrich/contact

Resolves a person profile from an email address, a domain plus full name, or a LinkedIn URL. Returns 204 when no match is found — this still counts as a billable call.

Response 200 OK (abridged)

{
  "person": {
    "full_name": "Ada Lovelace",
    "title": "Chief Mathematician",
    "seniority": "executive",
    "company": {
      "name": "Analytical Engines Ltd.",
      "domain": "lovelace.dev",
      "employee_count": 54,
      "founded": 2019,
      "technologies": ["cloudflare", "postgres", "python"]
    },
    "confidence": 0.91
  }
}

POST /batch

Submit up to 50,000 records for asynchronous processing. We POST a signed webhook to your callback URL when the job finishes, or you can poll GET /batch/{id} every 30 seconds.

{
  "type": "verify_email",
  "records": ["ada@lovelace.dev", "grace@hopper.org"],
  "webhook_url": "https://app.example.com/hooks/tpapi"
}

Webhooks

Webhook payloads are signed with HMAC-SHA256. Verify the X-TPA-Signature header (format: t=<unix_ts>,v1=<hex>) using your signing secret. Failed deliveries retry with exponential backoff for 24 hours.

Error codes

HTTP	Code	Meaning
400	invalid_request	Malformed JSON or missing required field
400	invalid_ip	Private or syntactically invalid IP address
401	invalid_api_key	Missing, invalid or revoked API key
402	quota_exceeded	Monthly call allowance used up
403	endpoint_not_in_plan	Endpoint requires a higher plan
404	not_found	Unknown resource (e.g. batch id)
422	unprocessable	Record semantically invalid (e.g. no MX hints)
429	rate_limited	Too many requests — see Retry-After
500	internal_error	Something broke on our side; safe to retry
503	upstream_timeout	Upstream check did not respond in time

Changelog

Version	Date	Changes
v2.3.1	2026-01-28	Fixed timezone drift in /geo responses near midnight UTC
v2.3.0	2025-11-14	Added probe_mailbox option; batch size limit raised to 50k
v2.2.0	2025-06-03	Webhook signatures switched to versioned HMAC scheme
v2.1.0	2024-09-19	Company enrichment endpoint; Go SDK 1.0
v2.0.0	2024-03-05	v2 API generally available; v1 sunset announced

This table is the short version. Dated entries, breaking-change notices and migration notes live on the full changelog page. Subscribe to the changelog feed or email support@third-party-api.com with questions. For live availability, see the status page — current rolling 90-day uptime is 99.96%.