Respondent Conversations API

Use this endpoint to fetch conversation records for a Diaform project, including the external identifiers and custom metadata that were attached at respondent-link creation time.

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): opened, started, completed, cancelled
• external_user_id (optional)
• external_account_id (optional)
• 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",
      "external_user_id": "user_123",
      "external_account_id": "account_456",
      "metadata": {
        "plan": "enterprise",
        "segment": "beta"
      },
      "summary": {
        "overall_sentiment": "positive",
        "respondent_email": "alex@acme.com",
        "answers": []
      },
      "invite": {
        "id": "3a4f49c7-b8f4-4c44-8f74-fd8e4277c3e4",
        "invitee_email": "alex@acme.com",
        "status": "completed",
        "created_at": "2026-05-07T12:00:00.000Z",
        "expires_at": null,
        "opened_at": "2026-05-07T12:01:11.000Z",
        "completed_at": "2026-05-07T12:15:41.000Z"
      }
    }
  ],
  "nextCursor": null
}

cURL Example#

curl "https://diaform.io/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.
• Use external_user_id and external_account_id to reconcile records with your own system.