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

# List Payees

`GET /v3/payees`

Get a paginated response listing the payees for a payor.

## Query parameters

- `payorId` string, uuid, required
- `ofacStatus` 'NONE' | 'PENDING' | 'REVIEW' | 'PASSED' | 'FAILED'
- `onboardedStatus` 'CREATED' | 'INVITED' | 'REGISTERED' | 'ONBOARDED'
- `Email` string, email
- `displayName` string
- `remoteId` string
- `payeeType` 'Individual' | 'Company'
- `payeeCountry` string
- `page` integer
- `pageSize` integer
- `sort` string

## Response `200`

Details of Payee

- PagedPayeeResponse2 — List Payees Response Object
  - `summary` PagedPayeeResponse2Summary
    - `totalPayeesCount` integer
    - `totalInvitedCount` integer
    - `totalRegisteredCount` integer
    - `totalOnboardedCount` integer
    - `totalWatchlistFailedCount` integer
  - `page` PagedPayeeResponsePage
    - `numberOfElements` integer
    - `totalElements` integer
    - `totalPages` integer
    - `page` integer
    - `pageSize` integer
  - `links` PagedPayeeResponseLinks[]
    - `rel` string
    - `href` string
  - `content` PayeeResponse2[]
    - `payeeId` string, uuid
    - `payorRefs` PayeePayorRefV3[], nullable
      - `payorId` string, uuid
      - `remoteId` string
      - `invitationStatus` 'ACCEPTED' | 'PENDING' | 'DECLINED'
      - `invitationStatusTimestamp` string, date-time, nullable — The timestamp when the invitation status is updated
      - `paymentChannelId` string, uuid
    - `email` string, email, nullable
    - `address` PayeeAddress
      - `line1` string, required
      - `line2` string, nullable
      - `line3` string, nullable
      - `line4` string, nullable
      - `city` string, required
      - `countyOrProvince` string, nullable
      - `zipOrPostcode` string, nullable
      - `country` string, required
    - `country` string
    - `displayName` string
    - `paymentChannel` PayeePaymentChannel
      - `paymentChannelName` string
      - `iban` string — Must match the regular expression ```^[A-Za-z0-9]+$```.
      - `accountNumber` string, required
      - `routingNumber` string, required
      - `countryCode` string, required — Country Code must be a valid 2 letter ISO 3166-1 country code.
      - `currency` 'USD' | 'GBP' | 'EUR', required
      - `accountName` string, required
    - `challenge` Challenge
      - `value` string, required
      - `description` string, required
    - `language` 'AR' | 'EN' | 'ES' | 'FR' | 'HE' | 'HI' | 'JA' | 'PT' | 'RU' | 'UR' | 'ZH' — Available Payee Language codes
    - `acceptTermsAndConditionsTimestamp` string, date-time, nullable — The timestamp when the payee last accepted T&Cs
    - `cellphoneNumber` string
    - `payeeType` 'Individual' | 'Company'
    - `company` CompanyResponse, nullable
      - `name` string, required
      - `operatingName` string, nullable
    - `individual` IndividualResponse
      - `name` IndividualV1Name, required
        - `title` string
        - `firstName` string, required
        - `otherNames` string
        - `lastName` string, required
    - `created` string, date-time
    - `gracePeriodEndDate` string, date, nullable
    - `watchlistStatusUpdatedTimestamp` string, date_time, nullable
    - `marketingOptIns` MarketingOptIn[]
      - `optedIn` boolean
      - `timestamp` string, date-time
    - `watchlistStatus` 'NONE' | 'PENDING' | 'REVIEW' | 'PASSED' | 'FAILED'
    - `onboardedStatus` 'CREATED' | 'INVITED' | 'REGISTERED' | 'ONBOARDED'

## 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` — Resource not found

## Changes

- **2020-01-28** `1b2abf26b5d6` — 2 breaking, 3 warning, 8 info
  - the `content/items/paymentChannel/countryCode` response property's minLength was decreased from `9` to `2` for the response status `200`
  - removed the required property `content/items/paymentChannel/routingNo` from the response with the `200` status
  - added the new `ACCEPTED` enum value to the `content/items/payorRefs/items/invitationStatus` response property for the response status `200`
  - added the new `DECLINED` enum value to the `content/items/payorRefs/items/invitationStatus` response property for the response status `200`
  - …9 more
- **2019-11-25** `86699f3efd3a` — 1 info
  - endpoint added
- **2019-07-15** `ced8e167a97c` — 1 info
  - api path removed with deprecation

[Change history](https://skmtc.dev/velopaymentsapi/apis/velo-payments-apis/changes/v3/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.dev/velopaymentsapi/apis/velo-payments-apis/revisions/1b2abf26b5d6?raw)