v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB

Instruments API

Create an Instrument Account

post/v1/organizations/{organization_id}/holders/{holder_id}/instruments

Path parameters

organization_idstring uuid required

The unique identifier of the Organization associated with the Ledger.

holder_idstring required

Holder ID (UUID)

Headers

Content-Typestring

The type of media of the resource. Recommended value is application/json.

X-Request-Idstring uuid

A unique identifier used to trace and track each request.

Authorizationstring

Bearer JWT token for authentication. Required when PLUGIN_AUTH_ENABLED=true (enforced in multi-tenant deployments). Optional in default OSS single-tenant mode. Format: Bearer <token>

X-Idempotencystring

A unique key that ensures transaction idempotency. If not provided, the system automatically generates a SHA-256 hash based on the request body. Keys are scoped per organization and ledger.

Always validate the X-Idempotency-Replayed response header to distinguish new transactions from cached replays.

See Retries and idempotency for best practices.

X-TTLinteger

The time-to-live for the idempotency key, defined in seconds. Defaults to 300 seconds (5 minutes) if not provided. Only the TTL from the first request is used; changing it on retries has no effect.

See Retries and idempotency for details.

Request body

accountIdstring uuid nullable required

createdAtstring date-time required

deletedAtstring date-time nullable required

documentstring

holderIdstring uuid required

idstring uuid

ledgerIdstring uuid nullable required

metadataobject

typestring

updatedAtstring date-time required

Example request

{
  "accountId": "00000000-0000-0000-0000-000000000000",
  "bankingDetails": {
    "account": "123450",
    "bankId": "12345",
    "branch": "0001",
    "closingDate": "2025-12-31",
    "countryCode": "US",
    "iban": "US12345678901234567890",
    "openingDate": "2025-01-01",
    "type": "CACC"
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "deletedAt": "2025-01-01T00:00:00Z",
  "document": "91315026015",
  "holderId": "00000000-0000-0000-0000-000000000000",
  "id": "00000000-0000-0000-0000-000000000000",
  "ledgerId": "00000000-0000-0000-0000-000000000000",
  "regulatoryFields": {
    "participantDocument": "12345678912345"
  },
  "relatedParties": [
    {
      "document": "12345678900",
      "endDate": "2026-01-01",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "John Smith",
      "role": "PRIMARY_HOLDER",
      "startDate": "2025-01-01"
    }
  ],
  "type": "NATURAL_PERSON",
  "updatedAt": "2025-01-01T00:00:00Z"
}

Response