Create User - Capa.fi

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/users \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "type": "INDIVIDUAL or BUSINESS",
  "email": "money@capa.fi",
  "externalUserId": "<string>",
  "alias": "<string>"
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/users"

payload = {
    "type": "INDIVIDUAL or BUSINESS",
    "email": "money@capa.fi",
    "externalUserId": "<string>",
    "alias": "<string>"
}
headers = {
    "partner-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'partner-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'INDIVIDUAL or BUSINESS',
    email: 'money@capa.fi',
    externalUserId: '<string>',
    alias: '<string>'
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-api.capa.fi/api/partner/v2/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'INDIVIDUAL or BUSINESS',
    'email' => 'money@capa.fi',
    'externalUserId' => '<string>',
    'alias' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/users"

	payload := strings.NewReader("{\n  \"type\": \"INDIVIDUAL or BUSINESS\",\n  \"email\": \"money@capa.fi\",\n  \"externalUserId\": \"<string>\",\n  \"alias\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("partner-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/users")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"INDIVIDUAL or BUSINESS\",\n  \"email\": \"money@capa.fi\",\n  \"externalUserId\": \"<string>\",\n  \"alias\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"INDIVIDUAL or BUSINESS\",\n  \"email\": \"money@capa.fi\",\n  \"externalUserId\": \"<string>\",\n  \"alias\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "data": {
    "userId": "9486244c-ff7d-4c22-9984-797179d7deaa"
  }
}

POST

api

partner

users

cURL

curl --request POST \
  --url https://staging-api.capa.fi/api/partner/v2/users \
  --header 'Content-Type: application/json' \
  --header 'partner-api-key: <api-key>' \
  --data '
{
  "type": "INDIVIDUAL or BUSINESS",
  "email": "money@capa.fi",
  "externalUserId": "<string>",
  "alias": "<string>"
}
'

import requests

url = "https://staging-api.capa.fi/api/partner/v2/users"

payload = {
    "type": "INDIVIDUAL or BUSINESS",
    "email": "money@capa.fi",
    "externalUserId": "<string>",
    "alias": "<string>"
}
headers = {
    "partner-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'partner-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: 'INDIVIDUAL or BUSINESS',
    email: 'money@capa.fi',
    externalUserId: '<string>',
    alias: '<string>'
  })
};

fetch('https://staging-api.capa.fi/api/partner/v2/users', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://staging-api.capa.fi/api/partner/v2/users",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => 'INDIVIDUAL or BUSINESS',
    'email' => 'money@capa.fi',
    'externalUserId' => '<string>',
    'alias' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "partner-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://staging-api.capa.fi/api/partner/v2/users"

	payload := strings.NewReader("{\n  \"type\": \"INDIVIDUAL or BUSINESS\",\n  \"email\": \"money@capa.fi\",\n  \"externalUserId\": \"<string>\",\n  \"alias\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("partner-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://staging-api.capa.fi/api/partner/v2/users")
  .header("partner-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"INDIVIDUAL or BUSINESS\",\n  \"email\": \"money@capa.fi\",\n  \"externalUserId\": \"<string>\",\n  \"alias\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://staging-api.capa.fi/api/partner/v2/users")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["partner-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"INDIVIDUAL or BUSINESS\",\n  \"email\": \"money@capa.fi\",\n  \"externalUserId\": \"<string>\",\n  \"alias\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "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 Status	Code	Message
401	`UNAUTHORIZED`	”API Key is missing”
401	`UNAUTHORIZED`	”Invalid API Key format”
401	`UNAUTHORIZED`	”Invalid API Key”
403	`INVALID_PARTNER_FLOW`	”The partner has an invalid flow.”

Endpoint-Specific Errors

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

Authorizations

partner-api-key

string

header

required

API key for the affiliated partner performing the request.

Body

application/json

type

enum<string>

required

The type of user.

Available options:

INDIVIDUAL,

BUSINESS

Example:

"INDIVIDUAL or BUSINESS"

string

required

The email of the user.

Example:

"money@capa.fi"

externalUserId

string

The external user id of the user.

alias

string

An optional alias or display name for the user.

Response

User created successfully. Returns the user details, including the generated user id.

success

boolean

Example:

true

data

object

Show child attributes

Start KYC

⌘I

​Important Notes

​Use Cases

​Error Codes

​Common Errors

​Endpoint-Specific Errors

Authorizations

Body

Response

Important Notes

Use Cases

Error Codes

Common Errors

Endpoint-Specific Errors