> ## Documentation Index > Fetch the complete documentation index at: https://docs.payana.la/llms.txt > Use this file to discover all available pages before exploring further. # List Beneficiaries > Lista beneficiarios paginados y permite filtrar por nombre. ## OpenAPI ````yaml GET /beneficiaries openapi: 3.1.0 info: title: Payana Accounts Payable API description: >- API pública para gestionar cuentas por pagar (payments) y beneficiarios (beneficiaries) en Payana, incluyendo notificaciones por webhooks cuando se procesan pagos. version: 1.0.0 servers: - url: https://api.prod.payana.cloud/public/api/v1 description: Production - url: https://api.develop.payana.cloud/public/api/v1 description: Develop security: - apiKeyAuth: [] tags: - name: Payments description: Crear y listar pagos - name: Beneficiaries description: Crear, listar y consultar beneficiarios - name: Webhooks description: Eventos de webhooks enviados por Payana - name: Banks description: Listar y consultar bancos - name: Transactions In description: Transacciones entrantes (polling, mismo formato que webhooks) - name: Documents description: Listar, consultar y operar documentos (cuentas por pagar) - name: DIAN Events description: >- Encolar eventos DIAN (030 Acuse de recibo, 031 Reclamo, 032 Recibo del bien, 033 Aceptación expresa, 034 Aceptación tácita) para documentos identificados por CUFE. El procesamiento es asíncrono. - name: Fiscal Sync description: >- Disparar y consultar sincronización de documentos fiscales desde el SAT (México) o la DIAN (Colombia). - name: Workflow Steps description: >- Resolver el paso en que está parado un documento dentro de su flujo: aprobación, clasificación o etiquetado. paths: /beneficiaries: get: tags: - Beneficiaries summary: List beneficiaries description: Lista beneficiarios paginados y permite filtrar por nombre. parameters: - name: search in: query description: Texto para buscar por nombre. schema: type: string - name: page in: query description: Página (1-indexed). schema: type: integer minimum: 1 default: 1 - name: per_page in: query description: Cantidad de ítems por página. schema: type: integer minimum: 1 maximum: 100 default: 25 responses: '200': description: Beneficiaries list response content: application/json: schema: $ref: '#/components/schemas/BeneficiaryListResponse' example: items: - reference: be07b610-c6f6-465c-8c43-c6469d3a585f name: Acme Inc. type: supplier email: contacto@gmail.com phone_number: null identifier_type: NIT identifier_number: '112233449' payment_terms: null fiscal_address: null contact_information: - type: email value: contacto@gmail.com - type: phone value: '+5725706683' bank_accounts: - reference: 35034bf9-babf-45c1-b9d1-c7267e2e02f0 bank_reference: 8b1895e2-5b13-4fa1-9633-382639b6d0e3 bank_name: Banco de Bogotá account_number: '999999999' created_at: '2025-06-01T18:00:35.194+00:00' updated_at: '2025-06-01T18:00:35.194+00:00' total: 1 current_page: 1 page_size: 25 total_pages: 1 '400': description: Bad request / validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: BeneficiaryListResponse: type: object required: - items - total - current_page - page_size - total_pages properties: items: type: array items: $ref: '#/components/schemas/Beneficiary' total: type: integer current_page: type: integer page_size: type: integer total_pages: type: integer ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/ErrorObject' example: success: false error: code: VALIDATION_ERROR message: The request contains invalid data details: amount: - Amount must be greater than 0 beneficiary_id: - Beneficiary does not exist Beneficiary: type: object required: - reference - name - identifier_number properties: reference: type: string name: type: string type: $ref: '#/components/schemas/BeneficiaryType' email: type: - string - 'null' phone_number: type: - string - 'null' identifier_type: anyOf: - $ref: '#/components/schemas/IdentifierType' - type: 'null' identifier_number: type: string payment_terms: type: - integer - 'null' fiscal_address: anyOf: - type: object properties: city_code: type: - string - 'null' city_name: type: - string - 'null' state_code: type: - string - 'null' state_name: type: - string - 'null' - type: 'null' contact_information: type: array items: $ref: '#/components/schemas/ContactInformation' bank_accounts: type: array items: $ref: '#/components/schemas/BankAccount' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time ErrorObject: type: object required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string details: anyOf: - $ref: '#/components/schemas/ErrorDetails' - type: 'null' BeneficiaryType: type: string enum: - supplier IdentifierType: type: string description: Tipo de identificación (ej. NIT, CC, RFC). ContactInformation: type: object required: - type - value properties: reference: type: string description: Referencia del contacto (cuando aplica). type: type: string description: Tipo de contacto (ej. email, phone). value: type: string BankAccount: type: object required: - reference - bank_reference - bank_name - account_number properties: reference: type: string bank_reference: type: string description: Referencia del banco (UUID). bank_name: type: - string - 'null' account_number: type: string account_type: type: string enum: - savings - checking validation_status: type: string enum: - pending - processing - validated - rejected - validation_error account_recipient_name: type: - string - 'null' account_recipient_document_number: type: - string - 'null' account_recipient_document_type: anyOf: - $ref: '#/components/schemas/IdentifierType' - type: 'null' created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time ErrorCode: type: string enum: - VALIDATION_ERROR - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - RATE_LIMITED - INTERNAL_ERROR ErrorDetails: type: object additionalProperties: type: array items: type: string securitySchemes: apiKeyAuth: type: apiKey in: header name: api-key description: API key provista por Payana. ````