---
title: "List Payees"
method: GET
path: "/v4/payees"
tags: ["Payees"]
---

# List Payees

`GET /v4/payees`

Get a paginated response listing the payees for a payor.

## Query parameters

- `payorId` string, uuid, required
- `watchlistStatus` string — Current watchlist status. One of the following values: NONE, PENDING, REVIEW, PASSED, FAILED
- `disabled` boolean
- `onboardedStatus` string — Payee onboarded status. One of the following values: CREATED, INVITED, REGISTERED, ONBOARDED
- `email` string, email
- `displayName` string
- `remoteId` string
- `payeeType` string — Type of Payee. One of the following values: Individual, Company
- `payeeCountry` string
- `ofacStatus` string — OFAC status. One of the following values: PENDING, PASSED, FAILED
- `page` integer
- `pageSize` integer
- `sort` string

## Response `200`

Details of Payee

- PagedPayeeResponseV4 — List Payees Response Object
  - `summary` PagedPayeeResponseV3Summary
    - `totalPayeesCount` integer
    - `totalInvitedCount` integer
    - `totalRegisteredCount` integer
    - `totalOnboardedCount` integer
    - `totalWatchlistFailedCount` integer
  - `page` PagedPayeeResponseV3Page
    - `numberOfElements` integer
    - `totalElements` integer
    - `totalPages` integer
    - `page` integer
    - `pageSize` integer
  - `links` PagedPayeeResponseV3Links[]
    - `rel` string
    - `href` string
  - `content` GetPayeeListResponseV4[]
    - `payeeId` string, uuid
    - `payorRefs` PayeePayorRefV4[], nullable
      - `payorId` string, uuid
      - `remoteId` string
      - `invitationStatus` string
      - `invitationStatusTimestamp` string, date-time, nullable — The timestamp when the invitation status is updated
      - `paymentChannelId` string, uuid
      - `payableStatus` boolean — Indicates if the payee is payable for this payor
      - `payableIssues` PayableIssueV4[] — Indicates any conditions which prevent the payee from being payable for this payor
        - `code` string, required
        - `message` string, required
    - `email` string, email, nullable
    - `onboardedStatus` string — Payee onboarded status. One of the following values: CREATED, INVITED, REGISTERED, ONBOARDED
    - `watchlistStatus` string — Current watchlist status. One of the following values: NONE, PENDING, REVIEW, PASSED, FAILED
    - `watchlistStatusUpdatedTimestamp` string, date_time, nullable
    - `watchlistOverrideComment` string, nullable
    - `language` string — An IETF BCP 47 language code which has been configured for use within this Velo environment.<BR> See the /v1/supportedLanguages endpoint to list the available codes for an environment.
    - `created` string, date-time
    - `country` string — Valid ISO 3166 2 character country code. See the <a href="https://www.iso.org/iso-3166-country-codes.html" target="_blank" a>ISO specification</a> for details.
    - `displayName` string
    - `payeeType` string — Type of Payee. One of the following values: Individual, Company
    - `disabled` boolean
    - `disabledComment` string
    - `disabledUpdatedTimestamp` string, date-time
    - `managedByPayorId` string, uuid — The id of the payor if the payee is managed
    - `individual` GetPayeeListResponseIndividualV4
      - `name` NameV4
        - `title` string
        - `firstName` string
        - `otherNames` string
        - `lastName` string
    - `company` GetPayeeListResponseCompanyV4
      - `name` string
      - `operatingName` string, nullable

## Other responses

- `400` — Invalid request. See Error message payload for details of failure
- `401` — Invalid access token. May be expired or invalid
- `403` — The authentication does not have permissions to access the resource This usually occurs when there is a valid authentication instance (client or user) but they do not have the required permissions
- `404` — The resource was not found or is no longer available

## Changes

- **2023-08-15** `b924ba134e09` — 1 info
  - added the optional property `content/items/managedByPayorId` to the response with the `200` status
- **2022-06-27** `1e7a1734a45c` — 14 breaking, 14 info
  - removed the enum value `CREATED` from the `query` request parameter `onboardedStatus`
  - removed the enum value `Company` from the `query` request parameter `payeeType`
  - removed the enum value `FAILED` from the `query` request parameter `ofacStatus`
  - removed the enum value `FAILED` from the `query` request parameter `watchlistStatus`
  - …24 more
- **2022-04-07** `da77064fe233` — 1 info
  - the `content/items/country` response's property pattern `^[A-Z]{2}$` was added for the status `200`
- **2020-09-25** `dd71433847a6` — 4 breaking, 37 info
  - the `errors/items/` response's property type/format changed from ``/`` to `object`/`` for status `400`
  - the `errors/items/` response's property type/format changed from ``/`` to `object`/`` for status `401`
  - the `errors/items/` response's property type/format changed from ``/`` to `object`/`` for status `403`
  - the `errors/items/` response's property type/format changed from ``/`` to `object`/`` for status `404`
  - …37 more
- **2020-08-13** `75bb7af5ae63` — 1 info
  - endpoint added

[Full history](https://skmtc.dev/velopaymentsapi/apis/velo-payments-apis/changes/v4/payees/get.md)

---

[API](https://skmtc.dev/velopaymentsapi/apis/velo-payments-apis.md) · [All operations](https://skmtc.dev/velopaymentsapi/apis/velo-payments-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/velopaymentsapi/velo-payments-apis/revisions/05c3f09fc50a/schema)