# List referrals

## Request

| Method | URL                                         |
| ------ | ------------------------------------------- |
| `GET`  | `https://api.getrewardful.com/v1/referrals` |

### Optional

| Parameter            | Description                                                                                                                                                                                                                                         |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `affiliate_id`       | Show referrals for the specified affiliate.                                                                                                                                                                                                         |
| `conversion_state`   | Show referrals that are currently in the specified [conversion state(s)](https://developers.getrewardful.com/rest-api/referrals/object#conversion-states). Pass `conversion_state[]` to specify multiple conversion states.                         |
| `email`              | Show referrals with the specified email address.                                                                                                                                                                                                    |
| `stripe_customer_id` | Show referrals with the specified Stripe customer ID.                                                                                                                                                                                               |
| `page`               | [Pagination](https://developers.getrewardful.com/rest-api/overview#pagination) cursor specifying which page to fetch.                                                                                                                               |
| `limit`              | How many results to return per page. Default is 25, maximum is 100.                                                                                                                                                                                 |
| `expand`             | Which object(s) to [expand](https://developers.getrewardful.com/rest-api/overview#expanding-objects) in response data. See below for available objects.                                                                                             |
| `updated_until`      | <p>Show only referrals updated before the requested timestamp formatted as <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>.</p><p>Use alone or with <code>updated\_since</code> to fetch referrals within a specified time range.</p> |
| `updated_since`      | <p>Show only referrals updated after the requested timestamp formatted as <a href="https://en.wikipedia.org/wiki/ISO_8601">ISO 8601</a>.</p><p>Use alone or with <code>updated\_until</code> to fetch referrals within a specified time range.</p>  |

### Expandable objects

| Parameter   | Description                                                                                                                                         |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `affiliate` | Includes the full [affiliate object](https://developers.rewardful.com/rest-api/affiliates/object) as a nested object for each referral in the list. |

### Examples

#### List all referrals

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals \
  -u YOUR_API_SECRET:
```

#### List all referrals and include nested affiliate object

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals?expand[]=affiliate \
  -u YOUR_API_SECRET:
```

#### List referrals for a specific affiliate

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals?affiliate_id=b533bfca-7c70-4dec-9691-e136a8d9a26c \
  -u YOUR_API_SECRET:
```

#### List referrals with a "lead" conversion state

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals?conversion_state=lead \
  -u YOUR_API_SECRET:
```

#### List referrals with a "lead" or "conversion" conversion state

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals?conversion_state[]=lead&conversion_state[]=conversion \
  -u YOUR_API_SECRET:
```

#### List referrals updated before a specific timestamp

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals?updated_until=2024-12-04T13:02:57+02:00 \
  -u YOUR_API_SECRET:
```

#### List referrals updated after a specific timestamp

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals?updated_since=2024-12-04T13:02:57+02:00 \
  -u YOUR_API_SECRET:
```

#### Pagination: request page 3 with 50 results per page

```bash
curl --request GET \
  --url https://api.getrewardful.com/v1/referrals?page=3&limit=50
  -u YOUR_API_SECRET:
```