> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# Identifying Users by Internal User ID

## Overview

Coinflow identifies your users by an internal user ID that you provide.

## Implementation

When using the API, pass your internal user ID in the header:

* **Header:** `x-coinflow-auth-user-id: YOUR_USER_ID`
* **Value:** Any unique, stable identifier from your system (database ID, customer ID, username, etc.)

### Example API Call

```bash
curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/withdraw/kyc \
  --header 'Authorization: YOUR_API_KEY' \
  --header 'x-coinflow-auth-user-id: user_12345' \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "user@example.com",
    "country": "US",
    "firstName": "Jane",
    "lastName": "Doe"
  }'
```

---

## User ID Requirements

#### Must Haves

**Required characteristics for user IDs**

* **Unique per user** - No duplicate IDs across your platform
* **Stable and permanent** - Never changes for a given user
* **Consistent format** - Alphanumeric strings recommended
* **Privacy-safe** - Don't use PII (emails, SSNs, names)

✅ Good examples: `user_12345`, `cust_abc123`, `uid-9876`

#### Best Practices

**Recommendations for robust identification**

* Use database primary keys or UUIDs
* Avoid sequential IDs that reveal user count
* Store Coinflow's withdrawer ID alongside your user ID
* Document the ID format in your integration
* Test with real-world ID formats early

⚠️ Avoid: emails, usernames (can change), sequential numbers

---

## Payout Flows Using User ID Identification

### Merchant Payout from Coinflow In-App Wallet

Most common flow for platforms managing user balances:

1. **Track user earnings** - Store balances in your database
2. **User requests payout** - Via your platform's UI
3. **KYC verification** - One-time identity check (if not done)
4. **Link bank account** - User adds payout destination
5. **Merchant initiates payout** - You call Coinflow API with user ID
6. **Funds disbursed** - From Coinflow wallet to user's bank

→ See [Merchant Payout (Coinflow Wallet)](/guides/payouts/implementation-methods/getting-started) for implementation details

---

## Common Questions

**Q: Can I use email addresses as user IDs?**
A: While possible, it's not recommended. Emails can change, creating issues with Coinflow records. Use stable database IDs instead.

**Q: What if I have multiple user ID formats across systems?**
A: Choose one canonical format for Coinflow integration. Map your various IDs to a single stable identifier in your integration layer.

**Q: Can I change a user's ID after they've completed KYC?**
A: No. Once a user completes KYC with a specific user ID, that ID is permanently associated with their Coinflow identity. Plan your ID strategy before going live.

**Q: Do I need to store Coinflow's withdrawer ID?**
A: Not required, but recommended for debugging and customer support. Store it alongside your user ID for reference.

**Q: Can one user have multiple IDs?**
A: Each unique user ID creates a separate Coinflow identity. If you need to consolidate user accounts, contact Coinflow support for guidance.