SwitchID API Documentation

https://www.switchlabs.dev/api/switchid/v1

Requests and responses are JSON over HTTPS. Responses carry Cache-Control: no-store because they contain consumer data.

• Send the key on every request as Authorization: Bearer sid_test_... or Authorization: Bearer sid_live_.... A missing, unknown, revoked or expired key returns 401 unauthorized.
• Each key belongs to one account and one environment. Results carry the matching environment, and a key can read only requests and usage from its own account and environment.
• Keys are issued with the scopes verify:write, requests:read, usage:read. A key without the scope an endpoint needs returns 403 forbidden_scope.
• Call the API from your server. Do not ship a key in a browser, mobile app or public repository.

Getting a key

Create a sandbox key on the SwitchID sandbox page. For live access, contact us.

Every check can cost money, so every POST carries a key that identifies one logical check. Retrying with the same key is never billed twice.

• Idempotency-Key is required on every POST. It must be 1 to 128 printable characters. Without a valid key the request returns 400 missing_idempotency_key before anything runs.
• Use one key per logical check, for example your application id plus a step name, or a UUID you store with the application.
• The same key with the same body returns the original result, with the same request_id, and is never billed twice. For this comparison the phone number is compared after normalization, the name ignores case and repeated spaces, and the order of add_ons does not matter.
• The same key with a different body returns 409 idempotency_conflict.
• If the first request with a key is still running, a repeat returns 202 with { "request_id": "...", "status": "pending" }. Poll GET /requests/{id} instead of sending a new check.
• After a network error, a timeout or a 5xx response, retry with the same key. A same-key retry is always safe: it runs the check only if the first attempt never started, and otherwise returns the stored outcome.
• A stored failure or rejection is final for its key. Replaying the key returns the same error and does not run the check again. Start a new check with a new key only after GET /requests/{id} confirms the failure was not billed and its cause is resolved. Never change keys to get around a pending request or a ledger_unavailable response.
• Keys are remembered for at least 30 days, separately for each account, environment and endpoint.

Each field group in a 200 result, and how to use it.

Warnings

Test keys never reach a paid provider. These numbers, in the reserved fictional 555-01xx block, always produce the same scenario, so you can exercise every branch of your integration. They behave this way only with sid_test_ keys. "Billable" below describes the billing.disposition the result reports; test usage is never invoiced.

Any other US number returns a deterministic synthetic result: the same number always gives the same line type, an invented carrier name, rate center SANDBOX, DC, and a caller-ID name of the form SAMPLE followed by six hexadecimal characters. Because that name is synthetic, comparing it with a real name normally returns mismatch. Validation still applies in the sandbox, so unparseable and non-US numbers return 422.

Every error uses the same envelope: { "error": { "code", "message", "request_id?", "details?" } }, with the HTTP status listed below.

{
  "error": {
    "code": "idempotency_conflict",
    "message": "This Idempotency-Key was already used with a different request.",
    "request_id": "3f2b8c1e-7d4a-4e9b-9c61-5a0d2e8f4b17"
  }
}

• Branch on error.code. The message is written for people and may change.
• request_id is present when the request was recorded. Keep it: it is how you and we find the request later.
• details is present for field validation errors, as a list of { path, message }, and for forbidden_sku, naming the rejected add-ons.
• Both 429 codes send a Retry-After header in whole seconds.

Billing

• A completed core_phone check is billable even when no usable caller-ID name is on file (caller_id.state placeholder, unavailable or error), because the carrier and line type were still looked up.
• Provider and system failures are not billed. Neither are rejected requests or numbers reported as invalid (result_state unavailable). The one exception is ledger_unavailable: that check may have completed, and once it is reconciled it is billed at most once.
• Replaying an Idempotency-Key is never billed twice.
• Re-checking the same number with the same subject_type within 24 hours of the original lookup is free. The result is served from your account's cache with billing.disposition not_billable and the free_recheck_within_24h warning. A result whose caller-name lookup failed is not cached, so checking that number again runs, and bills, a new lookup.
• Results are reused from your account's cache for 30 days by default; your agreement can set a different window. After the first 24 hours, a cached result is charged as your agreement sets for cache hits. billing.cache_hit and billing.unit_price_microdollars on each result show what applied. The name comparison is always recomputed against the name you send.
• Each result reports the unit price that applied in billing.unit_price_microdollars, in integer microdollars: $0.015 is 15000.
• Test usage (sid_test_ keys) is never invoiced. Test results still report the billing disposition that would apply, and GET /usage shows them for the test environment. Live usage is invoiced monthly.

Rate limits

• POST /verify is limited per API key and per account in each environment: 120 requests per minute each by default. Going over either returns 429 rate_limited with Retry-After.
• An account can also have a daily request cap and a monthly spend cap. Reaching one returns 429 spend_cap_reached with Retry-After.

OpenAPI document

Download the OpenAPI 3.1 document (contract version 2026-10-15.2). It is the source of truth for every field on this page.

Reference scripts

Two short scripts show a correct integration against the sandbox.

verify.sh

A bash script using curl, with python3 to format the JSON. It sends one check to the sandbox with a fresh Idempotency-Key, then replays the same key to show that a replay returns the stored outcome instead of starting a new paid check. Run it as SWITCHID_API_KEY=sid_test_... bash verify.sh, optionally followed by a phone number, name and subject type.

verify.mjs

A Node.js script (Node 18 or later, built-in fetch). It generates a UUID Idempotency-Key, retries network errors with the same key, reads GET /requests/{id} when a 202, 429 or 5xx response carries a request id, waits out short Retry-After values, and treats name_match.state unavailable as no evidence rather than a mismatch.

Contact us for a copy of either script.

More

• SwitchID overview
• SwitchID for lenders
• Get a sandbox key
• Request live access