Skip to main content
POST
/
account-service
/
v2
/
accounts
Create a new account
curl --request POST \
  --url https://api.pgw-sandbox.finventi.com/account-service/v2/accounts \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "accountType": "PRIVATE",
  "accountHolderName": "Jane Doe",
  "clientAccountId": "001",
  "accountHolderNameAliases": [
    "HGRP"
  ],
  "organisationIdentification": {
    "lei": "3423455234Y45D34",
    "bic": "DEUTDEFFXXX",
    "other": {
      "identification": "123-AS-323",
      "schemeNameCode": "DUNS",
      "schemeNameProprietary": "LocalRegistry",
      "issuer": "ChamberOfCommerce"
    }
  },
  "iban": "<string>",
  "countryCode": "LT",
  "bankCode": "70440",
  "accountCode": "1869"
}
'
{
  "id": 1,
  "clientAccountId": "acc_001",
  "iban": "LT121000011111111111",
  "accountType": "PRIVATE",
  "accountHolderName": "Jane Doe",
  "status": "OPEN",
  "createdAt": "2025-09-10T13:43:40.758Z",
  "updatedAt": "2025-09-10T13:55:40.758Z",
  "ibanMetadata": {
    "countryCode": "LT",
    "bankCode": "70440",
    "accountCode": "1869"
  },
  "accountHolderNameAliases": [
    "HGRP"
  ],
  "organisationIdentification": {
    "lei": "3423455234Y45D34",
    "bic": "DEUTDEFFXXX",
    "other": {
      "identification": "123-AS-323",
      "schemeNameCode": "BANK",
      "schemeNameProprietary": "LocalRegistry",
      "issuer": "ChamberOfCommerce"
    }
  }
}

​
Idempotent Endpointgaid

This endpoint supports idempotency to prevent duplicate account creation.

​
How to Use

  • Include an Idempotency-Key header with a unique value (UUID recommended)
  • The API returns the existing account when you reuse the same key
  • Retry requests safely without creating duplicates

​
Overview

This endpoint creates a new account, either PRIVATE or LEGAL. It validates the provided information, generates an IBAN, and creates the account with an OPEN status. All accounts require the account holder’s name, country code, and bank details for IBAN generation, while legal accounts also require a legal entity ID. You can optionally provide a unique clientAccountId to link the account to your internal systems.

Headers

​
Idempotency-Key
string
required

Unique string (often a UUID) used to safely retry requests

Example:

"8e7aafb1-92f2-4681-a068-a4819c03c0b6"

Body

application/json

Request to create a new account

​
accountType
enum<string>
required

Type of account (PRIVATE or LEGAL)

Available options:
PRIVATE,
LEGAL
Example:

"PRIVATE"

​
accountHolderName
string
required

Name of the account holder or company name if legal

Minimum string length: 1
Example:

"Jane Doe"

​
clientAccountId
string
required

Client's internal account ID (must be unique)

Example:

"001"

​
accountHolderNameAliases
string[] | null

Optional alternative names or identifiers to improve matching (e.g., acronyms, short forms like "IBM" for "International Business Machines")

Example:
["HGRP"]
​
organisationIdentification
object

Organisation identification details (for LEGAL accounts)

​
iban
string | null

Account IBAN

​
countryCode
string | null

ISO alpha-2 country code

Example:

"LT"

​
bankCode
string | null

Bank code

Example:

"70440"

​
accountCode
string | null

Account code

Example:

"1869"

Response

Account created successfully

Account information response

​
id
integer<int64>
required

Internal account identifier

Example:

1

​
clientAccountId
string
required

Client's internal account ID

Example:

"acc_001"

​
iban
string
required

International Bank Account Number

Example:

"LT121000011111111111"

​
accountType
enum<string>
required

Type of account

Available options:
PRIVATE,
LEGAL
Example:

"PRIVATE"

​
accountHolderName
string
required

Name of the account holder

Example:

"Jane Doe"

​
status
enum<string>
required

Account status

Available options:
OPEN,
CLOSED
Example:

"OPEN"

​
createdAt
string
required

Account creation timestamp

Example:

"2025-09-10T13:43:40.758Z"

​
updatedAt
string
required

Last update timestamp

Example:

"2025-09-10T13:55:40.758Z"

​
ibanMetadata
object

International Bank Account Generation Metadata

​
accountHolderNameAliases
string[] | null

Optional alternative names or identifiers to improve matching (e.g., acronyms, short forms like "IBM" for "International Business Machines")

Example:
["HGRP"]
​
organisationIdentification
object

Organisation identification details (for LEGAL accounts)