> ## 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.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Listar destinatarios

> Obtén una lista paginada de destinatarios de una cuenta autorizada.

Proporciona `account_id` como parámetro de consulta, o `X-Account-Code` como encabezado. Si ambos están presentes, el parámetro de consulta tiene prioridad. Los resultados se limitan a esa cuenta autorizada y a tu organización, ordenados por fecha de creación, del más reciente al más antiguo.

Usa `merchant_recipient_id` para una coincidencia exacta, opcionalmente combinado con `country` y `national_entity`. Cada respuesta exitosa contiene `data` como un arreglo y `pagination` como un objeto, incluso cuando solo coincide un destinatario. Si no hay coincidencias, devuelve HTTP `200` con `data: []` y `pagination.total: 0`.

`limit` tiene un valor predeterminado de `20` y acepta de `1` a `100`. `offset` tiene un valor predeterminado de `0` y acepta cualquier entero no negativo. Los valores de filtro vacíos o repetidos no son válidos.

Cada elemento contiene los campos base del destinatario. Las colecciones relacionadas como `withdrawal_methods`, `documentation`, `legal_representatives` y `onboardings` no se enriquecen. Usa [Get Recipient](https://docs.y.uno/es/reference/recipients-for-marketplace/get-recipient.md) para obtener el destinatario completo.

> [!WARNING]
>
> Los resultados del listado, incluidos los filtros por ID de comercio, tienen consistencia eventual. Un destinatario que acabas de crear, actualizar o eliminar puede tardar en reflejarse en la lista. Usa [Get Recipient](https://docs.y.uno/es/reference/recipients-for-marketplace/get-recipient.md) con su ID de Yuno para una lectura inmediata desde el almacén principal. Los fallos de acceso a datos del listado devuelven `503`; no se representan como resultados vacíos.

> [!NOTE]
>
> Este listado está disponible en `GET /v1/recipients/list`. La búsqueda existente [Get Recipient by Merchant ID](https://docs.y.uno/es/reference/recipients-for-marketplace/get-recipient-by-merchant-id.md) (`GET /v1/recipients?merchant_recipient_id=...`) permanece sin cambios: devuelve un objeto de destinatario de nivel superior y `400 RECIPIENT_NOT_FOUND` cuando ningún destinatario coincide. Quienes ya usan la búsqueda no necesitan migrar. Los contratos de GET por ID de Yuno y de PATCH/DELETE no cambian.


## OpenAPI

````yaml openapi/es/recipients-for-marketplace/list-recipients.json GET /recipients/list
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
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /recipients/list:
    get:
      summary: Listar destinatarios
      description: >-
        Devuelve una lista paginada limitada a la cuenta y la organización
        autorizadas. merchant_recipient_id es un filtro de coincidencia exacta;
        la respuesta sigue siendo un envoltorio incluso con cero o una
        coincidencia. Las lecturas son eventualmente consistentes.
      operationId: list-recipients
      parameters:
        - name: limit
          in: query
          description: Número máximo de destinatarios que se devolverán
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
        - name: offset
          in: query
          description: Número de destinatarios que se omitirán para la paginación
          required: false
          schema:
            type: integer
            default: 0
            minimum: 0
        - name: national_entity
          in: query
          description: Filtrar destinatarios por tipo de entidad nacional
          required: false
          schema:
            type: string
            enum:
              - INDIVIDUAL
              - ENTITY
        - name: country
          in: query
          description: Filtrar destinatarios por país
          required: false
          schema:
            type: string
        - name: merchant_recipient_id
          in: query
          description: >-
            Filtro exacto por ID de destinatario del comercio. Devuelve el mismo
            arreglo de datos y envoltorio de paginación; si no hay
            coincidencias, devuelve un arreglo vacío con total 0.
          required: false
          schema:
            type: string
            minLength: 1
        - name: account_id
          in: query
          description: >-
            UUID de la cuenta autorizada. Obligatorio, a menos que se envíe
            X-Account-Code en el encabezado de la solicitud.
          required: false
          schema:
            type: string
            format: uuid
        - name: X-Account-Code
          in: header
          description: >-
            UUID de la cuenta autorizada cuando se omite account_id. Si ambos
            están presentes, account_id tiene prioridad.
          required: false
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Lista de destinatarios obtenida correctamente
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/RecipientResponse'
                  pagination:
                    type: object
                    properties:
                      total:
                        type: integer
                        description: Número total de destinatarios
                      limit:
                        type: integer
                        description: Número de destinatarios por página
                      offset:
                        type: integer
                        description: Desplazamiento actual
                      has_more:
                        type: boolean
                        description: Si hay más destinatarios por obtener
              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
        '400':
          description: Parámetros de consulta no válidos
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: No autorizado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    code: INVALID_CREDENTIALS
                    messages:
                      - Invalid credentials
        '403':
          description: Prohibido
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Forbidden:
                  value:
                    code: AUTHORIZATION_REQUIRED
                    messages:
                      - The merchant has no authorization to use this API.
        '503':
          description: El listado de destinatarios no está disponible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RecipientResponse:
      type: object
      properties:
        id:
          type: string
          description: El identificador único del destinatario.
          example: 3aaa4d82-11e8-48ce-8ef5-04eee3a10802
        account_id:
          type: string
          description: El identificador de cuenta asociado a este destinatario.
          example: fe14c7c6-c75e-43b7-bdbe-4c87ad52c482
        merchant_recipient_id:
          type: string
          description: Identificador único del destinatario definido por el comercio.
          example: MERCHANT_182acf1d-faeb-4ff0-94cd-7fab11b282f6
        national_entity:
          type: string
          description: Tipo de entidad nacional del beneficiario.
          example: INDIVIDUAL
        entity_type:
          type: string
          description: Tipo de organización del beneficiario.
          example: PRIVATE
        first_name:
          type: string
          description: Nombre del beneficiario.
          example: Juan
        last_name:
          type: string
          description: Apellido del beneficiario.
          example: Perez
        legal_name:
          type:
            - string
            - 'null'
          description: Razón social del beneficiario.
          example: null
        email:
          type: string
          description: El correo electrónico del beneficiario.
          example: juan.perez@example.com
        date_of_birth:
          type: string
          description: Fecha de nacimiento del beneficiario.
          example: '1990-01-15'
        country:
          type: string
          description: El país del beneficiario.
          example: CO
        website:
          type: string
          description: La URL del sitio web del vendedor.
          example: https://juanperez.com
        industry:
          type: string
          description: El sector del vendedor.
          example: Technology
        merchant_category_code:
          type: string
          description: El código de categoría del comercio (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: Fecha de creación del destinatario (ISO 8601 MAX 27; MIN 27).
          example: '2025-08-27T15:41:19.497413Z'
        updated_at:
          type: string
          format: date-time
          description: >-
            Fecha de la última actualización del destinatario (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>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.