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

# Add beneficiary (account)

> Create a beneficiary to be referenced when preparing and executing transfers.

## Endpoint

`POST /api/v2.1/fintrans/{accountId}/beneficiaries`

<Note>
  This endpoint requires `X-Forwarded-From` and a device header. The backend accepts any of:
  `deviceId`, `X-Device-Id`, `device-id`.
</Note>

## Sample cURL

```bash theme={null}
curl --request POST \
  --url 'https://sandbox.finhub.cloud/api/v2.1/fintrans/{accountId}/beneficiaries' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'X-Tenant-Id: <TENANT_ID>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'User-Agent: <USER_AGENT>' \
  --header 'X-Forwarded-From: <FORWARDED_FROM>' \
  --header 'platform: Web' \
  --header 'deviceId: <DEVICE_ID>' \
  --data '{
    "purposeCode": "SUPP",
    "postalCode": "LT-01103",
    "shortName": "",
    "bicSwiftCode": "SONCLT21",
    "lastName": "Customer",
    "city": "Vilnius",
    "email": "customer.20260331114946-387074@testcorp.com",
    "bankName": "UAB Sonect Europe",
    "currency": "EUR",
    "country": "LT",
    "networkName": "SEPA",
    "firstName": "John",
    "bankAddress": "Gedimino pr. 20, Vilnius, Lithuania",
    "customerId": "2dac1793-ab48-420c-b0b5-01292302e188",
    "addressLine1": "1 Test Street",
    "partyType": "INDIVIDUAL_CUSTOMER",
    "iban": "LT213320011000055860",
    "companyName": ""
  }'
```

## Response Example

```json theme={null}
{
  "code": 200,
  "data": {
    "id": "3114774a-aa94-4648-9e57-5ff226ef02dd",
    "name": "",
    "iban": "LT213320011000055860",
    "type": "INDIVIDUAL_CUSTOMER",
    "status": "ACTIVE",
    "currency": "EUR",
    "country": "",
    "email": "",
    "phoneNumber": "",
    "shortName": "",
    "networkName": "SEPA",
    "bankName": "",
    "purposeCode": "",
    "assetId": "eba40e17-e539-430e-a6cc-2b0f01e4c86e"
  },
  "message": "Success"
}
```

<Note>
  Use the returned `assetId` as the `beneficiaryId` when preparing a financial operation.
</Note>

## Missing Headers Error Example

```json theme={null}
{
  "code": 500,
  "data": {
    "deviceId_accepted": [
      "deviceId",
      "X-Device-Id",
      "device-id"
    ],
    "missingHeaders": [
      "X-Forwarded-From",
      "deviceId"
    ]
  },
  "message": "Missing required header(s)"
}
```


## OpenAPI

````yaml openapi.yaml POST /api/v2.1/fintrans/{accountId}/beneficiaries
openapi: 3.1.0
info:
  title: Business BFF API
  version: 1.0.0
  description: Backend for Frontend - Business Panels Orchestration Layer
servers:
  - url: https://sandbox.finhub.cloud
    description: Sandbox Environment
security: []
tags:
  - name: AML
    description: Anti-Money Laundering checks and transaction monitoring
  - name: Admin - Consent Management
    description: Operations for managing consent templates and definitions
  - name: B2B Customer - Organization
    description: B2B organization registration and management
  - name: B2C Customer - Individual
    description: Individual customer registration and lifecycle management
  - name: BFF Admin - Tenant Initialization
    description: Lazy tenant initialization for fast startup
  - name: Catalog Hierarchy
    description: Hierarchical catalog management APIs
  - name: Catalog-Process Mapping
    description: APIs for catalog-process relationship management
  - name: Consent
    description: Payment consent creation and approval
  - name: Draft Management
  - name: External Events
    description: Kafka-to-HTTP bridge event ingestion and query
  - name: FinCard Virtual - Webhooks
    description: FinCard Virtual Card Webhook receiver
  - name: FinCard Virtual Account
    description: FinCard Virtual Card Account API proxy
  - name: FinCard Virtual Card Holder
    description: FinCard Virtual Card Holder API proxy
  - name: FinCard Virtual Cards
    description: FinCard Virtual Card API proxy
  - name: FinCard Virtual Common
    description: FinCard Virtual Card Common API proxy
  - name: FinCard Virtual Wallet
    description: FinCard Virtual Card Wallet API v2 proxy
  - name: FinTrans - Operations
    description: Financial transaction operations
  - name: Internal Webhooks
    description: Internal service-to-service webhook trigger (HMAC-secured)
  - name: MFE Preload
    description: MFE preload endpoints for SSR optimization
  - name: MFE Registry
    description: MFE Registry management endpoints
  - name: Payment Consent Management
    description: Operations for managing payment consents and validation
  - name: Person
    description: Person details for process context
  - name: Products
    description: Product Catalog Management API
  - name: Reference Data
    description: Shared reference data (countries, etc.)
  - name: Tenant Lifecycle
    description: Tenant mode transitions and lifecycle management
  - name: Tenant Registration
    description: Self-registration and tenant onboarding
  - name: Transfers
    description: Transfer prepare/execute aliases for muse-proxy compatibility
  - name: Verification
    description: Customer verification (KYC/KYB/AML) management
  - name: Wallet
    description: Wallet operations and balance management
  - name: Webhooks
    description: Webhook subscription and delivery management
paths:
  /api/v2.1/fintrans/{accountId}/beneficiaries:
    post:
      tags:
        - FinTrans - Operations
      summary: Create beneficiary
      description: >-
        Create a new beneficiary for financial transactions. Returns
        beneficiaryId used by subsequent transfer operations.
      parameters:
        - name: accountId
          schema:
            type: string
            format: uuid
            examples:
              - 00000000-0000-0000-0000-000000000000
          in: path
          required: true
        - name: X-Tenant-ID
          in: header
          required: true
          schema:
            type: string
            example: tenant-demo-001
        - name: X-User-ID
          in: header
          required: false
          schema:
            type: string
        - name: X-Forwarded-For
          in: header
          required: true
          description: Client IP address
          schema:
            type: string
            example: 127.0.0.1
        - name: X-Forwarded-From
          in: header
          required: true
          description: Client source identifier
          schema:
            type: string
            example: client-app
        - name: platform
          in: header
          required: true
          description: Client platform
          schema:
            type: string
            example: mobile
        - name: deviceId
          in: header
          required: true
          description: Device identifier
          schema:
            type: string
            example: device-demo-001
        - name: Authorization
          in: header
          required: true
          description: Bearer JWT
          schema:
            type: string
            example: >-
              Bearer
              eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJkZW1vLXVzZXIifQ.demo-signature
      requestBody:
        description: Beneficiary creation payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateBeneficiaryRequest'
        required: true
      responses:
        '201':
          description: Beneficiary created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponseBeneficiaryResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '500':
          description: Internal server error
components:
  schemas:
    CreateBeneficiaryRequest:
      type: object
      description: Create beneficiary request
      properties:
        partyType:
          type: string
          enum:
            - INDIVIDUAL_CUSTOMER
            - BUSINESS_CUSTOMER
          examples:
            - INDIVIDUAL_CUSTOMER
          description: Party type
          example: INDIVIDUAL_CUSTOMER
        companyName:
          type: string
          examples:
            - Acme Supplier Ltd
          description: Beneficiary company name
          example: Acme Supplier Ltd
        shortName:
          type: string
          examples:
            - Acme Supplier
          description: Short display name
          example: Acme Supplier
        iban:
          type: string
          examples:
            - LT121000011101001000
          description: Beneficiary IBAN
          example: LT121000011101001000
        currency:
          type: string
          examples:
            - EUR
          description: Transaction currency
          example: EUR
        country:
          type: string
          examples:
            - LT
          description: Beneficiary country code
          example: LT
        email:
          type: string
          examples:
            - payments@acme-supplier.test
          description: Beneficiary email
          example: payments@acme-supplier.test
        phoneNumber:
          type: string
          examples:
            - '+37060012345'
          description: Beneficiary phone number
          example: '+37060012345'
        bicSwiftCode:
          type: string
          examples:
            - HABALT22
          description: BIC/SWIFT code
          example: HABALT22
        networkName:
          type: string
          examples:
            - SEPA
          description: Payment network name
          example: SEPA
        bankName:
          type: string
          examples:
            - Sample Bank
          description: Beneficiary bank name
          example: Sample Bank
        purposeCode:
          type: string
          examples:
            - SUPP
          description: Purpose code
          example: SUPP
        accountNumber:
          type: string
          examples:
            - '1000011101001000'
          description: Bank account number
          example: '1000011101001000'
        bankCode:
          type: string
          examples:
            - '73000'
          description: Bank code
          example: '73000'
        addressLine1:
          type: string
          examples:
            - 123 Business Avenue
          description: Address line 1
          example: 123 Business Avenue
        addressLine2:
          type: string
          examples:
            - Suite 7
          description: Address line 2
          example: Suite 7
        city:
          type: string
          examples:
            - Vilnius
          description: City
          example: Vilnius
        stateProvince:
          type: string
          examples:
            - Vilnius County
          description: State or province
          example: Vilnius County
        postalCode:
          type: string
          examples:
            - LT-01001
          description: Postal code
          example: LT-01001
        organizationId:
          type: string
          examples:
            - 123e4567-e89b-12d3-a456-426614174010
          description: Organization identifier
          example: 123e4567-e89b-12d3-a456-426614174010
        customerId:
          type: string
          examples:
            - 123e4567-e89b-12d3-a456-426614174011
          description: Customer identifier
          example: 123e4567-e89b-12d3-a456-426614174011
        firstName:
          type: string
          examples:
            - Jane
          description: Beneficiary first name
          example: Jane
        dateOfBirth:
          type: string
          examples:
            - '1990-01-15T00:00:00.000Z'
          description: Date of birth (INDIVIDUAL party type)
          example: '1990-01-15T00:00:00.000Z'
        lastName:
          type: string
          examples:
            - Doe
          description: Beneficiary last name
          example: Doe
        name:
          type: string
          examples:
            - Jane Doe
          description: Beneficiary full name
          example: Jane Doe
        targetCustomerId:
          type: string
          examples:
            - 123e4567-e89b-12d3-a456-426614174012
          description: Target customer identifier
          example: 123e4567-e89b-12d3-a456-426614174012
        type:
          type: string
          examples:
            - EXTERNAL
          description: Beneficiary type
          example: EXTERNAL
        bankAddress:
          type: string
          examples:
            - 1 Bank Street, Vilnius
          description: Bank address
          example: 1 Bank Street, Vilnius
        bic:
          type: string
          examples:
            - HABALT22
          description: BIC code
          example: HABALT22
        allowedOperations:
          type: array
          examples:
            - - SEPA_TRANSFER
          items:
            type: string
          description: Allowed operation types
          example:
            - SEPA_TRANSFER
    BaseResponseBeneficiaryResponse:
      type: object
      description: Standard API response wrapper with beneficiary in data
      properties:
        code:
          type: integer
          format: int32
          examples:
            - 201
          description: HTTP-style status code
          example: 201
        data:
          $ref: '#/components/schemas/BeneficiaryResponse'
          type: object
          description: Beneficiary
        message:
          type: string
          examples:
            - Success
          description: Result message
          example: Success
    BeneficiaryResponse:
      type: object
      description: Beneficiary response payload
      properties:
        id:
          type: string
        name:
          type: string
        iban:
          type: string
        bic:
          type: string
        type:
          type: string
        status:
          type: string
        currency:
          type: string
        country:
          type: string
        email:
          type: string
        phoneNumber:
          type: string
        shortName:
          type: string
        networkName:
          type: string
        bankName:
          type: string
        purposeCode:
          type: string
        assetId:
          type: string
        message:
          type: string

````