API de convites de respondentes

Os convites de respondentes permitem que seus próprios sistemas convidem pessoas conhecidas para uma entrevista. Crie um link pessoal para um cliente com o e-mail ou o ID da conta dele associado, envie como quiser, e as respostas ficam ligadas a esse cliente desde o início.

Você precisa de um plano Pro, Business ou Enterprise e de uma chave de API. Para chaves e autenticação, veja a visão geral da API.

Para ler os resultados, use a API de conversas: cada conversa traz o invite dela e as identidades que você associou.

Criar um link de convite#

POST /api/v1/respondent-invites

Cada requisição cria um link para um respondente em um projeto. O Diaform também cria a conversa na hora e associa as identidades que você envia, então os resultados ficam ligados a essa pessoa desde o início.

Corpo da requisição#

Quando você envia send_email, a resposta traz um objeto email: { "status": "sent" }, { "status": "failed" } ou { "status": "skipped", "reason": "..." }. O convite é criado em todos os casos. Os motivos são no_email, unsubscribed, not_published, no_usage, monthly_limit (os e-mails de convite mensais do seu plano acabaram), answered, already_sent, in_progress, plan e not_found. Veja Identificar respondentes para saber o que o e-mail contém.

Os tipos comuns são email, name, identifier, user_id e account_id. Qualquer tipo que siga as regras funciona.

Exemplo#

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

Resposta#

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

Como o link se comporta#

1. Criado. O convite fica pending e a conversa dele fica invited.
2. Aberto. Quando o respondente abre o link, os dois passam para opened. A conversa passa para started assim que ele responde.
3. Retomado. Se o respondente sair e voltar pelo mesmo link, ele continua a mesma conversa.
4. Encerrado. Quando a conversa termina, seja concluída ou cancelada, o convite passa para completed e o link para de funcionar.

O projeto precisa estar publicado para o link abrir. Os links funcionam em projetos com Link público e com Links só por convite. Em projetos públicos, o link normal também continua funcionando. Veja Identificar respondentes.

Endpoint de conversas mais antigo#

GET /api/v1/respondent-conversations

Este endpoint lista as conversas de um projeto e continua funcionando, então as integrações existentes não precisam mudar. Para trabalhos novos, use Listar conversas, que adiciona filtros, transcrições e uma paginação mais simples.

Ele retorna conversations (cada uma com conversation_id, created_at, status, respondent_email, metadata, identities, summary e invite) e nextCursor, um objeto com created_at e id, ou null na última página. Envie esses dois valores de volta como cursor e cursorId.

Erros#

Os erros retornam JSON com uma mensagem em error e um code, como no restante da API. Um 400 também inclui details.fieldErrors, que indica o campo que falhou.

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

Limites#

Estes dois endpoints não têm limite de requisições. Cada convite aceita até 10 identidades (uma por tipo), e cada organização pode ter até 10 chaves de API.