> ## Documentation Index > Fetch the complete documentation index at: https://docs.optimaldial.com/llms.txt > Use this file to discover all available pages before exploring further. # List contacts > The same contacts as `GET /api/v1/contacts`, reporting the nine-tier `OptimalDial_Status` plus the OptimalDial Identity band. A contact only carries identity when the batch it was processed in had name columns mapped. ## OpenAPI ````yaml https://api.optimaldial.com/openapi/v1/spec.yaml get /api/v2/contacts openapi: 3.1.0 info: title: OptimalDial API version: '2026-08-19' summary: Submit phone-number lists, get them processed, receive webhooks. description: | The OptimalDial REST API lets you programmatically submit lists of phone numbers (CSV or JSON, 100–250,000 per request), download processed results, and receive HMAC-signed webhooks when uploads change state. Map a name column on an upload to enable **OptimalDial Identity**, which judges whether each number belongs to the contact named on that row and reports it alongside answer intent. Identity is in **public beta** — the output format is stable while we tune the thresholds, and feedback is very welcome at support@optimaldial.com. All endpoints require an API key as `Authorization: Bearer od_live_...`. Keys are minted in the in-app developer panel by an organization owner. See the human-readable docs at https://docs.optimaldial.com for quickstarts, the webhook signature verifier, and the changelog. contact: name: OptimalDial Support email: support@optimaldial.com url: https://docs.optimaldial.com license: name: Proprietary servers: - url: https://api.optimaldial.com description: Production security: - bearerAuth: [] tags: - name: uploads description: Submit, inspect, and download phone-number lists. - name: contacts description: > Single-contact API for per-row enrichment integrations. Available to every account with an API key. **Use `/api/v2/contacts`** — it mirrors every v1 route and additionally reports the nine-tier `OptimalDial_Status` and the OptimalDial Identity band. `/api/v1/contacts` is **legacy**: supported indefinitely with no removal planned, but its `optimaldial_status` reports the Answer Intent value only, so existing filters keep working untouched. Both versions operate on the same contacts — a contact created on either can be read on either, so moving to v2 needs no migration. Each `standard` contact is charged 1 credit; `max` contacts are billed so a batch totals `ceil(1.5 × count)` credits. Result is delivered via per-contact callback URL or registered webhook endpoints, and is also available via GET. - name: webhooks description: Register and manage webhook endpoints; inspect delivery history. - name: spam description: | Monitor your outbound numbers for spam/scam-likely flagging across the major US carriers (AT&T, T-Mobile, Verizon). Adding a number auto-initiates verification — required for the monitoring service to place test calls, not a security gate — and once the code is submitted OptimalDial re-tests daily, exposing per-carrier status, run history, and screenshots. Subscribe to the `spam.detected` and `number.verified` webhook events to be notified the moment a number flips to spam. Available to every account with an API key and an active subscription. - name: credits description: | Check your organization's current credit balance. Read-only and available to every account with an API key. paths: /api/v2/contacts: get: tags: - contacts summary: List contacts description: | The same contacts as `GET /api/v1/contacts`, reporting the nine-tier `OptimalDial_Status` plus the OptimalDial Identity band. A contact only carries identity when the batch it was processed in had name columns mapped. operationId: listContactsV2 parameters: - name: status in: query required: false schema: type: string enum: - queued - materialized - completed - failed - discarded - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query required: false description: Pass `next_cursor` from the previous response. schema: type: string responses: '200': description: Page of contacts, newest first. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ContactV2' next_cursor: type: - string - 'null' '401': $ref: '#/components/responses/Unauthorized' components: schemas: ContactV2: type: object description: > The v2 view of a contact. Identical to `Contact` except for what a completed result reports: | Field | v1 | v2 | |---|---|---| | `optimaldial_status` | `"Likely Answer"` | `"1 - Likely Right-Party Answer"` | | `optimaldial_answer_intent` | — | `"Likely Answer"` | | `optimaldial_identity` | — | `"Very High"` | allOf: - $ref: '#/components/schemas/Contact' - type: object properties: optimaldial_status: type: - string - 'null' description: >- The nine-tier `OptimalDial_Status` value. Falls back to the Answer Intent value for contacts processed before identity. example: 1 - Likely Right-Party Answer optimaldial_answer_intent: type: - string - 'null' description: Whether the number is likely to pick up, on its own. example: Likely Answer optimaldial_identity: type: - string - 'null' enum: - Very High - High - Medium - Low - Unknown - null description: >- How strongly the signals indicate the number belongs to your contact. Null when the batch had no name columns mapped. Note `Unknown` means no signal either way — it is not "safe". Contact: type: object required: - id - organization_id - phone - properties - status - credits_charged - created_at - updated_at properties: id: type: string format: uuid organization_id: type: string format: uuid phone: type: string description: E.164-normalized phone number (US/CA only). example: '+15551234567' properties: type: object additionalProperties: true description: Arbitrary extra fields echoed back from creation. status: type: string enum: - queued - processing - completed - failed - discarded optimaldial_status: type: - string - 'null' description: | The Answer Intent classification — e.g. `"Likely Answer"`, `"Likely Voicemail"`. Populated when `status == "completed"`. This field is **frozen on v1**: it keeps returning the Answer Intent value even for contacts processed with OptimalDial Identity, so existing filters keep working. Use `/api/v2/contacts` for the nine-tier status and the identity band. error_message: type: - string - 'null' validation_tier: type: string enum: - standard - max description: Validation pricing tier this contact was created with. credits_charged: type: integer minimum: 0 created_at: type: string format: date-time updated_at: type: string format: date-time ErrorEnvelope: type: object required: - detail properties: detail: oneOf: - type: string - type: object responses: Unauthorized: description: Missing or invalid API key. headers: WWW-Authenticate: schema: type: string example: Bearer content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: od_live_xxxxxxxx description: > OptimalDial API key, prefixed `od_live_`, sent as `Authorization: Bearer ...`. Mint keys in the in-app developer panel; they are scoped to a single organization. ````