Skip to main content
Updates the identity associated with a balance. This endpoint allows you to change which identity (user, customer, merchant) is linked to a specific balance, useful for account transfers, ownership changes, or identity consolidation.

​
Path Parameters

​
id
string
required
The unique identifier of the balance to update.

​
Request Body

​
identity_id
string
required
The ID of the new identity to associate with this balance.The identity must already exist in the system before associating it with a balance.

​
Response

​
message
string
Confirmation message indicating successful update.

​
Examples

curl -X PUT https://api.blnk.io/balances/bal_123abc/identity \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "usr_new_owner_456"
  }'

​
Validation

Before updating the identity association, Blnk validates:
  1. Balance Exists: The specified balance must exist
  2. Identity Exists: The new identity must already be created
  3. Valid Identity ID: The identity_id cannot be empty
If any validation fails, the request returns a 400 Bad Request error.

​
Use Cases

​
Account Transfer

Transfer a balance from one user to another: 
# Transfer balance from old owner to new owner
curl -X PUT https://api.blnk.io/balances/bal_123/identity \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "usr_new_owner"
  }'

​
Identity Consolidation

Merge multiple identities by reassigning their balances: 
# User merged accounts, update all balances to primary identity
curl -X PUT https://api.blnk.io/balances/bal_secondary_1/identity \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "usr_primary"}'

curl -X PUT https://api.blnk.io/balances/bal_secondary_2/identity \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "usr_primary"}'

​
Business Acquisition

Transfer merchant balances to acquiring company: 
curl -X PUT https://api.blnk.io/balances/bal_merchant_old/identity \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "org_acquiring_company"}'

​
Account Correction

Fix incorrectly assigned balances: 
# Balance was created with wrong identity
curl -X PUT https://api.blnk.io/balances/bal_wrong/identity \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "usr_correct_owner"}'

​
Organizational Restructuring

Move balances between departments or entities: 
# Move balance from sales to marketing department
curl -X PUT https://api.blnk.io/balances/bal_dept_123/identity \
  -H "Content-Type: application/json" \
  -d '{"identity_id": "dept_marketing"}'

​
Important Considerations

​
Fund Lineage Impact

If the balance has track_fund_lineage enabled:
  • Shadow Balances: Fund lineage shadow balances are tied to the identity
  • Lineage Preservation: Existing lineage mappings remain unchanged
  • Future Lineage: New lineage tracking will use the new identity
  • Migration Complexity: Consider implications before changing identity on lineage-tracked balances

​
Transaction History

  • Preserved: All transaction history remains intact
  • Audit Trail: The identity change itself should be logged externally
  • Reporting: Historical reports may need to account for identity changes

​
Multi-Currency Balances

  • Independent: Each balance-currency pair must be updated separately
  • Batch Operations: Use multiple API calls to update all currencies for an identity

​
Permissions and Access Control

  • Authorization: Ensure proper permissions before allowing identity changes
  • Verification: May require additional user verification for security
  • Compliance: Document identity changes for regulatory compliance

​
Workflow Example

Complete workflow for transferring account ownership: 
# Step 1: Verify the new identity exists
curl https://api.blnk.io/identities/usr_new_owner \
  -H "Authorization: Bearer YOUR_API_KEY"

# Step 2: Get current balance details
curl https://api.blnk.io/balances/bal_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Step 3: Update the identity association
curl -X PUT https://api.blnk.io/balances/bal_123/identity \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "usr_new_owner"
  }'

# Step 4: Verify the update
curl https://api.blnk.io/balances/bal_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Step 5: Log the ownership change in your system
# (Application-specific logging)

​
Error Responses

​
error
string
Error message describing what went wrong.
Common Errors:
Balance Not Found (400)
{
  "error": "balance validation failed: balance not found"
}
Identity Not Found (400)
{
  "error": "identity validation failed: identity not found"
}
Missing Identity ID (400)
{
  "error": "identity_id is required"
}
Invalid Balance ID (400)
{
  "error": "balance id is required. pass id in the route /:id"
}

​
Best Practices

  1. Verify First: Always verify both balance and identity exist before updating
  2. Document Changes: Maintain an audit log of identity changes in your application
  3. Notify Users: Inform affected users when balance ownership changes
  4. Batch Carefully: When updating multiple balances, implement error handling
  5. Test Thoroughly: Test identity changes in staging before production
  6. Compliance: Ensure identity changes comply with financial regulations

Build docs developers (and LLMs) love

Get started for freeTalk to us