> ## Documentation Index > Fetch the complete documentation index at: https://developer.fin.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Beneficiary > Create a new beneficiary account for payments and transfers This endpoint will be deprecated on May 20, 2026. Use [Create Beneficiary V3](https://developer.fin.com/api-reference/beneficiaries/create-beneficiary-v3) instead. ## Rules * Beneficiary creation requires the customer to be in the `APPROVED` status. * Two beneficiaries with the same destination are not allowed. ## De-Duplication Logic For *bank accounts*, the system checks: `bank_account.scheme`, `bank_account.number`, `bank_routing.scheme`, `bank_routing.number`. For *e-wallets*: `e_wallet.scheme`, `e_wallet.number`. ## Country-Specific Validation ### GBR (United Kingdom) * **Bank account number**: Must match `^[0-9]{4,9}$` for both `LOCAL` and `SWIFT` schemes. ## OpenAPI ````yaml POST /v2/beneficiaries openapi: 3.1.0 info: title: Fin.com API version: 1.0.0 description: A simple API specification servers: - url: https://sandbox.api.fin.com description: Sandbox server - url: https://api.fin.com description: Production server security: [] tags: - name: Authentication description: A modified OAuth 2.0 Client Credential Flow - name: Customers description: Customer management and document upload operations - name: Balances description: Retrieve wallet balance information - name: Catalogue description: | A set of endpoints to retrieve contextual data to assemble requests to fin.com's API - name: Beneficiaries description: Manage beneficiary accounts for payments and transfers - name: Transactions description: Transaction history and management for beneficiaries - name: Virtual Accounts description: Create and manage virtual accounts for USD to USDC conversions - name: Fees & FX Rates description: Retrieve fees and foreign exchange rates paths: /v2/beneficiaries: post: tags: - Beneficiaries summary: Create Beneficiary description: Create a new beneficiary account for payments and transfers requestBody: required: true content: application/json: schema: allOf: - type: object required: - customer_id - country - currency - account_holder - account_holder_address - receiver_meta_data - developer_fee - deposit_instruction - refund_instruction properties: customer_id: type: string example: cust_123456 country: type: string example: USA pattern: ^[A-Z]{3}$ currency: type: string example: USD counter_party: type: string enum: - FIRST_PARTY - THIRD_PARTY description: >- Indicates whether the beneficiary is a first-party or third-party account. Optional. example: FIRST_PARTY account_holder: oneOf: - title: Individual type: object required: - type - first_name - last_name - email - phone properties: type: type: string enum: - INDIVIDUAL first_name: type: string example: John last_name: type: string example: Doe email: type: string format: email example: john.doe@example.com phone: type: string example: '+1234567890' - title: Business type: object required: - type - business_name - email - phone properties: type: type: string enum: - BUSINESS business_name: type: string example: Acme Corp email: type: string format: email example: contact@acmecorp.com phone: type: string example: '+1234567890' account_holder_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: 456 Main Street street_line_2: type: string example: Apt 5B city: type: string example: Brooklyn state: type: string description: >- State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-NY postcode: type: string example: '11201' country: type: string example: USA pattern: ^[A-Z]{3}$ receiver_meta_data: type: object required: - transaction_purpose_id - occupation_remarks - relationship - nationality properties: transaction_purpose_id: type: integer example: 1 transaction_purpose_remarks: type: string example: Monthly salary payment occupation_id: type: integer example: 5 occupation_remarks: type: string example: Software Engineer relationship: type: string enum: - EMPLOYEE - FREELANCER - GIG_WORKER - AFFILIATE - CUSTOMER - FAMILY_MEMBER - FRIEND - SELF - OTHER - SUPPLIER - VENDOR - SERVICE_PROVIDER - MERCHANT - CONTRACTOR - SUBSIDIARY - PARENT_COMPANY - AFFILIATE_BUSINESS - BANK_ACCOUNT - BROKER - EXCHANGE - WALLET relationship_remarks: type: string example: Long-term contractor nationality: type: string example: USA pattern: ^[A-Z]{3}$ govt_id_number: type: string example: JG1121316A govt_id_issue_date: type: string format: date example: '2024-12-30' govt_id_expire_date: type: string format: date example: '2027-12-30' developer_fee: type: object required: - fixed - percentage properties: fixed: type: number example: 5 percentage: type: number example: 2.5 deposit_instruction: type: object required: - currency - rail properties: currency: type: string enum: - USDC rail: type: string enum: - POLYGON refund_instruction: type: object required: - wallet_address - currency - rail properties: wallet_address: type: string example: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb' currency: type: string enum: - USDC rail: type: string enum: - POLYGON settlement_config: type: object required: - auto_settlement properties: auto_settlement: type: boolean example: true - oneOf: - title: Bank Account type: object required: - bank_account - bank_routing - bank_address properties: bank_account: type: object required: - bank_name - number - scheme - type properties: bank_name: type: string example: Chase Bank number: type: string example: '1234567890' scheme: type: string enum: - LOCAL - SWIFT type: type: string enum: - CHECKING - SAVINGS - CURRENT bank_routing: type: array items: type: object required: - scheme - number properties: scheme: type: string enum: - ACH - BANK_CODE - BANK_IDENTIFIER - BRANCH_CODE - BRANCH_IDENTIFIER - BSB - IBAN - IFSC - SWIFT - TRANSIT_NUMBER - WIRE number: oneOf: - type: string - type: integer example: '021000021' bank_address: type: object required: - street_line_1 - city - state - postcode - country properties: street_line_1: type: string example: 123 Bank Street street_line_2: type: string example: Suite 100 city: type: string example: New York state: type: string description: >- State or province. Required. Must be an ISO 3166-2 subdivision code (e.g. US-CA, BD-13). example: US-NY postcode: type: string example: '10001' country: type: string example: USA pattern: ^[A-Z]{3}$ - title: E Wallet type: object required: - e_wallet properties: e_wallet: type: object required: - scheme - number properties: scheme: type: string example: BKASH number: type: string example: '+8801688502814' responses: '200': description: Beneficiary created successfully content: application/json: schema: type: object properties: data: type: object properties: id: type: string example: ben_123456 status: type: string example: active '400': description: Bad Request - Invalid input format content: application/json: schema: type: object properties: errors: type: array items: type: object message: type: string example: Validation failed! '401': $ref: '#/components/responses/AuthenticationError' '409': description: >- Conflict - A beneficiary with the same account details already exists content: application/json: schema: type: object properties: message: type: string example: >- A beneficiary with the same account details already exists. error: type: object properties: beneficiary_id: type: string format: uuid example: d9868585-78ba-4723-b0af-8f5b1cc5f9e2 '422': $ref: '#/components/responses/ValidationError' security: - bearerAuth: [] components: responses: AuthenticationError: description: Authentication failed due to invalid credentials content: application/json: schema: type: object properties: message: type: string example: Authentication failed ValidationError: description: Failed due to a formatting error. content: application/json: schema: type: object required: - message properties: message: type: string errors: type: array items: type: object additionalProperties: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Bearer token authentication. Obtain token from [Issue a Token](https://developer.fin.com/api-reference/authentication/issue-a-token) endpoint ````