> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cairhealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Phone Call: Retrieve Results

> Retrieve the outcomes of AI phone calls placed through the Cair platform. Returns only completed or failed calls — calls still in progress are excluded. Results are scoped to your organization based on your authentication token.

## Best Practices

* **Use date filters** to limit result sets. Querying without `dateFrom`/`dateTo` may return very large result sets that are slower to fetch.
* **Paginate efficiently** by using a `pageSize` of 50–100 and iterating through pages. Check `pagination.totalPages` to know when you've fetched all results.
* **Poll responsibly** if you are periodically checking for new results. A polling interval of 30–60 seconds is recommended. Use `dateFrom` set to your last poll timestamp to avoid re-fetching old results.
* **Filter by source** if you only care about calls placed through the API (`source=api`) versus calls placed from the Cair platform UI (`source=platform`).
* **Use `callId`** for single-call lookups instead of filtering a large result set — it's the most efficient way to check on a specific call.
* **Use `claimControlNumber`** to look up results for a specific claim; it matches either the payer's claim control number (ICN) or the claim control number from the call inputs. Combine with `dateFrom`/`dateTo` for faster queries.


## OpenAPI

````yaml GET /api/aiphonecall/v1/results
openapi: 3.1.0
info:
  title: Cair Health APIs
  description: APIs for the Cair Health platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://forecaster.cairhealth.com
security:
  - bearerAuth: []
paths:
  /api/aiphonecall/v1/results:
    get:
      description: >-
        Retrieve the outcomes of AI phone calls placed through the Cair
        platform. Returns only completed or failed calls — calls still in
        progress are excluded. Results are scoped to your organization based on
        your authentication token.
      parameters:
        - name: dateFrom
          in: query
          description: >-
            Only return calls completed on or after this date (inclusive, from
            00:00:00 UTC). Format: YYYY-MM-DD.
          required: false
          schema:
            type: string
            format: date
        - name: dateTo
          in: query
          description: >-
            Only return calls completed on or before this date (inclusive,
            through 23:59:59 UTC). Format: YYYY-MM-DD.
          required: false
          schema:
            type: string
            format: date
        - name: type
          in: query
          description: Filter by call type.
          required: false
          schema:
            type: string
            enum:
              - vob
              - custom_vob_aba
              - podiatry_vob
              - vob_rpm
              - denial
              - claim_status_inquiry
              - claim_status_wc
              - claim_status_auto_pip
              - custom_claim_status
              - prior_auth
              - prior_auth_cpt
              - prior_auth_status_nds
              - prior_auth_status_cpt
              - credentialing
              - credentialing_im
              - appeal
            description: >-
              vob = Verification of Benefits, custom_vob_aba = Custom VOB for
              ABA, podiatry_vob = Podiatry VOB, vob_rpm = VOB for Remote Patient
              Monitoring, denial = Denied Claim Follow-up, claim_status_inquiry
              = General Claim Status, claim_status_wc = Workers' Comp Claim
              Status, claim_status_auto_pip = Auto/PIP Claim Status,
              custom_claim_status = Custom Claim Status, prior_auth = Prior Auth
              (Drug-based), prior_auth_cpt = Prior Auth (CPT-based),
              prior_auth_status_nds = Prior Auth Status (NDS),
              prior_auth_status_cpt = Prior Auth Status (CPT), credentialing =
              Credentialing Inquiry, credentialing_im = Credentialing - IM,
              appeal = Appeal Call
        - name: status
          in: query
          description: Filter by outcome. Omit to return both completed and failed calls.
          required: false
          schema:
            type: string
            enum:
              - completed
              - failed
        - name: source
          in: query
          description: Filter by how the call was initiated.
          required: false
          schema:
            type: string
            enum:
              - platform
              - api
            description: platform = from the Cair UI, api = via the API
        - name: batchId
          in: query
          description: >-
            Filter by batch upload ID to retrieve results for a specific CSV
            batch.
          required: false
          schema:
            type: string
        - name: callId
          in: query
          description: Look up a specific call by its unique call ID.
          required: false
          schema:
            type: string
        - name: phoneNumber
          in: query
          description: Filter by the phone number that was called.
          required: false
          schema:
            type: string
        - name: claimControlNumber
          in: query
          description: >-
            Filter to calls where this value matches (case-insensitive) either
            the payer claim control number (ICN extracted from the call, e.g.
            for iMagnum) or the claim control number from the call inputs.
          required: false
          schema:
            type: string
        - name: page
          in: query
          description: Page number for pagination.
          required: false
          schema:
            type: integer
            default: 1
            minimum: 1
        - name: pageSize
          in: query
          description: Number of results per page.
          required: false
          schema:
            type: integer
            default: 50
            minimum: 1
            maximum: 200
        - name: sortOrder
          in: query
          description: Sort direction by completion date.
          required: false
          schema:
            type: string
            default: desc
            enum:
              - desc
              - asc
            description: desc = newest first, asc = oldest first
      responses:
        '200':
          description: Call results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CallResultsResponse'
              example:
                records:
                  - callId: abc123
                    type: vob
                    status: completed
                    phoneNumber: '+18005551234'
                    dateCreated: '2026-02-20T14:30:00.000Z'
                    dateCompleted: '2026-02-20T14:35:12.000Z'
                    results:
                      benefits_verified:
                        question: Are the benefits active?
                        answer: Yes, the benefits are active until December 31, 2026
                      copay_amount:
                        question: What is the copay amount for this service?
                        answer: The copay is $25 for office visits
                    formattedResults: >-
                      Benefits are active until 12/31/2026. Copay: $25 for
                      office visits.
                  - callId: def456
                    type: denial
                    status: failed
                    phoneNumber: '+18005559876'
                    dateCreated: '2026-02-20T15:00:00.000Z'
                    dateCompleted: '2026-02-20T15:05:30.000Z'
                    error: 'Call failed | Tag: call_denial_claim123 | ID: claim123'
                    errorDetails:
                      originalError: Call was disconnected after reaching IVR menu
                      internalTag: call_denial_claim123
                      internalId: claim123
                      timestamp: '2026-02-20T15:05:30.000Z'
                pagination:
                  totalRecords: 142
                  totalPages: 3
                  currentPage: 1
                  pageSize: 50
        '400':
          description: >-
            Invalid query parameters (e.g. malformed date, unsupported call
            type, page size exceeding 200)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: array
                    items:
                      type: object
                      properties:
                        code:
                          type: string
                        message:
                          type: string
                        path:
                          type: array
                          items:
                            type: string
              example:
                error: Invalid query parameters
                details:
                  - code: invalid_string
                    message: dateFrom must be YYYY-MM-DD
                    path:
                      - dateFrom
        '401':
          description: Bearer token is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized
        '500':
          description: Unexpected server-side error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unknown error occurred
      security:
        - bearerAuth: []
components:
  schemas:
    CallResultsResponse:
      type: object
      description: Paginated response containing call result records
      properties:
        records:
          type: array
          description: Array of call result objects
          items:
            $ref: '#/components/schemas/CallResultRecord'
        pagination:
          $ref: '#/components/schemas/CallResultPagination'
      required:
        - records
        - pagination
    Error:
      type: object
      properties:
        message:
          type: string
          description: Error message
    CallResultRecord:
      type: object
      description: >-
        A single call result record representing a completed or failed AI phone
        call
      properties:
        callId:
          type: string
          description: Unique identifier for the call
        type:
          type: string
          description: The call type (e.g. vob, denial, claim_status_inquiry)
        status:
          type: string
          enum:
            - completed
            - failed
          description: The call outcome
        phoneNumber:
          type: string
          description: The phone number that was called
        dateCreated:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the call was initiated
        dateCompleted:
          type: string
          format: date-time
          description: ISO 8601 timestamp of when the call finished (succeeded or failed)
        results:
          type: object
          description: >-
            Call results as a JSON object containing question-answer pairs from
            the AI conversation. Only present when status is completed.
          additionalProperties:
            type: object
            properties:
              question:
                type: string
              answer:
                type: string
        formattedResults:
          type: string
          description: >-
            A human-readable formatted version of the call results. Only present
            when status is completed.
        error:
          type: string
          description: >-
            A description of why the call failed. Only present when status is
            failed.
        errorDetails:
          $ref: '#/components/schemas/CallResultErrorDetails'
      required:
        - callId
        - type
        - status
        - phoneNumber
        - dateCreated
        - dateCompleted
    CallResultPagination:
      type: object
      description: Pagination metadata for call results
      properties:
        totalRecords:
          type: integer
          description: Total number of records matching your filters
        totalPages:
          type: integer
          description: Total number of pages available
        currentPage:
          type: integer
          description: The current page number
        pageSize:
          type: integer
          description: The number of records per page
      required:
        - totalRecords
        - totalPages
        - currentPage
        - pageSize
    CallResultErrorDetails:
      type: object
      description: >-
        Additional structured details about a failed call. Only present when
        status is failed.
      properties:
        originalError:
          type: string
          description: The original error message
        internalTag:
          type: string
          description: Internal tag for the failed call
        internalId:
          type: string
          description: Internal identifier for the failed call
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the failure
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````