API zaproszeń respondentów

Zaproszenia respondentów pozwalają Twoim systemom zapraszać na wywiad konkretne osoby. Utwórz osobisty link dla klienta z dołączonym e-mailem lub ID konta, wyślij go w dowolny sposób, a odpowiedzi będą powiązane z tym klientem od samego początku.

Potrzebujesz planu Pro, Business lub Enterprise i klucza API. O kluczach i uwierzytelnianiu przeczytasz na stronie Przegląd API.

Wyniki odczytasz przez API rozmów: każda rozmowa zawiera swoje invite i dołączone przez Ciebie tożsamości.

Tworzenie linku z zaproszeniem#

POST /api/v1/respondent-invites

Każde żądanie tworzy jeden link dla jednego respondenta w jednym projekcie. Diaform od razu tworzy też rozmowę i dołącza przesłane tożsamości, więc wyniki są powiązane z tą osobą od samego początku.

Treść żądania#

Gdy wyślesz send_email, odpowiedź zawiera obiekt email: { "status": "sent" }, { "status": "failed" } lub { "status": "skipped", "reason": "..." }. Zaproszenie jest tworzone w każdym przypadku. Możliwe powody to no_email, unsubscribed, not_published, no_usage, monthly_limit (miesięczny limit e-maili z zaproszeniami w Twoim planie został wykorzystany), answered, already_sent, in_progress, plan i not_found. O tym, co zawiera e-mail, przeczytasz w artykule Identyfikacja respondentów.

Popularne typy to email, name, identifier, user_id i account_id. Działa każdy typ zgodny z zasadami.

Przykład#

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

Odpowiedź#

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

Jak działa link#

1. Utworzenie. Zaproszenie ma status pending, a jego rozmowa invited.
2. Otwarcie. Gdy respondent otworzy link, oba zmieniają status na opened. Rozmowa przechodzi na started, gdy respondent odpowie.
3. Wznowienie. Jeśli respondent wyjdzie i wróci przez ten sam link, kontynuuje tę samą rozmowę.
4. Zakończenie. Gdy rozmowa się skończy, niezależnie od tego, czy jako zakończona, czy anulowana, zaproszenie przechodzi na completed, a link przestaje działać.

Żeby link się otworzył, projekt musi być opublikowany. Linki działają w projektach w trybie Link publiczny i Tylko linki z zaproszeniem. W projektach publicznych zwykły link też nadal działa. Zobacz Identyfikacja respondentów.

Starszy endpoint rozmów#

GET /api/v1/respondent-conversations

Ten endpoint zwraca listę rozmów w projekcie i nadal działa, więc istniejących integracji nie trzeba zmieniać. W nowych wdrożeniach korzystaj z endpointu Lista rozmów, który dodaje filtry, transkrypcje i prostszą paginację.

Zwraca conversations (każda z conversation_id, created_at, status, respondent_email, metadata, identities, summary i invite) oraz nextCursor, czyli obiekt z created_at i id albo null na ostatniej stronie. Odeślij te dwie wartości jako cursor i cursorId.

Błędy#

Błędy zwracają JSON z komunikatem error i wartością code, tak jak w pozostałej części API. Odpowiedź 400 zawiera też details.fieldErrors, które wskazuje błędne pole.

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

Limity#

Te dwa endpointy nie mają limitu żądań. Każde zaproszenie przyjmuje do 10 tożsamości (po jednej na typ), a każda organizacja może mieć do 10 kluczy API.