Saltar al contenido principal

Invitar miembros en bloque mediante la API

Invita a decenas o cientos de personas a tu organización (tenant) desde tu propio backend (un sistema de RR. HH., un flujo de incorporación, una herramienta de campañas) sin pasar por el portal. Cada invitación es un código de acceso. Quien abre su enlace de aceptación se une a tu organización como member (miembro), y el código puede, opcionalmente, iniciar una evaluación para esa persona en el momento en que se une.

Requisitos previos​

  • Un cliente API con estos permisos:
    • access_codes:write para crear y revocar códigos de invitación
    • access_codes:read para listar los códigos y su uso
    • tenant_methodologies:read para listar tus metodologías adoptadas
    • tags:read si agrupas las invitaciones (opcional)
    • tenant_users:read para conciliar quién se ha unido (opcional)
  • Un bearer token emitido desde ese cliente, como se describe en Autenticación. El token lleva todos los permisos concedidos al cliente, sea cual sea el scope concreto que nombres en la petición. Los ejemplos siguientes suponen que está en $TOKEN.

Los permisos quedan fijos durante toda la vida de un cliente. Si a un cliente existente le faltan estos, crea uno nuevo.

1. Elige una metodología​

Si cada miembro nuevo debe recibir una evaluación al llegar, la invitación tiene que nombrar una de las metodologías adoptadas por tu organización. Cualquier otro id se rechaza con un 422.

curl "https://$WISELOOK_HOST/v1/adopted-methodologies" \
  -H "Authorization: Bearer $TOKEN"
{
  "items": [
    {
      "methodology_id": "009f91ce-…",
      "name": "Eric One",
      "version": "1.0",
      "subscribed_at": "2026-07-27T06:04:24Z"
    }
  ]
}

Usa el methodology_id de la metodología elegida como assessment_methodology_id al crear la invitación en el paso 4.

2. Agrupa la campaña con etiquetas (opcional)​

Las etiquetas son las marcas propias de tu organización (equipos, departamentos, oficinas, cohortes), definidas en la página Etiquetas del portal. Añádelas a una invitación y todas las personas que se unan a través de ella quedan etiquetadas al llegar, así que una campaña llega ya agrupada para la búsqueda, los informes y el alcance de los gestores.

curl "https://$WISELOOK_HOST/v1/tags" \
  -H "Authorization: Bearer $TOKEN"
[
  {
    "id": "6f2d8a10-…",
    "tenant_id": "b4a1c2d3-…",
    "type": "department",
    "name": "Sales",
    "created_at": "2026-08-14T09:12:05Z"
  },
  {
    "id": "9c07e4b2-…",
    "tenant_id": "b4a1c2d3-…",
    "type": "cohort",
    "name": "2026-Q4 onboarding",
    "created_at": "2026-09-01T14:30:41Z"
  }
]

type es el eje y name el valor. Filtra un eje con ?type=department. Pasa los valores id elegidos como tag_ids al crear la invitación en el paso 4. Un id que no es tuyo se rechaza con un 422. Definir etiquetas nuevas sigue siendo una acción del portal.

3. Elige la forma de la invitación​

FormaCómoAdecuada paraLimitación
Un código de varios usosuna creación con max_uses: Ncampañas masivas: un enlace en un único envío de correolos canjes son anónimos hasta que la gente se une, y cualquiera puede usar un enlace filtrado hasta que lo revoques o caduque
Códigos de un solo uso por personaN creaciones con max_uses: 1despliegues con seguimiento: cada código corresponde a una persona invitada conocidauna llamada y un enlace por persona

Fija siempre expires_at, y fija max_uses de forma explícita. Un código sin límite y sin caducidad se puede canjear hasta que lo revoques.

4. Crea la invitación​

Un código de varios usos para una campaña de 50 personas del equipo de ventas, con cada persona que se une etiquetada en el equipo y con una evaluación asignada al llegar:

curl -X POST "https://$WISELOOK_HOST/v1/access-codes" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "max_uses": 50,
    "expires_at": "2026-10-01T00:00:00Z",
    "tag_ids": ["<TAG_UUID>"],
    "assessment_methodology_id": "<ADOPTED_METHODOLOGY_UUID>",
    "assessment_channel": "text"
  }'
{
  "id": "3e5f7a90-…",
  "tenant_id": "b4a1c2d3-…",
  "code": "K7QXM2P9",
  "expires_at": "2026-10-01T00:00:00Z",
  "max_uses": 50,
  "used_count": 0,
  "target_role": "member",
  "tag_ids": ["6f2d8a10-…"],
  "assessment_methodology_id": "009f91ce-…",
  "assessment_channel": "text",
  "created_by_tenant_user_id": null,
  "created_at": "2026-09-11T10:22:37Z",
  "updated_at": "2026-09-11T10:22:37Z"
}

El code es con lo que construyes el enlace de aceptación en el paso 5; guarda el id si tienes previsto revocar la invitación más adelante (paso 7). Notas:

  • Todas las personas que se unen con un código creado por la API reciben el rol member (miembro). Las invitaciones de administrador y de gestor solo se hacen desde el portal, a propósito.
  • La especificación de la evaluación va completa o no va: assessment_methodology_id y assessment_channel juntos, u omite ambos para una invitación simple.
  • El canal debe estar activado para tu organización (422 en caso contrario).

Para códigos por persona, repite la misma llamada con "max_uses": 1. Los reintentos son seguros si envías una cabecera Idempotency-Key (cualquier cadena única por petición lógica; una repetición devuelve la respuesta guardada en lugar de generar un segundo código).

5. Distribuye el enlace de aceptación​

Construye el enlace a partir del code devuelto:

https://$WISELOOK_HOST/tenant-ui/accept?code=<CODE>

A partir de aquí la distribución es cosa tuya. Esa es la razón de ser de esta API: Wiselook no envía correos a tus invitados. Tu backend envía el enlace por el canal que tu gente lee de verdad: el envío de correo de la campaña, tu mensajería corporativa (Slack, Teams), un portal de incorporación, un código QR en una diapositiva de un taller. Con códigos de un solo uso por persona, cada invitado recibe su propio enlace, así que tu sistema también puede saber exactamente quién ha actuado y quién no.

Al abrir el enlace, la persona invitada pasa por el inicio de sesión único, se crea su cuenta de Wiselook si hace falta, se une a tu organización y, si el código lleva una especificación de evaluación, se crea su evaluación en ese mismo momento.

6. Sigue los canjes​

curl "https://$WISELOOK_HOST/v1/access-codes" \
  -H "Authorization: Bearer $TOKEN"
[
  {
    "id": "3e5f7a90-…",
    "tenant_id": "b4a1c2d3-…",
    "code": "K7QXM2P9",
    "expires_at": "2026-10-01T00:00:00Z",
    "max_uses": 50,
    "used_count": 12,
    "target_role": "member",
    "tag_ids": ["6f2d8a10-…"],
    "assessment_methodology_id": "009f91ce-…",
    "assessment_channel": "text",
    "created_by_tenant_user_id": null,
    "created_at": "2026-09-11T10:22:37Z",
    "updated_at": "2026-09-18T08:03:12Z"
  }
]

Aquí se han consumido 12 de los 50 usos: 12 personas se han unido con este código. Los miembros nuevos aparecen en la página Miembros a medida que se unen.

Para conciliar exactamente quién se ha unido (y no solo cuántos), lista los usuarios de tu organización mediante la API. Con el permiso tenant_users:read:

curl "https://$WISELOOK_HOST/v1/tenant-users?email=ana@example.com" \
  -H "Authorization: Bearer $TOKEN"

Una fila coincidente significa que esa dirección es miembro de tu organización; una lista vacía significa que no lo es. Sin el filtro email, el mismo endpoint lista a todo el mundo, con sus roles y etiquetas, para que tu backend pueda comparar la lista de invitados con quienes se han unido de verdad.

Dos comportamientos que conviene conocer:

  • La evaluación automática solo se dispara para quienes se unen por primera vez. Un miembro ya activo que vuelve a abrir el enlace no recibe una evaluación duplicada ni consume un uso. (Un miembro eliminado que vuelve a unirse cuenta como nuevo: un uso, y la evaluación se dispara.)
  • Un uso se consume en el momento en que la unión tiene éxito, no cuando se abre el enlace.

7. Revoca​

curl -X DELETE "https://$WISELOOK_HOST/v1/access-codes/$CODE_ID" \
  -H "Authorization: Bearer $TOKEN"

Revocar (o la caducidad) detiene los canjes futuros de inmediato; las personas que ya se han unido no se ven afectadas. Revocar es idempotente. Un segundo delete es un 204 sin efecto.

Consulta también​