Create account holder
curl --request POST \
--url https://api.augustus.com/v1/account_holders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"account_program_id": "550e8400-e29b-41d4-a716-446655440002",
"beneficiary_data": {
"legal_name": "Jordan Rivera",
"residential_address": {
"line_1": "548 Market St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94103",
"country_code": "US",
"line_2": "Apartment 4B"
},
"date_of_birth": "1990-01-15",
"identification": {
"type": "ssn",
"value": "123-45-6789"
},
"country_of_citizenship": "US"
},
"metadata": {
"invoice_id": "INV-2026-0042"
}
}
'import requests
url = "https://api.augustus.com/v1/account_holders"
payload = {
"account_program_id": "550e8400-e29b-41d4-a716-446655440002",
"beneficiary_data": {
"legal_name": "Jordan Rivera",
"residential_address": {
"line_1": "548 Market St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94103",
"country_code": "US",
"line_2": "Apartment 4B"
},
"date_of_birth": "1990-01-15",
"identification": {
"type": "ssn",
"value": "123-45-6789"
},
"country_of_citizenship": "US"
},
"metadata": { "invoice_id": "INV-2026-0042" }
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
account_program_id: '550e8400-e29b-41d4-a716-446655440002',
beneficiary_data: {
legal_name: 'Jordan Rivera',
residential_address: {
line_1: '548 Market St',
city: 'San Francisco',
state: 'CA',
postal_code: '94103',
country_code: 'US',
line_2: 'Apartment 4B'
},
date_of_birth: '1990-01-15',
identification: {type: 'ssn', value: '123-45-6789'},
country_of_citizenship: 'US'
},
metadata: {invoice_id: 'INV-2026-0042'}
})
};
fetch('https://api.augustus.com/v1/account_holders', 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.augustus.com/v1/account_holders",
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([
'account_program_id' => '550e8400-e29b-41d4-a716-446655440002',
'beneficiary_data' => [
'legal_name' => 'Jordan Rivera',
'residential_address' => [
'line_1' => '548 Market St',
'city' => 'San Francisco',
'state' => 'CA',
'postal_code' => '94103',
'country_code' => 'US',
'line_2' => 'Apartment 4B'
],
'date_of_birth' => '1990-01-15',
'identification' => [
'type' => 'ssn',
'value' => '123-45-6789'
],
'country_of_citizenship' => 'US'
],
'metadata' => [
'invoice_id' => 'INV-2026-0042'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-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.augustus.com/v1/account_holders"
payload := strings.NewReader("{\n \"account_program_id\": \"550e8400-e29b-41d4-a716-446655440002\",\n \"beneficiary_data\": {\n \"legal_name\": \"Jordan Rivera\",\n \"residential_address\": {\n \"line_1\": \"548 Market St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94103\",\n \"country_code\": \"US\",\n \"line_2\": \"Apartment 4B\"\n },\n \"date_of_birth\": \"1990-01-15\",\n \"identification\": {\n \"type\": \"ssn\",\n \"value\": \"123-45-6789\"\n },\n \"country_of_citizenship\": \"US\"\n },\n \"metadata\": {\n \"invoice_id\": \"INV-2026-0042\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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.augustus.com/v1/account_holders")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"account_program_id\": \"550e8400-e29b-41d4-a716-446655440002\",\n \"beneficiary_data\": {\n \"legal_name\": \"Jordan Rivera\",\n \"residential_address\": {\n \"line_1\": \"548 Market St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94103\",\n \"country_code\": \"US\",\n \"line_2\": \"Apartment 4B\"\n },\n \"date_of_birth\": \"1990-01-15\",\n \"identification\": {\n \"type\": \"ssn\",\n \"value\": \"123-45-6789\"\n },\n \"country_of_citizenship\": \"US\"\n },\n \"metadata\": {\n \"invoice_id\": \"INV-2026-0042\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.augustus.com/v1/account_holders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"account_program_id\": \"550e8400-e29b-41d4-a716-446655440002\",\n \"beneficiary_data\": {\n \"legal_name\": \"Jordan Rivera\",\n \"residential_address\": {\n \"line_1\": \"548 Market St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94103\",\n \"country_code\": \"US\",\n \"line_2\": \"Apartment 4B\"\n },\n \"date_of_birth\": \"1990-01-15\",\n \"identification\": {\n \"type\": \"ssn\",\n \"value\": \"123-45-6789\"\n },\n \"country_of_citizenship\": \"US\"\n },\n \"metadata\": {\n \"invoice_id\": \"INV-2026-0042\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "68e0a1b2c3d4e5f60718293a",
"type": "account_holder",
"holder_type": "natural_person",
"status": "pending",
"beneficiary_data": {
"legal_name": "Jordan Rivera",
"residential_address": {
"line_1": "548 Market St",
"line_2": "Apartment 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94103",
"country_code": "US"
},
"date_of_birth": "1990-01-15",
"identification": {
"type": "ssn",
"value": "123-45-6789"
},
"country_of_citizenship": "US"
},
"metadata": {
"invoice_id": "INV-2026-0042"
},
"created_at": "2026-01-15T10:30:00Z"
}Account Holders
Create account holder
Creates a new account holder and starts asynchronous processing.
POST
/
v1
/
account_holders
Create account holder
curl --request POST \
--url https://api.augustus.com/v1/account_holders \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"account_program_id": "550e8400-e29b-41d4-a716-446655440002",
"beneficiary_data": {
"legal_name": "Jordan Rivera",
"residential_address": {
"line_1": "548 Market St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94103",
"country_code": "US",
"line_2": "Apartment 4B"
},
"date_of_birth": "1990-01-15",
"identification": {
"type": "ssn",
"value": "123-45-6789"
},
"country_of_citizenship": "US"
},
"metadata": {
"invoice_id": "INV-2026-0042"
}
}
'import requests
url = "https://api.augustus.com/v1/account_holders"
payload = {
"account_program_id": "550e8400-e29b-41d4-a716-446655440002",
"beneficiary_data": {
"legal_name": "Jordan Rivera",
"residential_address": {
"line_1": "548 Market St",
"city": "San Francisco",
"state": "CA",
"postal_code": "94103",
"country_code": "US",
"line_2": "Apartment 4B"
},
"date_of_birth": "1990-01-15",
"identification": {
"type": "ssn",
"value": "123-45-6789"
},
"country_of_citizenship": "US"
},
"metadata": { "invoice_id": "INV-2026-0042" }
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
account_program_id: '550e8400-e29b-41d4-a716-446655440002',
beneficiary_data: {
legal_name: 'Jordan Rivera',
residential_address: {
line_1: '548 Market St',
city: 'San Francisco',
state: 'CA',
postal_code: '94103',
country_code: 'US',
line_2: 'Apartment 4B'
},
date_of_birth: '1990-01-15',
identification: {type: 'ssn', value: '123-45-6789'},
country_of_citizenship: 'US'
},
metadata: {invoice_id: 'INV-2026-0042'}
})
};
fetch('https://api.augustus.com/v1/account_holders', 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.augustus.com/v1/account_holders",
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([
'account_program_id' => '550e8400-e29b-41d4-a716-446655440002',
'beneficiary_data' => [
'legal_name' => 'Jordan Rivera',
'residential_address' => [
'line_1' => '548 Market St',
'city' => 'San Francisco',
'state' => 'CA',
'postal_code' => '94103',
'country_code' => 'US',
'line_2' => 'Apartment 4B'
],
'date_of_birth' => '1990-01-15',
'identification' => [
'type' => 'ssn',
'value' => '123-45-6789'
],
'country_of_citizenship' => 'US'
],
'metadata' => [
'invoice_id' => 'INV-2026-0042'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-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.augustus.com/v1/account_holders"
payload := strings.NewReader("{\n \"account_program_id\": \"550e8400-e29b-41d4-a716-446655440002\",\n \"beneficiary_data\": {\n \"legal_name\": \"Jordan Rivera\",\n \"residential_address\": {\n \"line_1\": \"548 Market St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94103\",\n \"country_code\": \"US\",\n \"line_2\": \"Apartment 4B\"\n },\n \"date_of_birth\": \"1990-01-15\",\n \"identification\": {\n \"type\": \"ssn\",\n \"value\": \"123-45-6789\"\n },\n \"country_of_citizenship\": \"US\"\n },\n \"metadata\": {\n \"invoice_id\": \"INV-2026-0042\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
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.augustus.com/v1/account_holders")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"account_program_id\": \"550e8400-e29b-41d4-a716-446655440002\",\n \"beneficiary_data\": {\n \"legal_name\": \"Jordan Rivera\",\n \"residential_address\": {\n \"line_1\": \"548 Market St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94103\",\n \"country_code\": \"US\",\n \"line_2\": \"Apartment 4B\"\n },\n \"date_of_birth\": \"1990-01-15\",\n \"identification\": {\n \"type\": \"ssn\",\n \"value\": \"123-45-6789\"\n },\n \"country_of_citizenship\": \"US\"\n },\n \"metadata\": {\n \"invoice_id\": \"INV-2026-0042\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.augustus.com/v1/account_holders")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"account_program_id\": \"550e8400-e29b-41d4-a716-446655440002\",\n \"beneficiary_data\": {\n \"legal_name\": \"Jordan Rivera\",\n \"residential_address\": {\n \"line_1\": \"548 Market St\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94103\",\n \"country_code\": \"US\",\n \"line_2\": \"Apartment 4B\"\n },\n \"date_of_birth\": \"1990-01-15\",\n \"identification\": {\n \"type\": \"ssn\",\n \"value\": \"123-45-6789\"\n },\n \"country_of_citizenship\": \"US\"\n },\n \"metadata\": {\n \"invoice_id\": \"INV-2026-0042\"\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "68e0a1b2c3d4e5f60718293a",
"type": "account_holder",
"holder_type": "natural_person",
"status": "pending",
"beneficiary_data": {
"legal_name": "Jordan Rivera",
"residential_address": {
"line_1": "548 Market St",
"line_2": "Apartment 4B",
"city": "San Francisco",
"state": "CA",
"postal_code": "94103",
"country_code": "US"
},
"date_of_birth": "1990-01-15",
"identification": {
"type": "ssn",
"value": "123-45-6789"
},
"country_of_citizenship": "US"
},
"metadata": {
"invoice_id": "INV-2026-0042"
},
"created_at": "2026-01-15T10:30:00Z"
}Authorizations
Bearer token for authentication with Augustus Banking API
Headers
Idempotency key for safe retries. Reusing a key with an identical request body returns the cached response. Reusing a key with a different body returns 409.
Body
application/json
Account holder parameters
ID of the account program to create the account holder under.
Example:
"550e8400-e29b-41d4-a716-446655440002"
Type of the account holder.
Available options:
natural_person, business Personal information of the account holder. The shape you send follows country_of_citizenship: use US individual when it is US, and Non-US individual for any other country. Use Business when holder_type is business.
- US individual
- Non-US individual
- Business
Show child attributes
Show child attributes
Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
Show child attributes
Show child attributes
Example:
{ "invoice_id": "INV-2026-0042" }
Response
200 - application/json
Account holder created successfully
Unique identifier of the account holder.
Pattern:
^[0-9a-fA-F]{24}$Example:
"68e0a1b2c3d4e5f60718293a"
Resource type discriminator.
Available options:
account_holder Type of the account holder.
Available options:
natural_person, business Current account holder status.
Available options:
pending, active, closed Beneficiary details used to create this account holder. Which shape is returned follows country_of_citizenship: US individual when it is US, Non-US individual for any other country, Business when holder_type is business.
- US individual
- Non-US individual
- Business
Show child attributes
Show child attributes
Set of up to 50 key-value string pairs you can attach to store structured information, such as correlating this resource with an object in your own system. Keys may be up to 40 characters and values up to 500 characters.
Show child attributes
Show child attributes
Example:
{ "invoice_id": "INV-2026-0042" }
ISO 8601 UTC timestamp when the account holder was created.
Example:
"2026-01-15T10:30:00Z"
Was this page helpful?