Individual Customer Registration

Endpoint: POST /api/v2.1/customer/individual/registration

Prerequisites

Get Categorization Hierarchy

Call GET /customer/individual/categorization/hierarchy/ to retrieve available categories and features.This returns the valid values you can use in registration.

Prepare Registration Data

Structure your request according to the required nested format with individualCustomer.person and individualCustomer.user.

Submit Registration

POST the registration request with all required fields.

The system automatically assigns the customer to the B2C Individual category. The response includes the categorization object showing the assigned category and its features.

Endpoint

POST /api/v2.1/customer/individual/registration

Headers

For complete details on authentication, compliance headers, and SDK implementation examples, refer to the Standard HTTP Headers reference documentation.

X-Tenant-ID

string

required

Tenant identifier for multi-tenant operationsExample: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd

Authorization

string

required

Bearer token for authenticationExample: Bearer eyJ0eXAiOiJKV1QiLCJh...

Content-Type

string

required

Must be application/json

string

Response format (optional — defaults to application/json)Example: application/json, text/plain, */*

X-Forwarded-From

string

required

Client/application identifier — Use this header from browser clients to identify the request source. This is CORS-safe and will not trigger preflight failures.Example: playground, web-app, mobile-app

User-Agent

string

required

Client application identifier — required by the global request filter for security analysis and device fingerprintingExample: YourApp/1.0 or Mozilla/5.0 (Windows NT 10.0; Win64; x64)

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platformExample: web

deviceId

string

required

Unique device identifier for session tracking. Also accepted as X-Device-Id or device-idExample: 356938035643809

sec-ch-ua-platform

string

Browser client hint for OS platform (accepted alias for platform — automatically sent by modern browsers)Example: "Windows"

Request Body

The request body uses a nested structure. Do not send a flat object. All customer details must be inside the individualCustomer wrapper object.

Top-Level Fields

tenantId

string

Tenant identifier (optional at top level, also available in individualCustomer.tenantId)If not provided, will use the value from individualCustomer.tenantId or X-Tenant-ID header.

firstName

string

required

Customer’s first name (also duplicated in individualCustomer.person.firstName)

lastName

string

required

Customer’s last name (also duplicated in individualCustomer.person.lastName)

string

required

Customer’s email address (also duplicated in individualCustomer.person.email)Must be unique within the tenant.

phone

string

required

Phone number with country codeFormat: E.164 (e.g., +37060012345)

password

string

required

Password for the customer’s user accountSecurity Requirements:

Minimum 8 characters
Must contain uppercase and lowercase letters
Must contain at least one number
Must contain at least one special character

matchingPassword

string

required

Password confirmation (must exactly match password)

roleIds

string[]

required

Array of role identifiers for the userStandard Roles:

ACCOUNT_OWNER: Primary account owner
USER: Standard user permissions

Example: ["ACCOUNT_OWNER", "USER"]

dateOfBirth

string

Customer’s date of birth (YYYY-MM-DD format)Also duplicated in individualCustomer.person.dateOfBirthExample: "1990-05-15"

gender

string

Customer’s genderValid Values: "MALE", "FEMALE", "OTHER"Also duplicated in individualCustomer.person.gender

nationality

string

Customer’s nationality (ISO 3166-1 alpha-2 country code)Also duplicated in individualCustomer.person.nationalityExample: "LT", "US", "GB"

placeOfBirth

string

Customer’s place of birthAlso duplicated in individualCustomer.person.placeOfBirthExample: "Vilnius"

pincode

string

Customer’s PIN code (optional)Example: "12345"

customerCategory

object

Customer category assignment (optional)

Show customerCategory properties

string

Category database IDExample: "fs-cat-b2c-low-001"

name

string

Category display nameExample: "Individual Standard"

Individual Customer Object

individualCustomer

object

required

Nested object containing all customer details

Show individualCustomer properties

tenantId

string

required

Tenant identifier (must match top-level tenantId)

customerName

string

required

Full display name for the customerExample: "Marcus Jensen"

person

object

required

Personal information object

Show person properties

string

Optional person identifier (auto-generated if not provided)

firstName

string

required

Given name(s)

lastName

string

required

Family name(s)

string

required

Primary email address

dateOfBirth

string

required

Date of birth in ISO 8601 format (YYYY-MM-DD)Example: "1990-05-15"

gender

string

Gender identifierValid Values:

"MALE"
"FEMALE"
"OTHER"

nationality

string

required

ISO 3166-1 alpha-2 country code for nationalityExample: "LT", "US", "GB"

placeOfBirth

string

City or location of birth

fullName

string

Complete name for display purposes

addresses

array

required

Array of address objects (at least one required)

Show address properties

string

Optional address identifier (auto-generated if not provided)

type

string

required

Address type: "HOME", "WORK", "BILLING", or "SHIPPING"

street

string

required

Street address including building number

city

string

required

City name

postalCode

string

required

Postal/ZIP code

country

string

required

ISO 3166-1 alpha-2 country code

state

string

State or province (optional)

isPrimary

boolean

required

Whether this is the primary address

contacts

array

required

Array of contact objects

Show contact properties

string

Optional contact identifier

type

string

required

Contact type: "EMAIL", "PHONE", "MOBILE", or "FAX"

value

string

required

Contact value (email address, phone number, etc.)

isPrimary

boolean

required

Whether this is the primary contact method

user

object

required

User account information

Show user properties

string

Optional user identifier (auto-generated if not provided)

tenantId

string

required

Tenant identifier

username

string

required

Username for login (typically same as email)

string

required

User’s email address

password

string

required

User’s password (will be hashed)

status

string

required

Initial user statusDefault: "PENDING_ACTIVATION"

roles

string[]

required

Array of role strings (e.g., ["ACCOUNT_OWNER", "USER"])

isActive

boolean

Whether the user is active (default: false until activation)

Code Examples

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/registration" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "firstName": "Marcus",
    "lastName": "Jensen",
    "email": "marcus.jensen@example.com",
    "phone": "+37060012345",
    "password": "SecurePassword123!",
    "matchingPassword": "SecurePassword123!",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "nationality": "LT",
    "placeOfBirth": "Vilnius",
    "pincode": "12345",
    "roleIds": ["ACCOUNT_OWNER", "USER"],
    "customerCategory": {
      "id": "fs-cat-b2c-low-001",
      "name": "Individual Standard"
    },
    "individualCustomer": {
      "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
      "customerName": "Marcus Jensen",
      "person": {
        "id": "the2r6zaa6",
        "firstName": "Marcus",
        "lastName": "Jensen",
        "email": "marcus.jensen@example.com",
        "dateOfBirth": "1990-05-15",
        "gender": "MALE",
        "nationality": "LT",
        "placeOfBirth": "Vilnius",
        "fullName": "Marcus Jensen",
        "addresses": [
          {
            "id": "6vsvy01jbzo",
            "type": "HOME",
            "street": "123 Medium Risk Street",
            "city": "Compliance City",
            "postalCode": "12345",
            "country": "LT",
            "isPrimary": true
          }
        ],
        "contacts": [
          {
            "id": "g4dh2ch831",
            "type": "EMAIL",
            "value": "marcus.jensen@example.com",
            "isPrimary": true
          }
        ]
      },
      "user": {
        "id": "uhqvq7sc80m",
        "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
        "username": "marcus.jensen@example.com",
        "email": "marcus.jensen@example.com",
        "password": "SecurePassword123!",
        "status": "PENDING_ACTIVATION",
        "roles": ["ACCOUNT_OWNER", "USER"],
        "isActive": false
      }
    }
  }'

Advanced: Registration with Categorization

When registering medium or high-risk customers, you can include categorization with feature parametrization to define risk assessment parameters upfront. This follows the pattern used in production for sophisticated risk management.

How It Works

Get Categorization Hierarchy - Call GET /customer/individual/categorization/hierarchy/
Select Category - Choose appropriate category based on risk level (e.g., “MEDIUM_RISK_INDIVIDUAL”, “VERIFIED_INDIVIDUAL”)
Build Feature Relations - Map category features with smart value selection
Include in Registration - Add categorization object to individualCustomer

Example: Medium-Risk Customer with Categorization

curl -X POST "https://sandbox.finhub.cloud/api/v2.1/customer/individual/registration" \
  -H "Accept: application/json, text/plain, */*" \
  -H "Content-Type: application/json" \
  -H "X-Tenant-ID: 97e7ff29-15f3-49ef-9681-3bbfcce4f6cd" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Forwarded-From: e2e-test" \
  -H "platform: web" \
  -H "deviceId: 356938035643809" \
  -d '{
    "firstName": "Marcus",
    "lastName": "Jensen",
    "email": "marcus.jensen@example.com",
    "phone": "+37060012345",
    "password": "SecurePassword123!",
    "matchingPassword": "SecurePassword123!",
    "dateOfBirth": "1990-05-15",
    "gender": "MALE",
    "nationality": "LT",
    "placeOfBirth": "Vilnius",
    "pincode": "12345",
    "roleIds": ["ACCOUNT_OWNER", "USER"],
    "customerCategory": {
      "id": "fs-cat-b2c-low-001",
      "name": "Individual Standard"
    },
    "individualCustomer": {
      "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
      "customerName": "Marcus Jensen",
      "person": {
        "firstName": "Marcus",
        "lastName": "Jensen",
        "email": "marcus.jensen@example.com",
        "dateOfBirth": "1990-05-15",
        "gender": "MALE",
        "nationality": "LT",
        "addresses": [
          {
            "type": "HOME",
            "street": "123 Medium Risk Street",
            "city": "Vilnius",
            "postalCode": "12345",
            "country": "LT",
            "isPrimary": true
          }
        ],
        "contacts": [
          {
            "type": "EMAIL",
            "value": "marcus.jensen@example.com",
            "isPrimary": true
          }
        ]
      },
      "user": {
        "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
        "username": "marcus.jensen@example.com",
        "email": "marcus.jensen@example.com",
        "password": "SecurePassword123!",
        "status": "PENDING_ACTIVATION",
        "roles": ["ACCOUNT_OWNER", "USER"],
        "isActive": false
      },
      "categorization": {
        "id": "medium-risk-verified-5f8a9b",
        "name": "MEDIUM_RISK_VERIFIED_INDIVIDUAL",
        "description": "Medium risk verified individual customer",
        "isActive": true,
        "categoryFeatureRelations": [
          {
            "feature": {
              "id": "risk-assessment-3c4d",
              "code": "RISK_ASSESSMENT"
            },
            "enabled": true,
            "parametrization": [
              {
                "name": "RISK_LEVEL",
                "value": "MEDIUM"
              },
              {
                "name": "RISK_SCORE",
                "value": "55"
              },
              {
                "name": "PEP_STATUS",
                "value": "false"
              },
              {
                "name": "SANCTIONS_CHECK",
                "value": "STANDARD"
              },
              {
                "name": "MONITORING_FREQUENCY",
                "value": "WEEKLY"
              }
            ]
          },
          {
            "feature": {
              "id": "transaction-limits-7e2f",
              "code": "TRANSACTION_LIMITS"
            },
            "enabled": true,
            "parametrization": [
              {
                "name": "MONTHLY_LIMIT",
                "value": "20000"
              },
              {
                "name": "DAILY_LIMIT",
                "value": "5000"
              },
              {
                "name": "PER_TRANSACTION_LIMIT",
                "value": "2000"
              }
            ]
          },
          {
            "feature": {
              "id": "verification-requirements-9a1b",
              "code": "VERIFICATION_REQUIREMENTS"
            },
            "enabled": true,
            "parametrization": [
              {
                "name": "IDENTITY_VERIFICATION",
                "value": "REQUIRED"
              },
              {
                "name": "DOCUMENT_VERIFICATION",
                "value": "REQUIRED"
              },
              {
                "name": "ENHANCED_DUE_DILIGENCE",
                "value": "OPTIONAL"
              }
            ]
          }
        ]
      }
    }
  }'

Categorization Benefits

Why Use Categorization During Registration?

Risk-Based Onboarding - Automatically apply appropriate risk controls
Transaction Limits - Set limits based on customer risk profile
Verification Requirements - Define required KYC/AML checks upfront
Monitoring Frequency - Schedule appropriate transaction monitoring
Compliance Automation - Ensure regulatory requirements are met

Smart Value Selection

The examples above demonstrate smart value selection patterns used in production:

Parameter	Smart Selection Logic	Example Values
RISK_LEVEL	Match “MEDIUM”, “STANDARD”, or use middle value	MEDIUM, STANDARD, LOW
RISK_SCORE	Match 40-69 range for medium risk	55, 50, 60
PEP_STATUS	Match “FALSE” or “NO”	false, NO, NOT_APPLICABLE
SANCTIONS_CHECK	Match “STANDARD” or “PERIODIC”	STANDARD, PERIODIC, DAILY
MONITORING_FREQUENCY	Match “WEEKLY” or “STANDARD”	WEEKLY, STANDARD, DAILY
MONTHLY_LIMIT	Match 15K-25K range for medium risk	20000, 15000, 25000

Production Pattern: Always retrieve the categorization hierarchy first, then use smart value selection to build appropriate categoryFeatureRelations based on the customer’s risk profile.

Response

{
  "code": 200,
  "message": "B2C individual account created successfully. Redirect to activate-account page",
  "redirectUrl": "/auth/activate-account",
  "data": {
    "organization": false,
    "individual": true,
    "id": "5887c98c-b5b1-4234-b819-a4987f54aa77",
    "tenantId": "d1e2f3a4-b5c6-47d8-9e0f-1a2b3c4d5e6f",
    "customerType": "CT_PERSON",
    "customerStatus": "CS_REGISTRATION_COMPLETED",
    "categorization": {
      "active": true,
      "id": "B2CCustomerIndividual",
      "name": "B2C Individual",
      "description": "Customer categorization for B2C",
      "isActive": true,
      "categoryFeatureRelations": [],
      "parametrization": []
    },
    "person": {
      "lastName": "Jensen",
      "firstName": "Marcus",
      "id": "the2r6zaa6",
      "names": [
        {
          "type": "FIRST",
          "value": "Marcus"
        },
        {
          "type": "LAST",
          "value": "Jensen"
        }
      ],
      "dateOfBirth": "1990-05-15",
      "nationality": "LT",
      "email": "marcus.jensen@example.com",
      "contacts": [],
      "documents": [],
      "addresses": [
        {
          "type": "HOME",
          "street": "123 Medium Risk Street",
          "city": "Compliance City",
          "postalCode": "12345",
          "country": "LT",
          "isPrimary": true
        }
      ]
    },
    "user": {
      "id": "23cfc195-be4a-4e7c-88f2-ef789ae83d39",
      "email": "marcus.jensen@example.com",
      "roles": [],
      "permissions": [],
      "isActive": false,
      "requiresPasswordChange": false,
      "twoFactorEnabled": false
    },
    "notifications": [],
    "createdAt": "2026-01-12T19:21:59.019243Z",
    "updatedAt": "2026-01-12T19:21:59.019243Z",
    "consents": [],
    "organizationAssociations": []
  }
}

Response Fields

Success Response (data object)

Field	Type	Description
`id`	string	Unique customer identifier (UUID)
`tenantId`	string	Tenant identifier
`customerType`	string	Always `"CT_PERSON"` for individuals
`customerStatus`	string	Initial status: `"CS_REGISTRATION_COMPLETED"`
`individual`	boolean	Always `true` for individual customers
`organization`	boolean	Always `false` for individual customers
`person`	object	Person details (simplified from request)
`user`	object	User account details
`categorization`	object	Applied customer category
`redirectUrl`	string	Next step URL (activation page)
`createdAt`	string	ISO 8601 creation timestamp
`updatedAt`	string	ISO 8601 last update timestamp

Next Steps After Registration

User Receives Activation Email
- System sends activation email to registered address
- Email contains activation code and link
User Completes Activation
- See Individual Activation API for details
- Endpoint: POST /customer/individual/{customerId}/activation
KYC Verification Required
- After activation, customer must complete KYC verification
- See Verification Management
Account Becomes Fully Active
- After KYC approval, customer can perform all operations
- Wallet is created automatically upon activation

Common Validation Errors

Password Mismatch

Error:

{
  "code": 400,
  "message": "Password and matching password do not match"
}

Solution: Ensure password and matchingPassword are identical

Duplicate Email

Error:

{
  "code": 409,
  "message": "Customer with email '...' already exists"
}

Solution: Email addresses must be unique within the tenant. Use a different email or retrieve the existing customer.

Invalid Nested Structure

Error:

{
  "code": 400,
  "message": "individualCustomer is required"
}

Solution: Ensure you’re using the nested structure with individualCustomer.person.* hierarchy. Do not send a flat object.

Missing Required Fields

Error:

{
  "code": 400,
  "message": "firstName is required in person object"
}

Solution: All fields marked as “required” must be present in the request. Check the field is in the correct nested location.

Best Practices

Recommended Flow:

Validate Input - Check all required fields before sending
Hash Passwords - Never log or store passwords in plain text
Handle Activation - Guide user through activation process
Complete KYC - Ensure verification is completed before enabling financial operations
Monitor Status - Track customer status through the workflow

Password Security

Use strong password requirements (enforced by API)
Never send passwords over unencrypted connections
Implement password strength indicator in UI
Consider implementing password hashing client-side

Data Validation

// Example validation before API call
const validateRegistrationData = (data) => {
  const errors = [];
  
  // Check password match
  if (data.password !== data.matchingPassword) {
    errors.push('Passwords do not match');
  }
  
  // Validate email format
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(data.email)) {
    errors.push('Invalid email format');
  }
  
  // Validate phone format (E.164)
  const phoneRegex = /^\+[1-9]\d{1,14}$/;
  if (!phoneRegex.test(data.phone)) {
    errors.push('Invalid phone format (use E.164: +1234567890)');
  }
  
  // Check nested structure exists
  if (!data.individualCustomer || !data.individualCustomer.person) {
    errors.push('Missing required nested structure');
  }
  
  return errors;
};

API Schema Reference

For the complete OpenAPI schema specification of this endpoint, including all request and response structures, see the API Schema Mapping document.

Standard Headers

Complete HTTP headers reference for compliance

Individual Activation

Activate customer account after registration

Verification Management

Complete KYC verification process

Session Login

Create user session after activation

Consent Management

Manage customer consents (terms, privacy, data processing)

Changelog

Version	Date	Changes
v2.1	2026-01-13	Initial release

Headers

User-Agent

string

required

Browser user agent

Example:

"Mozilla/5.0"

X-Forwarded-For

string

required

Client/application Ip address

Example:

"192.168.0.1"

X-Forwarded-From

string

required

Client/application identifier for request source tracking

Example:

"playground"

X-Tenant-ID

string

required

Tenant identifier

Example:

"97e7ff29-15f3-49ef-9681-3bbfcce4f6cd"

platform

string

required

Client platform identifier. Also accepted as sec-ch-ua-platform

Example:

"web"

deviceId

string

required

Device identifier

Example:

"e2e-test-device"

Authorization

string

required

Bearer token from admin or customer session creation

Example:

"Bearer <token>"

Body

application/json

firstName

string

required

Example:

"Marcus"

lastName

string

required

Example:

"Jensen"

string

required

Example:

"marcus.jensen.1773494532320.cmcdd1@mediumrisk-example.com"

phone

string

required

Example:

"+37060012345"

password

string

required

Example:

"SecurePass123!"

matchingPassword

string

required

Example:

"SecurePass123!"

dateOfBirth

string

required

Example:

"1990-05-15"

gender

string

required

Example:

"MALE"

nationality

string

required

Example:

"Lithuania"

placeOfBirth

string

required

Example:

"Vilnius"

pincode

string

required

Example:

"12345"

roleIds

string[]

required

Example:

["ACCOUNT_OWNER", "USER"]

customerCategory

object

required

Show child attributes

individualCustomer

object

required

Show child attributes

Response

Individual customer registered successfully

Standard API response wrapper used by all endpoints

code

integer

HTTP status code

Example:

200

data

object

Response from customer registration endpoints

Show child attributes

message

string

Human-readable status message

Example:

"Success"

Client Categories

Product Suite

Service Models

CoreX Service Model

API Service Model

Hybrid Service Model

​Individual Customer Registration

​Prerequisites

​Endpoint

​Headers

​Request Body

​Top-Level Fields

​Individual Customer Object

​Code Examples

​Advanced: Registration with Categorization

​How It Works

​Example: Medium-Risk Customer with Categorization

​Categorization Benefits

​Smart Value Selection

​Response

​Response Fields

​Success Response (data object)

​Next Steps After Registration

​Common Validation Errors

​Password Mismatch

​Duplicate Email

​Invalid Nested Structure

​Missing Required Fields

​Best Practices

​Password Security

​Data Validation

​API Schema Reference

​Related Endpoints

Standard Headers

Individual Activation

Verification Management

Session Login

Consent Management

​Changelog

Headers

Body

Response

Individual Customer Registration

Prerequisites

Endpoint

Headers

Request Body

Top-Level Fields

Individual Customer Object

Code Examples

Advanced: Registration with Categorization

How It Works

Example: Medium-Risk Customer with Categorization

Categorization Benefits

Smart Value Selection

Response

Response Fields

Success Response (data object)

Next Steps After Registration

Common Validation Errors

Password Mismatch

Duplicate Email

Invalid Nested Structure

Missing Required Fields

Best Practices

Password Security

Data Validation

API Schema Reference

Related Endpoints

Changelog