Respondentuitnodigingen-API

Met respondentuitnodigingen kunnen je eigen systemen bekende mensen uitnodigen voor een interview. Maak een persoonlijke link voor een klant met diens e-mailadres of account-ID erin en verstuur die zoals je wilt. De antwoorden zijn dan vanaf het begin aan die klant gekoppeld.

Je hebt een Pro-, Business- of Enterprise-abonnement en een API-sleutel nodig. Zie het API-overzicht voor sleutels en authenticatie.

Gebruik de Gesprekken-API om de resultaten te lezen: elk gesprek bevat zijn invite en de identiteiten die je hebt gekoppeld.

Een uitnodigingslink maken#

POST /api/v1/respondent-invites

Elk request maakt één link voor één respondent in één project. Diaform maakt ook meteen het gesprek aan en koppelt de identiteiten die je meestuurt, zodat de resultaten vanaf het begin aan die persoon gekoppeld zijn.

Request-body#

Stuur je send_email mee, dan bevat de response een email-object: { "status": "sent" }, { "status": "failed" } of { "status": "skipped", "reason": "..." }. De uitnodiging wordt in alle gevallen gemaakt. De redenen zijn no_email, unsubscribed, not_published, no_usage, monthly_limit (de maandelijkse uitnodigingsmails van je abonnement zijn op), answered, already_sent, in_progress, plan en not_found. Zie Respondenten identificeren voor wat er in de e-mail staat.

Veelgebruikte types zijn email, name, identifier, user_id en account_id. Elk type dat aan de regels voldoet, werkt.

Voorbeeld#

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

Response#

{
  "organization_id": "4d6ecdb4-8543-4adf-ae65-1f24106d5474",
  "agent_id": "b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d",
  "agent_name": "Onboarding interviews",
  "invite": {
    "id": "3a4f49c7-b8f4-4c44-8f74-fd8e4277c3e4",
    "created_at": "2026-05-07T12:00:00.123456+00:00",
    "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.123456+00:00",
        "conversation_id": "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
        "source": "owner",
        "identity_type": "email",
        "value": "alex@acme.com",
        "metadata": {}
      },
      {
        "id": "120feee2-a10e-4b9a-af8e-a54d4dd672a1",
        "created_at": "2026-05-07T12:00:00.123456+00:00",
        "conversation_id": "0f8d43a2-6df9-49c8-bf5d-fd2b6ec2d9ee",
        "source": "owner",
        "identity_type": "account_id",
        "value": "acct_4821",
        "metadata": {}
      }
    ],
    "url": "https://acme.diaform.io/c/b8acb3ab-1f3d-4a7e-a846-b7f493f86b6d?invite=dia_resp_pCaJHykjUYBKZdkbVUtbyZRMC3yFzm246SK2K8lw"
  }
}

Hoe de link werkt#

1. Aangemaakt. De uitnodiging is pending en het gesprek is invited.
2. Geopend. Als de respondent de link opent, worden beide opened. Het gesprek gaat naar started zodra hij antwoordt.
3. Hervat. Gaat de respondent weg en komt hij terug via dezelfde link, dan gaat hij verder in hetzelfde gesprek.
4. Beëindigd. Als het gesprek eindigt, afgerond of geannuleerd, wordt de uitnodiging completed en werkt de link niet meer.

Het project moet gepubliceerd zijn om de link te kunnen openen. Links werken zowel bij projecten met Openbare link als met Alleen uitnodigingslinks. Bij openbare projecten blijft de gewone link ook werken. Zie Respondenten identificeren.

Ouder endpoint voor gesprekken#

GET /api/v1/respondent-conversations

Dit endpoint haalt de gesprekken van een project op en werkt nog steeds, dus bestaande integraties hoeven niet te veranderen. Gebruik voor nieuw werk Gesprekken ophalen. Dat voegt filters, transcripten en eenvoudigere paginering toe.

Het geeft conversations terug (elk met conversation_id, created_at, status, respondent_email, metadata, identities, summary en invite) en nextCursor, een object met created_at en id, of null op de laatste pagina. Stuur die twee waarden terug als cursor en cursorId.

Fouten#

Fouten geven JSON terug met een error-melding en een code, net als in de rest van de API. Een 400 bevat ook details.fieldErrors, dat het veld noemt waar het misging.

{
  "error": "Invalid request",
  "code": "invalid_request",
  "details": {
    "formErrors": [],
    "fieldErrors": {
      "identities": ["Add at least one respondent identity."]
    }
  }
}

Limieten#

Deze twee endpoints hebben geen ratelimit. Elke uitnodiging kan maximaal 10 identiteiten bevatten (één per type), en elke organisatie kan maximaal 10 API-sleutels hebben.