# List

The reward list endpoint allows you to **list rewards for a specific search**. If a search is not provided, it will return all rewards.

### Parameters

<table data-header-hidden><thead><tr><th width="181.33333333333331">Key</th><th>Type</th></tr></thead><tbody><tr><td><strong>Key</strong></td><td><strong>Type</strong></td></tr><tr><td><strong>search</strong></td><td>Array String (Pathway / Reward ID or name)</td></tr><tr><td><strong>DEPRECATED</strong></td><td></td></tr><tr><td><strong>keyword</strong></td><td>String (Keyword search of pathways or rewards).</td></tr></tbody></table>

### Example

The example below searches for a reward. This returns an array of matched **rewards with a list of vouchers and their states**.

```
curl -X POST \
  v1/rewards/list \
  -H 'Authorization: Basic <Your Base64 Encoded Token>' \
  -d '{
	"search" : ["Cup of coffee",...]
}'
```

### Success Response

The response will contain an **array of pathway reward combination objects** which contains `pathway` details and `rewards` (which is the list of rewards on the [pathway](https://docs.falkor.io/pathways/create-a-pathway)). This is the same structure as the reward webhook payload.

```
{
    "status": "success",
    "data": [
        {
            "pathway": {
                "name": "My Pathway",
                "ID": "FA-HCPG-06RF"
            },
            "rewards": [
                {
                    "ID": "FARE-STZH-05MD",
                    "name": "Cup of Coffee",
                    "vouchers": [
                        {
                            "guid": "6c720133-3916-4172-94c9-62d1394fc72b",
                            "firstname": "Example",
                            "lastname": "One",
                            "email": "one@example.com",
                            "country": "South Africa",
                            "city": "Cape Town",
                            "state": "notified",
                            "expires": "never"
                        },
                        {
                            "guid": "6c720133-3916-4172-94c9-62d1394fc72b",
                            "firstname": "Example",
                            "lastname": "Two",
                            "email": "two@example.com",
                            "country": "United Kingdom",
                            "city": "London",
                            "state": "notified",
                            "expires": "never"
                        },
                        ...etc
                    ]
                },
                ...etc
            ]
        },
        ..etc
    ],
    "hash": "a4c6da80893b7e82462d23f64dcabf08",
    "response_time": 0.11021113395690918
}
```

### Pathway Reward Combination Object

| Key         | Type                                             |
| ----------- | ------------------------------------------------ |
| **pathway** | Object. The name and SKU of the related pathway. |
| **rewards** | Array. A list of rewards.                        |

### Reward Object

| Key          | Type                                  |
| ------------ | ------------------------------------- |
| **ID**       | String. ID or reward SKU reference.   |
| **name**     | String. The name of the reward.       |
| **vouchers** | Array. A list of unredeemed vouchers. |

### Voucher Object

The voucher object will contain a `guid` which is **used in the consume endpoint for rewards**. This will allow integrations to set the voucher **state** if the intention is to **manage redemption** of awards via **external systems**.&#x20;

{% content-ref url="consume" %}
[consume](https://everyday-digital.gitbook.io/falkor-dev-docs/pathways/rewards/consume)
{% endcontent-ref %}

| Key           | Type                                                                             |
| ------------- | -------------------------------------------------------------------------------- |
| **guid**      | String. A GUID of the voucher.                                                   |
| **state**     | String. The state of the voucher (pending, notified, verify, redeemed, expired). |
| **expires**   | String. The date the voucher expires.                                            |
| **firstname** | String                                                                           |
| **lastname**  | String                                                                           |
| **email**     | String                                                                           |
| **country**   | String                                                                           |
| **city**      | String                                                                           |
|               |                                                                                  |