Description

Purpose and use

Personas hold reusable identity details for natural persons and organizations that appear in customer, signatory, shareholder, counterparty, or contact workflows. They keep identity facts separate from the business relationship that uses them.

Who uses this. Onboarding analysts, compliance teams, customer service, and operations staff use personas when verifying people, linking identities, and reviewing customer-related parties.

How it works. A persona stores identity, address, nationality, age, organization, and relationship details. Other modules link to that persona when they need the same person or organization in a customer, signatory, or counterparty context.

What users do. Users create or update persona data, link personas to business records, validate required identity fields, and search existing identities before creating duplicates.

Outcomes and side effects. Persona changes can affect onboarding evidence, signatory review, contact data, and compliance context. They do not by themselves approve a customer or post any ledger movement.

Related manuals: Customers, KYB, Addresses, Counterparties.

Overview

The Personas API provides functionality for managing personal and organizational identities, including:

• Personal information management
• Organization details
• Address management
• Identity linking
• Age and nationality validation
• Multi-entity relationships

Endpoints

Personal Identity Management

Create Persona

POST /v1/personas

Create a new personal identity record.

Request Body:

{
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-01",
  "nationality": "CHE",
  "actual_street": "Main Street",
  "actual_house": "123",
  "actual_house_number": "123",
  "actual_zip_code": "8001",
  "actual_city": "Zurich",
  "actual_country": "CHE",
  "reg_street": "Main Street",
  "reg_house": "123",
  "reg_house_number": "123",
  "reg_zip_code": "8001",
  "reg_city": "Zurich",
  "reg_country": "CHE",
  "metadata": {
    "language": "de",
    "preferred_contact": "email"
  },
  "active": true
}

Success Response (201):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "first_name": "John",
  "last_name": "Doe",
  "date_of_birth": "1990-01-01",
  "nationality": "CHE",
  "hash_id": "abc123",
  "active": true,
  "created_at": "2024-03-21T10:00:00Z",
  "created_by": "123e4567-e89b-12d3-a456-426614174000"
}

Get All Personas

GET /v1/personas

Retrieve all accessible personas.

Success Response (200):

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "nationality": "CHE",
    "hash_id": "abc123",
    "active": true,
    "created_at": "2024-03-21T10:00:00Z",
    "created_by": "123e4567-e89b-12d3-a456-426614174000"
  }
]

Get Persona by ID

GET /v1/personas/{persona_id}

Retrieve a specific persona's details.

Update Persona

PUT /v1/personas/{persona_id}

Request Body:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-01-01",
  "nationality": "CHE",
  "actual_street": "Main Street",
  "actual_house_number": "321",
  "actual_zip_code": "8001",
  "actual_city": "Zurich",
  "actual_country": "CHE",
  "metadata": {
    "preferred_contact": "email"
  },
  "active": false
}

Delete Persona

DELETE /v1/personas/{persona_id}

Delete a persona record.

User-Persona Operations

Get User's Persona

GET /v1/personas/user/{user_id}

Get persona associated with a user.

Get User's Persona (v2)

GET /v2/personas/user/{user_id}

Get persona associated with a user, including linked_to records.

Update User's Persona

PUT /v1/personas/user/{user_id}

Request Body:

{
  "first_name": "Jane",
  "last_name": "Doe",
  "nationality": "CHE",
  "actual_street": "Main Street",
  "actual_house_number": "321",
  "actual_zip_code": "8001",
  "actual_city": "Zurich",
  "actual_country": "CHE",
  "metadata": {
    "preferred_contact": "phone"
  },
  "active": true
}

Persona Links

Create Link

POST /v1/persona-links

Create a link between a persona and another entity.

Request Body:

{
  "persona_id": "550e8400-e29b-41d4-a716-446655440000",
  "rec_id": "123e4567-e89b-12d3-a456-426614174000",
  "rec_type_name": "organizations",
  "metadata": {
    "role": "director",
    "start_date": "2024-01-01"
  },
  "active": true
}

Get Link

GET /v1/persona-links/{id}

Retrieve a specific link.

Update Link

PUT /v1/persona-links/{id}

Request Body:

{
  "metadata": {
    "role": "advisor",
    "start_date": "2024-04-01"
  },
  "active": false
}

Delete Link

DELETE /v1/persona-links/{id}

Delete a link.

List Links

GET /v1/persona-links

List all persona links.

Personal Identity Management (v2)

Get All Personas (v2)

GET /v2/personas

Retrieve personas with get_all behavior (search, sort, pagination, stack). Each returned persona item includes the same structure as /v2/personas/{persona_id}:

• persona fields
• linked_to array with related records

Get Persona by ID (v2)

GET /v2/personas/{persona_id}

Retrieve one persona with linked_to records.

Validation Rules

Personal Information

1. Name Requirements:

   • First name required
   • Last name required
   • Maximum length: 100 characters

2. Date of Birth:

   • Required field
   • Must be in the past
   • Must be within last 150 years
   • Must be at least 18 years old
   • Valid calendar date

Error Codes

Query Parameters

List Personas

List Personas (v2)

List Links

Response Status Codes

Versioning

The API is versioned through the URL path. Supported versions are v1 and v2.

Example: /v1/personas