Respondent Invite API

Use this endpoint to create one targeted respondent link for a single Uncovia project. Creating an invite also creates the conversation record in advance and attaches the identities you provide.

Endpoint#

POST /api/v1/respondent-invites

Authentication#

Use an organization API key in the Authorization header:

Authorization: Bearer dia_org_live_...

This endpoint works for both Public link and Invite-only links projects. On public projects, invite links pre-attach identities while the normal public link remains available.

Request Body#

{
  "agentId": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
  "identities": [
    { "type": "email", "value": "alex@acme.com" },
    { "type": "name", "value": "Alex Morgan" },
    { "type": "identifier", "value": "customer-123" }
  ]
}

Response#

{
  "organization_id": "4d6ecdb4-8543-4adf-ae65-1f24106d5474",
  "agent_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
  "agent_name": "Churn Interview",
  "invite": {
    "id": "3a4f49c7-b8f4-4c44-8f74-fd8e4277c3e4",
    "created_at": "2026-05-07T12:00:00.000Z",
    "status": "pending",
    "opened_at": null,
    "completed_at": null,
    "conversation_id": "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
    "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"
      }
    ],
    "url": "https://acme.uncovia.com/c/b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d?invite=dia_resp_..."
  }
}

Notes#

• Create one respondent link per request.
• Each link is tied to exactly one project.
• Each request must include at least one identity.
• Supported identity examples include email, name, identifier, uuid, user_id, and account_id.
• The same link resumes the same conversation until the conversation is completed.
• Once the conversation is completed, the link stops working.

cURL Example#

curl -X POST https://uncovia.com/api/v1/respondent-invites \
  -H "Authorization: Bearer dia_org_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
    "identities": [
      { "type": "email", "value": "alex@acme.com" },
      { "type": "name", "value": "Alex Morgan" }
    ]
  }'