Vastaajakutsu-API

Vastaajakutsujen avulla omat järjestelmäsi voivat kutsua tunnettuja henkilöitä haastatteluun. Luo asiakkaalle henkilökohtainen linkki, johon on liitetty hänen sähköpostiosoitteensa tai tilinsä ID, ja lähetä se haluamallasi tavalla, niin vastaukset on yhdistetty kyseiseen asiakkaaseen alusta asti.

Tarvitset Pro-, Business- tai Enterprise-paketin ja API-avaimen. Katso avaimet ja todennus sivulta API:n yleiskatsaus.

Lue tulokset Keskustelu-API:lla: jokaisessa keskustelussa on sen invite ja liittämäsi tunnisteet.

Luo kutsulinkki#

POST /api/v1/respondent-invites

Jokainen pyyntö luo yhden linkin yhdelle vastaajalle yhdessä projektissa. Diaform luo myös keskustelun saman tien ja liittää siihen lähettämäsi tunnisteet, joten tulokset on yhdistetty kyseiseen henkilöön alusta asti.

Pyynnön runko#

Kun lähetät send_email-kentän, vastauksessa on email-objekti: { "status": "sent" }, { "status": "failed" } tai { "status": "skipped", "reason": "..." }. Kutsu luodaan joka tapauksessa. Syitä ovat no_email, unsubscribed, not_published, no_usage, monthly_limit (pakettisi kuukauden kutsusähköpostit on käytetty), answered, already_sent, in_progress, plan ja not_found. Katso sähköpostin sisältö sivulta Vastaajien tunnistaminen.

Yleisiä tyyppejä ovat email, name, identifier, user_id ja account_id. Mikä tahansa säännöt täyttävä tyyppi toimii.

Esimerkki#

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

Vastaus#

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

Miten linkki toimii#

1. Luotu. Kutsun tila on pending ja sen keskustelun tila invited.
2. Avattu. Kun vastaaja avaa linkin, molempien tilaksi tulee opened. Keskustelun tila vaihtuu started-tilaan, kun vastaaja vastaa.
3. Jatkettu. Jos vastaaja poistuu ja palaa saman linkin kautta, hän jatkaa samaa keskustelua.
4. Päättynyt. Kun keskustelu päättyy, joko valmiina tai peruttuna, kutsun tilaksi tulee completed ja linkki lakkaa toimimasta.

Projektin on oltava julkaistu, jotta linkki aukeaa. Linkit toimivat projekteissa, joissa on valittuna joko Julkinen linkki tai Vain kutsulinkit. Julkisissa projekteissa myös tavallinen linkki toimii edelleen. Katso Vastaajien tunnistaminen.

Vanhempi keskustelujen päätepiste#

GET /api/v1/respondent-conversations

Tämä päätepiste listaa projektin keskustelut ja toimii edelleen, joten olemassa olevia integraatioita ei tarvitse muuttaa. Käytä uusissa toteutuksissa kohtaa Listaa keskustelut, jossa on lisäksi suodattimet, litteroinnit ja yksinkertaisempi sivutus.

Se palauttaa kentän conversations (kussakin conversation_id, created_at, status, respondent_email, metadata, identities, summary ja invite) sekä kentän nextCursor, joka on objekti, jossa on created_at ja id, tai viimeisellä sivulla null. Lähetä nämä kaksi arvoa takaisin parametreina cursor ja cursorId.

Virheet#

Virheet palauttavat JSON-vastauksen, jossa on error-viesti ja code, kuten muuallakin API:ssa. 400-vastauksessa on lisäksi details.fieldErrors, joka nimeää virheellisen kentän.

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

Rajat#

Näillä kahdella päätepisteellä ei ole pyyntörajaa. Jokaiseen kutsuun mahtuu enintään 10 tunnistetta (yksi kutakin tyyppiä), ja kullakin organisaatiolla voi olla enintään 10 API-avainta.