Accounts

Use account endpoints to create a person or business account and to poll onboarding status. These endpoints operate on the authenticated client context; do not pass collaborator or account ids unless an endpoint explicitly defines them.

GetAccountStatusQueryV1 is the source of truth for onboarding state. Poll it after account creation and after each user action requested by the response.

Some response field and enum names retain legacy provider-specific wording for compatibility. Do not display provider names directly to users; map these values to product-facing labels in your UI.

Create a full account

Create a full individual or business account with identity, contact, and address details.

POST /accounts/full/v1 CreateFullAccountCommandV1

curl https://api-preview.kunga.eu/accounts/full/v1   --request POST   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{
    "accountType": "Personal",
    "email": "[email protected]",
    "birthDate": "1990-01-15",
    "name": "Alex",
    "lastName": "Rivera",
    "identificationType": "Passport",
    "identificationNumber": "X1234567",
    "phoneNumber": "+34600000000",
    "address": {
      "streetLine1": "Example Street 10",
      "streetLine2": null,
      "city": "Madrid",
      "stateName": "Madrid",
      "stateCode": "MD",
      "countryName": "Spain",
      "countryCode": "ESP",
      "postalCode": "28001"
    },
    "companyName": null,
    "companyRegistrationNumber": null
  }'

Expected response:

{
  "personId": "123e4567-e89b-12d3-a456-426614174000",
  "companyId": null
}

For business accounts, set accountType to Business and provide companyName and companyRegistrationNumber.

Get account status

Poll this endpoint to retrieve onboarding progress, required action links, rejection reasons, wallets, and current account metadata.

QUERY /accounts/status/v1 GetAccountStatusQueryV1

curl https://api-preview.kunga.eu/accounts/status/v1   --request QUERY   --header 'Content-Type: application/json'   --header 'Authorization: Basic <BASE64(uuid:password)>'   --data '{}'

If proof of address is required and a file has already been uploaded, include proofOfAddressStaticFileId:

{
  "proofOfAddressStaticFileId": "123e4567-e89b-12d3-a456-426614174000"
}

Example complete response:

{
  "accountCreationStatus": "Complete",
  "bridgeAccountStatus": "Active",
  "isProofOfAddressRequired": false,
  "wallets": [
    {
      "id": "2c3d38cd-acc9-5c48-be51-20b128d23ab1",
      "address": "0x123456789abcdef0123456789abcdef01234567",
      "blockchain": "BASE",
      "balances": []
    }
  ],
  "virtualAccounts": [],
  "rejectionReasons": []
}

Important response fields

accountCreationStatus: high-level onboarding state. Use this for user-facing flow decisions.
isProofOfAddressRequired: whether a proof-of-address document must be uploaded.
Verification link fields: user-action links when extra verification is required.
wallets: app wallets available for transfers and Auto Convert Route destinations.
virtualAccounts: legacy compatibility field. New route setup should use Auto Convert Routes.
rejectionReasons: items the user or integration must resolve before onboarding can complete.

Onboarding lifecycle

Status	Meaning	Integration action
`SumsubKnowYourCustomer`	Identity verification must be started.	Send the user to the returned verification link, then poll again.
`SumsubWaitForKnowYourCustomer`	Identity verification is under review.	Poll periodically and avoid asking for duplicate submissions.
`BridgeAcceptTermsOfService`	Terms must be accepted through the returned action link.	Send the user to the action link, then poll again.
`BridgeCompleteKnowYourCustomer`	Additional verification is required.	Send the user to the returned action link.
`UploadProofOfAddress`	Proof of address is required.	Upload the document, then poll with `proofOfAddressStaticFileId`.
`BridgeFillRegulatoryInformation`	Additional regulatory answers are required.	Collect and submit the requested information.
`BridgeProvideSourceOfFundsData`	Source-of-funds details are required.	Collect and submit the requested information.
`Complete`	Account can transact.	Enable saved contacts, direct transfers, and Auto Convert Routes.
`ProblemAccountDeactivated`	Account cannot transact.	Stop transfer creation and contact support with the request id.

Onboarding examples

Initial KYC required

{
  "accountCreationStatus": "SumsubKnowYourCustomer",
  "sumsubKycLink": {
    "link": "https://example.com/kyc-session",
    "status": "init"
  }
}

Complete the required KYC action and then call GetAccountStatusQueryV1 again.

Accept terms of service

{
  "accountCreationStatus": "BridgeAcceptTermsOfService",
  "bridgeAccountStatus": "NotStarted",
  "bridgeKycLink": {
    "tosLink": "https://example.com/accept-terms",
    "tosStatus": "pending",
    "rejectionReasons": []
  }
}

Complete verification

{
  "accountCreationStatus": "BridgeCompleteKnowYourCustomer",
  "bridgeAccountStatus": "Incomplete",
  "bridgeKycLink": {
    "kycLink": "https://example.com/verify",
    "kycStatus": "not_started",
    "rejectionReasons": []
  }
}

Complete

{
  "accountCreationStatus": "Complete",
  "bridgeAccountStatus": "Active",
  "wallets": []
}

When the account reaches Complete, the user can create saved contacts, direct transfers, and Auto Convert Routes.