API pre pozvánky respondentov

Pozvánky respondentov umožňujú vašim systémom pozvať na rozhovor konkrétnych ľudí. Vytvorte pre zákazníka osobný odkaz s pripojeným e-mailom alebo ID účtu, pošlite ho akýmkoľvek spôsobom a jeho odpovede sú s týmto zákazníkom prepojené od začiatku.

Potrebujete plán Pro, Business alebo Enterprise a API kľúč. Kľúče a overenie opisuje Prehľad API.

Výsledky načítate cez API pre rozhovory: každý rozhovor obsahuje svoj invite a identity, ktoré ste pripojili.

Vytvorenie odkazu na pozvanie#

POST /api/v1/respondent-invites

Každá požiadavka vytvorí jeden odkaz pre jedného respondenta v jednom projekte. Diaform zároveň hneď vytvorí rozhovor a pripojí identity, ktoré pošlete, takže výsledky sú s danou osobou prepojené od začiatku.

Telo požiadavky#

Keď pošlete send_email, odpoveď obsahuje objekt email: { "status": "sent" }, { "status": "failed" } alebo { "status": "skipped", "reason": "..." }. Pozvánka sa vytvorí v každom prípade. Dôvody sú no_email, unsubscribed, not_published, no_usage, monthly_limit (mesačný limit e-mailov s pozvánkami vo vašom pláne je vyčerpaný), answered, already_sent, in_progress, plan a not_found. Čo e-mail obsahuje, nájdete v časti Identifikácia respondentov.

Bežné typy sú email, name, identifier, user_id a account_id. Funguje akýkoľvek typ, ktorý spĺňa pravidlá.

Príklad#

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

Odpoveď#

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

Ako sa odkaz správa#

1. Vytvorený. Pozvánka je pending a jej rozhovor je invited.
2. Otvorený. Keď respondent otvorí odkaz, pozvánka aj rozhovor prejdú na opened. Rozhovor prejde na started, keď respondent odpovie.
3. Obnovený. Ak respondent odíde a vráti sa cez ten istý odkaz, pokračuje v tom istom rozhovore.
4. Skončený. Keď sa rozhovor skončí, či už dokončením alebo zrušením, pozvánka sa zmení na completed a odkaz prestane fungovať.

Aby sa odkaz otvoril, projekt musí byť zverejnený. Odkazy fungujú pri projektoch v režime Verejný odkaz aj Odkazy len na pozvanie. Pri verejných projektoch funguje ďalej aj bežný odkaz. Viac v časti Identifikácia respondentov.

Starší endpoint pre rozhovory#

GET /api/v1/respondent-conversations

Tento endpoint vypisuje rozhovory projektu a funguje ďalej, takže existujúce integrácie nemusíte meniť. Pre nové integrácie použite Zoznam rozhovorov, ktorý pridáva filtre, prepisy a jednoduchšie stránkovanie.

Vracia conversations (každý s conversation_id, created_at, status, respondent_email, metadata, identities, summary a invite) a nextCursor, objekt s created_at a id, alebo null na poslednej stránke. Tieto dve hodnoty pošlite späť ako cursor a cursorId.

Chyby#

Chyby vracajú JSON so správou error a kódom code, rovnako ako vo zvyšku API. Odpoveď 400 obsahuje aj details.fieldErrors, kde je uvedené pole, ktoré neprešlo kontrolou.

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

Limity#

Tieto dva endpointy nemajú limit počtu požiadaviek. Každá pozvánka prijme najviac 10 identít (jedna z každého typu) a každá organizácia môže mať najviac 10 API kľúčov.