v1

latestOpenAPI 3.1.02026-07-263644911022.4 KB

Holders API

Create a Holder

post/v1/organizations/{organization_id}/holders

Path parameters

organization_idstring uuid required

The unique identifier of the Organization associated with the Ledger.

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

createdAtstring date-time required

deletedAtstring date-time nullable required

documentstring

externalIdstring

idstring uuid

metadataobject

namestring

typestring

updatedAtstring date-time required

Example request

{
  "addresses": {
    "additional1": {
      "city": "New York",
      "country": "US",
      "description": "Home",
      "line1": "123 Financial Avenue",
      "line2": "Suite 1500",
      "state": "NY",
      "zipCode": "10001"
    },
    "additional2": {
      "city": "New York",
      "country": "US",
      "description": "Home",
      "line1": "123 Financial Avenue",
      "line2": "Suite 1500",
      "state": "NY",
      "zipCode": "10001"
    },
    "primary": {
      "city": "New York",
      "country": "US",
      "description": "Home",
      "line1": "123 Financial Avenue",
      "line2": "Suite 1500",
      "state": "NY",
      "zipCode": "10001"
    }
  },
  "contact": {
    "mobilePhone": "+1555555555",
    "otherPhone": "+1555555555",
    "primaryEmail": "john.doe@example.com",
    "secondaryEmail": "john.doe@example.com"
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "deletedAt": "2025-01-01T00:00:00Z",
  "document": "91315026015",
  "externalId": "G4K7N8M2",
  "id": "00000000-0000-0000-0000-000000000000",
  "legalPerson": {
    "activity": "Electronic devices development",
    "foundingDate": "2025-01-01",
    "representative": {
      "document": "91315026015",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "role": "CFO"
    },
    "size": "Medium",
    "status": "Active",
    "tradeName": "Lerian Studio",
    "type": "Limited Liability"
  },
  "name": "John Doe",
  "naturalPerson": {
    "birthDate": "1990-01-01",
    "civilStatus": "Single",
    "fatherName": "John Doe",
    "favoriteName": "John",
    "gender": "Male",
    "motherName": "Jane Doe",
    "nationality": "Brazilian",
    "socialName": "John Doe",
    "status": "Active"
  },
  "type": "NATURAL_PERSON",
  "updatedAt": "2025-01-01T00:00:00Z"
}

Response