Respondentinbjudnings-API

Med respondentinbjudningar kan dina egna system bjuda in kända personer till en intervju. Skapa en personlig länk för en kund med kundens e-postadress eller konto-ID kopplat, skicka den på valfritt sätt, så är svaren kopplade till kunden från början.

Du behöver planen Pro, Business eller Enterprise och en API-nyckel. Läs mer om nycklar och autentisering under API-översikt.

För att läsa resultaten använder du Konversations-API:t: varje konversation innehåller sin invite och de identiteter du kopplade.

Skapa en inbjudningslänk#

POST /api/v1/respondent-invites

Varje förfrågan skapar en länk för en respondent i ett projekt. Diaform skapar också konversationen direkt och kopplar de identiteter du skickar, så att resultaten hör ihop med personen från början.

Förfrågans body#

När du skickar send_email innehåller svaret ett email-objekt: { "status": "sent" }, { "status": "failed" } eller { "status": "skipped", "reason": "..." }. Inbjudan skapas i samtliga fall. Orsakerna är no_email, unsubscribed, not_published, no_usage, monthly_limit (din plans inbjudningsmejl för månaden är slut), answered, already_sent, in_progress, plan och not_found. Under Identifiera respondenter ser du vad mejlet innehåller.

Vanliga typer är email, name, identifier, user_id och account_id. Alla typer som följer reglerna fungerar.

Exempel#

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

Så fungerar länken#

1. Skapad. Inbjudan är pending och dess konversation är invited.
2. Öppnad. När respondenten öppnar länken blir båda opened. Konversationen går över till started när respondenten svarar.
3. Återupptagen. Om respondenten lämnar och kommer tillbaka via samma länk fortsätter hen i samma konversation.
4. Avslutad. När konversationen är slut, oavsett om den slutfördes eller avbröts, blir inbjudan completed och länken slutar fungera.

Projektet måste vara publicerat för att länken ska gå att öppna. Länkarna fungerar i projekt med både Publik länk och Endast inbjudningslänkar. I publika projekt fortsätter den vanliga länken också att fungera. Läs mer under Identifiera respondenter.

Äldre endpoint för konversationer#

GET /api/v1/respondent-conversations

Den här endpointen listar ett projekts konversationer och fungerar fortfarande, så befintliga integrationer behöver inte ändras. För nya integrationer använder du Lista konversationer, som dessutom har filter, transkriptioner och enklare paginering.

Den returnerar conversations (var och en med conversation_id, created_at, status, respondent_email, metadata, identities, summary och invite) och nextCursor, ett objekt med created_at och id, eller null på sista sidan. Skicka tillbaka de två värdena som cursor och cursorId.

Fel#

Fel returnerar JSON med ett error-meddelande och en code, precis som i resten av API:t. En 400 innehåller också details.fieldErrors, som anger vilket fält som inte godkändes.

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

Gränser#

De här två endpointsen har ingen hastighetsbegränsning. Varje inbjudan tar upp till 10 identiteter (en per typ), och varje organisation kan ha upp till 10 API-nycklar.