Respondentinvitations-API

Med respondentinvitationer kan dine egne systemer invitere kendte personer til et interview. Opret et personligt link til en kunde med kundens e-mail eller konto-ID knyttet til, send det, som du vil, og så er svarene knyttet til kunden fra start.

Du skal bruge en Pro-, Business- eller Enterprise-plan og en API-nøgle. Se API-overblikket for nøgler og godkendelse.

Brug Samtale-API'et til at læse resultaterne: hver samtale indeholder sin invite og de identiteter, du har knyttet til den.

Opret et invitationslink#

POST /api/v1/respondent-invites

Hver forespørgsel opretter ét link til én respondent i ét projekt. Diaform opretter også samtalen med det samme og knytter de identiteter, du sender, til den, så resultaterne hører til personen fra start.

Body i forespørgslen#

Når du sender send_email, indeholder svaret et email-objekt: { "status": "sent" }, { "status": "failed" } eller { "status": "skipped", "reason": "..." }. Invitationen oprettes i alle tilfælde. Årsagerne er no_email, unsubscribed, not_published, no_usage, monthly_limit (din plans månedlige invitationsmails er brugt op), answered, already_sent, in_progress, plan og not_found. Se Identifikation af respondenter for at se, hvad e-mailen indeholder.

Almindelige typer er email, name, identifier, user_id og account_id. Alle typer, der følger reglerne, virker.

Eksempel#

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" }
    ]
  }'

Svar#

{
  "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"
  }
}

Sådan opfører linket sig#

1. Oprettet. Invitationen er pending, og dens samtale er invited.
2. Åbnet. Når respondenten åbner linket, bliver begge opened. Samtalen skifter til started, så snart respondenten svarer.
3. Genoptaget. Hvis respondenten går og kommer tilbage via samme link, fortsætter vedkommende den samme samtale.
4. Afsluttet. Når samtalen slutter, uanset om den er gennemført eller annulleret, bliver invitationen completed, og linket holder op med at virke.

Projektet skal være udgivet, for at linket kan åbne. Links virker for projekter med både Offentligt link og Kun invitationslinks. På offentlige projekter virker det normale link også fortsat. Se Identifikation af respondenter.

Ældre endpoint til samtaler#

GET /api/v1/respondent-conversations

Dette endpoint viser et projekts samtaler og virker stadig, så eksisterende integrationer behøver ikke at blive ændret. Til nyt arbejde skal du bruge Vis samtaler, som tilføjer filtre, transskriptioner og enklere paginering.

Det returnerer conversations (hver med conversation_id, created_at, status, respondent_email, metadata, identities, summary og invite) og nextCursor, et objekt med created_at og id, eller null på den sidste side. Send de to værdier tilbage som cursor og cursorId.

Fejl#

Fejl returnerer JSON med en besked i error og en code, ligesom i resten af API'et. En 400 indeholder også details.fieldErrors, som angiver det felt, der fejlede.

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

Grænser#

Disse to endpoints har ingen grænse for antallet af forespørgsler. Hver invitation kan have op til 10 identiteter (én pr. type), og hver organisation kan have op til 10 API-nøgler.