Primary navigation

CallerScope
Check a number

DEVELOPER API

Ship trust you can explain.

A stable caller-intelligence API with isolated test/live keys, an inspectable schema and a safe path to first success.

CONTROLLED PRE-LAUNCH ACCESS

From key to first result.

One stable API for explainable caller assessments. Start with the reserved test fixture, isolate every application, and move to production only after organization approval.

Download OpenAPI 3.1Explore the contract
cURLGET · TEST FIXTURE
curl --fail-with-body \
  --request GET \
  --url 'https://callerscope.com/api/v1/numbers/%2B12025550100' \
  --header "Authorization: Bearer $CALLERSCOPE_API_KEY" \
  --header 'Accept: application/json'

Set the environment variable in your server runtime only.

  1. 01

    Request test access

    An organization admin creates a key for exactly one application and environment.

  2. 02

    Keep the key server-side

    Store it in a secrets manager—never in browser code, a mobile app or a repository.

  3. 03

    Call the reserved fixture

    Test mode returns synthetic data only; the number below is an internationally reserved example.

TRUST BOUNDARY

A CallerScope key. Never a database key.

A custom NoCodeBackend CNAME changes the address of a public projection, not its authority. B2B requests always terminate at the CallerScope gateway, which enforces tenant, scope, environment, quota, normalized schema and audit.

01

Your server

Presents an app-specific key.

02

CallerScope API

Verifies tenant, scope and quota.

03

Sanitized result

Returns a stable contract without private fields.

cs_test_…

Test

Reserved synthetic fixtures only. It can never read live tenant data.

cs_live_…

Live

Sanitized production data after organization approval and plan activation.

API v1 · JSON

A small contract. Explicit states.

State, severity, confidence and freshness are separate dimensions. Unknown is a valid response—not hidden danger and not an error.

JSONILLUSTRATIVE FIXTURE RESPONSE
{
  "data": {
    "e164": "+12025550100",
    "state": "suspicious",
    "severity": "medium",
    "confidence": "high",
    "freshness": "current",
    "reasonCodes": [
      "RESERVED_TEST_FIXTURE",
      "MULTIPLE_SOURCE_FAMILIES"
    ],
    "reportCount": 7,
    "sourceCount": 3,
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "meta": {
    "requestId": "req_[request-id]",
    "schemaVersion": 1
  }
}
data.state
unknown · limited · nuisance · suspicious · high_risk · mixed · verified_business · stale
data.severity
none · low · medium · high; omitted from the minimal unknown state
data.confidence
insufficient · low · medium · high
data.freshness
current · aging · stale · unknown; omitted from the minimal unknown state
data.reasonCodes
stable machine-readable reasons without private evidence
data.reportCount / sourceCount
sanitized aggregate counts only; optional for unknown
meta
requestId · schemaVersion

ENDPOINTS

One lookup or a batch.

A batch preserves input order and charges one unit per number. One item failure does not hide the other results.

25numbers per batch

MethodPathAccessMetering
GET/api/v1/numbers/{e164}numbers:read1 unit
POST/api/v1/numbers/batchnumbers:read1–25 units
GET/api/v1/usageusage:readup to 93 days
WorkspaceAPI keys and webhooksorganization adminindependent audit
cURLPOST · 1 RESERVED ITEM
curl --fail-with-body \
  --request POST \
  --url 'https://callerscope.com/api/v1/numbers/batch' \
  --header "Authorization: Bearer $CALLERSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"numbers":["+12025550100"]}'

OPERATE

Keys designed to change safely.

Every application and environment has its own lifecycle. A compromised key can be revoked without rotating upstream infrastructure.

429Retry-After without exposing internal capacity
  1. 01

    Create

    Choose an application, test/live environment, least-privilege scopes and optional expiry. Plaintext is shown once.

  2. 02

    Observe

    Review safe usage aggregates by organization, environment and day—never the phone numbers queried.

  3. 03

    Rotate

    Deploy a replacement during the bounded 24-hour overlap, then confirm traffic has moved to the new key.

  4. 04

    Revoke

    Invalidate any key independently and immediately. Extra keys never increase organization quota.

Least privilege

Use one key per app and environment, granting only the scopes it needs.

Secret storage

Keep secrets in a key manager. Exclude them from logs, analytics, errors and client bundles.

Bounded retries

Set a timeout, honor Retry-After and reuse the same X-Idempotency-Key for retry-safe workspace operations.

WEBHOOKS

Material changes, not a noisy stream.

Webhooks are managed in the organization workspace, delivered at least once and signed with a separate secret. Receivers must verify the signature over the unmodified body and deduplicate the event ID.

  • number.assessment.changed
  • number.severe_evidence.corroborated
  • business.verification.changed
  • remedy.outcome.changed

STABILITY

Versions you can plan around.

/v1

Stable major version

Backward-compatible additions may ship. A breaking change requires a new major path.

schemaVersion

Machine-readable schema

Every response carries a schema version and requestId for support without logging the number.

Deprecation

Announced retirement

X-CallerScope-Api-Version and X-CallerScope-Api-Deprecated expose lifecycle state. Retirement adds a concrete Sunset date and migration path.

PRODUCTION ACCESS IS NOT OPEN YET

Plan a safe integration.

Production API access is not open yet. Contact us to discuss your use case and availability.

Discuss API accessFor businesses