Referidos

Cuando una persona llega a un bot a través del enlace de referido de otro contacto, se crea un vínculo entre ellos: quien invitó es el referente, y el invitado, el referido. Los vínculos forman una cadena: las personas que el contacto invitó personalmente son su primera línea, las invitadas por ellas son la segunda línea, y así sucesivamente. Para ver cómo funciona en el panel, consulta Referidos.

Los métodos de esta página te permiten llevar un programa de referidos en tu propio sistema: otorgar bonos a lo largo de la cadena, crear informes de la red y comprobar las condiciones de una promoción.

Los tres métodos reciben un contacto por su ID, contact_id, y solo trabajan con contactos de tus propios bots. Los contactos de las respuestas tienen la misma estructura que en los métodos de contactos: Campos del contacto.

Errores comunes a los métodos de esta página (los demás están en Errores):

Código	Cuándo	Respuesta
`404`	Ningún contacto de tus bots tiene este `contact_id`: no existe o pertenece a otra cuenta	`{"message": "Contact not found", "errors": {"contact_id": ["Contact not found"]}}`
`422`	Falta `contact_id` o no es un número; `depth`, `level` o `is_flat` no son válidos	`{"message": "…", "errors": {…}}`

Un contacto de otra cuenta y uno inexistente reciben la misma respuesta, así que la respuesta no revela si el ID existe en otra cuenta.

getReferrers

Devuelve la cadena de referentes del contacto hacia arriba: quién lo invitó, quién invitó a esa persona, y así sucesivamente.

GETPOSThttps://app.cleverapp.pro/api/v1/getReferrers

Parámetro	Tipo	Obligatorio	Descripción
`contact_id`	número	sí	ID del contacto
`depth`	número	no	Cuántos niveles subir: de 1 a 1000. Por defecto, 10
`is_flat`	booleano	no	`true` o `1`: devolver los referentes como una lista; `false` o `0`: anidados unos dentro de otros. Lo mismo en la cadena de consulta de un `GET`: `true`, `false`, `1` o `0`. Por defecto, `false`

Solicitud

curl -X POST "https://app.cleverapp.pro/api/v1/getReferrers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815170, "depth": 2}'

Respuesta 200

{
  "data": {
    "id": 4815170,
    "bot_id": 12345,
    "phone": null,
    "email": null,
    "name": "Michael Brown",
    "address": null,
    "messenger": "telegram",
    "utm": [],
    "avatar": null,
    "telegram_id": "223456781",
    "telegram_username": null,
    "vk_user_id": null,
    "created_at": "2026-09-29T15:02:47+00:00",
    "unsubscribed_at": null,
    "referrer": {
      "id": 4815162,
      "bot_id": 12345,
      "phone": "15550100123",
      "email": null,
      "name": "Emily Johnson",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "123456789",
      "telegram_username": "emily_j",
      "vk_user_id": null,
      "created_at": "2026-09-28T07:41:12+00:00",
      "unsubscribed_at": null,
      "referrer": {
        "id": 4814901,
        "bot_id": 12345,
        "phone": null,
        "email": null,
        "name": "Sarah Miller",
        "address": null,
        "messenger": "telegram",
        "utm": [],
        "avatar": null,
        "telegram_id": "323456782",
        "telegram_username": "sarah_m",
        "vk_user_id": null,
        "created_at": "2026-09-20T11:30:05+00:00",
        "unsubscribed_at": null,
        "tags": ["partner"],
        "variables": []
      },
      "tags": [],
      "variables": []
    },
    "tags": [],
    "variables": []
  }
}

La respuesta contiene el propio contacto, y su campo referrer contiene al referente con su propio referrer, y así hasta depth. Si no hay referente, el contacto no tiene el campo referrer.

Con "is_flat": true, data es una lista de referentes sin el propio contacto, del más cercano al más lejano. Cada uno tiene un campo level: -1 es quien invitó al contacto, -2 es su referente, y así sucesivamente:

{
  "data": [
    {
      "id": 4815162,
      "name": "Emily Johnson",
      "…": "…",
      "tags": [],
      "variables": [],
      "level": -1
    },
    {
      "id": 4814901,
      "name": "Sarah Miller",
      "…": "…",
      "tags": ["partner"],
      "variables": [],
      "level": -2
    }
  ]
}

Los campos del contacto en la lista son los mismos que arriba; aquí están abreviados. Sin referentes: {"data": []}.

getReferrals

Devuelve la primera línea del contacto (las personas que invitó personalmente), 15 por página.

GETPOSThttps://app.cleverapp.pro/api/v1/getReferrals

Parámetro	Tipo	Obligatorio	Descripción
`contact_id`	número	sí	ID del contacto
`filters[tag_name]`	cadena o array de cadenas	no	Solo los referidos que tienen estas etiquetas, todas a la vez. Se usan las 10 primeras etiquetas
`page`	número	no	Número de página, a partir de 1. Por defecto, 1

Solicitud de los referidos con la etiqueta «paid»:

Solicitud

curl -X POST "https://app.cleverapp.pro/api/v1/getReferrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815162, "filters": {"tag_name": ["paid"]}}'

Respuesta 200

{
  "data": [
    {
      "id": 4815170,
      "bot_id": 12345,
      "phone": null,
      "email": null,
      "name": "Michael Brown",
      "address": null,
      "messenger": "telegram",
      "utm": [],
      "avatar": null,
      "telegram_id": "223456781",
      "telegram_username": null,
      "vk_user_id": null,
      "created_at": "2026-09-29T15:02:47+00:00",
      "unsubscribed_at": null,
      "tags": ["paid"],
      "variables": []
    }
  ],
  "links": {
    "first": "https://app.cleverapp.pro/api/v1/getReferrals?page=1",
    "last": "https://app.cleverapp.pro/api/v1/getReferrals?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": […],
    "path": "https://app.cleverapp.pro/api/v1/getReferrals",
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}

Los referidos se ordenan por id ascendente. El tamaño de página no se puede cambiar. Pide las páginas siguientes con el parámetro page hasta que links.next sea null; envía contact_id y el filtro en cada solicitud: las URL de links no los llevan.

getCountReferrals

Cuenta los referidos del contacto: toda la red o una sola línea.

GETPOSThttps://app.cleverapp.pro/api/v1/getCountReferrals

Parámetro	Tipo	Obligatorio	Descripción
`contact_id`	número	sí	ID del contacto
`level`	número	no	Número de línea, a partir de 1: `1`, las personas que el contacto invitó personalmente; `2`, las invitadas por ellas, y así sucesivamente. Sin él, se cuenta toda la red
`filters[tag_name]`	cadena o array de cadenas	no	Solo los referidos que tienen estas etiquetas, todas a la vez. Se usan las 10 primeras etiquetas

Cuántas personas hay en la segunda línea:

Solicitud

curl "https://app.cleverapp.pro/api/v1/getCountReferrals?contact_id=4815162&level=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Respuesta 200

{
  "data": {
    "count": 7
  }
}

Si el contacto no ha invitado a nadie, count es 0.

Aquí el número está en data.count, mientras que getNumberOfContacts lo devuelve en un count de nivel superior, sin data. Es así por motivos históricos y se mantiene para no romper las integraciones existentes.

Referidos#

getReferrers#

getReferrals#

getCountReferrals#

Referidos

getReferrers

getReferrals

getCountReferrals