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

# Enroll a Beneficiary with the provider

> Registers the Beneficiary as a Checkbook marketplace sub-user (create → KYC → verify → register default bank) so payouts reach them with zero rail-originated emails. The default bank is decrypted and registered at enrollment time. Idempotent per (beneficiary, environment, provider) — re-enrolling returns the existing record, never a second sub-user. Provider credentials are encrypted at rest and never returned. The environment is the caller's session environment.



## OpenAPI

````yaml POST /v1/beneficiaries/{id}/enroll
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/{id}/enroll:
    post:
      tags:
        - Beneficiaries
      summary: Enroll a Beneficiary as a recipient sub-user
      description: >-
        Registers the Beneficiary as a Checkbook marketplace sub-user (create →
        KYC → verify → register default bank) so payouts reach them with zero
        rail-originated emails. The default bank is decrypted and registered at
        enrollment time. Idempotent per (beneficiary, environment, provider) —
        re-enrolling returns the existing record, never a second sub-user.
        Provider credentials are encrypted at rest and never returned. The
        environment is the caller's session environment.
      operationId: BeneficiaryEnrollmentsController_enroll
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollBeneficiaryDto'
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryEnrollmentResponseDto'
        '401':
          description: Missing or invalid credentials
        '404':
          description: Beneficiary or bank account not found
      security:
        - api_key: []
components:
  schemas:
    EnrollBeneficiaryDto:
      type: object
      properties:
        bank_account_id:
          type: string
          description: >-
            Which of the Beneficiary's bank accounts to register with the
            provider. Omit to auto-resolve the single payout-usable account;
            required when the Beneficiary has more than one.
    BeneficiaryEnrollmentResponseDto:
      type: object
      properties:
        id:
          type: string
        beneficiary_id:
          type: string
        environment:
          type: string
          enum:
            - sandbox
            - production
        provider:
          type: string
          description: Logical enrollment provider
          example: checkbook
        provider_ref:
          type: object
          nullable: true
          description: >-
            Provider's canonical handle (Checkbook user id). Read from the
            provider-account registry that owns it, so null for a rail that
            registers no handle.
        provider_user_id:
          type: object
          description: >-
            The provider recipient handle dispatch addresses (Checkbook minted
            user_id)
          nullable: true
        status:
          type: string
          enum:
            - pending
            - verified
            - rejected
            - suspended
            - closed
        provider_state:
          type: string
          description: Verbatim provider lifecycle token
        created_at:
          type: string
          format: date-time
        status_changed_at:
          type: string
          format: date-time
        verified_at:
          type: object
          format: date-time
          nullable: true
      required:
        - id
        - beneficiary_id
        - environment
        - provider
        - provider_ref
        - provider_user_id
        - status
        - provider_state
        - created_at
        - status_changed_at
        - verified_at
  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

````