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

# Bulk-invite Beneficiaries

> The invite-first flow, pluralized (1..500 rows): each row becomes an identity-only stub (identity_pending) and every persisted stub receives a full_onboarding collection link. Row failures (duplicate email, wrong-type identity field) are reported per row in `failed` and never abort the rest of the file.



## OpenAPI

````yaml POST /v1/beneficiaries/bulk-invites
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_<env>_<id>_<secret>).
  version: 0.0.1
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/beneficiaries/bulk-invites:
    post:
      tags:
        - Beneficiaries
      summary: Bulk-invite Beneficiaries from CSV rows
      description: >-
        The invite-first flow, pluralized (1..500 rows): each row becomes an
        identity-only stub (identity_pending) and every persisted stub receives
        a full_onboarding collection link. Row failures (duplicate email,
        wrong-type identity field) are reported per row in `failed` and never
        abort the rest of the file.
      operationId: BeneficiariesController_bulkInvite
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBulkInvitesDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkInviteResponseDto'
        '401':
          description: Missing or invalid credentials
      security:
        - api_key: []
components:
  schemas:
    CreateBulkInvitesDto:
      type: object
      properties:
        rows:
          description: CSV rows to invite (1..500).
          type: array
          items:
            $ref: '#/components/schemas/BulkInviteRowDto'
        message:
          type: string
          description: >-
            Optional free-text note from the sender, included in every invite
            email of the batch.
          maxLength: 1000
      required:
        - rows
    BulkInviteResponseDto:
      type: object
      properties:
        invited:
          type: array
          items:
            $ref: '#/components/schemas/BulkInvitedRowDto'
        failed:
          type: array
          items:
            $ref: '#/components/schemas/BulkInviteFailedRowDto'
      required:
        - invited
        - failed
    BulkInviteRowDto:
      type: object
      properties:
        beneficiary_type:
          type: string
          enum:
            - person
            - business
        email:
          type: string
          format: email
        first_name:
          type: string
          description: 'Person: given name'
        last_name:
          type: string
          description: 'Person: family name'
        business_name:
          type: string
          description: 'Business: legal business name'
        nickname:
          type: string
          description: Cleff-only display label. Never sent to a provider.
      required:
        - beneficiary_type
        - email
    BulkInvitedRowDto:
      type: object
      properties:
        index:
          type: number
          description: Zero-based position of the row in the request.
        id:
          type: string
        email:
          type: string
          format: email
      required:
        - index
        - id
        - email
    BulkInviteFailedRowDto:
      type: object
      properties:
        index:
          type: number
          description: Zero-based position of the row in the request.
        email:
          type: string
          format: email
        error:
          type: string
          description: Why the row was rejected.
      required:
        - index
        - email
        - error
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: ck_<env>_<id>_<secret>
      type: http
      description: >-
        Cleff API key issued to a Business that self-registers via POST
        /v1/registration

````