# Beneficiary List Query

> Query beneficiary records with pagination.

```yaml
openapi: 3.1.0
info:
  title: Beneficiary List Query
  version: 1.0.0
  description: Query beneficiary records with pagination.
paths:
  /api/v1/beneficiary/queryList:
    post:
      summary: Beneficiary List Query
      description: Query beneficiary records with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: string
                  description: Merchant number assigned by Onerway. Retrieve it from the merchant
                    portal or onboarding material after your sandbox or
                    production account is created.
                payeeStatus:
                  type: string
                  description: Optional beneficiary review-status filter.
                beneficiaryId:
                  type: string
                  description: Optional beneficiary ID filter.
                merchantRefId:
                  type: string
                  description: Optional merchant-side beneficiary reference ID filter.
                cardNumber:
                  type: string
                  description: Optional bank-account or card-number filter.
                size:
                  type: integer
                  description: Page size.
                current:
                  type: integer
                  description: Current page number.
                sign:
                  type: string
                  description: Request signature string. Generate it according to the Transfer
                    request-signing rules with your merchant private key.
              required:
                - merchantNo
                - size
                - current
                - sign
            examples:
              query-beneficiaries-by-status:
                summary: Query beneficiaries by status
                value:
                  beneficiaryId: "12345"
                  cardNumber: "1234567890123456"
                  current: 1
                  merchantNo: "800181"
                  merchantRefId: beneficiary_demo_001
                  payeeStatus: PASS
                  sign: "{{SIGN}}"
                  size: 10
      responses:
        "200":
          description: Beneficiary list result
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: Response code returned by Onerway.
                  respMsg:
                    type:
                      - string
                      - "null"
                    description: Response message returned by Onerway.
                    x-onerway-value:
                      nullable: true
                      when:
                        en: No response message is returned.
                        zh: 未返回响应信息时为 `null`。
                  data:
                    type: object
                    properties:
                      records:
                        type: array
                        description: Beneficiary records.
                        items:
                          type: object
                          properties:
                            beneficiaryId:
                              type: string
                              description: Beneficiary ID.
                            merchantRefId:
                              type: string
                              description: Merchant-side beneficiary reference ID.
                            createTime:
                              type: string
                              description: Beneficiary creation time.
                            updateTime:
                              type: string
                              description: Beneficiary last update time.
                            merchantNo:
                              type: string
                              description: Merchant number that owns this beneficiary record.
                            nationality:
                              type: string
                              description: Beneficiary nationality.
                            status:
                              type: string
                              description: Beneficiary record status.
                            remark:
                              type: string
                              description: Beneficiary remark returned by the system.
                            payoutCurrency:
                              type: string
                              description: Configured payout currency.
                            expireDate:
                              type: string
                              description: Beneficiary expiration time when available.
                            bankName:
                              type: string
                              description: Beneficiary bank name.
                            accountName:
                              type: string
                              description: Beneficiary account name.
                            bankAddress:
                              type: string
                              description: Beneficiary bank address.
                            payeeStatus:
                              type: string
                              description: Beneficiary review status.
                            accountBelong:
                              type: string
                              description: Account ownership flag. `0` for own account and `1` for
                                another-person account.
                            bankCountry:
                              type: string
                              description: Receiving bank country.
                            entityType:
                              type: string
                              description: Beneficiary entity type. `0` for business and `1` for individual.
                            payeeAddress:
                              type: string
                              description: Beneficiary address summary.
                            paymentMethod:
                              type: string
                              description: Configured payout method.
                            payeeCountry:
                              type: string
                              description: Beneficiary country.
                            receiverInfo:
                              type: string
                              description: Beneficiary identity information returned as a JSON string.
                            address:
                              type: string
                              description: Beneficiary address information returned as a JSON string.
                            accountInfomation:
                              type: string
                              description: Beneficiary account information returned as a JSON string.
                      total:
                        type: integer
                        description: Total record count.
                      size:
                        type: integer
                        description: Page size.
                      current:
                        type: integer
                        description: Current page number.
                    description: Paged beneficiary list result.
              examples:
                beneficiary-list-result:
                  summary: Beneficiary list result
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      records:
                        - beneficiaryId: "12345"
                          merchantRefId: beneficiary_demo_001
                          createTime: 2024-01-15 10:30:00
                          updateTime: 2024-01-20 14:45:00
                          merchantNo: "800181"
                          nationality: US
                          status: ACTIVE
                          remark: Primary beneficiary account
                          payoutCurrency: USD
                          expireDate: 2024-12-31 23:59:59
                          bankName: Demo Bank
                          accountName: John Smith
                          bankAddress: 123 Main Street, New York, NY 10001
                          payeeStatus: PASS
                          accountBelong: "0"
                          bankCountry: US
                          entityType: "1"
                          payeeAddress: 456 Oak Avenue, Los Angeles, CA 90210
                          paymentMethod: BANK_TRANSFER
                          payeeCountry: US
                          receiverInfo: '{"firstName":"John","lastName":"Smith","email":"john.smith@example.com"}'
                          address: '{"addressLine1":"456 Oak Avenue","city":"Los
                            Angeles","state":"CA","postalCode":"90210"}'
                          accountInfomation: '{"cardNumber":"1234567890123456","accountType":"CHECKING","bankName":"Demo
                            Bank"}'
                      total: 1
                      size: 10
                      current: 1
```