Skip to main content
Number Health provides the shared evidence behind the app’s fleet view and the revdesk.dev Spam Test. A handset observation means “observed on this carrier at this time,” not a guarantee that a number is clear on every network. Read the server’s evidence state and recommended action rather than calculating readiness or storing authoritative results in localStorage.
The APIs below cover fleet evidence, Number Sets, saved sessions, and audited observations. They do not yet provide tester-invite redemption, automatic inbound-to-browser handoff, alternate provisioning, billing resolution, or scheduled retirement. Availability follows the Number Health rollout; a documented operation does not imply that these additional workflows are enabled.

​
Authentication and permissions

Use an organization-scoped bearer credential. Creating sets, updating sets, starting sessions, and attaching calls also require an associated user for attribution. Keep long-lived API keys on your server; use the client-token flow for browser integrations. Responses use { "data": ... }; list responses also include meta.total_results. Set, session, and attempt creation return 201. Other Number Health operations return 200 on success.

​
Read policy and fleet evidence

Fetch GET /v1/number-health/policy for the canonical policy version, evidence thresholds, UTC deduplication rule, and current fresh-check/remediation prices. Use these values in cost previews and guidance instead of duplicating constants in clients. GET /v1/number-health/numbers returns owned numbers, identity status, provider scores and freshness, set membership, carrier observations, health_warning, and recommended_action. Optional filters are team_id, number_set_id, area_code, and state. Inspect observations for carrier, outcome, observed_label, observed_at, duration, and callback evidence. NUMBER_ONLY and LOCATION are non-spam observations, but do not confirm the correct clinic name. Null scores or timestamps mean unavailable evidence, not zero risk. Fleet reads use cached reputation. A paid refresh is a separate explicit GET /v1/caller-trust/reputation/numbers/{phone}?fresh=true request. Remediation uses the existing Caller Trust remediation API. Preview the cost and obtain approval before issuing paid operations; creating a test session does not request a fresh reputation check.

​
Organize Number Sets

A Number Set groups numbers for one clinic or calling purpose. Area code is only a visual fallback; sharing an area code does not make two numbers replacements for one another. Create a set with POST /v1/number-health/sets:
Use actual owned phone IDs from the fleet response. GET /v1/number-health/sets returns sets and their members. PATCH /v1/number-health/sets/{id} updates fields and upserts supplied members; omitted members are not removed. To make a member ineligible for selection, set outbound_enabled to false or use an ineligible lifecycle state. RETIRED is accepted by the update endpoint. These membership changes affect outbound selection only. They do not buy/release numbers, change billing, disable inbound service, or delete call history. Marking a member RETIRED is not carrier number retirement. Preview selection without placing a call:
The response includes from_number, phone_id, evidence_state, health_warning, and selection_source: "number_set_sticky_health". Selection considers active, outbound-enabled ACTIVE/STANDBY members, preferring the healthiest tier, then priority and a recipient-sticky tie-breaker. Health or membership changes can change the selected caller ID. If all eligible members are flagged, selection still succeeds with a warning. No eligible member returns 409. See caller-ID selection when dialing for exact-number precedence and the /v1/calls/dial request.

​
Run a resumable Spam Test

​
1. Create the session

Obtain the tester’s consent before submitting their phone number. The consent flag records the operator’s assertion; it is not an OTP verification or an invitation redemption flow.
Carrier values are ATT, TMOBILE, VERIZON, OTHER, and UNKNOWN. Scope kinds are ALL, TEAM, NUMBER_SET, AREA_CODE, FLAGGED, and NEEDS_DATA. For TEAM, NUMBER_SET, and AREA_CODE, supply the matching identifier or three-digit area code in scope.value. The returned data.id identifies the saved session. GET /v1/number-health/sessions/{id} returns its selected phone_ids and attempts. Use those server records to resume on another device. PATCH the same URL with { "status": "PAUSED" }, ACTIVE, COMPLETED, or CANCELLED to change its lifecycle without deleting evidence. The selected queue is saved when the session starts.

​
2. Observe the inbound call, then call back

Have the tester call the candidate RevDesk number first. Read GET /v1/number-health/sessions/{id}/inbound?phone_id=101 for server-confirmed progress: call_id, status, answered_at, ended_at, duration_seconds, callback_verified, and human. Only calls from this tester to a queued number after session creation are considered.
This endpoint observes the number’s existing inbound routing. It does not redirect the call to the browser operator. Arrange human inbound handling before a readiness test. An AI answering an inbound call is not qualifying human callback evidence.
For a human browser callback, use the existing WebRTC flow with the exact candidate from_number and the consented tester as to_number. No assigned AI agent is required. Disable duplicate placement while a call request is pending. Attach the resulting call to the session using POST /v1/number-health/sessions/{id}/attempts:
This endpoint attaches an existing call; it does not dial. The server checks ownership, queue membership, session timing, and tester destination. Human modes reject AI calls. Wait for carrier completion events before recording the observation; a browser stopwatch is not duration evidence.

​
3. Record exactly what appeared

Submit to POST /v1/number-health/attempts/{id}/observation:
Outcomes are CLEAN (correct name), NUMBER_ONLY, LOCATION, WRONG_NAME, SPAM, SCAM, BLOCKED, NO_RING, or UNKNOWN. Supply the exact display text, not a guessed carrier verdict. The server measures durations and derives callback evidence from actual calls. Do not set callback_verified: true automatically: that optional field is an explicit, audited operator attestation. Reposting a corrected observation preserves a before/after audit snapshot. If the call has not reached a terminal carrier state, the endpoint returns 400 with retry guidance. After saving, reload the session and fleet for evidence eligibility, exclusion reasons, and the next recommended action. Save the session ID; localStorage is not the results database.

​
Readiness is evidence, not a warm-up guarantee

The current policy targets 8 qualifying human calls, 5 consented testers, 4 active days, and a 60-second conversational duration. Readiness also needs clean observations on AT&T, T-Mobile, and Verizon, a verified callback, LOW provider risk, and no recent negative display. Only one qualifying number/tester interaction per UTC calendar day contributes to readiness. There is no 48-hour rejection of legitimate extra calls. These are RevDesk evidence criteria, not a carrier promise that call length or a fixed number of calls removes spam labels. Do not disguise synthetic calls or automate repetitive warm-up loops. The QA mode records exclusion; it is not a dedicated AI/prerecorded scenario runner.