> For the complete documentation index, see [llms.txt](https://docs.sparkloop.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sparkloop.app/api-v3/objects-schema/referral-object.md).

# Referral Object

## Referral Object

One subscriber a partner program received from a partner. The referral is the referred reader — its `uuid` is the subscriber's.

| Field                  | Type           | Description                                                                                                      |
| ---------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `uuid`                 | String         | The referred subscriber's UUID (`sub_…`).                                                                        |
| `email`                | String         | Subscriber email.                                                                                                |
| `name`                 | String \| null | Subscriber name.                                                                                                 |
| `country`              | String \| null | Acquisition country (uppercase ISO code, e.g. `US`).                                                             |
| `status`               | String         | Referral status (e.g. `confirmed`, `pending`, `rejected`).                                                       |
| `commission`           | Number         | Commission for this referral, in dollars.                                                                        |
| `rejection_reason`     | String \| null | Why it was rejected, if applicable.                                                                              |
| `payable`              | Boolean        | Whether this referral is payable.                                                                                |
| `referred_at`          | String \| null | When the referral was made (ISO 8601).                                                                           |
| `confirmed_at`         | String \| null | When it was confirmed (ISO 8601).                                                                                |
| `rejected_at`          | String \| null | When it was rejected (ISO 8601).                                                                                 |
| `recommending_partner` | Object         | The partner publication that drove it (**Publication Object**). Present only with `expand=recommending_partner`. |

**Example (`expand=recommending_partner`)**

```json
{
  "uuid": "sub_7b8c9d0e",
  "email": "reader@example.com",
  "name": "Jordan Rivera",
  "country": "US",
  "status": "confirmed",
  "commission": 2.5,
  "rejection_reason": null,
  "payable": true,
  "referred_at": "2026-06-02T11:00:00.000Z",
  "confirmed_at": "2026-06-09T11:00:00.000Z",
  "rejected_at": null,
  "recommending_partner": {
    "uuid": "pub_5fc782e24409",
    "name": "The Daily Byte",
    "description": "A daily newsletter about tech and culture.",
    "logo_url": "https://assets.sparkloop.app/logos/pub_5fc782e24409.png",
    "url": "https://thedailybyte.com"
  }
}
```