API Documentation

Lead enrichment API documentation

Send first name, last name, phone, email, and postal code. Get a full lead record back with address, match confidence, and credit usage details.

You can also use our ZIP to address API to convert ZIP input into structured address data in real time.

Real-time APIJSON / Form POST supported100 free credits every monthUS-only

Minimum required fields: first_name, last_name, phone, email, and postal_code.

Quickstart

1. Get your API key

Create an account and generate your BetterPings API key from the dashboard.

2. Send a request

POST to /v1/enrich with first_name, last_name, phone, email, and postal_code.

3. Read the response

Use betterpings_grade, betterpings_confidence, and the enriched address fields in your routing or CRM flow.

Endpoint

POSThttps://betterpings.com/v1/enrich

Single public endpoint. Source attribution is inferred from the API key — no source ID required in the URL.

Authentication

Three authentication methods are supported, checked in this order of precedence:

PreferredAuthorization Header

Authorization: Bearer <api_key>

X-API-Key Header

X-API-Key: <api_key>

Form PostPOST Body Field

api_key=<api_key>

Supported for form-post integrations with your lead routing platform.

Query-string authentication is not supported.

HTTP Headers

These headers are sent with your HTTP request — they are separate from the body fields listed below.

Header	Status	Example	Description
`Authorization`	required	`Bearer bp_live_xxxxx`	Bearer token with your API key
`Content-Type`	required	`application/json`	Request body format
`Idempotency-Key`	optional	`550e8400-e29b-41d4-a716-446655440000`	Unique key to safely retry requests without being charged twice. You generate this value — typically a UUID. If the same key is sent again within 24 hours, the original response is returned at no additional cost.

Idempotency Details

If you send the same Idempotency-Key again within 24 hours, the original response is returned and no additional credit is charged
Replayed responses include a Idempotent-Replayed: true response header
Keys are scoped to your account — other organizations' keys don't affect yours
Keys must be 1–255 characters: letters, numbers, hyphens, underscores, dots, or colons

Content Types

application/json
application/x-www-form-urlencoded
multipart/form-data

Input Fields

Field	Status	Description
first_name	required	First name
last_name	required	Last name
phone	required	Phone number (normalized to 10 digits)
email	required	Email address
postal_code	required	5-digit ZIP code
state	optional	2-letter US state abbreviation (supplemental, not required)
city	optional	City name
ip_address	optional	Consumer IP address
user_agent	optional	Browser user agent string
dob	optional	Date of birth (e.g. 1985-04-12)

Field names are case-insensitive. All fields support an optional lead. prefix (e.g. lead.first_name).

Validation Rules

Required fields: first_name, last_name, phone, email, postal_code

postal_code is normalized to 5 digits where possible (e.g. "852" becomes "00852")

phone is normalized to 10 digits (leading 1 stripped from 11-digit numbers)

Invalid requests return error outcomes such as invalid_data or invalid_zip

JSON Example

POST https://betterpings.com/v1/enrich

curl -X POST https://betterpings.com/v1/enrich \
  -H "Authorization: Bearer bp_live_xxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
  "first_name": "John",
  "last_name": "Smith",
  "phone": "6025551212",
  "email": "john@example.com",
  "postal_code": "85001",
  "state": "AZ",
  "city": "Phoenix",
  "ip_address": "203.0.113.10",
  "user_agent": "Mozilla/5.0",
  "dob": "1985-04-12"
}'

Form Post Example

Content-Type: application/x-www-form-urlencoded

api_key=bp_live_xxxxx
first_name=John
last_name=Smith
phone=6025551212
email=john@example.com
postal_code=85001
state=AZ
city=Phoenix
ip_address=203.0.113.10
user_agent=Mozilla/5.0
dob=1985-04-12

Form Post Setup

BetterPings supports direct form-post integrations with your lead routing platform.

Configuration

Endpoint URL

https://betterpings.com/v1/enrich

Method

POST

Authentication

Set api_key as a static value in your lead routing platform. This field does not change per lead.

Mapped Fields

Map these fields to the corresponding lead fields in your flow:

first_namelast_namephoneemailpostal_codestatecityip_addressuser_agentdob

Example Response

Successful enrichment response (18 fields):

{
  "betterpings_request_id": "req_2c3b3d91",
  "betterpings_grade": "A",
  "betterpings_confidence": 92,
  "betterpings_first_name": "John",
  "betterpings_last_name": "Smith",
  "betterpings_email": "john@example.com",
  "betterpings_phone": "6025551212",
  "betterpings_postal_code": "85001",
  "betterpings_country": "US",
  "betterpings_state": "AZ",
  "betterpings_city": "Phoenix",
  "betterpings_address_1": "123 Main St",
  "betterpings_address_2": null,
  "betterpings_inferred_ip": "172.59.78.126",
  "betterpings_outcome": "address_verified",
  "betterpings_credits_used": 1,
  "betterpings_credits_remaining": 4999,
  "betterpings_credits_used_this_month": 87
}

Response Fields

Every successful enrichment returns 18 fields:

Field	Description
betterpings_request_id	Unique ID for the enrichment request
betterpings_grade	Match confidence grade: A (High), B (Probable), or C (Weak)
betterpings_confidence	Numeric confidence score from 0 to 100
betterpings_first_name	First name
betterpings_last_name	Last name
betterpings_email	Email address
betterpings_phone	Phone number
betterpings_postal_code	ZIP code
betterpings_country	Country code (defaults to US)
betterpings_state	Enriched or derived state
betterpings_city	City
betterpings_address_1	Street address
betterpings_address_2	Suite / unit / apartment
betterpings_inferred_ip	Best-effort IP estimate generated when a source IP is not provided. Intended for routing, analytics, and system compatibility — not as a verified user identifier.
betterpings_credits_used	Credits consumed (1 per successful enrichment, 0 otherwise)
betterpings_credits_remaining	Remaining credit balance after request
betterpings_credits_used_this_month	Total credits consumed this calendar month
betterpings_outcome	Enrichment result status. One of: `address_verified` — Full address appended and verified `address_matched` — Address found with partial or lower-confidence match `no_match` — No address could be found for this lead `invalid_zip` — Provided postal code could not be validated `invalid_data` — Input data was malformed or missing required fields

Enriched values take priority over submitted values. Internal provider calls, scoring breakdowns, and cost data are never exposed in the public API.

Rate Limits

Rate limits are enforced per API key to protect service stability.

Limit	Default
Sustained rate	10 requests/second
Burst allowance	30 requests
Max concurrent in-flight	10 requests

When rate-limited, the API returns HTTP 429 with a JSON body containing retry_after_seconds and a Retry-After header.

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Please retry shortly.",
  "retry_after_seconds": 3
}

Rate-limited requests do not consume credits. Contact support@betterpings.com for custom rate limits.

Error Codes

Code	Description
missing_auth	No API key provided in request.
invalid_api_key	API key is invalid or not found.
source_inactive	The source associated with the key is disabled.
invalid_input	Request body is malformed or missing required fields.
invalid_zip	Provided postal_code could not be validated.
rate_limited	Too many requests. Retry after the interval specified in the response.
internal_error	Unexpected server error.

Implementation Notes

•All API responses are JSON.
•The API is currently US-only. The country field always returns "US".
•Source attribution is inferred from the API key. Each key belongs to a single source.
•Rate-limited requests do not consume credits.
•Concurrent request limits apply per API key (default: 10).
•API keys can be rotated or revoked from the BetterPings dashboard.
•Free monthly credits reset each month and do not roll over. Purchased credits do not expire.