API za pozivnice ispitanika

Pozivnice ispitanika omogućuju vašim sustavima da poznate osobe pozovu na intervju. Izradite osobnu poveznicu za korisnika s pridruženom e-adresom ili ID-jem računa, pošaljite je kako god želite, a odgovori su od početka povezani s tim korisnikom.

Potrebni su vam paket Pro, Business ili Enterprise i API ključ. Ključeve i autentifikaciju opisuje Pregled API-ja.

Rezultate čitajte putem API-ja za razgovore: svaki razgovor sadrži svoj invite i identitete koje ste pridružili.

Izrada pozivne poveznice#

POST /api/v1/respondent-invites

Svaki zahtjev izrađuje jednu poveznicu za jednog ispitanika u jednom projektu. Diaform odmah izrađuje i razgovor te mu pridružuje identitete koje pošaljete, pa su rezultati od početka povezani s tom osobom.

Tijelo zahtjeva#

Kad pošaljete send_email, odgovor sadrži objekt email: { "status": "sent" }, { "status": "failed" } ili { "status": "skipped", "reason": "..." }. Pozivnica se izrađuje u svakom slučaju. Razlozi su no_email, unsubscribed, not_published, no_usage, monthly_limit (mjesečno ograničenje e-poruka s pozivnicama u vašem paketu je iskorišteno), answered, already_sent, in_progress, plan i not_found. Što e-poruka sadrži, pogledajte u članku Prepoznavanje ispitanika.

Uobičajene vrste su email, name, identifier, user_id i account_id. Radi svaka vrsta koja poštuje pravila.

Primjer#

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

Odgovor#

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

Kako se poveznica ponaša#

1. Izrađena. Pozivnica je pending, a njezin razgovor invited.
2. Otvorena. Kad ispitanik otvori poveznicu, oboje postaje opened. Razgovor prelazi u started čim ispitanik odgovori.
3. Nastavljena. Ako ispitanik ode i vrati se istom poveznicom, nastavlja isti razgovor.
4. Završena. Kad razgovor završi, bilo kao dovršen ili otkazan, pozivnica postaje completed i poveznica prestaje raditi.

Projekt mora biti objavljen da bi se poveznica otvorila. Poveznice rade i za projekte s načinom Javna poveznica i za one s načinom Samo pozivne poveznice. Na javnim projektima i obična poveznica nastavlja raditi. Pogledajte Prepoznavanje ispitanika.

Starija krajnja točka za razgovore#

GET /api/v1/respondent-conversations

Ova krajnja točka vraća popis razgovora projekta i još uvijek radi, pa postojeće integracije ne treba mijenjati. Za novi razvoj koristite Popis razgovora, koji dodaje filtre, transkripte i jednostavnije straničenje.

Vraća conversations (svaki s conversation_id, created_at, status, respondent_email, metadata, identities, summary i invite) i nextCursor, objekt s created_at i id, ili null na zadnjoj stranici. Te dvije vrijednosti pošaljite natrag kao cursor i cursorId.

Pogreške#

Pogreške vraćaju JSON s porukom error i vrijednošću code, kao i u ostatku API-ja. Odgovor 400 sadrži i details.fieldErrors, koji navodi polje s pogreškom.

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

Ograničenja#

Ove dvije krajnje točke nemaju ograničenje broja zahtjeva. Svaka pozivnica prima najviše 10 identiteta (po jedan za svaku vrstu), a svaka organizacija može imati najviše 10 API ključeva.