# Referrals

When a person comes to a bot through another contact's referral link, a link between them is created: the one who invited is the **referrer**, the invited one is the **referral**. The links form a chain: those the contact invited personally are their first line, those invited by them are the second line, and so on. For how this works in the dashboard, see [Referrals](https://support.watbot.org/chatbots/contacts/accounts-referrals#referrals).

The methods on this page let you run a referral programme in your own system: award bonuses along the chain, build network reports, check promotion conditions.

All three methods take a contact by its ID — `contact_id` — and work only with contacts of your own bots. Contacts in the responses have the same shape as in the contact methods: [Contact fields](https://support.watbot.org/api/contacts#contact-fields).

Errors common to the methods on this page (others are under [Errors](https://support.watbot.org/api#errors)):

| Code | When | Response |
|---|---|---|
| `404` | None of your bots' contacts has this `contact_id` — it does not exist or belongs to another account | `{"message": "Contact not found", "errors": {"contact_id": ["Contact not found"]}}` |
| `422` | `contact_id` is missing or not a number; invalid `depth`, `level` or `is_flat` | `{"message": "…", "errors": {…}}` |

A contact of another account and a non-existent one get the same answer, so the response does not reveal whether the ID exists in another account.

## getReferrers

Returns the contact's chain of referrers upwards: who invited them, who invited that person, and so on.

```endpoint
GET POST https://watbot.org/api/v1/getReferrers
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | number | yes | Contact ID |
| `depth` | number | no | How many levels up to go: 1 to 1000. Default 10 |
| `is_flat` | boolean | no | `true` or `1` — return the referrers as a list; `false` or `0` — nested inside each other. The same in a `GET` query string: `true`, `false`, `1` or `0`. Default `false` |

```bash title="Request"
curl -X POST "https://watbot.org/api/v1/getReferrers" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"contact_id": 4815170, "depth": 2}'
```

```json title="Response 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": []
  }
}
```

The response holds the contact itself, and its `referrer` field holds the referrer with their own `referrer`, and so on down to `depth`. If there is no referrer, the contact has no `referrer` field.

With `"is_flat": true`, `data` is a list of referrers without the contact itself, from nearest to farthest. Each has a `level` field: `-1` is the person who invited the contact, `-2` is their referrer, and so on:

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

The contact fields in the list are the same as above — they are shortened here. No referrers — `{"data": []}`.

## getReferrals

Returns the contact's first line — the people they invited personally — 15 per page.

```endpoint
GET POST https://watbot.org/api/v1/getReferrals
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | number | yes | Contact ID |
| `filters[tag_name]` | string or array of strings | no | Only referrals that have these tags — all of them at once. The first 10 tags are used |
| `page` | number | no | Page number, starting from 1. Default 1 |

Requesting referrals tagged "paid":

```bash title="Request"
curl -X POST "https://watbot.org/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"]}}'
```

```json title="Response 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://watbot.org/api/v1/getReferrals?page=1",
    "last": "https://watbot.org/api/v1/getReferrals?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": […],
    "path": "https://watbot.org/api/v1/getReferrals",
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}
```

Referrals are sorted by ascending `id`. The page size cannot be changed. Request the next pages with the `page` parameter until `links.next` becomes `null`; send `contact_id` and the filter with every request — the URLs in `links` do not carry them.

## getCountReferrals

Counts the contact's referrals: the whole network or a single line.

```endpoint
GET POST https://watbot.org/api/v1/getCountReferrals
```

| Parameter | Type | Required | Description |
|---|---|---|---|
| `contact_id` | number | yes | Contact ID |
| `level` | number | no | Line number, from 1: `1` — people the contact invited personally, `2` — people invited by them, and so on. Without it, the whole network is counted |
| `filters[tag_name]` | string or array of strings | no | Only referrals that have these tags — all of them at once. The first 10 tags are used |

How many people are in the second line:

```bash title="Request"
curl "https://watbot.org/api/v1/getCountReferrals?contact_id=4815162&level=2" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
```

```json title="Response 200"
{
  "data": {
    "count": 7
  }
}
```

If the contact has not invited anyone, `count` is `0`.

Here the number is in `data.count`, while [getNumberOfContacts](https://support.watbot.org/api/contacts#getnumberofcontacts) returns it in a top-level `count`, without `data`. This is historical and stays as is so as not to break existing integrations.