Skip to main content
POST
/
api
/
partner
/
v2
/
users
cURL
curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/users \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <partner-api-key>' \
  --data '
{
  "type": "INDIVIDUAL or BUSINESS",
  "email": "[email protected]",
  "externalUserId": "1441d100-8cc3-40ca-9e55-6183d6f11f18",
  "alias": "John Doe"
}
'
{
  "success": true,
  "data": {
    "userId": "9486244c-ff7d-4c22-9984-797179d7deaa"
  }
}
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

HeaderDescription
PartnerApiKeyAPI key associated with your partner account. Required. See API Key Generation Guide.
This endpoint requires authentication using a valid partner-api-key.

​
📥 Request Body

FieldTypeRequiredDescription
typestring✅The type of user to create. Must be either INDIVIDUAL or BUSINESS.
emailstring✅Email address of the user. Must be unique per partner.
externalUserIdstring✅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

FieldTypeDescription
userIdstringThe unique ID of the user created under your partner account.

​
📘 Example Response

JSON
{
  "userId": "9486244c-ff7d-4c22-9984-797179d7deaa"
}

​
⚠️ Important Notes & Requirements

  • Partner API Key is mandatory: All requests must include a valid PartnerApiKey in the header. Get your API key.
  • Unique Identifiers: Each externalUserId must 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 type field must be either INDIVIDUAL or BUSINESS. 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 userId and 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 the externalUserId field 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 set type to BUSINESS to 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.

Headers

​
partner-api-key
string
required

Api key for the affiliated partner that is performing the request

Body

application/json
​
type
enum<string>
required

The type of user.

Available options:
INDIVIDUAL,
BUSINESS
Example:

"INDIVIDUAL or BUSINESS"

​
email
string
required

The email of the user.

Example:

"[email protected]"

​
externalUserId
string

The external user id of the user.

Example:

"1441d100-8cc3-40ca-9e55-6183d6f11f18"

​
alias
string

An optional alias or display name for the user.

Example:

"John Doe"

Response

201 - application/json
​
success
boolean
Example:

true

​
data
object