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

# ListVoiceWidgetConversationsAPI mirrors erdo_voice_widget_conversation_list.
The optional widget


> handle, since/until window and paging ride the query string; the organization comes from the caller's identity. Each row carries the lead produced: \`contact\` (null = not analysed, {} = nobody reachable), \`lead\_status\`, \`lead\_saved\_at\`, and \`canonical\_lead\_id\` / \`lead\_reference\`; the \`canonical\_lead\_id\` parameter narrows to one lead.




## OpenAPI

````yaml /api/openapi.json get /v1/voice/calls
openapi: 3.0.0
info:
  title: Erdo API
  description: >-
    Erdo's REST API: query and write datasets, run agents, manage threads,
    integrations, pages, evals, workstreams, experiments, and bounded outreach.
    Authenticate with a Bearer API key (erdo_api_...) or scoped token
    (erdo_token_...).
  version: '2026-11-21'
servers:
  - url: https://api.erdo.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/voice/calls:
    get:
      summary: >
        ListVoiceWidgetConversationsAPI mirrors
        erdo_voice_widget_conversation_list.

        The optional widget
      description: >
        handle, since/until window and paging ride the query string; the
        organization comes from the caller's identity. Each row carries the lead
        produced: \`contact\` (null = not analysed, {} = nobody reachable),
        \`lead\_status\`, \`lead\_saved\_at\`, and \`canonical\_lead\_id\` /
        \`lead\_reference\`; the \`canonical\_lead\_id\` parameter narrows to
        one lead.
      operationId: GET:mcp.ListVoiceCallsAPI
      parameters:
        - allowEmptyValue: true
          explode: true
          in: query
          name: agent
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: direction
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: since
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: until
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: limit
          required: false
          schema:
            format: int64
            type: integer
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: offset
          required: false
          schema:
            format: int64
            type: integer
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: cursor
          required: false
          schema:
            type: string
          style: form
        - allowEmptyValue: true
          explode: true
          in: query
          name: canonical_lead_id
          required: false
          schema:
            type: string
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  conversations:
                    items:
                      $ref: '#/components/schemas/voice.CallConversationSummary'
                    type: array
                  count:
                    format: int64
                    type: integer
                  limit:
                    format: int64
                    type: integer
                  next_cursor:
                    type: string
                  offset:
                    format: int64
                    type: integer
                  organization_slug:
                    description: |
                      or the client the request named.
                    title: >
                      OrganizationSlug is the organization the calls belong to:
                      the caller's own,
                    type: string
                  total:
                    description: >
                      canonical\_lead\_id, since/until) at the moment of THIS
                      request, read in the same snapshot as this page and
                      independent of limit/offset/cursor — the same field the
                      widget conversation list carries. It is live: a call
                      captured between two page requests changes it, so a walk
                      across pages is complete when next\_cursor is absent,
                      never when the rows collected reach Total. It is what a
                      reporting tile counts without fetching every row.
                    format: int64
                    title: >
                      Total is how many calls match the filter (agent,
                      direction,
                    type: integer
                type: object
          description: Success response
        default:
          $ref: '#/components/responses/APIError'
components:
  schemas:
    voice.CallConversationSummary:
      description: >
        whether a transcript was captured, never the transcript payload itself
        (the list query does not select transcript\_json — TOAST discipline).
      properties:
        booked_at:
          description: >
            in-call booking tool created the calendar event and recorded it —
            and BookedStart is the slot that was booked. Both describe the
            newest such booking: a person who rebooks on the call booked twice,
            and the second is the meeting they hold. BookedAt is null when
            nothing was booked; BookedStart is also null for a booking whose
            start the tool could not read. They ride the list so a reader learns
            of the meeting the moment it is made, rather than when the
            conversation-leads pipeline next copies it onto the lead row.
          format: date-time
          title: >
            BookedAt is when a meeting was booked DURING this call — the moment
            the
          type: string
        booked_start:
          format: date-time
          type: string
        call_id:
          type: string
        call_successful:
          type: string
        canonical_lead_id:
          description: >
            the id to match a lead page on, rather than the caller's number.
            Empty while the call awaits its write, when the lead dataset is not
            enrolled in lead identity, when capture was off, and on every call
            recorded before conversations carried the identity (there is no
            backfill).
          title: >
            CanonicalLeadID is the permanent lead this call's lead write
            resolved to —
          type: string
        consent_basis:
          type: string
        contact:
          allOf:
            - $ref: '#/components/schemas/leadcontact.Contact'
          description: >
            transcript and the carrier-verified caller ID. Deliberately NOT
            omitempty: null means "not analysed yet" and {} means "analysed,
            nobody reachable" — different facts, and only inbound calls are ever
            analysed at all.
          title: >
            Contact is what the caller gave, extracted by the summary cron from
            the
          nullable: true
        created_at:
          format: date-time
          type: string
        dial_outcome:
          description: >
            canceled (canceled means the lead was never dialled because the
            person did not answer their own phone or press 1). Answered,
            voicemail and no\_answer all have status \`completed\`, so this
            field tells them apart; an AI call that never connected carries
            no\_answer | busy | failed | canceled, and one with no ending
            carries Erdo's best guess. Empty on inbound calls, calls not yet
            ended and AI calls from before outcomes were recorded. It is
            separate from \`status\`, which describes the record.
          title: >
            DialOutcome is what became of the LEAD's leg: answered | voicemail |
            no_answer |

            busy | failed |
          type: string
        direction:
          description: |
            (Erdo placed the call).
          title: >
            Direction is "inbound" (someone called the agent's number) or
            "outbound"
          type: string
        duration_seconds:
          format: int32
          maximum: 2147483647
          minimum: -2147483648
          type: integer
        ended_at:
          format: date-time
          type: string
        from_number:
          description: >
            inbound call, and the agent's own caller ID on an outbound one.
            Empty on rows written before the column existed.
          title: |
            FromNumber is the line the call came FROM: the caller's number on an
          type: string
        has_transcript:
          type: boolean
        lead_reference:
          description: |
            link or an SMS carries; empty exactly when CanonicalLeadID is.
          title: >
            LeadReference is the same identity as a 22-character reference, the
            form a
          type: string
        lead_saved_at:
          format: date-time
          title: |
            LeadSavedAt is when that outcome was recorded, null while awaiting.
          type: string
          nullable: true
        lead_status:
          description: >
            awaiting one, then created | existing | disabled | refused | test,
            or no\_booking for an outbound call that ended without a meeting
            booked on it.
          title: >
            LeadStatus is what the lead writer did with this call: "" while it
            is still
          type: string
        lead_turns:
          description: >
            something, counted from the transcript. Only filled when the list
            was asked WithLeadTurns; 0 otherwise. A voicemail greeting is one
            turn, a person who picks up and talks is more; the provider's
            silence marker ("...", the pause after a beep) is not a turn
            (spokenLeadTurnMessages).
          format: int64
          title: |
            LeadTurns is how many times the other side of an outbound call said
          type: integer
        placed_by_name:
          description: >
            from the Call button on a lead carries the name of whoever pressed
            it, and every AI-placed and inbound call leaves it empty. It is what
            turns a row in the list into "Called by Ana".
          title: >
            PlacedByName is the person who placed this call, when a person did:
            a call
          type: string
        provider_agent_id:
          description: >
            Recorded on inbound rows (it is their ownership handle); empty on
            older outbound rows, which predate the column.
          title: >
            ProviderAgentID identifies the voice agent that held the
            conversation.
          type: string
        recipient_name:
          type: string
        status:
          type: string
        to_number:
          title: >
            ToNumber is the number dialled — the agent's own number on an
            inbound call.
          type: string
        transcript_summary:
          type: string
      title: |
        CallConversationSummary is one row of an org's call list: metadata and
      type: object
    leadcontact.Contact:
      description: >
        dataset has columns for; there is deliberately no company. EmailCheck
        and NameCheck say how the person gave the value beside them (a Check\*
        constant) and EmailAlternative is the other form of the address when the
        person's spelling and what was heard disagree. They are evidence about
        the values, so they travel with the value they describe (Merge) and are
        blank whenever it is. A conversation extracted before they existed
        carries none, which reads as "not recorded", never "unconfirmed".
      properties:
        email:
          type: string
        email_alternative:
          type: string
        email_check:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        name_check:
          type: string
        phone:
          type: string
      title: >
        Contact is what a person told us about themselves. The four value fields
        are the

        ones the leads
      type: object
  responses:
    APIError:
      content:
        application/json:
          schema:
            externalDocs:
              url: https://pkg.go.dev/encore.dev/beta/errs#Error
            properties:
              code:
                description: Error code
                example: not_found
                externalDocs:
                  url: https://pkg.go.dev/encore.dev/beta/errs#ErrCode
                type: string
              details:
                description: Error details
                type: object
              message:
                description: Error message
                type: string
            title: APIError
            type: object
      description: Error response
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An Erdo API key (erdo_api_...) or scoped token (erdo_token_...).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.