Gestionar miembros mediante la API

Consulta las personas de tu organización (tenant) y gestiona sus etiquetas desde tu propio backend. Son las mismas personas que el portal muestra en la página Miembros. Cada fila combina la cuenta de la plataforma (correo electrónico, nombre visible) con la visión que tiene tu organización de esa persona (rol, estado, etiquetas).

Requisitos previos

• Un cliente API con estos permisos:
  • tenant_users:read para listar y consultar miembros
  • tenant_users:write para actualizarlos y cambiar sus etiquetas
• Un bearer token emitido desde ese cliente, como se describe en Autenticación. Los ejemplos siguientes suponen que está en $TOKEN.

1. Listar y buscar

curl "https://$WISELOOK_HOST/v1/tenant-users" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    {
      "id": "8c1f5d20-3b4e-4a71-9f02-6d5c4b3a2e10",
      "email": "maria@example.com",
      "name": "Maria Ortega",
      "work_email": "m.ortega@acme.com",
      "job_title": "Regional Lead",
      "preferred_locale": "es-ES",
      "role": "member",
      "status": "active",
      "tags": [{ "id": "1a2b3c4d-…", "type": "team", "name": "Sales EMEA" }],
      "joined_at": "2026-09-02T10:11:12Z"
    }
  ],
  "total": 38,
  "page": 1,
  "page_size": 20,
  "pages": 2
}

Los filtros se combinan (AND): ?email= (coincidencia exacta de la dirección), ?role=, ?status=, ?tag_id=, más ?page= y ?page_size=. Consulta Invitar miembros en bloque para usar el filtro email y conciliar quién se ha unido.

email y name vienen de la cuenta de la plataforma de la persona. En el raro caso de que esa consulta no esté disponible momentáneamente, llegan como null; el resto de la fila siempre es exacto.

work_email, job_title y preferred_locale son el registro propio de tu organización sobre esa persona. preferred_locale decide el idioma en el que se realiza una evaluación, antes de aplicar el predeterminado de la metodología.

2. Consultar un miembro

{id} es el id de las filas de la lista: el id de esa persona dentro de tu organización. Úsalo en todos los sitios donde se nombra a un miembro, también al iniciar una evaluación.

curl "https://$WISELOOK_HOST/v1/tenant-users/8c1f5d20-3b4e-4a71-9f02-6d5c4b3a2e10" \
  -H "Authorization: Bearer $TOKEN"

La respuesta es una sola fila con la misma forma que los elementos de la lista. Un usuario que no es miembro de tu organización responde 404.

3. Gestionar las etiquetas de un miembro

La pertenencia a etiquetas es un subrecurso con altas y bajas por valor, así que tu backend nunca tiene que leer el conjunto actual, modificarlo y volver a escribirlo entero (lo que perdería un cambio concurrente). Ambas escrituras son idempotentes. Los ids de etiqueta vienen de la lista de etiquetas de tu organización (Etiquetas).

Lista las etiquetas de un miembro (las mismas filas que incluye la fila del miembro):

curl "https://$WISELOOK_HOST/v1/tenant-users/8c1f5d20-3b4e-4a71-9f02-6d5c4b3a2e10/tags" \
  -H "Authorization: Bearer $TOKEN"

Añade una etiqueta; la respuesta es la fila del miembro actualizada:

curl -X POST "https://$WISELOOK_HOST/v1/tenant-users/8c1f5d20-3b4e-4a71-9f02-6d5c4b3a2e10/tags" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"tag_id": "1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6"}'

Añadir una etiqueta que el miembro ya tiene es un 200 sin efecto. Quita una etiqueta (204; quitar una etiqueta que el miembro no tiene también es 204):

curl -X DELETE "https://$WISELOOK_HOST/v1/tenant-users/8c1f5d20-3b4e-4a71-9f02-6d5c4b3a2e10/tags/1a2b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6" \
  -H "Authorization: Bearer $TOKEN"

Un id de etiqueta que no es de tu organización responde 422 unknown_tag en ambas llamadas, nunca un éxito silencioso.

4. Actualizar un miembro

Envía solo los campos que quieras cambiar. Lo que omitas no se toca.

curl -X PATCH "https://$WISELOOK_HOST/v1/tenant-users/8c1f5d20-3b4e-4a71-9f02-6d5c4b3a2e10" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/merge-patch+json' \
  -d '{"job_title": "Regional Director", "preferred_locale": "es-ES"}'

La respuesta es el miembro actualizado, con la misma forma que una consulta.

Campo	Notas
name	Su nombre visible
work_email	El correo que tu organización tiene para esa persona, no su inicio de sesión
job_title
preferred_locale	BCP-47. Decide el idioma en el que se realiza una evaluación
role	admin, manager o member
status	active o removed. invited pertenece al flujo de invitación

Requiere el permiso tenant_users:write. Las etiquetas no se definen aquí. Usa las llamadas de alta y baja de arriba, para que añadir una etiqueta nunca reescriba las demás.

Dos comportamientos que conviene conocer:

• Enviar null es un error, no una forma de vaciar un campo. Omite el campo. Un documento vacío también se rechaza, para que un PATCH sin cambios no pueda confundirse con una edición correcta.
• No puedes degradar ni eliminar a tu último administrador activo (409 last_active_admin). Asciende antes a otra persona.

Errores

Estado	Código	Significado
404	user_not_found	No es miembro de tu organización
422	unknown_tag	El id de etiqueta no es de tu organización (llamadas de alta/baja de etiquetas)
409	last_active_admin	Dejaría a tu organización sin ningún administrador activo
415		PATCH enviado sin Content-Type: application/merge-patch+json
422	(validación)	Un id o un cuerpo mal formados, un campo null o un patch vacío

Consulta también

• Clientes API para crear el cliente y elegir sus permisos.
• Autenticación para la emisión de tokens en detalle.
• Invitar miembros en bloque para incorporar a las personas a tu organización en primer lugar.