v0.2

Introduction

Welcome to the Kunga API. This starting page gives a concise introduction to the platform's HTTP/JSON APIs, usage expectations, and an important temporary convention we adopt for certain read-style requests.

Quick overview

Kunga exposes a set of HTTPS endpoints that accept and return JSON. Endpoints follow REST-like conventions for resources such as identities, users, metrics, and integrations. All calls must be made over TLS and authenticated according to the section that applies to your identity type (user JWT, External API Consumer, etc.). Responses follow consistent HTTP status codes and structured error objects.

construction

Currently in Beta

This API is currently in beta version. Expect breaking changes; integration teams should prepare for required updates when new major versions are published.

menu_book API Calls Reference open_in_new

Environments

Kunga provides multiple deployment environments to support development, testing, and production workloads. Each environment exposes the same API surface and conventions, but differs in stability guarantees, data characteristics, and intended usage.

Available environments

Production

Live
Base URL https://api.kunga.eu/
Purpose Live, customer-facing traffic.

Preview / Sandbox

Testing
Base URL https://api-preview.kunga.eu/
Purpose Integration testing, previews, and experimentation.

Conventions

Follow these conventions to keep the API catalogue consistent, to make client generation predictable, and to support multiple simultaneous API versions when breaking changes occur.

OperationId naming rules

Use PascalCase and a clear suffix to indicate intent and version.

Query operations (read-style endpoints)

Pattern:<Verb><Resource><Qualifier>QueryV<MAJOR>
Example:GetCurrentIdentityUserQueryV1

Even when the implementation temporarily uses PATCH to accept a body for query parameters, the operation name should convey that this is a read/query operation.

Command operations (state-changing endpoints)

Pattern:<Verb><Resource><Qualifier>CommandV<MAJOR>
Example:CreateFullAccountCommandV1
info

Version number in OperationId: Append a major version only (V) to the operationId. Minor/patch bumps do not change the operationId.

Response type naming rules

Each operation has a single response type name derived from the operationId by appending Response.

OperationGetCurrentIdentityUserQueryV1→GetCurrentIdentityUserQueryV1Response
OperationCreateFullAccountCommandV1→CreateFullAccountCommandV1Response

Response schema names should be stored in components/schemas in OpenAPI using the response type name.

construction

Currently in beta only the version v1 will be used and might have breaking changes.

Path versioning

Place the version at the end of the path segment for clarity and routing simplicity. Use the major version only in the path (e.g., v1, v2).

GET/PATCH (query-style):/identity/current/v1
Command-style:/accounts/v1
construction

Currently in beta only the version v1 will be used and might have breaking changes.

Multiple versions and coexistence

  • •Some endpoints will have multiple published versions (e.g., v1, v2) when breaking changes are introduced.
  • •Deploy new major version on /.../vN while leaving the older version active on /.../v(N-1)
  • •New clients should target the latest stable major version
  • •Existing clients remain supported for a deprecation window
construction

Currently in beta only the version v1 will be used and might have breaking changes.

Temporary convention: using PATCH for GET requests that need a body

Until the OpenAPI specification and tooling in our ecosystem reliably support a hypothetical QUERY HTTP method, some read-style operations in Kunga accept a request body. To accommodate this without breaking widely-used OpenAPI tooling, we temporarily use the PATCH method for those calls.

Why this change exists

  • →Many clients and the OpenAPI tooling assume GET requests should not contain bodies; using GET with a body creates compatibility problems.
  • →There is no standard QUERY method in OpenAPI today; introducing a non-standard method would reduce interoperability with existing tools.
  • →PATCH allows us to accept a JSON body while keeping interactions idempotent in practice for query-style endpoints.

Guidance for integrators

  • •Treat these PATCH endpoints as read/query endpoints when used with an empty or query-style JSON body. Do not assume they modify server state unless explicitly documented.
  • •Continue to use correct HTTP semantics for endpoints that truly update resources (e.g., PUT, POST, DELETE).
  • •Expect the API to migrate to a clearer method when OpenAPI and ecosystems provide a stable, interoperable solution. We will announce breaking changes and provide migration guidance.
External API Consumer

Intro External API Consumer

Overview

External API Consumers are machine identities (external servers or services) that call Kunga APIs using HTTP Basic Authentication instead of the normal JWT-based user flows. Use this authentication method for long-lived server-to-server integration where JWTs are inconvenient because they expire frequently.

Username UUID assigned to the External API Consumer (e.g. 3fa85f64-5717-4562-b3fc-2c963f66afa6)
Password Secret string generated by Kunga when the consumer is created.
Auth scheme HTTP Basic Auth over TLS (HTTPS).
info

Note that GET HTTP Methods are PATCH HTTP Methods temporarily.

Quick verification (first request)

Use the following request to verify that a consumer's credentials are valid and to retrieve the current user information.

PATCH GetCurrentIdentityUserQueryV1

cURL (explicit header):

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

cURL (convenience -u):

curl -u "uuid:password" \
https://api-preview.kunga.eu/identity/current/v1 \
--request PATCH \
--header 'Content-Type: application/json' \
--data '{}'

The endpoint above returns the representation of the current identity (the External API Consumer) when credentials are valid.

External API Consumer

Create Account

This page documents how to create a full user account in Kunga and how to poll its creation status. The flow typically requires completing one or more KYC steps via third-party providers.

info

collaboratorAccountId — Use your collaborator account id.

Create a new full account

Create a full account (person or company) including identification and contact details.

POST /accounts/full/v1 — CreateFullAccountCommandV1
curl https://api-preview.kunga.eu/accounts/full/v1 \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "collaboratorAccountId": <YourAccountId>,
  "accountType": "Undefined",
  "email": "",
  "birthDate": "",
  "name": "",
  "lastName": "",
  "identificationType": "Undefined",
  "identificationNumber": "",
  "phoneNumber": "",
  "address": {
    "streetLine1": "",
    "streetLine2": null,
    "city": "",
    "stateName": "",
    "stateCode": "",
    "countryName": "",
    "countryCode": "",
    "postalCode": ""
  },
  "companyName": null,
  "companyRegistrationNumber": null
}'

Response:

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

Get account creation status

After creating an account, use the status endpoint to retrieve the current creation progress and any KYC links that need to be completed.

PATCH /accounts/status/v1 — GetAccountStatusQueryV1
curl https://api-preview.kunga.eu/accounts/status/v1 \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --data '{
  "accountId": "123e4567-e89b-12d3-a456-426614174000",
  "collaboratorAccountId": <YourAccountId>
}'

KYC Flow Steps

1

Initial KYC required (Sumsub)

{
  "accountCreationStatus": "knowYourCustomer",
  "sumsubKycLink": {
    "link": "https://in.sumsub.com/websdk/p/...",
    "status": "init"
  }
}

Complete the KYC and then call GetAccountStatusQueryV1.

2

Accept Terms of Service (bridge TOS step)

{
  "accountCreationStatus": "bridgeAcceptTermsOfService",
  "bridgeAccountStatus": "notStarted",
  "bridgeKycLink": {
    "tosLink": "https://dashboard.sandbox.bridge.xyz/accept-terms-of-service?...",
    "tosStatus": "pending",
    "rejectionReasons": []
  }
}
3

Complete KYC (Persona/Bridge)

{
  "accountCreationStatus": "bridgeCompleteKnowYourCustomer",
  "bridgeAccountStatus": "incomplete",
  "bridgeKycLink": {
    "kycLink": "https://bridge.withpersona.com/verify?...",
    "kycStatus": "not_started",
    "rejectionReasons": []
  }
}
4

Final state — complete

When user completes the last KYC status will be:

{
  "accountCreationStatus": "complete",
  "bridgeAccountStatus": "active"
}
External API Consumer

Create Virtual Account

POST /virtual-accounts/v1 — CreateVirtualAccountCommandV1
curl https://api-preview.kunga.eu/virtual-accounts/v1 \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "accountId": <YourUserAccountId>,
  "collaboratorAccountId": <YourCollaboratorAccountId>,
  "type": "UsdWithAch",
  "destination": {
    "paymentRail": "Ethereum",
    "currency": "Usdc",
    "toAddress": "0x123456789abcdef0123456789abcdef01234567"
  }
}'
info

Note that only UsdWithAch Virtual Account works in Sandbox.

Changelogs

v0.3

Not Released
  • Added New Transaction system

v0.2

Not Released
  • Added New Documentation
  • Added multiple Accounts for single Identity User
  • Added multiple Access Methods for single Identity User
  • Added External API Consumer
  • Added Basic Access Method as not expiring token authentication

v0.1

Released
  • First Released Version

API Calls Reference

Full interactive API reference with all endpoints, schemas, and example requests.

menu_book Abrir referencia completa de la API open_in_new