curl --request POST \
--url https://api.venlyfinance.com/v1/parties \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"partyType": "INDIVIDUAL",
"externalId": "user-12345",
"firstName": "Jane",
"lastName": "Doe",
"address": {
"addressLine1": "1 Example Street",
"city": "Amsterdam",
"postalCode": "1011AB",
"country": "NL"
}
}
'import requests
url = "https://api.venlyfinance.com/v1/parties"
payload = {
"partyType": "INDIVIDUAL",
"externalId": "user-12345",
"firstName": "Jane",
"lastName": "Doe",
"address": {
"addressLine1": "1 Example Street",
"city": "Amsterdam",
"postalCode": "1011AB",
"country": "NL"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
partyType: 'INDIVIDUAL',
externalId: 'user-12345',
firstName: 'Jane',
lastName: 'Doe',
address: {
addressLine1: '1 Example Street',
city: 'Amsterdam',
postalCode: '1011AB',
country: 'NL'
}
})
};
fetch('https://api.venlyfinance.com/v1/parties', 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.venlyfinance.com/v1/parties",
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([
'partyType' => 'INDIVIDUAL',
'externalId' => 'user-12345',
'firstName' => 'Jane',
'lastName' => 'Doe',
'address' => [
'addressLine1' => '1 Example Street',
'city' => 'Amsterdam',
'postalCode' => '1011AB',
'country' => 'NL'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.venlyfinance.com/v1/parties"
payload := strings.NewReader("{\n \"partyType\": \"INDIVIDUAL\",\n \"externalId\": \"user-12345\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"address\": {\n \"addressLine1\": \"1 Example Street\",\n \"city\": \"Amsterdam\",\n \"postalCode\": \"1011AB\",\n \"country\": \"NL\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.venlyfinance.com/v1/parties")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"partyType\": \"INDIVIDUAL\",\n \"externalId\": \"user-12345\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"address\": {\n \"addressLine1\": \"1 Example Street\",\n \"city\": \"Amsterdam\",\n \"postalCode\": \"1011AB\",\n \"country\": \"NL\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.venlyfinance.com/v1/parties")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"partyType\": \"INDIVIDUAL\",\n \"externalId\": \"user-12345\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"address\": {\n \"addressLine1\": \"1 Example Street\",\n \"city\": \"Amsterdam\",\n \"postalCode\": \"1011AB\",\n \"country\": \"NL\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"result": {
"id": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22",
"externalId": "user-12345",
"partyType": "INDIVIDUAL",
"status": "ACTIVE",
"firstName": "Jane",
"lastName": "Doe",
"address": {
"addressLine1": "1 Example Street",
"city": "Amsterdam",
"postalCode": "1011AB",
"country": "NL"
},
"createdAt": "2026-01-15T09:30:00Z",
"updatedAt": "2026-01-15T09:30:00Z",
"version": 0
}
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
]
}{
"success": false,
"errors": [
{
"code": "unauthenticated",
"message": "Please authenticate to perform this action."
}
]
}{
"success": false,
"errors": [
{
"code": "forbidden",
"message": "You do not have permission to access this resource."
}
]
}{
"success": false,
"errors": [
{
"code": "concurrent-modification",
"message": "This request has been modified by another user. Please refresh and try again."
}
]
}{
"success": false,
"errors": [
{
"code": "internal-error",
"message": "An unexpected error occurred. Please try again later."
}
]
}Create a party
Onboard an individual or organisation — the root entity that holds accounts.
curl --request POST \
--url https://api.venlyfinance.com/v1/parties \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"partyType": "INDIVIDUAL",
"externalId": "user-12345",
"firstName": "Jane",
"lastName": "Doe",
"address": {
"addressLine1": "1 Example Street",
"city": "Amsterdam",
"postalCode": "1011AB",
"country": "NL"
}
}
'import requests
url = "https://api.venlyfinance.com/v1/parties"
payload = {
"partyType": "INDIVIDUAL",
"externalId": "user-12345",
"firstName": "Jane",
"lastName": "Doe",
"address": {
"addressLine1": "1 Example Street",
"city": "Amsterdam",
"postalCode": "1011AB",
"country": "NL"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
partyType: 'INDIVIDUAL',
externalId: 'user-12345',
firstName: 'Jane',
lastName: 'Doe',
address: {
addressLine1: '1 Example Street',
city: 'Amsterdam',
postalCode: '1011AB',
country: 'NL'
}
})
};
fetch('https://api.venlyfinance.com/v1/parties', 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.venlyfinance.com/v1/parties",
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([
'partyType' => 'INDIVIDUAL',
'externalId' => 'user-12345',
'firstName' => 'Jane',
'lastName' => 'Doe',
'address' => [
'addressLine1' => '1 Example Street',
'city' => 'Amsterdam',
'postalCode' => '1011AB',
'country' => 'NL'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.venlyfinance.com/v1/parties"
payload := strings.NewReader("{\n \"partyType\": \"INDIVIDUAL\",\n \"externalId\": \"user-12345\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"address\": {\n \"addressLine1\": \"1 Example Street\",\n \"city\": \"Amsterdam\",\n \"postalCode\": \"1011AB\",\n \"country\": \"NL\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.venlyfinance.com/v1/parties")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"partyType\": \"INDIVIDUAL\",\n \"externalId\": \"user-12345\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"address\": {\n \"addressLine1\": \"1 Example Street\",\n \"city\": \"Amsterdam\",\n \"postalCode\": \"1011AB\",\n \"country\": \"NL\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.venlyfinance.com/v1/parties")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"partyType\": \"INDIVIDUAL\",\n \"externalId\": \"user-12345\",\n \"firstName\": \"Jane\",\n \"lastName\": \"Doe\",\n \"address\": {\n \"addressLine1\": \"1 Example Street\",\n \"city\": \"Amsterdam\",\n \"postalCode\": \"1011AB\",\n \"country\": \"NL\"\n }\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"result": {
"id": "7e3b9c2a-1f4d-4a8b-9c11-2d6e8f0a1b22",
"externalId": "user-12345",
"partyType": "INDIVIDUAL",
"status": "ACTIVE",
"firstName": "Jane",
"lastName": "Doe",
"address": {
"addressLine1": "1 Example Street",
"city": "Amsterdam",
"postalCode": "1011AB",
"country": "NL"
},
"createdAt": "2026-01-15T09:30:00Z",
"updatedAt": "2026-01-15T09:30:00Z",
"version": 0
}
}{
"success": false,
"errors": [
{
"code": "invalid-request",
"message": "The request contains invalid parameters."
}
]
}{
"success": false,
"errors": [
{
"code": "unauthenticated",
"message": "Please authenticate to perform this action."
}
]
}{
"success": false,
"errors": [
{
"code": "forbidden",
"message": "You do not have permission to access this resource."
}
]
}{
"success": false,
"errors": [
{
"code": "concurrent-modification",
"message": "This request has been modified by another user. Please refresh and try again."
}
]
}{
"success": false,
"errors": [
{
"code": "internal-error",
"message": "An unexpected error occurred. Please try again later."
}
]
}manage:parties — see Required scopes.
Creates a party. Use partyType: INDIVIDUAL with firstName/lastName, or ORGANISATION with name (and optional vatNumber). The returned id is what you pass when opening an account. Identity verification runs asynchronously after creation — track it on kycStatus (individuals) or kybStatus (organisations); see Account verification.Authorizations
OAuth2 client credentials flow. Token endpoints:
Body
Type of party
INDIVIDUAL, ORGANISATION Optional external reference ID
255Required for INDIVIDUAL parties
100Required for INDIVIDUAL parties
100Organisation name. Required for ORGANISATION parties
255VAT number. ORGANISATION parties only
50Contact email for the party. Optional, but supply a real one up front for an individual on a self-custody account.
When an account holder is onboarded to a partner their email is forwarded with the case. If the party
has none, a synthetic <case-id>@venlyfinance.com address is used so onboarding still proceeds — and
because the partner stores that email write-once, adding a real address later does not replace
the synthetic one. There is no way to correct it afterwards.
255Standardized address format used across all endpoints
Show child attributes
Show child attributes
Optional Sumsub share token, forwarding a verification you already completed in your own
Sumsub account. Accepted only when creating a party inline via
Create an account —
POST /parties rejects it with 400 sumsub-token-not-supported.
Requires partyType: INDIVIDUAL (KYC only), a SELF_CUSTODY company wallet type, and a
provisioned verification tenant. Never persisted and never returned. If the forward fails,
the entire account-creation transaction is rolled back — retry with a fresh token.
See Sumsub token sharing.
4096Was this page helpful?

