> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

# List Recipients

Retrieves a list of recipients for the authenticated account. Supports pagination and filtering.


## OpenAPI

````yaml openapi/recipients-for-marketplace/list-recipients.json GET /recipients
openapi: 3.1.0
info:
  title: Recipients API
  version: 1.0.0
  description: >-
    API for managing recipients in split payment scenarios. This feature enables
    merchants to split payments among multiple recipients, which is particularly
    beneficial for marketplace models where transactions need to be divided
    among different sellers or stakeholders.
servers:
  - url: https://api-sandbox.y.uno/v1
security:
  - sec0: []
    sec1: []
paths:
  /recipients:
    get:
      summary: List Recipients
      operationId: list-recipients
      parameters:
        - name: limit
          in: query
          description: Maximum number of recipients to return
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Number of recipients to skip for pagination
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: national_entity
          in: query
          description: Filter recipients by national entity type
          required: false
          schema:
            type: string
            enum:
              - INDIVIDUAL
              - ENTITY
        - name: country
          in: query
          description: Filter recipients by country
          required: false
          schema:
            type: string
      responses:
        '200':
          description: List of recipients retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecipientResponse'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Total number of recipients
                      limit:
                        type: integer
                        description: Number of recipients per page
                      offset:
                        type: integer
                        description: Current offset
                      has_more:
                        type: boolean
                        description: Whether there are more recipients to fetch
              examples:
                Success Response:
                  value:
                    data:
                      - id: 9104911d-5df9-429e-8488-ad41abea1a4b
                        account_id: 9104911d-5df9-429e-8488-ad41abea1a4b
                        merchant_recipient_id: AAAA01
                        national_entity: INDIVIDUAL
                        first_name: John
                        last_name: Doe
                        email: john.doe@email.com
                        country: CO
                        created_at: '2024-01-15T10:30:00Z'
                        updated_at: '2024-01-15T10:30:00Z'
                    pagination:
                      total: 1
                      limit: 20
                      offset: 0
                      has_more: false
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    code: INVALID_CREDENTIALS
                    messages:
                      - Invalid credentials
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden:
                  value:
                    code: AUTHORIZATION_REQUIRED
                    messages:
                      - The merchant has no authorization to use this API.
components:
  schemas:
    RecipientResponse:
      type: object
      properties:
        id:
          type: string
          description: The unique identifier of the recipient.
          example: 3aaa4d82-11e8-48ce-8ef5-04eee3a10802
        account_id:
          type: string
          description: The account identifier associated with this recipient.
          example: fe14c7c6-c75e-43b7-bdbe-4c87ad52c482
        merchant_recipient_id:
          type: string
          description: Unique identifier of the recipient defined by the merchant.
          example: MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6
        national_entity:
          type: string
          description: Beneficiary's national entity type.
          example: INDIVIDUAL
        entity_type:
          type: string
          description: Beneficiary's type of organization.
          example: PRIVATE
        first_name:
          type: string
          description: Beneficiary's name.
          example: Juan
        last_name:
          type: string
          description: Beneficiary's last name.
          example: Perez
        legal_name:
          type:
            - string
            - 'null'
          description: Beneficiary's legal name.
          example: null
        email:
          type: string
          description: The Beneficiary's email.
          example: juan.perez@example.com
        date_of_birth:
          type: string
          description: Beneficiary's date of birth.
          example: '1990-01-15'
        country:
          type: string
          description: The Beneficiary's country.
          example: CO
        website:
          type: string
          description: The seller's website URL.
          example: https://juanperez.com
        industry:
          type: string
          description: The seller's industry.
          example: Technology
        merchant_category_code:
          type: string
          description: The merchant category code (MCC) (MAX 235; MIN 1).
          example: '5734'
        document:
          type: object
          properties:
            document_number:
              type: string
              example: '1234567890'
            document_type:
              type: string
              example: CC
        phone:
          type: object
          properties:
            country_code:
              type: string
              example: '57'
            number:
              type: string
              example: '3001234567'
        address:
          type: object
          properties:
            address_line_1:
              type: string
              example: 'Carrera 7 # 32-16'
            address_line_2:
              type:
                - string
                - 'null'
              example: Oficina 201
            city:
              type: string
              example: Bogota
            country:
              type: string
              example: CO
            state:
              type: string
              example: Cundinamarca
            zip_code:
              type: string
              example: '110311'
            neighborhood:
              type: string
              example: Centro
        legal_representatives:
          type: array
          items:
            type: object
            properties:
              merchant_reference:
                type: string
                example: REP_001
              first_name:
                type: string
                example: Maria
              last_name:
                type: string
                example: Gonzalez
              email:
                type: string
                example: maria.gonzalez@example.com
              date_of_birth:
                type: string
                example: '1985-05-20'
              country:
                type: string
                example: CO
              nationality:
                type: string
                example: CO
              title:
                type: string
                example: CEO
              publicly_exposed_person:
                type: boolean
                example: false
              ultimate_beneficial_owner:
                type: boolean
                example: true
              document:
                type: object
                properties:
                  document_type:
                    type: string
                    example: CC
                  document_number:
                    type: string
                    example: '0987654321'
              phone:
                type: object
                properties:
                  country_code:
                    type: string
                    example: '57'
                  number:
                    type: string
                    example: '3109876543'
              address:
                type: object
                properties:
                  address_line_1:
                    type: string
                    example: 'Calle 26 # 13-19'
                  address_line_2:
                    type:
                      - string
                      - 'null'
                    example: null
                  country:
                    type: string
                    example: CO
                  state:
                    type: string
                    example: Cundinamarca
                  city:
                    type: string
                    example: Bogota
                  zip_code:
                    type: string
                    example: '110311'
        withdrawal_methods:
          type: object
          properties:
            bank:
              type: object
              properties:
                code:
                  type: string
                  example: '001'
                branch:
                  type: string
                  example: '004'
                branch_digit:
                  type:
                    - string
                    - 'null'
                  example: '123'
                account:
                  type: string
                  example: '1234567890'
                account_digit:
                  type:
                    - string
                    - 'null'
                  example: '123'
                account_type:
                  type: string
                  example: SAVINGS
                routing:
                  type: string
                  example: '021000021'
                country:
                  type: string
                  example: CO
                currency:
                  type: string
                  example: COP
        documentation:
          type: array
          items:
            type: object
            properties:
              file_name:
                type: string
                example: cc-front.pdf
              content_type:
                type: string
                example: application/pdf
              content_category:
                type: string
                example: IDENTIFICATION
              content:
                type: string
                example: JVBERi0xLjQKJ...
        onboardings:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                example: 84c42684-dbe5-4e0f-bd17-4d094e19762d
              type:
                type: string
                example: ONBOARD_ONTO_THE_PROVIDER
              workflow:
                type: string
                example: DIRECT
              status:
                type: string
                example: PENDING
              callback_url:
                type: string
                example: https://merchant.example.com/webhook/onboarding
              provider:
                type: object
                properties:
                  id:
                    type: string
                    example: ALELO
                  connection_id:
                    type: string
                    example: cc389b51-53a1-4a29-af40-c8cee26c3399
                  recipient_id:
                    type:
                      - string
                      - 'null'
                    example: null
                  redirect_url:
                    type:
                      - string
                      - 'null'
                    example: null
                  onboarding_url:
                    type:
                      - string
                      - 'null'
                    example: null
                  legal_entity:
                    type:
                      - string
                      - 'null'
                    example: null
                  balance_account_id:
                    type:
                      - string
                      - 'null'
                    example: null
                  legal_entity_id:
                    type:
                      - string
                      - 'null'
                    example: null
              documentation:
                type: array
                items:
                  type: object
                  properties:
                    file_name:
                      type: string
                      example: utility-bill.pdf
                    content_type:
                      type: string
                      example: application/pdf
                    content_category:
                      type: string
                      example: ADDRESS_PROOF
                    content:
                      type: string
                      example: JVBERi0xLjQKJ...
              legal_representatives:
                type: array
                items:
                  type: object
                example: []
              requirements:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                      example: document.cc
                    message:
                      type: string
                      example: Provide CC document image
                    status:
                      type: string
                      example: PENDING
              withdrawal_methods:
                type: object
                properties:
                  bank:
                    type: object
                    properties:
                      code:
                        type: string
                        example: '002'
                      branch:
                        type: string
                        example: '002'
                      branch_digit:
                        type:
                          - string
                          - 'null'
                        example: null
                      account:
                        type: string
                        example: '9876543210'
                      account_digit:
                        type:
                          - string
                          - 'null'
                        example: null
                      account_type:
                        type: string
                        example: SAVINGS
                      routing:
                        type: string
                        example: '021000022'
                      country:
                        type: string
                        example: CO
                      currency:
                        type: string
                        example: COP
              terms_of_service:
                type: object
                properties:
                  acceptance:
                    type: boolean
                    example: true
                  date:
                    type: string
                    example: '2025-07-21T20:43:54Z'
                  ip:
                    type: string
                    example: 129.21.111.11
              created_at:
                type: string
                format: date-time
                example: '2025-08-27T15:41:19.516982Z'
              updated_at:
                type: string
                format: date-time
                example: '2025-08-27T15:41:19.516989Z'
        created_at:
          type: string
          format: date-time
          description: Recipient creation date (ISO 8601 MAX 27; MIN 27).
          example: '2025-08-27T15:41:19.497413Z'
        updated_at:
          type: string
          format: date-time
          description: Last Recipient updated date (ISO 8601 MAX 27; MIN 27).
          example: '2025-08-27T15:41:19.497425Z'
    ErrorResponse:
      type: object
      properties:
        code:
          type: string
          example: INVALID_REQUEST
        messages:
          type: array
          items:
            type: string
            example: Invalid request
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````