Respondent Conversations API

Use this endpoint to fetch conversation records for a Uncovia project, including summary data and invite lifecycle metadata when a conversation was started from an invite link.

Endpoint#

GET /api/v1/respondent-conversations

Authentication#

Use an organization API key in the Authorization header:

Authorization: Bearer dia_org_live_...

Query Parameters#

• agentId (required)
• limit (optional, default 50, max 100)
• status (optional): invited, opened, started, completed, cancelled
• cursor and cursorId for pagination

Example Request#

GET /api/v1/respondent-conversations?agentId=b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d&status=completed&limit=25

Response#

{
  "organization_id": "4d6ecdb4-8543-4adf-ae65-1f24106d5474",
  "agent_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
  "conversations": [
    {
      "conversation_id": "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
      "created_at": "2026-05-07T12:15:41.000Z",
      "status": "completed",
      "respondent_email": "alex@acme.com",
      "metadata": {},
      "identities": [
        {
          "id": "71138f36-d16a-41f8-8a1f-65b9b8d483e3",
          "created_at": "2026-05-07T12:00:00.000Z",
          "conversation_id": "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
          "source": "owner",
          "identity_type": "email",
          "value": "alex@acme.com"
        }
      ],
      "summary": {
        "overall_sentiment": "positive",
        "respondent_email": null,
        "respondent_identities": [
          { "type": "email", "value": "alex@acme.com" }
        ],
        "answers": []
      },
      "invite": {
        "id": "3a4f49c7-b8f4-4c44-8f74-fd8e4277c3e4",
        "status": "completed",
        "created_at": "2026-05-07T12:00:00.000Z",
        "opened_at": "2026-05-07T12:01:11.000Z",
        "completed_at": "2026-05-07T12:15:41.000Z"
      }
    }
  ],
  "nextCursor": null
}

cURL Example#

curl "https://uncovia.com/api/v1/respondent-conversations?agentId=b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d&status=completed&limit=25" \
  -H "Authorization: Bearer dia_org_live_..."

Notes#

• Pagination is descending by created_at.
• The response includes both the conversation payload and the invite lifecycle metadata.
• Invited conversations can appear with status: "invited" before the respondent opens the link.
• identities contains owner-provided, system-collected, and AI-extracted respondent identifiers that are safe to show in exports and integrations.
• Internal embed session identifiers are used only for resume behavior and are not returned by this API.