# openappend — People Data API

A single JSON API over ~971M phones and 380.8M people. Every phone number is
scored for dialability and DNC compliance, ranked callable-first so your best
number is always first. Also reverses emails to phones and phones to emails.
Built for agent-first workflows: use it from Claude, LangChain, n8n, or any
tool that speaks MCP, or call the REST API directly.

Base URL: https://api.openappend.com/v1
Docs (human): https://openappend.com/docs
Getting started: https://openappend.com/getting-started
Full contract (agents): https://openappend.com/llms-full.txt
Agent / MCP setup: https://openappend.com/agents
MCP endpoint (remote SSE): https://api.openappend.com/mcp
Interactive playground: https://openappend.com/playground

## Authentication
Bearer key on every request: Authorization: Bearer oa_live_<32hex>
Keys are shown once at creation and stored only as a SHA-256 hash.
oa_test_ keys hit a sandbox slice and are never billed.
Missing/garbled key -> 401 missing_or_malformed_key. Unknown/revoked -> 401 invalid_key.

## The Three Endpoints
GET  /v1/fields          Discover every filterable/returnable field. FREE.
POST /v1/people/count    Size an audience for a filter set. FREE.
POST /v1/people/search   Return matching records. reveal:false is FREE
                          (counts + fields, contacts gated); reveal:true bills
                          1 credit per record returned.

Read the schema from GET /v1/fields — never hard-code the field list. New
fields are added there without a version bump.

## Shortcuts (single-key reversals)
POST /v1/email-to-phone  Email -> callable, DNC-scored phones. 1 credit per hit.
POST /v1/phone-to-email  Phone -> email(s). 1 credit per hit. Misses are free.

## Curated Views (pre-built audiences)
GET /v1/views/callable-mobiles   line_type=mobile, dnc=false, disconnected=false
GET /v1/views/homeowners         home_owner=true
GET /v1/views/high-income        income_range in top bands
GET /v1/views/reachable          has_phone=true OR has_email=true
GET /v1/views/renters            home_owner=false, dwelling_type in [apartment, multi]
Views accept flat query params (state=IL, age_min=30, home_owner=true) and
bill like search.

## Filter Grammar
filters is an object keyed by field name. A bare value means equality; an
operator object means range/set operations. Fields AND together; use "in"
for OR-within-a-field.
Operators: eq, in, gte, lte, between (inclusive), prefix, exists.
Ordinal fields (income_range, net_worth, credit_range, home_value) are banded
— compare by band labels like "100k"; valid bands are listed in /v1/fields.

Example filter:
{
  "state": "CA",
  "age": { "gte": 30, "lte": 50 },
  "income_range": { "gte": "100k" },
  "dnc": false,
  "has_email": { "exists": true }
}

## Billing: Qualify Then Pay
GET  /v1/fields                              FREE
POST /v1/people/count                        FREE
POST /v1/people/search reveal:false          FREE (returns counts, not contacts)
POST /v1/people/search reveal:true           1 credit per record
POST /v1/email-to-phone or /v1/phone-to-email 1 credit per hit (miss free)
Any 4xx/5xx                                  FREE (errors never charge)

Recommended flow: count (free, size your audience) -> search reveal:false
(free, verify you'll get good data) -> search reveal:true (pay only for what
you commit to).

## Response Format
Every 200 response: { data, page?, meta }.
meta includes: credits_used (this request), credits_remaining (balance
after), latency_ms, request_id (quote it in support questions).

## MCP Tools (wrap the same endpoints)
Use openappend in Claude, LangChain, n8n, or any MCP-aware tool:
- people_fields  -> GET  /v1/fields
- people_count   -> POST /v1/people/count
- people_search  -> POST /v1/people/search
- email_to_phone -> POST /v1/email-to-phone
- phone_to_email -> POST /v1/phone-to-email

Two ways to run it:
1. stdio: npx -y @openappend/mcp (local server)
2. Remote: configure https://api.openappend.com/mcp (SSE endpoint)
Both ways: provide your API key and base URL in your agent config.

## DNC & Callable-First Ranking
Every phone in the dataset carries live telco data: DNC flag (is this number
on the National Do Not Call Registry?), line type (mobile/landline/other),
last activity, and a dialability rank. We rank callable-first: phones[0] is
always the safest bet. Filter by dnc:false for TCPA compliance.

## Versioning
The contract lives under /v1. Additive changes ship without a version bump
(read /v1/fields for new fields). Breaking changes get a new path (/v2);
/v1 keeps running.

## Examples
Count executives in California:
POST /v1/people/count
{ "filters": { "state": "CA", "job_title": { "prefix": "exec" } } }

Find a phone number for an email (agent-friendly):
POST /v1/email-to-phone
{ "email": "jane@example.com" }

Search for dialable homeowners, see the count first:
POST /v1/people/search
{ "filters": { "home_owner": true, "dnc": false }, "reveal": false }

## Support
- Issues, feature requests: support@openappend.com
- Agent setup help: https://openappend.com/agents
- Rate limits, quotas: docs (contact support for enterprise)

## Note
As of August 2026, openappend is in private beta. This file describes the
live API contract; access is invite-based until public launch.