POST
/
end-users
Create an individual end user (KYC)
curl --request POST \
  --url https://api.balansas.com/functions/v1/customer-api/end-users \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "[email protected]",
  "dob": "<string>",
  "address": {
    "line1": "<string>",
    "city": "<string>",
    "postalCode": "<string>",
    "country": "<string>",
    "line2": "<string>",
    "state": "<string>"
  },
  "middleName": "<string>",
  "phone": "<string>",
  "birthCountry": "<string>",
  "nationality": "<string>",
  "ipAddress": "<string>",
  "tags": [
    "<string>"
  ],
  "signupAt": "2023-11-07T05:31:56Z",
  "metadata": {},
  "linkedCryptoWallets": [
    {
      "coin": "<string>",
      "walletAddress": "<string>",
      "relationship": []
    }
  ],
  "umbrellaLinkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "onboarding_url_token": "<string>",
  "kycReportBase64": "<string>",
  "kycReportFilename": "<string>",
  "sumsubReportBase64": "<string>",
  "sumsubReportFilename": "<string>"
}
'
import requests

url = "https://api.balansas.com/functions/v1/customer-api/end-users"

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "[email protected]",
    "dob": "<string>",
    "address": {
        "line1": "<string>",
        "city": "<string>",
        "postalCode": "<string>",
        "country": "<string>",
        "line2": "<string>",
        "state": "<string>"
    },
    "middleName": "<string>",
    "phone": "<string>",
    "birthCountry": "<string>",
    "nationality": "<string>",
    "ipAddress": "<string>",
    "tags": ["<string>"],
    "signupAt": "2023-11-07T05:31:56Z",
    "metadata": {},
    "linkedCryptoWallets": [
        {
            "coin": "<string>",
            "walletAddress": "<string>",
            "relationship": []
        }
    ],
    "umbrellaLinkId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "onboarding_url_token": "<string>",
    "kycReportBase64": "<string>",
    "kycReportFilename": "<string>",
    "sumsubReportBase64": "<string>",
    "sumsubReportFilename": "<string>"
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    firstName: '<string>',
    lastName: '<string>',
    email: '[email protected]',
    dob: '<string>',
    address: {
      line1: '<string>',
      city: '<string>',
      postalCode: '<string>',
      country: '<string>',
      line2: '<string>',
      state: '<string>'
    },
    middleName: '<string>',
    phone: '<string>',
    birthCountry: '<string>',
    nationality: '<string>',
    ipAddress: '<string>',
    tags: ['<string>'],
    signupAt: '2023-11-07T05:31:56Z',
    metadata: {},
    linkedCryptoWallets: [{coin: '<string>', walletAddress: '<string>', relationship: []}],
    umbrellaLinkId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    onboarding_url_token: '<string>',
    kycReportBase64: '<string>',
    kycReportFilename: '<string>',
    sumsubReportBase64: '<string>',
    sumsubReportFilename: '<string>'
  })
};

fetch('https://api.balansas.com/functions/v1/customer-api/end-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://api.balansas.com/functions/v1/customer-api/end-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([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'email' => '[email protected]',
    'dob' => '<string>',
    'address' => [
        'line1' => '<string>',
        'city' => '<string>',
        'postalCode' => '<string>',
        'country' => '<string>',
        'line2' => '<string>',
        'state' => '<string>'
    ],
    'middleName' => '<string>',
    'phone' => '<string>',
    'birthCountry' => '<string>',
    'nationality' => '<string>',
    'ipAddress' => '<string>',
    'tags' => [
        '<string>'
    ],
    'signupAt' => '2023-11-07T05:31:56Z',
    'metadata' => [
        
    ],
    'linkedCryptoWallets' => [
        [
                'coin' => '<string>',
                'walletAddress' => '<string>',
                'relationship' => [
                                
                ]
        ]
    ],
    'umbrellaLinkId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'onboarding_url_token' => '<string>',
    'kycReportBase64' => '<string>',
    'kycReportFilename' => '<string>',
    'sumsubReportBase64' => '<string>',
    'sumsubReportFilename' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-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://api.balansas.com/functions/v1/customer-api/end-users"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"dob\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"middleName\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"birthCountry\": \"<string>\",\n  \"nationality\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"signupAt\": \"2023-11-07T05:31:56Z\",\n  \"metadata\": {},\n  \"linkedCryptoWallets\": [\n    {\n      \"coin\": \"<string>\",\n      \"walletAddress\": \"<string>\",\n      \"relationship\": []\n    }\n  ],\n  \"umbrellaLinkId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"onboarding_url_token\": \"<string>\",\n  \"kycReportBase64\": \"<string>\",\n  \"kycReportFilename\": \"<string>\",\n  \"sumsubReportBase64\": \"<string>\",\n  \"sumsubReportFilename\": \"<string>\"\n}")

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

	req.Header.Add("x-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://api.balansas.com/functions/v1/customer-api/end-users")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"dob\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"middleName\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"birthCountry\": \"<string>\",\n  \"nationality\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"signupAt\": \"2023-11-07T05:31:56Z\",\n  \"metadata\": {},\n  \"linkedCryptoWallets\": [\n    {\n      \"coin\": \"<string>\",\n      \"walletAddress\": \"<string>\",\n      \"relationship\": []\n    }\n  ],\n  \"umbrellaLinkId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"onboarding_url_token\": \"<string>\",\n  \"kycReportBase64\": \"<string>\",\n  \"kycReportFilename\": \"<string>\",\n  \"sumsubReportBase64\": \"<string>\",\n  \"sumsubReportFilename\": \"<string>\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.balansas.com/functions/v1/customer-api/end-users")

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

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"[email protected]\",\n  \"dob\": \"<string>\",\n  \"address\": {\n    \"line1\": \"<string>\",\n    \"city\": \"<string>\",\n    \"postalCode\": \"<string>\",\n    \"country\": \"<string>\",\n    \"line2\": \"<string>\",\n    \"state\": \"<string>\"\n  },\n  \"middleName\": \"<string>\",\n  \"phone\": \"<string>\",\n  \"birthCountry\": \"<string>\",\n  \"nationality\": \"<string>\",\n  \"ipAddress\": \"<string>\",\n  \"tags\": [\n    \"<string>\"\n  ],\n  \"signupAt\": \"2023-11-07T05:31:56Z\",\n  \"metadata\": {},\n  \"linkedCryptoWallets\": [\n    {\n      \"coin\": \"<string>\",\n      \"walletAddress\": \"<string>\",\n      \"relationship\": []\n    }\n  ],\n  \"umbrellaLinkId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"onboarding_url_token\": \"<string>\",\n  \"kycReportBase64\": \"<string>\",\n  \"kycReportFilename\": \"<string>\",\n  \"sumsubReportBase64\": \"<string>\",\n  \"sumsubReportFilename\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "id": "9e2b1c34-5d6e-4f70-8a91-2b3c4d5e6f70",
    "fr_end_user_id": "eu_5Lk9Pm",
    "end_user_type": "INDIVIDUAL",
    "first_name": "Maria",
    "middle_name": "Elena",
    "last_name": "Rossi",
    "company_name": "Helix Trading Ltd",
    "email": "[email protected]",
    "reference_code": "EU-GWG2HS32",
    "status": "pending_verification",
    "fr_owner_business_id": "busi_8Jh2KdLm5Qx",
    "registration_number": "12345678",
    "registration_date": "2019-06-15",
    "business_type": "LIMITED_COMPANY",
    "incorporation_country": "IE",
    "sector": "OTHER_PRODUCTS_SERVICES",
    "risk_tier": "low_risk",
    "verification_completed_at": "2026-05-21T08:00:00.000Z",
    "disclosure_accepted_at": "2026-05-23T10:05:00.000Z",
    "disclosure_version": "ppa-v1.2-2026-05-23",
    "reverse_solicitation": {
      "required": true,
      "accepted": false
    },
    "created_at": "2026-05-28T11:02:09.456Z",
    "updated_at": "2026-05-28T11:02:09.456Z"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}
{
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>"
  }
}

Authorizations

​
x-api-key
string
header
required

Customer API key. Send as x-api-key: sk_... or Authorization: Bearer sk_.... Write operations also require an X-CSRF-Token header (64-char hex).

Body

application/json
​
firstName
string
required
Required string length: 1 - 100
​
lastName
string
required
Required string length: 1 - 100
​
email
string<email>
required
Maximum string length: 255
​
dob
string
required
Pattern: ^\d{4}-\d{2}-\d{2}$
​
address
object
required
​
middleName
string
Maximum string length: 100
​
phone
string
Maximum string length: 20
​
birthCountry
string
Required string length: 2
​
nationality
Required string length: 2
​
identificationDocument
object
​
ipAddress
string
Maximum string length: 45
​
annualSalaryRange
enum<string>
Available options:
RANGE_0_TO_25000,
RANGE_25000_TO_50000,
RANGE_50000_TO_100000,
RANGE_100000_TO_150000,
ABOVE_150000
​
tags
string[]
Maximum array length: 20
Required string length: 1 - 100
​
riskRating
enum<string>
Available options:
LOW,
MEDIUM,
HIGH
​
signupAt
string<date-time>
​
metadata
object
​
linkedCryptoWallets
object[]
Maximum array length: 50
​
umbrellaLinkId
string<uuid>
​
onboarding_url_token
string
Required string length: 1 - 100
​
reverseSolicitationAttestation
object
​
verificationMethod
enum<string>
Available options:
hosted_kyc,
pdf_upload,
sumsub_websdk
​
kycReportBase64
string
Required string length: 1 - 14680064
​
kycReportFilename
string
Maximum string length: 255
​
sumsubReportBase64
string
Required string length: 1 - 14680064
​
sumsubReportFilename
string
Maximum string length: 255

Response

Success

​
data
object
required