Description

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

Name Requirements:
- First name required
- Last name required
- Maximum length: 100 characters
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

Code	Description
personas.first_name_required	First name is required
personas.last_name_required	Last name is required
personas.first_name_too_long	First name exceeds 100 characters
personas.last_name_too_long	Last name exceeds 100 characters
personas.date_of_birth_required	Date of birth is required
personas.date_of_birth_future	Date of birth cannot be in the future
personas.date_of_birth_invalid	Invalid date of birth
personas.age_under_18	Must be at least 18 years old
personas.day_invalid_for_month	Day invalid for month
personas.day_invalid	Day invalid
personas.month_invalid	Month invalid
personas.year_invalid	Year invalid
personas.date_of_death_invalid	Invalid date of death
personas.failed_to_serialize	Failed to parse request body
personas.invalid_persona_id	Invalid persona ID
personas.persona_not_found	Persona not found
personas.failed_to_validate	Failed to validate input

Query Parameters

List Personas

Parameter	Type	Description
active	boolean	Filter by active status
nationality	string	Filter by ISO 3166-1 alpha-3 country code
limit	integer	Maximum number of records (default: 20, max: 100)
offset	integer	Number of records to skip for pagination

List Personas (v2)

Parameter	Type	Description
limit	integer	Maximum number of records
offset	integer	Number of records to skip
sort	string	Comma-separated sort fields, use `-` prefix for DESC
stack	string	Stack/group by a field
search.id.eq	uuid	Filter by persona ID
search.created_at.eq	string	Filter by `created_at`
search.created_by.eq	uuid	Filter by `created_by`
search.modified_at.eq	string	Filter by `modified_at`
search.modified_by.eq	uuid	Filter by `modified_by`
search.active.eq	boolean	Filter by active flag
search.metadata.like	string	Search in metadata text
search.first_name.like	string	Filter by first name
search.last_name.like	string	Filter by last name
search.date_of_birth.eq	date	Filter by date of birth
search.date_of_death.eq	date	Filter by date of death
search.nationality.eq	string	Filter by nationality
search.hash_id.like	string	Filter by hash ID
search.linked_to.record_id	uuid	Filter personas linked to a specific record ID
search.linked_to.record_type	string	Filter personas linked to a specific record type

List Links

Parameter	Type	Description
rec_type_name	string	Filter by linked entity type
active	boolean	Filter by active status
limit	integer	Maximum number of records (default: 20, max: 100)
offset	integer	Number of records to skip for pagination

Response Status Codes

Status	Description
200	Success - Request completed successfully
201	Created - New resource created successfully
400	Bad Request - Invalid input data
401	Unauthorized - Missing or invalid authentication
403	Forbidden - Insufficient permissions
404	Not Found - Resource not found
422	Unprocessable Entity - Validation error
500	Internal Server Error - Server error

Versioning

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

Example: /v1/personas

Description

On this page