Creates a new user under the partner account.
Each user must have a unique externalUserId and email address within the scope of the partner.
🔐 Headers
| Header | Description |
|---|---|
PartnerApiKey | API key associated with your partner account. Required. See API Key Generation Guide. |
This endpoint requires authentication using a valid
partner-api-key.
📥 Request Body
Field | Type | Required | Description |
|---|---|---|---|
type | string | ✅ | The type of user to create. Must be either INDIVIDUAL or BUSINESS. |
email | string | ✅ | Email address of the user. Must be unique per partner. |
externalUserId | string | ✅ | External ID of the user as defined by your system. Used for future references. |
📘 Example Request
curl --request POST \
--url https://staging-api.capa.fi/api/partner/v2/users \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'partner-api-key: {{API-KEY}}' \
--data '
{
"type": "INDIVIDUAL",
"email": "[email protected]",
"externalUserId": "1441d100-8cc3-40ca-9e55-6183d6f11f18"
}
'
📤 Response Body
Field | Type | Description |
|---|---|---|
userId | string | The unique ID of the user created under your partner account. |
📘 Example Response
{
"userId": "9486244c-ff7d-4c22-9984-797179d7deaa"
}
⚠️ Important Notes & Requirements
- Partner API Key is mandatory: All requests must include a valid
PartnerApiKeyin the header. Get your API key. - Unique Identifiers: Each
externalUserIdmust be unique per partner. If reused, it will cause a conflict. - Email Format: Ensure the email follows a valid format and is unique within your partner account.
- User Types: The
typefield must be eitherINDIVIDUALorBUSINESS. These types help categorize users for regulatory or operational purposes. - KYC Requirements: Creating a user does not initiate KYC. That must be handled separately using the KYC Link Generation endpoint.
- User Linking: You are responsible for securely storing the returned
userIdand linking it to your internal user model.
✅ Use Cases
-
User Onboarding
Partners can create users in advance of any financial operation, associating them with an email and external ID for tracking and compliance. -
CRM & Platform Syncing
Use theexternalUserIdfield to match your internal users to those created on the Capa platform, allowing seamless identity resolution across systems. -
Business Account Registration
When onboarding companies, you can settypetoBUSINESSto distinguish corporate flows from individual flows. -
Pre-KYC Setup
Create users in advance to associate them with wallets, transactions, or redirect links before triggering identity verification or off-ramp transactions.