API de invitaciones a participantes

Las invitaciones a participantes permiten que tus propios sistemas inviten a una entrevista a personas que ya conoces. Crea un enlace personal para un cliente con su correo o su ID de cuenta asociado, envíalo como quieras, y sus respuestas quedan vinculadas a ese cliente desde el principio.

Necesitas un plan Pro, Business o Enterprise y una clave de API. Para las claves y la autenticación, consulta la descripción general de la API.

Para leer los resultados, usa la API de conversaciones: cada conversación incluye su invite y las identidades que asociaste.

Crear un enlace de invitación#

POST /api/v1/respondent-invites

Cada solicitud crea un enlace para un participante en un proyecto. Diaform también crea la conversación al momento y le asocia las identidades que envías, así que los resultados quedan vinculados a esa persona desde el principio.

Cuerpo de la solicitud#

Cuando envías send_email, la respuesta incluye un objeto email: { "status": "sent" }, { "status": "failed" } o { "status": "skipped", "reason": "..." }. La invitación se crea en todos los casos. Los motivos son no_email, unsubscribed, not_published, no_usage, monthly_limit (se agotaron los correos de invitación mensuales de tu plan), answered, already_sent, in_progress, plan y not_found. Consulta Identificar a los participantes para ver qué contiene el correo.

Los tipos habituales son email, name, identifier, user_id y account_id. Sirve cualquier tipo que cumpla las reglas.

Ejemplo#

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

Respuesta#

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

Cómo funciona el enlace#

1. Creado. La invitación está en pending y su conversación en invited.
2. Abierto. Cuando el participante abre el enlace, ambas pasan a opened. La conversación pasa a started en cuanto responde.
3. Retomado. Si el participante sale y vuelve con el mismo enlace, continúa la misma conversación.
4. Terminado. Cuando termina la conversación, ya sea completada o cancelada, la invitación pasa a completed y el enlace deja de funcionar.

El proyecto debe estar publicado para que el enlace se abra. Los enlaces funcionan tanto en proyectos con Enlace público como con Solo enlaces de invitación. En los proyectos públicos, el enlace normal también sigue funcionando. Consulta Identificar a los participantes.

Endpoint de conversaciones anterior#

GET /api/v1/respondent-conversations

Este endpoint lista las conversaciones de un proyecto y sigue funcionando, así que las integraciones existentes no tienen que cambiar. Para los desarrollos nuevos, usa Listar conversaciones, que añade filtros, transcripciones y una paginación más sencilla.

Devuelve conversations (cada una con conversation_id, created_at, status, respondent_email, metadata, identities, summary e invite) y nextCursor, un objeto con created_at e id, o null en la última página. Envía esos dos valores de vuelta como cursor y cursorId.

Errores#

Los errores devuelven JSON con un mensaje en error y un code, como en el resto de la API. Un 400 también incluye details.fieldErrors, que indica el campo que falló.

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

Límites#

Estos dos endpoints no tienen límite de solicitudes. Cada invitación admite hasta 10 identidades (una por tipo), y cada organización puede tener hasta 10 claves de API.