Respondentinvitasjons-API

Med respondentinvitasjoner kan dine egne systemer invitere kjente personer til et intervju. Lag en personlig lenke for en kunde med e-postadressen eller konto-ID-en knyttet til, send den slik du vil, så er svarene knyttet til den kunden fra starten av.

Du trenger planen Pro, Business eller Enterprise og en API-nøkkel. Se API-oversikten for nøkler og autentisering.

For å lese resultatene bruker du Samtale-API-et: hver samtale inneholder invite og identitetene du knyttet til den.

Lag en invitasjonslenke#

POST /api/v1/respondent-invites

Hver forespørsel lager én lenke for én respondent i ett prosjekt. Diaform lager også samtalen med en gang og knytter til identitetene du sender, så resultatene er koblet til den personen fra starten av.

Innhold i forespørselen#

Når du sender send_email, har svaret et email-objekt: { "status": "sent" }, { "status": "failed" } eller { "status": "skipped", "reason": "..." }. Invitasjonen opprettes uansett. Årsakene er no_email, unsubscribed, not_published, no_usage, monthly_limit (planens månedlige invitasjoner på e-post er brukt opp), answered, already_sent, in_progress, plan og not_found. Se Identifiser respondenter for hva e-posten inneholder.

Vanlige typer er email, name, identifier, user_id og account_id. Alle typer som følger reglene, fungerer.

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

Slik oppfører lenken seg#

1. Opprettet. Invitasjonen er pending, og samtalen er invited.
2. Åpnet. Når respondenten åpner lenken, blir begge opened. Samtalen går over til started når respondenten svarer.
3. Gjenopptatt. Hvis respondenten går og kommer tilbake via samme lenke, fortsetter respondenten den samme samtalen.
4. Avsluttet. Når samtalen er over, enten den er fullført eller avbrutt, blir invitasjonen completed, og lenken slutter å virke.

Prosjektet må være publisert for at lenken skal åpnes. Lenkene fungerer for prosjekter med både Offentlig lenke og Kun invitasjonslenker. På offentlige prosjekter fortsetter også den vanlige lenken å virke. Se Identifiser respondenter.

Eldre endepunkt for samtaler#

GET /api/v1/respondent-conversations

Dette endepunktet lister opp samtalene i et prosjekt og virker fortsatt, så eksisterende integrasjoner trenger ikke å endres. For nytt arbeid bruker du List opp samtaler, som legger til filtre, transkripsjoner 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 siste siden. Send de to verdiene tilbake som cursor og cursorId.

Feil#

Feil returnerer JSON med en error-melding og en code, som i resten av API-et. En 400 har også details.fieldErrors, som oppgir feltet som feilet.

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

Grenser#

Disse to endepunktene har ingen grense for antall forespørsler. Hver invitasjon tar opptil 10 identiteter (én per type), og hver organisasjon kan ha opptil 10 API-nøkler.