The FieldSwap API is a single-shot identity-data API. You send one piece of identity data (email, phone, LinkedIn URL, IP, or full name), and ask for another field back (phone, employment, social, address, etc.). On a cache miss FieldSwap cascades through configured third-party data vendors and persists the result, so the same lookup is free next time within the field's TTL.

All product endpoints live under /v1/. Breaking changes ship under a new major version; backwards-compatible additions (new optional fields, new outputtypes) ship within /v1/.

Every /v1/* request requires an API key. Generate one in the API keys tab. Keys are shown once on creation — store them in a secret manager, not in source.

You can authenticate two ways. They are equivalent; pick whichever your stack prefers:

Authorization: Bearer fs_live_<your_key>
# or
X-Api-Key: fs_live_<your_key>

Keys are scoped to a single workspace (tenant). Treat them like passwords: rotate periodically, revoke any key that may have leaked, and use a separate key per environment or service so you can revoke without coordinated downtime.

Resolve a single output field for one identity input. Each call costs 1 credit regardless of whether the result was served from cache or freshly fetched from a vendor. If the cascade returns no data the call still costs 1 credit (this matches the underlying vendor billing model — you pay per query, not per match).

Request body

{
  "input":  { "type": "<field-type>", "value": "<string>" },
  "output": "<field-type>"
}

Example

curl -X POST https://api.fieldswap.founderscale.com/v1/lookup \
  -H "Authorization: Bearer fs_live_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "input":  { "type": "email", "value": "ada@example.com" },
    "output": "phone"
  }'

Response

{
  "request_id": "8f1d2c20-…",
  "person_id":  "0a4e5b66-…",
  "input":  { "type": "email", "value": "ada@example.com" },
  "output": {
    "type": "phone",
    "value": { "phone_e164": "+14155551234" },
    "fetched_at": "2026-05-08T17:40:21.118Z",
    "source_vendor": "exampledata",
    "fresh": true
  },
  "hit_source": "vendor",
  "credits_charged": 1,
  "credits_remaining": 9847,
  "status": "ok"
}

Both input.type and output use the same enum. Some fields are only meaningful as inputs (ip) or as outputs (employment, social) — supplying them in the wrong direction returns 400.

Normalization. Inputs are always normalized before lookup, so Ada@Example.com and ada@example.com hit the same cache row. Phones are parsed to E.164; if parsing fails we return 400 with {"detail":"could not parse phone"}.

Errors are returned with an HTTP status code and a JSON body of the shape { "detail": "<message>" }. The x-request-id header is set on every response — quote it when contacting support.

Retry guidance. Lookups are not idempotent (each call costs a credit), but retries on 429 and 5xx are safe — a re-issued lookup within the cache TTL hits the cache and skips vendor work. Always honor Retry-After on 429.

Limits are enforced per API key. The default is 100 requests / minute per key; contact us to raise it. Every response includes:

X-RateLimit-Limit:     100
X-RateLimit-Remaining: 87
X-RateLimit-Reset:     1715192461   # unix seconds
Retry-After:           23           # only on 429

On top of per-key throttling there is a per-workspace daily provider spend cap — once your configured cap is hit, lookups return 402 payment_required until the next UTC day. Configure the cap in Billing.

Every request is logged with input/output type, hit source, latency, status, and the person it resolved to. View them in the Logs tab, or pull them programmatically:

GET /logs?limit=100&cursor=2026-05-08T00:00:00Z
GET /billing/usage      # current period credits + request count
GET /billing/ledger     # credit ledger entries

These dashboard endpoints require a JWT session, not an API key — they exist for the FieldSwap UI. If you want programmatic access to usage data, request a reporting key (separate scope) via support.

Two unauthenticated endpoints exist so end users (data subjects) can invoke their privacy rights without going through your support team. You do not call these from your backend; you link to them from your privacy policy.

Submit a DSAR

{
  "requester_email": "ada@example.com",
  "type":            "access" | "delete",
  "identity_type":   "email",
  "identity_value":  "ada@example.com",
  "note":            "optional free text"
}

Opt out

{
  "identity_type":  "email",
  "identity_value": "ada@example.com",
  "reason":         "optional"
}

Opt-out is permanent for the identity until reversed by support. Subsequent lookups for an opted-out person return status: opt_out with no output and zero credits charged.

You don't need to write code to call FieldSwap. Revenue-ops teams can wire /v1/lookup into a Zapier Zap or a Make scenario using each tool's generic HTTP step — no official app required. A typical flow: a new lead lands in your CRM, FieldSwap resolves their email into a phone number, and the result is written back to the record.

Step-by-step guides for each tool:

• Using FieldSwap with Zapier
• Using FieldSwap with Make.com

These cover the enrichment (action) direction only. A FieldSwap-as-a-trigger integration isn't available yet.

The API is small enough that an SDK isn't required — any HTTP client works. Official client libraries for Node and Python are on the roadmap.

For interactive testing without writing code, use the Playground. It runs against your live workspace and deducts real credits.

Found a bug or have a question? Email support@fieldswap.io with the failing request_id from x-request-id.