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": "money@capa.fi",
  "externalUserId": "1441d100-8cc3-40ca-9e55-6183d6f11f18",
  "alias": "John Doe"
}
'
{
  "success": true,
  "data": {
    "userId": "9486244c-ff7d-4c22-9984-797179d7deaa"
  }
}
Creates a new user under your partner account. Each user must have a unique email address within the scope of the partner. After creation, initiate KYC verification before the user can transact.

​
Important Notes

  • Each externalUserId (if provided) must be unique per partner. Reuse will cause a conflict.
  • Creating a user does not initiate KYC — use the KYC verification link endpoint next.
  • Set type to INDIVIDUAL for personal accounts or BUSINESS for corporate accounts. Business users use KYB verification instead of KYC.
  • Store the returned userId — you’ll need it for all subsequent API calls for this user.

​
Use Cases

  • User onboarding: Create users ahead of any financial operation.
  • CRM syncing: Use externalUserId to map Capa users to your internal user model.
  • Business registration: Set type to BUSINESS for corporate flows.

​
Error Codes

​
Common Errors

HTTP StatusCodeMessage
401UNAUTHORIZED”API Key is missing”
401UNAUTHORIZED”Invalid API Key format”
401UNAUTHORIZED”Invalid API Key”
403INVALID_PARTNER_FLOW”The partner has an invalid flow.”

​
Endpoint-Specific Errors

HTTP StatusCodeMessage
400INVALID_USER_INPUT_ERROR”Invalid User Input” (validation errors for type, email, externalUserId, alias)
400BAD_REQUEST”Provided email is not valid”
500INTERNAL_SERVER_ERROR”User creation failed”

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:

"money@capa.fi"

​
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