> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rewards Endpoints

## Rewards Fields

| Field          | Data Type           | Definition                                                                                                                                                |
| :------------- | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `account_guid` | String              | The unique identifier for the `account` associated with the `reward`. Defined by MX. This value may be `null` if data is not available from the provider. |
| `balance_type` | String (enumerated) | The type of balance associated with the `reward`, for example, `BALANCE_TO_LEVEL`, or `TOTAL_BALANCE`.                                                    |
| `balance`      | Decimal             | The balance of the `reward`.                                                                                                                              |
| `created_at`   | String              | The time at which the `reward` was created.                                                                                                               |
| `description`  | String              | The description for the `reward` as given by the data provider.                                                                                           |
| `expires_on`   | String              | The date on which the balance expires.                                                                                                                    |
| `guid`         | String              | The unique identifier for the `reward`. Defined by MX.                                                                                                    |
| `member_guid`  | String              | The unique identifier for the `member` associated with the `reward`. Defined by MX.                                                                       |
| `unit_type`    | String (enumerated) | The units in which the balance is given, for example, `MILES` or `POINTS`.                                                                                |
| `user_guid`    | String              | The unique identifier for the `user` associated with the `reward`. Defined by MX.                                                                         |

### Balance Types

| Balance type        | Definition                                      |
| :------------------ | :---------------------------------------------- |
| `BALANCE`           | The reward `balance`.                           |
| `BALANCE_TO_LEVEL`  | The `balance` required to reach a reward level. |
| `BALANCE_TO_REWARD` | The `balance` required to qualify for a reward. |
| `EXPIRING_BALANCE`  | The reward `balance` that will be expiring.     |
| `TOTAL_BALANCE`     | The total reward `balance` available.           |

### Unit Types

| Unit type  |
| :--------- |
| `MILES`    |
| `POINTS`   |
| `SEGMENTS` |
| `DOLLARS`  |

## Fetch Rewards

Calling this endpoint initiates an aggregation-type event which will gather the member's rewards information, as well as account and transaction information.

Rewards data is also gathered with Atrium's daily background aggregations.

<Warning>
  **WARNING**

  This endpoint can trigger multi-factor authentication. It is therefore important that the end user be present when fetching rewards.
</Warning>

**Endpoint**: `POST /users/{user_guid}/members/{member_guid}/fetch_rewards`

<CodeGroup>
  ```bash Request theme={null}
  $ curl -i -X POST 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/fetch_rewards' \
    -H 'Accept: application/vnd.mx.atrium.beta+json' \
    -H 'Content-Type: application/json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "member": {
      "aggregated_at": "2016-10-13T18:07:57+00:00",
      "connection_status": "CONNECTED",
      "guid": "MBR-7c6f361b-e582-15b6-60c0-358f12466b4b",
      "identifier": "unique_id",
      "institution_code": "chase",
      "is_being_aggregated": true,
      "metadata": "{\"credentials_last_refreshed_at\": \"2015-10-15\"}",
      "name": "Chase Bank",
      "status": "INITIATED",
      "successfully_aggregated_at": "2016-10-13T17:57:38+00:00",
      "user_guid": "USR-fa7537f3-48aa-a683-a02a-b18940482f54"
    }
  }
  ```
</CodeGroup>

## List Rewards

Use this endpoint to list all the `rewards` associated with a specified `member`.

**Endpoint**: `GET /users/{user_guid}/members/{member_guid}/rewards`

<CodeGroup>
  ```bash Request theme={null}
  $ curl -i -X GET 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/rewards' \
    -H 'Accept: application/vnd.mx.atrium.beta+json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "rewards": [
      {
        "account_guid": "ACT-1234",
        "balance": 102,
        "balance_type": "EXPIRING_BALANCE",
        "created_at": "2020-01-28T21:09:01+0000",
        "description": "A description of the reward.",
        "expires_on": "2020-02-28",
        "guid": "RWD-1234",
        "member_guid": "MBR-4567",
        "unit_type": "POINTS",
        "user_guid": "USR-1234"
      },
      {
        "account_guid": "ACT-2345",
        "balance": 455,
        "balance_type": "EXPIRING_BALANCE",
        "created_at": "2020-01-28T21:09:01+0000",
        "description": "A description of the reward.",
        "expires_on": "2020-02-28",
        "guid": "RWD-2345",
        "member_guid": "MBR-4567",
        "unit_type": "POINTS",
        "user_guid": "USR-1234"
      }
    ]
  }
  ```
</CodeGroup>

## Read a Reward

Use this endpoint to read a specific `reward` based on its unique GUID.

**Endpoint**: `GET /users/{user_guid}/members/{member_guid}/rewards/{reward_guid}`

<CodeGroup>
  ```bash Request theme={null}
  $ curl -i -X GET 'https://vestibule.mx.com/users/{user_guid}/members/{member_guid}/rewards/{reward_guid}' \
    -H 'Accept: application/vnd.mx.atrium.beta+json' \
    -H 'MX-API-Key: {mx_api_key}' \
    -H 'MX-Client-ID: {mx_client_id}'
  ```

  ```json Response theme={null}
  {
    "reward": {
      "account_guid": "ACT-1234",
      "balance": 102,
      "balance_type": "EXPIRING_BALANCE",
      "created_at": "2020-01-28T21:09:01+0000",
      "description": "A description of the reward.",
      "expires_on": "2020-02-28",
      "guid": "RWD-1234",
      "member_guid": "MBR-4567",
      "unit_type": "POINTS",
      "user_guid": "USR-1234"
    }
  }
  ```
</CodeGroup>