---
title: "List authoritative number-health evidence"
method: GET
path: "/v1/number-health/numbers"
tags: ["Number Health"]
---

# List authoritative number-health evidence

`GET /v1/number-health/numbers`

## Request

- Base URL: `https://api.revdesk.com`
- URL: `https://api.revdesk.com/v1/number-health/numbers`
- Auth: HTTP bearer

Returns every phone number in the workspace with Number Set membership, provider scores, carrier-specific handset observations, evidence freshness, and the next recommended action.

## Query parameters

- `state` 'CLEAN_OBSERVED' | 'NEEDS_DATA' | 'WATCH' | 'FLAGGED' | 'SETUP_INCOMPLETE' | 'RETIRED'
- `team_id` string, uuid
- `number_set_id` string
- `area_code` string

## Response `200`

Success

- object
  - `data` object[], required
    - `id` integer, required
    - `phone_number` string, required
    - `name` string, nullable, required
    - `is_active` boolean, required
    - `team_id` string, nullable, required
    - `team_name` string, nullable, required
    - `area_code` string, required
    - `cnam_display_name` string, nullable, required
    - `cnam_status` string, nullable, required
    - `caller_registry_status` string, nullable, required
    - `reputation_enrolled_at` string, date-time, nullable, required
    - `number_set_id` string, nullable, required
    - `number_set_name` string, nullable, required
    - `number_set_use_case` string, nullable, required
    - `member_role` 'PRIMARY' | 'ALTERNATE', nullable, required
    - `member_state` 'PREPARING' | 'ACTIVE' | 'STANDBY' | 'RETIRED', nullable, required
    - `evidence_state` 'CLEAN_OBSERVED' | 'NEEDS_DATA' | 'WATCH' | 'FLAGGED' | 'SETUP_INCOMPLETE' | 'RETIRED', required
    - `health_warning` string, nullable, required
    - `recommended_action` string, required
    - `has_alternate` boolean, required
    - `spam_risk` 'LOW' | 'MEDIUM' | 'HIGH', nullable, required
    - `spam_category` string, nullable, required
    - `maturity_score` number, nullable, required
    - `connection_score` number, nullable, required
    - `engagement_score` number, nullable, required
    - `sentiment_score` number, nullable, required
    - `reputation_refreshed_at` string, date-time, nullable, required
    - `qualifying_calls` integer, required
    - `callback_verified` boolean, required
    - `observations` object[], required
      - `id` string, required
      - `carrier` 'ATT' | 'TMOBILE' | 'VERIZON' | 'OTHER' | 'UNKNOWN', required
      - `outcome` 'CLEAN' | 'NUMBER_ONLY' | 'LOCATION' | 'SPAM' | 'SCAM' | 'BLOCKED' | 'WRONG_NAME' | 'NO_RING' | 'UNKNOWN', nullable, required
      - `observed_label` string, nullable, required
      - `observed_at` string, date-time, required
      - `duration_seconds` number, nullable, required
      - `callback_verified` boolean, required
  - `meta` object, required
    - `total_results` number, required

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict (incl. idempotency conflicts)
- `429`: Rate limited

---

[API](https://skmtc.dev/revdesk/apis/revdesk-v1-api.md) · [All operations](https://skmtc.dev/revdesk/apis/revdesk-v1-api/llms.txt) · [OpenAPI document](https://skmtc.dev/revdesk/apis/revdesk-v1-api/revisions/fcbd43530a48?raw)