> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvera.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a beneficiary

> Create a new beneficiary for the given customer.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/customers/{customerId}/beneficiaries
openapi: 3.1.0
info:
  title: Nuvera API
  description: Nuvera Payment Platform REST API
  version: '1.0'
  contact: {}
servers:
  - url: http://localhost:45000
security: []
tags: []
paths:
  /api/v1/customers/{customerId}/beneficiaries:
    post:
      tags:
        - Beneficiaries
      summary: Create a beneficiary
      description: Create a new beneficiary for the given customer.
      operationId: BeneficiaryController_create
      parameters:
        - name: customerId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBeneficiaryDto'
      responses:
        default:
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficiaryOutputDto_Output'
      security:
        - x-api-key: []
          signed-request: []
components:
  schemas:
    CreateBeneficiaryDto:
      type: object
      properties:
        customerId:
          type: string
          description: ID of the customer this beneficiary belongs to
        country:
          type: string
          minLength: 1
          description: Beneficiary country
        companyName:
          type: string
          minLength: 1
          maxLength: 200
          description: Beneficiary company name
        address:
          type: string
          minLength: 1
          description: Company address
        zipCode:
          type: string
          minLength: 1
          description: ZIP/Postal code
        currencyCode:
          type: string
          const: USD
          description: Currency code
        iban:
          description: IBAN (if applicable)
          type: string
        accountNumber:
          description: Bank account number
          type: string
        bankBic:
          description: Bank SWIFT/BIC code
          type: string
        wireRoutingNumber:
          description: Wire routing number (if applicable)
          type: string
        achRoutingNumber:
          description: ACH routing number (if applicable)
          type: string
        intermediaryBank:
          description: Intermediary bank (if applicable)
          type: string
      required:
        - customerId
        - country
        - companyName
        - address
        - zipCode
        - currencyCode
        - bankBic
    BeneficiaryOutputDto_Output:
      type: object
      properties:
        id:
          type: string
        customerId:
          type: string
        country:
          type: string
        companyName:
          type: string
        address:
          type: string
        zipCode:
          type: string
        currencyCode:
          type: string
        bankName:
          type: string
        bankBic:
          type: string
        bankCountryCode:
          type: string
        bankAddress:
          type: string
        accountNumber:
          anyOf:
            - type: string
            - type: 'null'
        iban:
          anyOf:
            - type: string
            - type: 'null'
        wireRoutingNumber:
          anyOf:
            - type: string
            - type: 'null'
        achRoutingNumber:
          anyOf:
            - type: string
            - type: 'null'
        intermediaryBank:
          anyOf:
            - type: string
            - type: 'null'
        status:
          type: string
        createdAt:
          type: string
        updatedAt:
          type: string
        screening:
          anyOf:
            - type: object
              properties:
                screeningSubjectId:
                  type: string
                status:
                  type: string
                  enum:
                    - NOT_SCREENED
                    - PENDING
                    - CLEAR
                    - UNDER_REVIEW
                    - CLEARED
                    - CONFIRMED_HIT
                paymentHold:
                  type: boolean
                openMatchCount:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                highestSeverity:
                  anyOf:
                    - type: string
                      enum:
                        - BLOCKING
                        - ADVISORY
                    - type: 'null'
                lastScreenedAt:
                  anyOf:
                    - type: string
                    - type: 'null'
              required:
                - screeningSubjectId
                - status
                - paymentHold
                - openMatchCount
                - highestSeverity
                - lastScreenedAt
              additionalProperties: false
            - type: 'null'
      required:
        - id
        - customerId
        - country
        - companyName
        - address
        - zipCode
        - currencyCode
        - bankName
        - bankBic
        - bankCountryCode
        - bankAddress
        - accountNumber
        - iban
        - wireRoutingNumber
        - achRoutingNumber
        - intermediaryBank
        - status
        - createdAt
        - updatedAt
      additionalProperties: false
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Nuvera API application secret key
    signed-request:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: RS256 per-request signed JWT

````