Respondent Invite API

Use this endpoint to create one or more targeted respondent links for a single Diaform project.

Endpoint#

POST /api/v1/respondent-invites

Authentication#

Use an organization API key in the Authorization header:

Authorization: Bearer dia_org_live_...

This endpoint is intended for invite-only projects. If the project is still using the public access mode, Diaform returns 409.

Request Body#

{
  "agentId": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
  "invites": [
    {
      "invitee_email": "alex@acme.com",
      "external_user_id": "user_123",
      "external_account_id": "account_456",
      "metadata": {
        "plan": "enterprise",
        "segment": "beta",
        "language": "en"
      }
    }
  ]
}

Response#

{
  "organization_id": "4d6ecdb4-8543-4adf-ae65-1f24106d5474",
  "agent_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
  "agent_name": "Churn Interview",
  "created": 1,
  "invites": [
    {
      "id": "3a4f49c7-b8f4-4c44-8f74-fd8e4277c3e4",
      "created_at": "2026-05-07T12:00:00.000Z",
      "invitee_email": "alex@acme.com",
      "external_user_id": "user_123",
      "external_account_id": "account_456",
      "metadata": {
        "plan": "enterprise",
        "segment": "beta",
        "language": "en"
      },
      "status": "pending",
      "expires_at": null,
      "opened_at": null,
      "completed_at": null,
      "conversation_id": null,
      "url": "https://acme.diaform.io/c/b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d?invite=dia_resp_..."
    }
  ]
}

Notes#

• Create up to 100 respondent links per request.
• Each link is tied to exactly one project.
• The same link resumes the same conversation until the conversation is completed.
• Once the conversation is completed, the link stops working.
• metadata must be a JSON object.

cURL Example#

curl -X POST https://diaform.io/api/v1/respondent-invites \
  -H "Authorization: Bearer dia_org_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
    "invites": [
      {
        "invitee_email": "alex@acme.com",
        "external_user_id": "user_123",
        "external_account_id": "account_456",
        "metadata": {
          "plan": "enterprise",
          "segment": "beta"
        }
      }
    ]
  }'