Leads, tableros y actividades

Resumen

Un lead es una persona o una empresa del embudo de un equipo: sus datos de contacto, en qué punto está (board y stage), su status y sus contact_permissions. Un registro con record_kind: "client" es un cliente, no un lead: no tiene estado del embudo, así que su status es null. Los leads y los clientes salen de los mismos endpoints.

Los ocho estados son new, contacted, qualified, negotiating, converted, lost, archived y unreachable. converted no significa "ganado". Un lead cuyo estado no conoce esta versión de la API conserva record_kind: "lead" y trae status: null. Un lead archivado indica el motivo en archive_reason, incluidos merged y family_transfer para los leads que dejan atrás las fusiones y los traspasos.

Aplica contact_permissions antes de que cualquiera de tus sistemas contacte con la persona: Sincroniza una copia explica cada uno.

Atribución y respuesta

GET /v1/leads/{id} devuelve el lead con dos facetas: attribution, de dónde vino, y response, cómo le ha respondido el equipo en sus conversaciones y llamadas. Cada faceta tiene su propia version, así que un mensaje nuevo cambia la respuesta del lead sin cambiar el lead. Una faceta es null mientras Totem aún la prepara. Las listas devuelven solo el lead. El feed de cambios entrega las facetas como elementos propios, lead_attribution y lead_response, con el identificador del lead. Cobertura de los datos explica qué puede decirte cada faceta y qué no.

Buscar por teléfono o correo electrónico

POST /v1/leads/search busca los leads de un equipo por teléfono o correo electrónico exactos. Envía exactamente uno de phone o email en el cuerpo JSON, nunca en una URL:

curl https://api.totemstudio.ai/v1/leads/search \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID" \
  -H "Content-Type: application/json" \
  -d '{"email": "alex.rivera@example.com"}'

La coincidencia es exacta con el número tal como lo guarda Totem, no con el phone normalizado que muestra el lead. Un teléfono coincide con un registro guardado en E.164, con o sin su + inicial; un registro guardado con espacios o sin prefijo de país no se encuentra, ni siquiera con el phone que la API devuelve para él. Un correo coincide con la dirección tal como la enviaste o en minúsculas. Los registros que Totem aún no ha entregado a la API se omiten hasta que lo haga. La búsqueda también devuelve registros archivados, fusionados y clientes; sigue merged_into hasta el lead que se conservó. Devuelve como máximo 10 leads, en una sola respuesta que nunca se pagina, así que, si muchos registros comparten un teléfono o una dirección de correo electrónico, puede que no los devuelva todos.

Actividades

GET /v1/leads/{id}/activities devuelve el historial de un lead, página a página: cada cambio de etapa, de estado o de miembros asignados, y cuándo ocurrió. actor_kind indica quién lo hizo: una persona (human), la IA (ai), una automatización de Totem (system), alguien a través de la API (api) o unknown. Totem sabe quién hizo un cambio solo cuando el mismo guardado escribió el estado del lead, así que un cambio de etapa o de responsables hecho por sí solo es unknown. Las páginas no van por fecha, así que ordena por occurred_at. Las actividades nunca cambian una vez escritas, pero se eliminan junto con su lead, y las nuevas llegan también por el feed de cambios.

Tableros y etapas

Un tablero es un embudo, con sus etapas en orden. La stage de un lead indica la etapa en la que está. Cada etapa tiene un mode que indica quién mueve los leads: solo las personas (standard), las personas y la IA, que puede mover leads a la etapa (supervised), o la IA, que hace la prospección y mueve los leads a la etapa y fuera de ella (automated).

GET /v1/boards devuelve los tableros de un equipo con sus etapas, página a página. Los tableros también llegan por el feed de cambios; lee esta lista cuando un lead indique una etapa que aún no has visto. Una etapa sin posición guardada no aparece en su tablero, así que no vuelvas a leer la lista por una etapa que no incluyó la última vez.

Lista los leads

GET /v1/leads

Devuelve una página de leads y clientes del equipo, en un orden estable que no tiene significado. Filtra como máximo por uno de board, stage o status; un tablero o una etapa que el equipo no tiene devuelve una página vacía. Para mantener una copia al día, sigue el feed de cambios en lugar de volver a leer esta lista.

Permisos: crm:read
Límite de frecuencia: Sincronización

Parámetros de consulta

limit integer Rango 1–100 Por defecto 25
Elementos por página, de 1 a 100. Por defecto, 25.
cursor string 1–512 caracteres
El next_cursor de la página anterior. Omítelo en la primera página.
board string Prefijo del id brd_…
Solo los leads de este tablero. Como máximo uno de board, stage y status.
stage string Prefijo del id stg_…
Solo los leads de esta etapa. Como máximo uno de board, stage y status.
status string
Solo los leads con este estado. Como máximo uno de board, stage y status.
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos Lead.

object string
Siempre list.
data Array<Lead>
Los elementos de esta página.
has_more boolean
true si hay otra página: pídela con next_cursor, aunque esta traiga menos elementos que limit.
next_cursor string Puede ser null
Cursor opaco de la página siguiente, o null en la última. No lo interpretes.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 capture_not_ready Los datos del equipo aún se están preparando
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/leads?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "object": "lead",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "record_kind": "lead",
      "name": "Alex",
      "surname": "Rivera",
      "email": "alex.rivera@example.com",
      "company": "Example Dental",
      "phone": "+12025550123",
      "phone_status": "valid",
      "status": "contacted",
      "status_set_by": "ai",
      "archive_reason": null,
      "archived_from_status": null,
      "contact_permissions": {
        "do_not_contact": false,
        "email_opt_out": false,
        "email_opt_out_at": null,
        "whatsapp_consent": null,
        "provenance": {
          "do_not_contact": null,
          "email_opt_out": null,
          "whatsapp_consent": null
        }
      },
      "merged_into": null,
      "transferred_to": null,
      "revived_at": null,
      "pipeline_cleared": false,
      "converted_at": null,
      "value_at_conversion": null,
      "priority": "high",
      "tags": [
        "spring-check-up"
      ],
      "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
      "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
      "assignees": [
        "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
      ],
      "estimated_value": 1200,
      "estimated_value_currency": null,
      "source": "meta_lead_ads",
      "source_channel": null,
      "source_detail": null,
      "source_provenance": "member_editable",
      "created_at": "2026-09-28T10:15:00.000Z",
      "version": 3,
      "updated_at": "2026-09-28T10:20:01.250Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJrIjoibGVhZCIsImEiOiJsZWFkX3I3MkVmYlJOVXp1cU9SRkpSME84SHhBd0VYZDkzakdVVFlNYU1NWEtTRjBRYkxTOENpVUtKcEVQMzRMRlFHIiwicyI6ImYzNTI3NzI2MTkwYiJ93iHyRg"
}

Obtén un lead con su atribución y su respuesta

GET /v1/leads/{id}

Devuelve un lead con sus dos facetas: attribution (de dónde viene) y response (cómo le ha respondido el equipo), cada una con su propia version. Un lead creado hace un momento puede responder 404 resource_missing hasta que Totem lo prepare; el feed de cambios lo entrega entonces.

Permisos: crm:read
Límite de frecuencia: Lectura

Parámetros de ruta

id string Obligatorio Prefijo del id lead_…
El identificador público del lead.

Respuesta

Devuelve un objeto LeadDetail.

id string Prefijo del id lead_…
Identificador público del registro.
object string
Siempre lead.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece el registro.
record_kind string
lead si el registro tiene un estado del embudo; si no, client. Un lead cuyo estado no conoce esta versión trae status: null.
Valores posibles
- lead
- client
name string Puede ser null
Nombre o nombre visible, o null.
surname string Puede ser null
Apellidos, o null.
email string Puede ser null
Email tal como está guardado, o null.
company string Puede ser null
Empresa, o null.
phone string Puede ser null
Teléfono en E.164, solo si el número guardado es válido; si no, null.
phone_status string
valid (ver phone), invalid (hay un número guardado que no es válido, por ejemplo uno guardado sin prefijo de país) o missing.
Valores posibles
- valid
- invalid
- missing
status string Puede ser null
Estado en el embudo; null en un cliente o si es un estado que esta versión no conoce. converted no significa "ganado".
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
status_set_by string Puede ser null
Quién fijó el estado actual: una persona, la IA, la automatización de Totem, una llamada a la API o desconocido (ninguna transición registrada llega a él). Null cuando status es null.
Valores posibles
- human
- ai
- system
- api
- unknown
archive_reason string Puede ser null
Por qué se archivó el registro, como código cerrado; el texto libre guardado es other. Null si no hay ninguno.
Valores posibles
- opt_out
- no_consent
- not_interested
- not_qualified
- no_contact
- merged
- family_transfer
- other
archived_from_status string Puede ser null
El estado que tenía el lead antes de su archivo actual; null si no está archivado o si se desconoce.
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
contact_permissions object
Permisos de contacto. Aplícalos antes de cualquier contacto desde tus propios sistemas.
- do_not_contact boolean
  Verdadero cuando la persona pidió no ser contactada nunca (motivo de archivo opt_out). Detén todos los canales.
- email_opt_out boolean
  Verdadero cuando la persona se dio de baja del correo electrónico comercial y de seguimiento.
- email_opt_out_at string Puede ser null Formato date-time
  Cuándo se registró la baja del correo electrónico, o null.
- whatsapp_consent boolean Puede ser null
  Consentimiento de WhatsApp: false si se rechazó, true si consta, null si se desconoce.
- provenance object
  El origen de cada permiso.
merged_into string Puede ser null Prefijo del id lead_…
El lead en el que se fusionó este registro, o null (también si ese lead ya no existe).
transferred_to object Puede ser null
Adónde se traspasó este lead dentro de tu organización, o null. El equipo puede ser uno que tu clave no lee.
- team string Prefijo del id team_…
  El equipo de destino.
- lead string Puede ser null Prefijo del id lead_…
  El lead de destino, o null si su id no puede nombrarse entre equipos: lo creó el traspaso de un asistente, o el traspaso cayó en un lead existente de anuncios (Meta, Google Ads o LinkedIn) u otro lead con id fijo.
revived_at string Puede ser null Formato date-time
Cuándo volvió el contacto por su cuenta y reactivó un lead archivado por última vez, o null.
pipeline_cleared boolean
Verdadero si el lead se convirtió con "borrar datos del embudo": tablero, etapa, prioridad, responsables, valor estimado y los campos de origen salvo source_channel son null porque se borraron.
converted_at string Puede ser null Formato date-time
Cuándo se convirtió el lead, mientras su estado es converted; si no, null.
value_at_conversion number Puede ser null
El valor estimado al convertirlo, en unidades principales. Se conserva al borrar los datos del embudo.
priority string Puede ser null
Prioridad, o null.
Valores posibles
- low
- medium
- high
- urgent
tags Array<string>
Etiquetas tal como están guardadas. lead y booking son etiquetas del sistema.
board string Puede ser null Prefijo del id brd_…
El tablero, resuelto a través de la etapa si la hay; o null.
stage string Puede ser null Prefijo del id stg_…
La etapa, o null.
assignees Array<string> Puede ser null Prefijo del id mem_…
Miembros asignados, ordenados. Null cuando el registro no tiene datos del embudo.
estimated_value number Puede ser null
Valor estimado en unidades principales tal como está guardado (con decimales), o null.
estimated_value_currency null Puede ser null
Siempre null: Totem no guarda moneda con el valor.
source string Puede ser null
El origen guardado del lead; api cubre también los leads que crea el propio Totem (por ejemplo, desde una conversación o una llamada), ver source_detail. Null si no hay ninguno.
Valores posibles
- meta_lead_ads
- manual
- website_form
- booking_page
- csv_import
- api
- chatbot
- google_ads
- linkedin
- other
source_channel string Puede ser null
El canal por el que empezó el registro (por ejemplo whatsapp, phone, widget), o null. El equipo puede editarlo.
source_detail string Puede ser null
conversation, call, external:<proveedor>, gated_ad:<origen>, family_handoff, api_intake o unknown; null cuando source no necesita detalle.
source_provenance string Puede ser null
server_written si Totem fijó el origen a partir de lo que informó la plataforma de anuncios; si no, member_editable (el equipo puede cambiarlo). Null junto con source.
Valores posibles
- server_written
- member_editable
created_at string Formato date-time
Cuándo se creó el registro.
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.
attribution LeadAttribution Puede ser null
La faceta de atribución del lead, o null mientras Totem aún la prepara.
response LeadResponse Puede ser null
La faceta de respuesta del lead, o null mientras Totem aún la prepara.

Errores

403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 resource_missing Recurso no encontrado
409 capture_not_ready Los datos del equipo aún se están preparando

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/leads/lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG' \
  -H "Authorization: Bearer $TOTEM_API_KEY"

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "record_kind": "lead",
  "name": "Alex",
  "surname": "Rivera",
  "email": "alex.rivera@example.com",
  "company": "Example Dental",
  "phone": "+12025550123",
  "phone_status": "valid",
  "status": "contacted",
  "status_set_by": "ai",
  "archive_reason": null,
  "archived_from_status": null,
  "contact_permissions": {
    "do_not_contact": false,
    "email_opt_out": false,
    "email_opt_out_at": null,
    "whatsapp_consent": null,
    "provenance": {
      "do_not_contact": null,
      "email_opt_out": null,
      "whatsapp_consent": null
    }
  },
  "merged_into": null,
  "transferred_to": null,
  "revived_at": null,
  "pipeline_cleared": false,
  "converted_at": null,
  "value_at_conversion": null,
  "priority": "high",
  "tags": [
    "spring-check-up"
  ],
  "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
  "assignees": [
    "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
  ],
  "estimated_value": 1200,
  "estimated_value_currency": null,
  "source": "meta_lead_ads",
  "source_channel": null,
  "source_detail": null,
  "source_provenance": "member_editable",
  "created_at": "2026-09-28T10:15:00.000Z",
  "version": 3,
  "updated_at": "2026-09-28T10:20:01.250Z",
  "attribution": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_attribution",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "original_capture": {
      "capture": "at_creation",
      "captured_at": "2026-09-28T10:15:00.000Z",
      "source": "meta_lead_ads",
      "source_hint": null,
      "source_channel": null,
      "external_provider": null,
      "received_at": "2026-09-28T10:15:00.000Z",
      "submitted_at": "2026-09-28T10:14:30.000Z",
      "origin": null,
      "campaign": {
        "id": {
          "value": "120210000000000101",
          "provenance": "provider"
        },
        "name": {
          "value": "Spring check-up",
          "provenance": "provider"
        }
      },
      "ad": {
        "id": {
          "value": "120210000000000303",
          "provenance": "provider"
        },
        "name": {
          "value": "Free first visit",
          "provenance": "provider"
        }
      },
      "ad_set": {
        "id": {
          "value": "120210000000000202",
          "provenance": "provider"
        },
        "name": {
          "value": "Families nearby",
          "provenance": "provider"
        }
      },
      "ad_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "form": {
        "id": {
          "value": "900000000000000404",
          "provenance": "provider"
        },
        "name": {
          "value": "Book a check-up",
          "provenance": "provider"
        }
      },
      "creative": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "asset_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "page": {
        "id": {
          "value": "100000000000000505",
          "provenance": "provider"
        },
        "name": {
          "value": "Example Dental",
          "provenance": "provider"
        }
      },
      "utm": null,
      "click_network": {
        "value": null,
        "provenance": "not_captured"
      },
      "ad_referral": null,
      "family_origin": null,
      "audience": {
        "value": null,
        "missing_reason": "unsupported"
      }
    },
    "original_capture_missing_reason": null,
    "latest_submission": null,
    "latest_submission_missing_reason": "not_captured",
    "version": 1,
    "updated_at": "2026-09-28T10:15:02.100Z"
  },
  "response": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_response",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "last_inbound_at": "2026-10-01T08:58:00.000Z",
    "last_outbound_at": "2026-10-01T08:59:30.000Z",
    "awaiting_reply": false,
    "last_answered_call_at": "2026-09-28T10:17:00.000Z",
    "last_whatsapp_delivery_status": "read",
    "coverage": {
      "conversations": 2,
      "calls": 1,
      "channels_without_delivery_data": [
        "email"
      ],
      "truncated": false
    },
    "version": 7,
    "updated_at": "2026-10-01T08:59:31.040Z"
  }
}

Busca leads por teléfono o correo exactos

POST /v1/leads/search

Busca los leads del equipo cuyo teléfono o correo electrónico coincida exactamente, incluidos los archivados, los fusionados y los clientes (sigue merged_into hasta el lead que se conservó). Envía exactamente uno de phone o email en el cuerpo JSON, nunca en la URL. Devuelve como máximo 10 leads, elegidos entre los 20 primeros registros que coincidan, en una sola respuesta que nunca se pagina.

Permisos: crm:read
Límite de frecuencia: Lectura

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Cuerpo de la petición

Exactamente uno de phone o email, en el cuerpo JSON y nunca en la URL.

phone string Condicional 3–40 caracteres
Un teléfono en formato E.164 (+12025550123). Encuentra el número guardado en E.164, con o sin +, y en los formatos que escriben las bibliotecas de teléfonos: +1 202-555-0123, (202) 555-0123 y 2025550123. Otros formatos, como 202 555 0123, no aparecen.
email string Condicional 3–254 caracteres
Un correo electrónico. Encuentra los registros guardados exactamente igual o en minúsculas.

Respuesta

Devuelve una lista de objetos Lead.

object string
Siempre list.
data Array<Lead> ≤ 10 elementos
Los leads que coinciden: como máximo 10.
has_more boolean
Siempre false, aunque coincidan más registros: la búsqueda devuelve como máximo 10 leads y no tiene página siguiente.
next_cursor null Puede ser null
Siempre null: la búsqueda no se pagina.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 capture_not_ready Los datos del equipo aún se están preparando

+ 12 errores comunes

curl -X POST 'https://api.totemstudio.ai/v1/leads/search' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID" \
  -H "Content-Type: application/json" \
  --data '{"phone": "+12025550123"}'

{
  "object": "list",
  "data": [
    {
      "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "object": "lead",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "record_kind": "lead",
      "name": "Alex",
      "surname": "Rivera",
      "email": "alex.rivera@example.com",
      "company": "Example Dental",
      "phone": "+12025550123",
      "phone_status": "valid",
      "status": "contacted",
      "status_set_by": "ai",
      "archive_reason": null,
      "archived_from_status": null,
      "contact_permissions": {
        "do_not_contact": false,
        "email_opt_out": false,
        "email_opt_out_at": null,
        "whatsapp_consent": null,
        "provenance": {
          "do_not_contact": null,
          "email_opt_out": null,
          "whatsapp_consent": null
        }
      },
      "merged_into": null,
      "transferred_to": null,
      "revived_at": null,
      "pipeline_cleared": false,
      "converted_at": null,
      "value_at_conversion": null,
      "priority": "high",
      "tags": [
        "spring-check-up"
      ],
      "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
      "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
      "assignees": [
        "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
      ],
      "estimated_value": 1200,
      "estimated_value_currency": null,
      "source": "meta_lead_ads",
      "source_channel": null,
      "source_detail": null,
      "source_provenance": "member_editable",
      "created_at": "2026-09-28T10:15:00.000Z",
      "version": 3,
      "updated_at": "2026-09-28T10:20:01.250Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Lista las actividades de un lead

GET /v1/leads/{id}/activities

Devuelve una página de actividades del lead: cada cambio de etapa, de estado o de miembros asignados, con cuándo ocurrió y, si Totem lo registró, quién lo hizo. Las páginas no van por fecha, así que ordena por occurred_at. Una actividad no cambia una vez escrita, y las nuevas también llegan por el feed de cambios.

Permisos: crm:read
Límite de frecuencia: Sincronización

Parámetros de ruta

id string Obligatorio Prefijo del id lead_…
El identificador público del lead.

Parámetros de consulta

limit integer Rango 1–100 Por defecto 25
Elementos por página, de 1 a 100. Por defecto, 25.
cursor string 1–512 caracteres
El next_cursor de la página anterior. Omítelo en la primera página.

Respuesta

Devuelve una lista de objetos Activity.

object string
Siempre list.
data Array<Activity>
Los elementos de esta página.
has_more boolean
true si hay otra página: pídela con next_cursor, aunque esta traiga menos elementos que limit.
next_cursor string Puede ser null
Cursor opaco de la página siguiente, o null en la última. No lo interpretes.

Errores

403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 resource_missing Recurso no encontrado
409 capture_not_ready Los datos del equipo aún se están preparando
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/leads/lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG/activities?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "act_aBgzeetVKDEjpAAkXfEFF53ZGd2ZMmGhUDKgagqLbh6c7R1GqOl0xsFw7pyRhD3SqqYWGMdb371xxj",
      "object": "activity",
      "livemode": false,
      "type": "stage_changed",
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
      "occurred_at": "2026-09-28T10:20:00.000Z",
      "actor_kind": "ai",
      "stage_snapshot": {
        "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
        "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
        "name": "Contacted"
      },
      "value_snapshot": 1200,
      "from": {
        "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
        "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
      },
      "to": {
        "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
        "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
      },
      "version": 1,
      "updated_at": "2026-09-28T10:20:01.500Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Lista los tableros con sus etapas

GET /v1/boards

Devuelve una página de tableros del equipo, cada uno con sus etapas en el orden del embudo. Los tableros también llegan por el feed de cambios; lee esta lista cuando los necesites al momento, por ejemplo cuando un lead indique una etapa que aún no conoces.

Permisos: crm:read
Límite de frecuencia: Sincronización

Parámetros de consulta

limit integer Rango 1–100 Por defecto 25
Elementos por página, de 1 a 100. Por defecto, 25.
cursor string 1–512 caracteres
El next_cursor de la página anterior. Omítelo en la primera página.

Cabeceras

Totem-Team string Condicional Prefijo del id team_…
El equipo que se lee, como identificador team_…. Omítelo si la clave lee un solo equipo; es obligatorio si lee varios (400 team_required). Si lo envías, debe indicar un equipo que la clave lee: un identificador mal formado recibe 400 invalid_request, y un equipo fuera de la clave, 404 team_not_accessible, igual que una petición sin la cabecera cuando la clave ya no lee ningún equipo.

Respuesta

Devuelve una lista de objetos Board.

object string
Siempre list.
data Array<Board>
Los elementos de esta página.
has_more boolean
true si hay otra página: pídela con next_cursor, aunque esta traiga menos elementos que limit.
next_cursor string Puede ser null
Cursor opaco de la página siguiente, o null en la última. No lo interpretes.

Errores

400 team_required Falta el equipo
403 team_state_restricted Equipo restringido
403 sector_restricted Sector restringido
404 team_not_accessible Equipo no accesible
409 capture_not_ready Los datos del equipo aún se están preparando
429 quota_exceeded Cuota diaria superada

+ 12 errores comunes

curl 'https://api.totemstudio.ai/v1/boards?limit=25' \
  -H "Authorization: Bearer $TOTEM_API_KEY" \
  -H "Totem-Team: $TOTEM_TEAM_ID"

{
  "object": "list",
  "data": [
    {
      "id": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
      "object": "board",
      "livemode": false,
      "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
      "name": "New patients",
      "is_default": true,
      "is_archived": false,
      "appointment_booked_stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
      "stages": [
        {
          "object": "stage",
          "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
          "name": "New",
          "position": 0,
          "is_default": true,
          "is_final": false,
          "is_archive": false,
          "mode": "automated"
        },
        {
          "object": "stage",
          "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
          "name": "Contacted",
          "position": 1,
          "is_default": false,
          "is_final": false,
          "is_archive": false,
          "mode": "supervised"
        },
        {
          "object": "stage",
          "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
          "name": "Visit booked",
          "position": 2,
          "is_default": false,
          "is_final": true,
          "is_archive": false,
          "mode": "standard"
        }
      ],
      "version": 4,
      "updated_at": "2026-09-02T16:40:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

El objeto `Lead`

Un lead o cliente: solo los campos del lead.

Atributos

id string Prefijo del id lead_…
Identificador público del registro.
object string
Siempre lead.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece el registro.
record_kind string
lead si el registro tiene un estado del embudo; si no, client. Un lead cuyo estado no conoce esta versión trae status: null.
Valores posibles
- lead
- client
name string Puede ser null
Nombre o nombre visible, o null.
surname string Puede ser null
Apellidos, o null.
email string Puede ser null
Email tal como está guardado, o null.
company string Puede ser null
Empresa, o null.
phone string Puede ser null
Teléfono en E.164, solo si el número guardado es válido; si no, null.
phone_status string
valid (ver phone), invalid (hay un número guardado que no es válido, por ejemplo uno guardado sin prefijo de país) o missing.
Valores posibles
- valid
- invalid
- missing
status string Puede ser null
Estado en el embudo; null en un cliente o si es un estado que esta versión no conoce. converted no significa "ganado".
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
status_set_by string Puede ser null
Quién fijó el estado actual: una persona, la IA, la automatización de Totem, una llamada a la API o desconocido (ninguna transición registrada llega a él). Null cuando status es null.
Valores posibles
- human
- ai
- system
- api
- unknown
archive_reason string Puede ser null
Por qué se archivó el registro, como código cerrado; el texto libre guardado es other. Null si no hay ninguno.
Valores posibles
- opt_out
- no_consent
- not_interested
- not_qualified
- no_contact
- merged
- family_transfer
- other
archived_from_status string Puede ser null
El estado que tenía el lead antes de su archivo actual; null si no está archivado o si se desconoce.
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
contact_permissions object
Permisos de contacto. Aplícalos antes de cualquier contacto desde tus propios sistemas.
- do_not_contact boolean
  Verdadero cuando la persona pidió no ser contactada nunca (motivo de archivo opt_out). Detén todos los canales.
- email_opt_out boolean
  Verdadero cuando la persona se dio de baja del correo electrónico comercial y de seguimiento.
- email_opt_out_at string Puede ser null Formato date-time
  Cuándo se registró la baja del correo electrónico, o null.
- whatsapp_consent boolean Puede ser null
  Consentimiento de WhatsApp: false si se rechazó, true si consta, null si se desconoce.
- provenance object
  El origen de cada permiso.
merged_into string Puede ser null Prefijo del id lead_…
El lead en el que se fusionó este registro, o null (también si ese lead ya no existe).
transferred_to object Puede ser null
Adónde se traspasó este lead dentro de tu organización, o null. El equipo puede ser uno que tu clave no lee.
- team string Prefijo del id team_…
  El equipo de destino.
- lead string Puede ser null Prefijo del id lead_…
  El lead de destino, o null si su id no puede nombrarse entre equipos: lo creó el traspaso de un asistente, o el traspaso cayó en un lead existente de anuncios (Meta, Google Ads o LinkedIn) u otro lead con id fijo.
revived_at string Puede ser null Formato date-time
Cuándo volvió el contacto por su cuenta y reactivó un lead archivado por última vez, o null.
pipeline_cleared boolean
Verdadero si el lead se convirtió con "borrar datos del embudo": tablero, etapa, prioridad, responsables, valor estimado y los campos de origen salvo source_channel son null porque se borraron.
converted_at string Puede ser null Formato date-time
Cuándo se convirtió el lead, mientras su estado es converted; si no, null.
value_at_conversion number Puede ser null
El valor estimado al convertirlo, en unidades principales. Se conserva al borrar los datos del embudo.
priority string Puede ser null
Prioridad, o null.
Valores posibles
- low
- medium
- high
- urgent
tags Array<string>
Etiquetas tal como están guardadas. lead y booking son etiquetas del sistema.
board string Puede ser null Prefijo del id brd_…
El tablero, resuelto a través de la etapa si la hay; o null.
stage string Puede ser null Prefijo del id stg_…
La etapa, o null.
assignees Array<string> Puede ser null Prefijo del id mem_…
Miembros asignados, ordenados. Null cuando el registro no tiene datos del embudo.
estimated_value number Puede ser null
Valor estimado en unidades principales tal como está guardado (con decimales), o null.
estimated_value_currency null Puede ser null
Siempre null: Totem no guarda moneda con el valor.
source string Puede ser null
El origen guardado del lead; api cubre también los leads que crea el propio Totem (por ejemplo, desde una conversación o una llamada), ver source_detail. Null si no hay ninguno.
Valores posibles
- meta_lead_ads
- manual
- website_form
- booking_page
- csv_import
- api
- chatbot
- google_ads
- linkedin
- other
source_channel string Puede ser null
El canal por el que empezó el registro (por ejemplo whatsapp, phone, widget), o null. El equipo puede editarlo.
source_detail string Puede ser null
conversation, call, external:<proveedor>, gated_ad:<origen>, family_handoff, api_intake o unknown; null cuando source no necesita detalle.
source_provenance string Puede ser null
server_written si Totem fijó el origen a partir de lo que informó la plataforma de anuncios; si no, member_editable (el equipo puede cambiarlo). Null junto con source.
Valores posibles
- server_written
- member_editable
created_at string Formato date-time
Cuándo se creó el registro.
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "record_kind": "lead",
  "name": "Alex",
  "surname": "Rivera",
  "email": "alex.rivera@example.com",
  "company": "Example Dental",
  "phone": "+12025550123",
  "phone_status": "valid",
  "status": "contacted",
  "status_set_by": "ai",
  "archive_reason": null,
  "archived_from_status": null,
  "contact_permissions": {
    "do_not_contact": false,
    "email_opt_out": false,
    "email_opt_out_at": null,
    "whatsapp_consent": null,
    "provenance": {
      "do_not_contact": null,
      "email_opt_out": null,
      "whatsapp_consent": null
    }
  },
  "merged_into": null,
  "transferred_to": null,
  "revived_at": null,
  "pipeline_cleared": false,
  "converted_at": null,
  "value_at_conversion": null,
  "priority": "high",
  "tags": [
    "spring-check-up"
  ],
  "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
  "assignees": [
    "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
  ],
  "estimated_value": 1200,
  "estimated_value_currency": null,
  "source": "meta_lead_ads",
  "source_channel": null,
  "source_detail": null,
  "source_provenance": "member_editable",
  "created_at": "2026-09-28T10:15:00.000Z",
  "version": 3,
  "updated_at": "2026-09-28T10:20:01.250Z"
}

El objeto `LeadDetail`

Un lead con sus facetas attribution y response, cada una con su propia version. Una faceta es null solo mientras Totem aún la prepara.

Atributos

id string Prefijo del id lead_…
Identificador público del registro.
object string
Siempre lead.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece el registro.
record_kind string
lead si el registro tiene un estado del embudo; si no, client. Un lead cuyo estado no conoce esta versión trae status: null.
Valores posibles
- lead
- client
name string Puede ser null
Nombre o nombre visible, o null.
surname string Puede ser null
Apellidos, o null.
email string Puede ser null
Email tal como está guardado, o null.
company string Puede ser null
Empresa, o null.
phone string Puede ser null
Teléfono en E.164, solo si el número guardado es válido; si no, null.
phone_status string
valid (ver phone), invalid (hay un número guardado que no es válido, por ejemplo uno guardado sin prefijo de país) o missing.
Valores posibles
- valid
- invalid
- missing
status string Puede ser null
Estado en el embudo; null en un cliente o si es un estado que esta versión no conoce. converted no significa "ganado".
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
status_set_by string Puede ser null
Quién fijó el estado actual: una persona, la IA, la automatización de Totem, una llamada a la API o desconocido (ninguna transición registrada llega a él). Null cuando status es null.
Valores posibles
- human
- ai
- system
- api
- unknown
archive_reason string Puede ser null
Por qué se archivó el registro, como código cerrado; el texto libre guardado es other. Null si no hay ninguno.
Valores posibles
- opt_out
- no_consent
- not_interested
- not_qualified
- no_contact
- merged
- family_transfer
- other
archived_from_status string Puede ser null
El estado que tenía el lead antes de su archivo actual; null si no está archivado o si se desconoce.
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
contact_permissions object
Permisos de contacto. Aplícalos antes de cualquier contacto desde tus propios sistemas.
- do_not_contact boolean
  Verdadero cuando la persona pidió no ser contactada nunca (motivo de archivo opt_out). Detén todos los canales.
- email_opt_out boolean
  Verdadero cuando la persona se dio de baja del correo electrónico comercial y de seguimiento.
- email_opt_out_at string Puede ser null Formato date-time
  Cuándo se registró la baja del correo electrónico, o null.
- whatsapp_consent boolean Puede ser null
  Consentimiento de WhatsApp: false si se rechazó, true si consta, null si se desconoce.
- provenance object
  El origen de cada permiso.
merged_into string Puede ser null Prefijo del id lead_…
El lead en el que se fusionó este registro, o null (también si ese lead ya no existe).
transferred_to object Puede ser null
Adónde se traspasó este lead dentro de tu organización, o null. El equipo puede ser uno que tu clave no lee.
- team string Prefijo del id team_…
  El equipo de destino.
- lead string Puede ser null Prefijo del id lead_…
  El lead de destino, o null si su id no puede nombrarse entre equipos: lo creó el traspaso de un asistente, o el traspaso cayó en un lead existente de anuncios (Meta, Google Ads o LinkedIn) u otro lead con id fijo.
revived_at string Puede ser null Formato date-time
Cuándo volvió el contacto por su cuenta y reactivó un lead archivado por última vez, o null.
pipeline_cleared boolean
Verdadero si el lead se convirtió con "borrar datos del embudo": tablero, etapa, prioridad, responsables, valor estimado y los campos de origen salvo source_channel son null porque se borraron.
converted_at string Puede ser null Formato date-time
Cuándo se convirtió el lead, mientras su estado es converted; si no, null.
value_at_conversion number Puede ser null
El valor estimado al convertirlo, en unidades principales. Se conserva al borrar los datos del embudo.
priority string Puede ser null
Prioridad, o null.
Valores posibles
- low
- medium
- high
- urgent
tags Array<string>
Etiquetas tal como están guardadas. lead y booking son etiquetas del sistema.
board string Puede ser null Prefijo del id brd_…
El tablero, resuelto a través de la etapa si la hay; o null.
stage string Puede ser null Prefijo del id stg_…
La etapa, o null.
assignees Array<string> Puede ser null Prefijo del id mem_…
Miembros asignados, ordenados. Null cuando el registro no tiene datos del embudo.
estimated_value number Puede ser null
Valor estimado en unidades principales tal como está guardado (con decimales), o null.
estimated_value_currency null Puede ser null
Siempre null: Totem no guarda moneda con el valor.
source string Puede ser null
El origen guardado del lead; api cubre también los leads que crea el propio Totem (por ejemplo, desde una conversación o una llamada), ver source_detail. Null si no hay ninguno.
Valores posibles
- meta_lead_ads
- manual
- website_form
- booking_page
- csv_import
- api
- chatbot
- google_ads
- linkedin
- other
source_channel string Puede ser null
El canal por el que empezó el registro (por ejemplo whatsapp, phone, widget), o null. El equipo puede editarlo.
source_detail string Puede ser null
conversation, call, external:<proveedor>, gated_ad:<origen>, family_handoff, api_intake o unknown; null cuando source no necesita detalle.
source_provenance string Puede ser null
server_written si Totem fijó el origen a partir de lo que informó la plataforma de anuncios; si no, member_editable (el equipo puede cambiarlo). Null junto con source.
Valores posibles
- server_written
- member_editable
created_at string Formato date-time
Cuándo se creó el registro.
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.
attribution LeadAttribution Puede ser null
La faceta de atribución del lead, o null mientras Totem aún la prepara.
response LeadResponse Puede ser null
La faceta de respuesta del lead, o null mientras Totem aún la prepara.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "record_kind": "lead",
  "name": "Alex",
  "surname": "Rivera",
  "email": "alex.rivera@example.com",
  "company": "Example Dental",
  "phone": "+12025550123",
  "phone_status": "valid",
  "status": "contacted",
  "status_set_by": "ai",
  "archive_reason": null,
  "archived_from_status": null,
  "contact_permissions": {
    "do_not_contact": false,
    "email_opt_out": false,
    "email_opt_out_at": null,
    "whatsapp_consent": null,
    "provenance": {
      "do_not_contact": null,
      "email_opt_out": null,
      "whatsapp_consent": null
    }
  },
  "merged_into": null,
  "transferred_to": null,
  "revived_at": null,
  "pipeline_cleared": false,
  "converted_at": null,
  "value_at_conversion": null,
  "priority": "high",
  "tags": [
    "spring-check-up"
  ],
  "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
  "assignees": [
    "mem_h548E7UiYhutHhucVrQCzkM0eaea0"
  ],
  "estimated_value": 1200,
  "estimated_value_currency": null,
  "source": "meta_lead_ads",
  "source_channel": null,
  "source_detail": null,
  "source_provenance": "member_editable",
  "created_at": "2026-09-28T10:15:00.000Z",
  "version": 3,
  "updated_at": "2026-09-28T10:20:01.250Z",
  "attribution": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_attribution",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "original_capture": {
      "capture": "at_creation",
      "captured_at": "2026-09-28T10:15:00.000Z",
      "source": "meta_lead_ads",
      "source_hint": null,
      "source_channel": null,
      "external_provider": null,
      "received_at": "2026-09-28T10:15:00.000Z",
      "submitted_at": "2026-09-28T10:14:30.000Z",
      "origin": null,
      "campaign": {
        "id": {
          "value": "120210000000000101",
          "provenance": "provider"
        },
        "name": {
          "value": "Spring check-up",
          "provenance": "provider"
        }
      },
      "ad": {
        "id": {
          "value": "120210000000000303",
          "provenance": "provider"
        },
        "name": {
          "value": "Free first visit",
          "provenance": "provider"
        }
      },
      "ad_set": {
        "id": {
          "value": "120210000000000202",
          "provenance": "provider"
        },
        "name": {
          "value": "Families nearby",
          "provenance": "provider"
        }
      },
      "ad_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "form": {
        "id": {
          "value": "900000000000000404",
          "provenance": "provider"
        },
        "name": {
          "value": "Book a check-up",
          "provenance": "provider"
        }
      },
      "creative": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "asset_group": {
        "id": {
          "value": null,
          "provenance": "not_captured"
        }
      },
      "page": {
        "id": {
          "value": "100000000000000505",
          "provenance": "provider"
        },
        "name": {
          "value": "Example Dental",
          "provenance": "provider"
        }
      },
      "utm": null,
      "click_network": {
        "value": null,
        "provenance": "not_captured"
      },
      "ad_referral": null,
      "family_origin": null,
      "audience": {
        "value": null,
        "missing_reason": "unsupported"
      }
    },
    "original_capture_missing_reason": null,
    "latest_submission": null,
    "latest_submission_missing_reason": "not_captured",
    "version": 1,
    "updated_at": "2026-09-28T10:15:02.100Z"
  },
  "response": {
    "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
    "object": "lead_response",
    "livemode": false,
    "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
    "last_inbound_at": "2026-10-01T08:58:00.000Z",
    "last_outbound_at": "2026-10-01T08:59:30.000Z",
    "awaiting_reply": false,
    "last_answered_call_at": "2026-09-28T10:17:00.000Z",
    "last_whatsapp_delivery_status": "read",
    "coverage": {
      "conversations": 2,
      "calls": 1,
      "channels_without_delivery_data": [
        "email"
      ],
      "truncated": false
    },
    "version": 7,
    "updated_at": "2026-10-01T08:59:31.040Z"
  }
}

El objeto `LeadAttribution`

De dónde viene un lead: su captura original y su último envío.

Atributos

id string Prefijo del id lead_…
Identificador público del registro.
object string
Siempre lead_attribution.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece el lead.
original_capture object Puede ser null
Cómo entró el lead en el CRM por primera vez, fijado una sola vez; null si no se capturó. "Original" es la primera vez que el contacto entró en el CRM, no el primer anuncio al que respondió.
- capture string
  at_creation: fijado con el lead tal como se guardó por primera vez. at_activation: copiado una vez del lead tal como estaba al activar la API, para un lead sin registro de captura (creado antes de que Totem empezara a registrar la atribución, o cuya creación no se registró).
  Valores posibles
  at_creation
  at_activation
- captured_at string Formato date-time
  Cuándo se escribió el registro.
- source string Puede ser null
  El origen del lead en la captura, del mismo conjunto que el source del lead; api cubre también los leads que crea el propio Totem (por ejemplo, desde una conversación o una llamada, ver origin). Null si no había ninguno.
  Valores posibles
  meta_lead_ads
  manual
  website_form
  booking_page
  csv_import
  api
- source_hint string Puede ser null
  El origen real de un lead de anuncios restringido guardado como api, o null.
- source_channel string Puede ser null
  El canal en la captura, o null.
- external_provider string Puede ser null
  El portal o la plataforma de citas de un lead reenviado o sincronizado, o null.
- received_at string Puede ser null Formato date-time
  Cuándo se recibió el lead, tal como se escribió la primera vez, o null.
- submitted_at string Puede ser null Formato date-time
  Cuándo dice la plataforma de anuncios que se envió el formulario, o null.
- origin object Puede ser null
  La conversación o llamada que creó el lead (nunca su id), o null (también para un origen de otro tipo).
- campaign object
  La campaña.
- ad object
  El anuncio.
- ad_set object
  El conjunto de anuncios de Meta.
- ad_group object
  El grupo de anuncios de Google Ads.
- form object
  El formulario de clientes potenciales.
- creative object
  La creatividad.
- asset_group object
  El grupo de recursos de Google Ads.
- page object
  La página de Facebook.
- utm object Puede ser null
  Las cinco claves UTM estándar, o null si no se capturó ninguna.
- click_network object
  La red del primer identificador de clic (google o meta). El identificador nunca se guarda.
- ad_referral object Puede ser null
  El primer referido de anuncio de Meta de la conversación que creó el lead, o null.
- family_origin object Puede ser null
  El traspaso desde otro equipo de tu organización que creó el lead, o null.
- audience object
  No disponible en esta versión.
original_capture_missing_reason string Puede ser null
not_captured cuando original_capture es null; si no, null.
Valores posibles
- not_captured
latest_submission object Puede ser null
El envío de anuncio más reciente registrado para este lead, incluida una repetición sobre un contacto existente; null si no hay ninguno. Un envío que la plataforma de anuncios informa como borrado (un miembro de LinkedIn que borra su respuesta al formulario) deja de mostrarse, y cuando el más reciente caduca o se retira puede mostrarse uno anterior.
- provider string
  La plataforma de anuncios.
  Valores posibles
  meta
  google_ads
  linkedin
- submitted_at string Puede ser null Formato date-time
  Cuándo dice la plataforma que se envió, o null.
- campaign object
  La campaña.
- ad object
  El anuncio.
- ad_set object
  El conjunto de anuncios de Meta.
- ad_group object
  El grupo de anuncios de Google Ads.
- form object
  El formulario de clientes potenciales.
- creative object
  La creatividad.
- asset_group object
  El grupo de recursos de Google Ads.
- utm object Puede ser null
  Sus claves UTM, o null.
- expires_at string Puede ser null Formato date-time
  Cuándo deja de poder leerse este envío (Google Ads y LinkedIn lo guardan 90 días); null en Meta.
latest_submission_missing_reason string Puede ser null
not_captured cuando latest_submission es null; si no, null.
Valores posibles
- not_captured
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead_attribution",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "original_capture": {
    "capture": "at_creation",
    "captured_at": "2026-09-28T10:15:00.000Z",
    "source": "meta_lead_ads",
    "source_hint": null,
    "source_channel": null,
    "external_provider": null,
    "received_at": "2026-09-28T10:15:00.000Z",
    "submitted_at": "2026-09-28T10:14:30.000Z",
    "origin": null,
    "campaign": {
      "id": {
        "value": "120210000000000101",
        "provenance": "provider"
      },
      "name": {
        "value": "Spring check-up",
        "provenance": "provider"
      }
    },
    "ad": {
      "id": {
        "value": "120210000000000303",
        "provenance": "provider"
      },
      "name": {
        "value": "Free first visit",
        "provenance": "provider"
      }
    },
    "ad_set": {
      "id": {
        "value": "120210000000000202",
        "provenance": "provider"
      },
      "name": {
        "value": "Families nearby",
        "provenance": "provider"
      }
    },
    "ad_group": {
      "id": {
        "value": null,
        "provenance": "not_captured"
      }
    },
    "form": {
      "id": {
        "value": "900000000000000404",
        "provenance": "provider"
      },
      "name": {
        "value": "Book a check-up",
        "provenance": "provider"
      }
    },
    "creative": {
      "id": {
        "value": null,
        "provenance": "not_captured"
      }
    },
    "asset_group": {
      "id": {
        "value": null,
        "provenance": "not_captured"
      }
    },
    "page": {
      "id": {
        "value": "100000000000000505",
        "provenance": "provider"
      },
      "name": {
        "value": "Example Dental",
        "provenance": "provider"
      }
    },
    "utm": null,
    "click_network": {
      "value": null,
      "provenance": "not_captured"
    },
    "ad_referral": null,
    "family_origin": null,
    "audience": {
      "value": null,
      "missing_reason": "unsupported"
    }
  },
  "original_capture_missing_reason": null,
  "latest_submission": null,
  "latest_submission_missing_reason": "not_captured",
  "version": 1,
  "updated_at": "2026-09-28T10:15:02.100Z"
}

El objeto `LeadResponse`

Cómo ha respondido el equipo a un lead en sus conversaciones y llamadas: los últimos mensajes en cada sentido y si tiene una respuesta pendiente. Usa el identificador de su lead.

Atributos

id string Prefijo del id lead_…
Identificador público del registro.
object string
Siempre lead_response.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
last_inbound_at string Puede ser null Formato date-time
El último mensaje del cliente en cualquiera de las conversaciones del lead (UTC), o null. No cuentan: mensajes borrados, historial de WhatsApp importado ni los turnos del visitante del chat web. Los contenidos compartidos de Instagram no se distinguen y sí cuentan.
last_outbound_at string Puede ser null Formato date-time
El último mensaje enviado al cliente que no falló, en cualquiera de las conversaciones del lead y lo enviara quien lo enviara (UTC), o null. El historial de WhatsApp importado sí cuenta.
awaiting_reply boolean
Verdadero cuando last_inbound_at es posterior a la última respuesta en cualquiera de las conversaciones del lead. Una respuesta es un mensaje enviado que no falló y que se registró como respuesta de conversación o sin propósito; no cuentan la prospección, los mensajes transaccionales (como los recordatorios) ni el historial importado. La mayoría de los mensajes guardados no tienen propósito, así que un envío automático registrado sin él también cuenta como respuesta. Falso si el cliente nunca ha escrito.
last_answered_call_at string Puede ser null Formato date-time
Cuándo empezó la última llamada del lead cuyo outcome es answered_human o answered_ai (UTC), o null. Una saliente conectada en las líneas de teléfono de Totem es unknown, así que no cuenta.
last_whatsapp_delivery_status string Puede ser null
delivered, read o failed del último mensaje enviado al lead por WhatsApp. Null si ese mensaje aún no tiene confirmación (sent nunca se guarda) o si al lead no se le ha enviado ningún mensaje por WhatsApp.
Valores posibles
- delivered
- read
- failed
coverage object
De qué se calcularon estos datos.
- conversations integer Rango 0–20
  Las conversaciones del lead con las que se calcularon estos datos, de la más reciente a la más antigua; como máximo 20.
- calls integer Rango 0–50
  Las llamadas del lead con las que se calculó last_answered_call_at, de la más reciente a la más antigua; como máximo 50.
- channels_without_delivery_data Array<string>
  Los canales de esas conversaciones que no guardan confirmaciones de entrega (todos menos WhatsApp), ordenados.
  Valores posibles
  sms
  facebook
  instagram
  tiktok
  chatbot
  email
- truncated boolean
  Verdadero si se alcanzó un límite de lectura (20 conversaciones, 200 mensajes o 50 llamadas): la actividad más antigua no se leyó, así que una hora puede ser null o anterior a la real, y awaiting_reply puede no ver una respuesta más antigua.
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

{
  "id": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "object": "lead_response",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "last_inbound_at": "2026-10-01T08:58:00.000Z",
  "last_outbound_at": "2026-10-01T08:59:30.000Z",
  "awaiting_reply": false,
  "last_answered_call_at": "2026-09-28T10:17:00.000Z",
  "last_whatsapp_delivery_status": "read",
  "coverage": {
    "conversations": 2,
    "calls": 1,
    "channels_without_delivery_data": [
      "email"
    ],
    "truncated": false
  },
  "version": 7,
  "updated_at": "2026-10-01T08:59:31.040Z"
}

El objeto `Activity`

Una transición de etapa, estado o responsables de un lead. Una actividad no cambia una vez escrita.

Atributos comunes a todas las variantes

id string Prefijo del id act_…
Identificador público del registro.
object string
Siempre activity.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece el lead.
lead string Puede ser null Prefijo del id lead_…
El lead que cambió. Null solo mientras Totem aún no ha asignado su id al lead.
occurred_at string Formato date-time
Cuándo se guardó el cambio.
actor_kind string
Quién hizo el cambio: una persona, la IA, la automatización de Totem, una llamada a la API o desconocido. Totem sabe quién hizo un cambio solo cuando el mismo guardado escribió el estado del lead, así que un cambio de etapa o de responsables hecho por sí solo es desconocido.
Valores posibles
- human
- ai
- system
- api
- unknown
stage_snapshot object Puede ser null
La etapa en la que quedó el lead tras el cambio (al borrar los datos del embudo, la que dejó), o null.
- stage string Puede ser null Prefijo del id stg_…
  La etapa.
- board string Puede ser null Prefijo del id brd_…
  Su tablero, o null en una etapa antigua sin tablero.
- name string Puede ser null
  El nombre de la etapa cuando se registró el cambio, o null si la etapa ya estaba borrada.
value_snapshot number Puede ser null
El valor estimado en ese momento, en unidades principales, o null.
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

Variantes

Cada Activity es exactamente una de estas 3 variantes.

Una transición de estado

Cuando type es uno de status_changed archived unarchived revived

type string
status_changed, archived, unarchived o revived (el contacto volvió por su cuenta y reabrió un lead archivado).
Valores posibles
- status_changed
- archived
- unarchived
- revived
from string Puede ser null
El estado anterior, o null si no había.
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable
to string
El estado posterior.
Valores posibles
- new
- contacted
- qualified
- negotiating
- converted
- lost
- archived
- unreachable

Un cambio de etapa

Cuando type es stage_changed

type string
Siempre stage_changed.
from object Puede ser null
La etapa y el tablero anteriores, o null si el lead no tenía ninguno.
- stage string Puede ser null Prefijo del id stg_…
  La etapa.
- board string Puede ser null Prefijo del id brd_…
  El tablero, o null en una etapa antigua sin tablero.
to object
La etapa y el tablero posteriores.
- stage string Puede ser null Prefijo del id stg_…
  La etapa.
- board string Puede ser null Prefijo del id brd_…
  El tablero, o null en una etapa antigua sin tablero.

Un cambio de miembros asignados

Cuando type es assignees_changed

type string
Siempre assignees_changed.
from Array<string> Prefijo del id mem_…
Los miembros asignados antes, ordenados.
to Array<string> Prefijo del id mem_…
Los miembros asignados después, ordenados.

{
  "id": "act_aBgzeetVKDEjpAAkXfEFF53ZGd2ZMmGhUDKgagqLbh6c7R1GqOl0xsFw7pyRhD3SqqYWGMdb371xxj",
  "object": "activity",
  "livemode": false,
  "type": "stage_changed",
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "lead": "lead_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXKSF0QbLS8CiUKJpEP34LFQG",
  "occurred_at": "2026-09-28T10:20:00.000Z",
  "actor_kind": "ai",
  "stage_snapshot": {
    "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
    "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
    "name": "Contacted"
  },
  "value_snapshot": 1200,
  "from": {
    "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
    "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
  },
  "to": {
    "stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
    "board": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst"
  },
  "version": 1,
  "updated_at": "2026-09-28T10:20:01.500Z"
}

El objeto `Board`

Un tablero con sus etapas en el orden del embudo.

Atributos

id string Prefijo del id brd_…
Identificador público del registro.
object string
Siempre board.
livemode boolean
true en datos reales; false en los datos de ejemplo.
team string Prefijo del id team_…
El equipo al que pertenece este registro.
name string Puede ser null ≥ 1 caracteres
El nombre del tablero, o null si no hay ninguno guardado.
is_default boolean
Verdadero en el tablero por defecto del equipo, donde llegan los leads nuevos salvo que se enruten a otro.
is_archived boolean
Verdadero si el tablero está archivado (oculto en el selector de tableros). Sus leads se siguen exportando.
appointment_booked_stage string Puede ser null Prefijo del id stg_…
La etapa de este tablero a la que pasa un lead cuando se confirma su primera cita, o null si no hay ninguna o no es una etapa de este tablero.
stages Array<object>
Las etapas del tablero, ordenadas por posición y después por id. Una etapa sin ninguna posición guardada no aparece, aunque un lead puede seguir indicándola.
- object string
  Siempre stage.
- id string Prefijo del id stg_…
  Id público de la etapa; el stage de un lead la nombra.
- name string Puede ser null ≥ 1 caracteres
  El nombre de la etapa, o null si no hay ninguno guardado.
- position number Puede ser null
  La posición de la etapa en su tablero, de izquierda a derecha; null si la posición guardada no es un número. Las etapas se listan en este orden.
- is_default boolean
  Verdadero en la etapa a la que entran los leads nuevos de este tablero.
- is_final boolean
  Verdadero en una etapa final: mover un lead aquí lo marca como convertido.
- is_archive boolean
  Verdadero en una etapa de archivo, cuyos leads no se muestran en la vista principal del tablero.
- mode string Puede ser null
  Quién mueve los leads: standard (solo personas), supervised (la IA puede meter leads, las personas los sacan) o automated (la IA hace el contacto y mete y saca leads); null si es un valor que esta versión no conoce.
  Valores posibles
  standard
  supervised
  automated
version integer Rango ≥ 1
Aumenta cada vez que cambia alguno de los campos exportados del registro. Aplica un cambio solo si su versión es mayor que la que guardas.
updated_at string Formato date-time
Cuándo registró Totem esta versión (UTC). No es la hora en que ocurrió el hecho.

{
  "id": "brd_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMX3trzsVUZQuHcMSuDh1aRIst",
  "object": "board",
  "livemode": false,
  "team": "team_r9uYrIW4gSFJJ6hZQ9ip1UIpPaAD1CF7NR",
  "name": "New patients",
  "is_default": true,
  "is_archived": false,
  "appointment_booked_stage": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
  "stages": [
    {
      "object": "stage",
      "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVR3422Yg",
      "name": "New",
      "position": 0,
      "is_default": true,
      "is_final": false,
      "is_archive": false,
      "mode": "automated"
    },
    {
      "object": "stage",
      "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVS3oYvs0",
      "name": "Contacted",
      "position": 1,
      "is_default": false,
      "is_final": false,
      "is_archive": false,
      "mode": "supervised"
    },
    {
      "object": "stage",
      "id": "stg_r72EfbRNUzuqORFJR0O8HxAwEXd93jGUTYMaMMXWBYWcKwVTY3CRZlVT1QpfZ5",
      "name": "Visit booked",
      "position": 2,
      "is_default": false,
      "is_final": true,
      "is_archive": false,
      "mode": "standard"
    }
  ],
  "version": 4,
  "updated_at": "2026-09-02T16:40:00.000Z"
}

Resumen

Atribución y respuesta

Buscar por teléfono o correo electrónico

Actividades

Tableros y etapas

Parámetros de consulta

Cabeceras

Respuesta

Errores

Parámetros de ruta

Respuesta

Errores

Cabeceras

Cuerpo de la petición

Respuesta

Errores

Parámetros de ruta

Parámetros de consulta

Respuesta

Errores

Parámetros de consulta

Cabeceras

Respuesta

Errores

El objeto Lead

Atributos

El objeto LeadDetail

Atributos

El objeto LeadAttribution

Atributos

El objeto LeadResponse

Atributos

El objeto Activity

Atributos comunes a todas las variantes

Variantes

Una transición de estado

Un cambio de etapa

Un cambio de miembros asignados

El objeto Board

Atributos

El objeto `Lead`

El objeto `LeadDetail`

El objeto `LeadAttribution`

El objeto `LeadResponse`

El objeto `Activity`

El objeto `Board`