# GET /api/public/merchants

> Retrieve a paged list of Merchants

- Surface: `/api/public` · operationId `listMerchants` · Group: Merchant
- Authorisation: Token with scope `public:merchants:read`
- Organisation key: can't reach this route: the key check answers 403 `route_not_available`. Use a platform token for it.
- The spec: https://developers.rivr.io/openapi/api-public.json
- The spec's introduction: https://developers.rivr.io/reference/api-public.md
- Page in the portal: https://developers.rivr.io/reference/api-public/listMerchants

The examples target the sandbox (`https://api.test.rivr.io`) and need test credentials.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `pageNumber` | query | integer (int32) | no |  |
| `pageSize` | query | integer (int32) | no |  |
| `searchText` | query | string | no |  |

## Responses

### 200

OK

`application/json`

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `merchants` | Merchant[] |  |
| `merchants[].id` | string (uuid) |  |
| `merchants[].name` | string | (nullable) |
| `merchants[].organisationNumber` | string | (nullable) |
| `merchants[].externalId` | string | (nullable) |
| `metadata` | Metadata |  |
| `metadata.pageNumber` | integer (int32) |  |
| `metadata.pageSize` | integer (int32) |  |
| `metadata.totalItems` | integer (int32) |  |
| `metadata.totalPages` | integer (int32) |  |

**Example**

```json
{
  "merchants": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "string",
      "organisationNumber": "string",
      "externalId": "string"
    }
  ],
  "metadata": {
    "pageNumber": 0,
    "pageSize": 0,
    "totalItems": 0,
    "totalPages": 0
  }
}
```

### 401

The token is missing (`token_missing`), not valid (`token_invalid`), expired (`token_expired`) or could not be
checked (`authentication_unavailable`), or it reaches no platform (`platform_token_required`).

Error codes: [token_missing](https://developers.rivr.io/errors/token_missing.md), [token_invalid](https://developers.rivr.io/errors/token_invalid.md), [token_expired](https://developers.rivr.io/errors/token_expired.md), [authentication_unavailable](https://developers.rivr.io/errors/authentication_unavailable.md), [platform_token_required](https://developers.rivr.io/errors/platform_token_required.md)

`application/json`

```json
{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid Authorization Header",
  "propertyName": null,
  "message": "The request has no valid Authorization header. Send the token in the Authorization header, after Bearer.",
  "errorCode": "token_missing",
  "code": "token_missing",
  "type": "https://developers.rivr.io/errors/token_missing"
}
```

### 403

The token lacks the scope (`invalid_scope`), is a rivr-auth token that is not a clinic token
(`clinic_token_required`), or is an organisation API key, which this route is closed to (`route_not_available`).
The body also carries `error` and `error_description`, as before.

Error codes: [route_not_available](https://developers.rivr.io/errors/route_not_available.md), [invalid_scope](https://developers.rivr.io/errors/invalid_scope.md), [clinic_token_required](https://developers.rivr.io/errors/clinic_token_required.md)

`application/json`

```json
{
  "error": "route_not_available",
  "error_description": "This route cannot be called with an organization API key.",
  "propertyName": null,
  "message": "This route cannot be called with an organization API key.",
  "errorCode": "route_not_available",
  "code": "route_not_available",
  "type": "https://developers.rivr.io/errors/route_not_available"
}
```

### 500

Something unexpected failed: `internal_error`.

Error codes: [internal_error](https://developers.rivr.io/errors/internal_error.md)

`application/json`

```json
{
  "propertyName": null,
  "message": "Something unexpected failed at Rivr, and whether the request was carried out is not known. Check the order or what the request was about before you retry.",
  "errorCode": "internal_error",
  "code": "internal_error",
  "type": "https://developers.rivr.io/errors/internal_error"
}
```

## Example request

```bash
curl -X GET https://api.test.rivr.io/api/public/merchants \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```