API degli inviti ai rispondenti

Gli inviti ai rispondenti permettono ai tuoi sistemi di invitare persone note a un’intervista. Crea un link personale per un cliente con la sua email o il suo ID account già associati, invialo come preferisci, e le sue risposte sono collegate a quel cliente fin dall’inizio.

Ti servono un piano Pro, Business o Enterprise e una chiave API. Per chiavi e autenticazione, vedi la Panoramica dell’API.

Per leggere i risultati, usa l’API delle conversazioni: ogni conversazione contiene il suo invite e le identità che hai associato.

Crea un link di invito#

POST /api/v1/respondent-invites

Ogni richiesta crea un link per un rispondente in un progetto. Diaform crea subito anche la conversazione e le associa le identità che invii, così i risultati sono collegati a quella persona fin dall’inizio.

Corpo della richiesta#

Quando invii send_email, la risposta contiene un oggetto email: { "status": "sent" }, { "status": "failed" } oppure { "status": "skipped", "reason": "..." }. L’invito viene creato in ogni caso. I motivi sono no_email, unsubscribed, not_published, no_usage, monthly_limit (le email di invito mensili del tuo piano sono esaurite), answered, already_sent, in_progress, plan e not_found. Vedi Identificare i rispondenti per sapere cosa contiene l’email.

I tipi più comuni sono email, name, identifier, user_id e account_id. Funziona qualsiasi tipo che rispetti le regole.

Esempio#

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

Risposta#

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

Come si comporta il link#

1. Creato. L’invito è pending e la sua conversazione è invited.
2. Aperto. Quando il rispondente apre il link, entrambi diventano opened. La conversazione passa a started appena risponde.
3. Ripreso. Se il rispondente esce e torna con lo stesso link, continua la stessa conversazione.
4. Concluso. Quando la conversazione finisce, completata o annullata, l’invito diventa completed e il link smette di funzionare.

Il progetto deve essere pubblicato perché il link si apra. I link funzionano sia nei progetti con Link pubblico sia in quelli con Link solo su invito. Nei progetti pubblici continua a funzionare anche il link normale. Vedi Identificare i rispondenti.

Vecchio endpoint delle conversazioni#

GET /api/v1/respondent-conversations

Questo endpoint elenca le conversazioni di un progetto e funziona ancora, quindi le integrazioni esistenti non devono cambiare. Per i nuovi sviluppi, usa Elenca le conversazioni, che aggiunge filtri, trascrizioni e una paginazione più semplice.

Restituisce conversations (ognuna con conversation_id, created_at, status, respondent_email, metadata, identities, summary e invite) e nextCursor, un oggetto con created_at e id, oppure null nell’ultima pagina. Rimanda questi due valori come cursor e cursorId.

Errori#

Gli errori restituiscono un JSON con un messaggio error e un code, come nel resto dell’API. Un 400 include anche details.fieldErrors, che indica il campo non valido.

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

Limiti#

Questi due endpoint non hanno un limite di frequenza. Ogni invito accetta fino a 10 identità (una per tipo) e ogni organizzazione può avere fino a 10 chiavi API.