Skip to main content

​
What are identities?

Identities represent the people or organizations that own balances in your ledger system. The Identity model in Blnk allows you to store customer information, personal details, and business data while providing built-in support for PII (Personally Identifiable Information) tokenization to meet compliance and privacy requirements. Identities help you:
  • Link balances to customers for easy account management
  • Store customer information in a structured format
  • Tokenize sensitive data to comply with privacy regulations
  • Manage both individuals and organizations with flexible fields
  • Maintain KYC/compliance data alongside financial records

​
Identity structure

The Identity model in Blnk contains the following fields:
​
identity_id
string
Unique identifier for the identity (auto-generated)
​
identity_type
string
Type of identity (e.g., “individual”, “business”, “corporate”)
​
organization_name
string
Name of the organization (for business identities)
​
category
string
Category or classification of the identity
​
first_name
string
Individual’s first name
​
last_name
string
Individual’s last name
​
other_names
string
Middle names or other names
​
gender
string
Gender information
​
email_address
string
Email address
​
phone_number
string
Phone number
​
nationality
string
Nationality or citizenship
​
street
string
Street address
​
country
string
Country
​
state
string
State or province
​
post_code
string
Postal or ZIP code
​
city
string
City
​
dob
timestamp
Date of birth
​
created_at
timestamp
When the identity was created
​
meta_data
object
Custom metadata and tokenization tracking

​
Example identity object

{
  "identity_id": "id_abc123def456",
  "identity_type": "individual",
  "first_name": "Jane",
  "last_name": "Doe",
  "email_address": "[email protected]",
  "phone_number": "+1234567890",
  "nationality": "US",
  "street": "123 Main Street",
  "city": "New York",
  "state": "NY",
  "post_code": "10001",
  "country": "USA",
  "dob": "1990-01-15T00:00:00Z",
  "created_at": "2024-03-04T10:30:00Z",
  "meta_data": {
    "kyc_status": "verified",
    "customer_tier": "premium"
  }
}

​
Creating an identity

​
Individual identity

Create an identity for an individual customer: 
curl -X POST http://localhost:5001/identities \
  -H "Content-Type: application/json" \
  -d '{
    "identity_type": "individual",
    "first_name": "Jane",
    "last_name": "Doe",
    "email_address": "[email protected]",
    "phone_number": "+1234567890",
    "nationality": "US",
    "street": "123 Main Street",
    "city": "New York",
    "state": "NY",
    "post_code": "10001",
    "country": "USA",
    "dob": "1990-01-15T00:00:00Z",
    "meta_data": {
      "kyc_status": "pending",
      "customer_tier": "standard"
    }
  }'

{
  "identity_id": "id_abc123def456",
  "identity_type": "individual",
  "first_name": "Jane",
  "last_name": "Doe",
  "email_address": "[email protected]",
  "phone_number": "+1234567890",
  "nationality": "US",
  "street": "123 Main Street",
  "city": "New York",
  "state": "NY",
  "post_code": "10001",
  "country": "USA",
  "dob": "1990-01-15T00:00:00Z",
  "created_at": "2024-03-04T10:30:00Z",
  "meta_data": {
    "kyc_status": "pending",
    "customer_tier": "standard"
  }
}

​
Business identity

Create an identity for a business or organization: 
curl -X POST http://localhost:5001/identities \
  -H "Content-Type: application/json" \
  -d '{
    "identity_type": "business",
    "organization_name": "Acme Corporation",
    "category": "technology",
    "email_address": "[email protected]",
    "phone_number": "+1987654321",
    "street": "456 Business Ave",
    "city": "San Francisco",
    "state": "CA",
    "post_code": "94105",
    "country": "USA",
    "meta_data": {
      "business_registration": "BR123456",
      "tax_id": "TAX789012"
    }
  }'

​
Linking identities to balances

Identities can be linked to balances to associate customer information with their accounts.

​
Create a balance with an identity

curl -X POST http://localhost:5001/balances \
  -H "Content-Type: application/json" \
  -d '{
    "ledger_id": "ldg_customer123",
    "currency": "USD",
    "identity_id": "id_abc123def456"
  }'

curl -X PUT http://localhost:5001/balances/bal_xyz789/identity \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "id_abc123def456"}'

​
Retrieve a balance with identity information

curl "http://localhost:5001/balances/bal_xyz789?include=identity"
The response includes the full identity object: 
{
  "balance_id": "bal_xyz789",
  "balance": "50000",
  "currency": "USD",
  "identity_id": "id_abc123def456",
  "identity": {
    "identity_id": "id_abc123def456",
    "first_name": "Jane",
    "last_name": "Doe",
    "email_address": "[email protected]"
  }
}

​
PII tokenization

Blnk provides built-in tokenization to protect sensitive personally identifiable information (PII). Tokenization replaces sensitive data with secure tokens, helping you comply with privacy regulations like GDPR, CCPA, and PCI DSS.

​
How tokenization works

  1. Store original data: Sensitive fields are encrypted and stored securely
  2. Replace with tokens: Field values are replaced with secure tokens
  3. Track tokenized fields: Metadata tracks which fields are tokenized
  4. Detokenize when needed: Retrieve original values with proper authorization

​
Tokenizing identity fields

Tokenize specific fields of an identity: 
curl -X POST http://localhost:5001/identities/id_abc123def456/tokenize \
  -H "Content-Type: application/json" \
  -d '{
    "fields": ["email_address", "phone_number", "street"]
  }'
After tokenization, the identity looks like: 
{
  "identity_id": "id_abc123def456",
  "first_name": "Jane",
  "last_name": "Doe",
  "email_address": "tok_email_xyz789",
  "phone_number": "tok_phone_abc123",
  "street": "tok_street_def456",
  "meta_data": {
    "tokenized_fields": {
      "EmailAddress": true,
      "PhoneNumber": true,
      "Street": true
    }
  }
}

​
Tokenizing a single field

curl -X POST http://localhost:5001/identities/id_abc123def456/tokenize/email_address

​
Detokenizing fields

Retrieve the original values of tokenized fields: 
curl -X POST http://localhost:5001/identities/id_abc123def456/detokenize \
  -H "Content-Type: application/json" \
  -d '{
    "fields": ["email_address", "phone_number"]
  }'

{
  "fields": {
    "email_address": "[email protected]",
    "phone_number": "+1234567890"
  }
}

​
Detokenize all fields

Omit the fields parameter to detokenize all tokenized fields: 
curl -X POST http://localhost:5001/identities/id_abc123def456/detokenize \
  -H "Content-Type: application/json" \
  -d '{}'

​
View tokenized fields

Check which fields are currently tokenized: 
curl http://localhost:5001/identities/id_abc123def456/tokenized-fields

{
  "tokenized_fields": [
    "EmailAddress",
    "PhoneNumber",
    "Street"
  ]
}

​
Managing identities

​
Retrieve an identity

curl http://localhost:5001/identities/id_abc123def456

​
List all identities

# Get identities with pagination
curl "http://localhost:5001/identities?limit=20&offset=0"

​
Filter identities

# Filter by identity type
curl "http://localhost:5001/identities?identity_type_eq=individual"

# Filter by name
curl "http://localhost:5001/identities?first_name_eq=Jane"

# Filter by category
curl "http://localhost:5001/identities?category_in=retail,premium"

​
Update an identity

curl -X PUT http://localhost:5001/identities/id_abc123def456 \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "[email protected]",
    "meta_data": {
      "kyc_status": "verified",
      "customer_tier": "premium"
    }
  }'

​
Delete an identity

curl -X DELETE http://localhost:5001/identities/id_abc123def456
Deleting an identity does not delete associated balances. Ensure you handle balance ownership before deleting identities.

​
Use cases

Create an identity during customer registration:
  1. Collect customer information
  2. Create identity record
  3. Tokenize sensitive fields (email, phone, address)
  4. Create customer balance linked to identity
  5. Store only the identity_id in your application
This keeps PII in Blnk’s secure storage while your application works with IDs.
Use identities to manage compliance:
{
  "meta_data": {
    "kyc_status": "verified",
    "kyc_date": "2024-03-04",
    "kyc_provider": "provider_name",
    "risk_level": "low",
    "verification_documents": ["passport", "utility_bill"]
  }
}
Link multiple balances (different currencies) to one identity:
# Create USD balance
curl -X POST http://localhost:5001/balances \
  -d '{"identity_id": "id_customer", "currency": "USD"}'

# Create EUR balance
curl -X POST http://localhost:5001/balances \
  -d '{"identity_id": "id_customer", "currency": "EUR"}'
Now you can query all balances for a customer by their identity_id.
Tokenize PII for GDPR/CCPA compliance:
  • Tokenize sensitive fields on creation
  • Only detokenize when necessary (customer support, compliance checks)
  • Log detokenization requests for audit trails
  • Implement role-based access to detokenization endpoints

​
Best practices

Always tokenize PII fields that you don’t need for regular operations:
  • Email addresses
  • Phone numbers
  • Street addresses
  • Date of birth
  • Government IDs
Keep non-sensitive fields (like names) in plain text for easier querying.
Store additional customer information in meta_data:
{
  "meta_data": {
    "kyc_status": "verified",
    "account_manager": "manager_123",
    "customer_since": "2024-01-15",
    "preferences": {
      "notifications": true,
      "newsletter": false
    }
  }
}
Restrict access to detokenization endpoints:
  • Require authentication and authorization
  • Log all detokenization requests
  • Implement rate limiting
  • Use role-based permissions (only support staff can detokenize)
Use identity_type and category consistently:
{
  "identity_type": "individual",
  "category": "retail_customer"
}

{
  "identity_type": "business",
  "category": "merchant"
}
This makes filtering and reporting easier.
When customers update their information:
  1. Verify the update request
  2. Log the change for audit purposes
  3. Re-tokenize if updating sensitive fields
  4. Update any cached data in your application

​
Next steps

Balances

Link identities to customer balances

Transactions

Record financial movements for customers

Privacy & Compliance

Learn more about compliance features

API Reference

Complete API documentation for identities

Build docs developers (and LLMs) love

Get started for freeTalk to us