> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecleff.com/llms.txt > Use this file to discover all available pages before exploring further. # Import a Beneficiary base > Creates up to 500 Beneficiaries in one call, each with their bank account and compliance acknowledgment. Rows succeed or fail independently; `results` carries the outcome of each. ## OpenAPI ````yaml POST /v1/beneficiaries/import openapi: 3.0.0 info: title: Cleff API description: >- Payout orchestration platform. All endpoints under /v1/ require an API key in the Authorization header (Bearer ck___). version: 0.0.1 contact: {} servers: [] security: [] tags: [] paths: /v1/beneficiaries/import: post: tags: - Beneficiaries summary: Import verified Beneficiaries with their bank accounts description: >- Creates up to 500 Beneficiaries in one call, each with their bank account and compliance acknowledgment. Rows succeed or fail independently; `results` carries the outcome of each. operationId: BeneficiariesController_import parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImportBeneficiariesDto' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ImportBeneficiariesResponseDto' '401': description: Missing or invalid credentials security: - api_key: [] components: schemas: ImportBeneficiariesDto: type: object properties: rows: description: Rows to import (1..500). Each row is validated on its own. type: array items: $ref: '#/components/schemas/ImportBeneficiaryRowDto' required: - rows ImportBeneficiariesResponseDto: type: object properties: results: description: One result per request row, in input order. type: array items: $ref: '#/components/schemas/ImportBeneficiaryRowResultDto' created_count: type: number description: How many rows landed. Equals the number of `created` results. failed_count: type: number description: How many rows were rejected. Equals the number of `failed` results. required: - results - created_count - failed_count ImportBeneficiaryRowDto: type: object properties: beneficiary_type: type: string enum: - person - business email: type: string format: email phone: type: string description: >- Optional contact phone. Used for the recipient-enrollment provider KYC step; never an identity field. nickname: type: string description: >- Cleff-only display label, preferred over the legal name. Never sent to a provider. first_name: type: string description: 'Person: given name' last_name: type: string description: 'Person: family name' country_of_residence: type: string description: 'Person: ISO 3166-1 alpha-2 country of residence' date_of_birth: type: string description: 'Person: date of birth (YYYY-MM-DD)' business_name: type: string description: 'Business: legal business name' country_of_incorporation: type: string description: 'Business: ISO 3166-1 alpha-2 country of incorporation' registration_number: type: string description: >- Business: Cleff-owned KYB record only. Never transmitted to Routefusion. tax_id: type: string description: Tax identifier (Routefusion tax_number) postal_address: description: Optional mailing/legal address allOf: - $ref: '#/components/schemas/PostalAddressDto' acknowledged: type: boolean description: >- Must be true: your attestation that you have verified this recipient's identity. The row is created already compliant. bank: description: >- Required. The bank account to register for this recipient, in the same shape as POST /v1/beneficiaries/{id}/bank-accounts. If you do not hold bank details, use POST /v1/beneficiaries/bulk-invites instead. allOf: - $ref: '#/components/schemas/RegisterBankAccountDto' required: - beneficiary_type - email - acknowledged - bank ImportBeneficiaryRowResultDto: type: object properties: index: type: number description: Zero-based position of the row in the request. status: type: string enum: - created - failed beneficiary_id: type: string description: Present on created rows. bank_account_id: type: string description: Present on created rows. payout_usable: type: boolean description: >- Present on created rows: whether a Payout to this bank account would be accepted. False when the routing details could not be validated for the corridor: the Beneficiary is created and compliant, but Payouts to this account are refused. error: description: Present on failed rows. allOf: - $ref: '#/components/schemas/ImportRowErrorDto' required: - index - status PostalAddressDto: type: object properties: line1: type: string description: Street address line 1 (required when an address is present) line2: type: string description: Street address line 2 (suite, unit, etc.) city: type: string description: City / locality (required when an address is present) state: type: string description: State / province / region postal_code: type: string description: Postal / ZIP code country: type: string description: >- ISO 3166-1 alpha-2 mailing country (required when an address is present) RegisterBankAccountDto: type: object properties: account_holder_name: type: string country: type: string description: ISO 3166-1 alpha-2 of the bank country currency: type: string description: ISO 4217 currency code account_number: type: string description: Domestic account number (US/JP/etc.) routing_code: type: string description: US ABA, UK sort code, BR branch_code, etc. iban: type: string description: IBAN — required for European corridors swift_bic: type: string description: SWIFT/BIC — required for cross-border SWIFT routing clabe: type: string description: CLABE — Mexican domestic routing (18 digits) pix_key: type: string description: Pix key — Brazilian instant-payment identifier bank_name: type: string account_type: type: string enum: - checking - savings description: >- ACH account type (US). Defaults to checking at enrollment when unset. required: - account_holder_name - country - currency ImportRowErrorDto: type: object properties: code: type: string description: Error code, from the same set the error envelope uses. message: type: string field: type: string description: The offending field, when the failure names one. required: - code - message securitySchemes: api_key: scheme: bearer bearerFormat: ck___ type: http description: >- Cleff API key issued to a Business that self-registers via POST /v1/registration ````