Update an account
curl --request PATCH \
--url https://api.sandbox.tracefinance.com/v1/accounts/{accountId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"owner": {
"type": "COMPANY",
"legalName": "Acme Ltda",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"industry": "SOFTWARE_DEVELOPMENT",
"expectedMonthlyVolume": "FROM_0_TO_50000",
"incorporateDate": "2018-05-12",
"isStartup": false,
"address": {
"addressLine1": "Rua das Flores, 100",
"addressLine2": "Suite 456",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postalCode": "01234-567"
}
}
}
'import requests
url = "https://api.sandbox.tracefinance.com/v1/accounts/{accountId}"
payload = { "owner": {
"type": "COMPANY",
"legalName": "Acme Ltda",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"industry": "SOFTWARE_DEVELOPMENT",
"expectedMonthlyVolume": "FROM_0_TO_50000",
"incorporateDate": "2018-05-12",
"isStartup": False,
"address": {
"addressLine1": "Rua das Flores, 100",
"addressLine2": "Suite 456",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postalCode": "01234-567"
}
} }
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
owner: {
type: 'COMPANY',
legalName: 'Acme Ltda',
taxId: {value: '11222333000181', type: 'CNPJ'},
industry: 'SOFTWARE_DEVELOPMENT',
expectedMonthlyVolume: 'FROM_0_TO_50000',
incorporateDate: '2018-05-12',
isStartup: false,
address: {
addressLine1: 'Rua das Flores, 100',
addressLine2: 'Suite 456',
city: 'São Paulo',
state: 'SP',
country: 'BR',
postalCode: '01234-567'
}
}
})
};
fetch('https://api.sandbox.tracefinance.com/v1/accounts/{accountId}', 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.sandbox.tracefinance.com/v1/accounts/{accountId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'owner' => [
'type' => 'COMPANY',
'legalName' => 'Acme Ltda',
'taxId' => [
'value' => '11222333000181',
'type' => 'CNPJ'
],
'industry' => 'SOFTWARE_DEVELOPMENT',
'expectedMonthlyVolume' => 'FROM_0_TO_50000',
'incorporateDate' => '2018-05-12',
'isStartup' => false,
'address' => [
'addressLine1' => 'Rua das Flores, 100',
'addressLine2' => 'Suite 456',
'city' => 'São Paulo',
'state' => 'SP',
'country' => 'BR',
'postalCode' => '01234-567'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Idempotency-Key: <x-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.sandbox.tracefinance.com/v1/accounts/{accountId}"
payload := strings.NewReader("{\n \"owner\": {\n \"type\": \"COMPANY\",\n \"legalName\": \"Acme Ltda\",\n \"taxId\": {\n \"value\": \"11222333000181\",\n \"type\": \"CNPJ\"\n },\n \"industry\": \"SOFTWARE_DEVELOPMENT\",\n \"expectedMonthlyVolume\": \"FROM_0_TO_50000\",\n \"incorporateDate\": \"2018-05-12\",\n \"isStartup\": false,\n \"address\": {\n \"addressLine1\": \"Rua das Flores, 100\",\n \"addressLine2\": \"Suite 456\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"postalCode\": \"01234-567\"\n }\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-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.patch("https://api.sandbox.tracefinance.com/v1/accounts/{accountId}")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"owner\": {\n \"type\": \"COMPANY\",\n \"legalName\": \"Acme Ltda\",\n \"taxId\": {\n \"value\": \"11222333000181\",\n \"type\": \"CNPJ\"\n },\n \"industry\": \"SOFTWARE_DEVELOPMENT\",\n \"expectedMonthlyVolume\": \"FROM_0_TO_50000\",\n \"incorporateDate\": \"2018-05-12\",\n \"isStartup\": false,\n \"address\": {\n \"addressLine1\": \"Rua das Flores, 100\",\n \"addressLine2\": \"Suite 456\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"postalCode\": \"01234-567\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.tracefinance.com/v1/accounts/{accountId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"owner\": {\n \"type\": \"COMPANY\",\n \"legalName\": \"Acme Ltda\",\n \"taxId\": {\n \"value\": \"11222333000181\",\n \"type\": \"CNPJ\"\n },\n \"industry\": \"SOFTWARE_DEVELOPMENT\",\n \"expectedMonthlyVolume\": \"FROM_0_TO_50000\",\n \"incorporateDate\": \"2018-05-12\",\n \"isStartup\": false,\n \"address\": {\n \"addressLine1\": \"Rua das Flores, 100\",\n \"addressLine2\": \"Suite 456\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"postalCode\": \"01234-567\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
"customer": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
},
"owner": {
"type": "COMPANY",
"legalName": "Acme Ltda",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"industry": "SOFTWARE_DEVELOPMENT",
"expectedMonthlyVolume": "FROM_0_TO_50000",
"address": {
"addressLine1": "Rua das Flores, 100",
"city": "São Paulo",
"country": "BR",
"postalCode": "01234-567",
"addressLine2": "Suite 456",
"state": "SP"
},
"ubos": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "João Silva",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"address": {
"addressLine1": "Rua das Flores, 100",
"city": "São Paulo",
"country": "BR",
"postalCode": "01234-567",
"addressLine2": "Suite 456",
"state": "SP"
},
"phone": "5511999999999",
"email": "joao.silva@example.com",
"isLegalRepresentative": false,
"currentState": {
"status": "PENDING",
"createdAt": "2026-01-15T10:30:00Z",
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
},
"ownershipPercentage": 50
}
]
},
"assets": [
{
"currency": "BRL",
"allowsVirtualAccounts": false,
"status": "ONBOARDING"
}
],
"requirements": {
"currentlyDue": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"pendingVerification": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"errors": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"satisfied": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
]
},
"tags": [
{
"key": "psp",
"value": "Amazon"
},
{
"key": null,
"value": "hidden"
},
{
"key": "compliance-tier",
"value": "high"
}
],
"currentState": {
"status": "ACTION_REQUIRED",
"createdAt": "2026-01-15T10:30:00Z",
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
},
"states": [
{
"status": "ACTION_REQUIRED",
"createdAt": "2026-01-15T10:30:00Z",
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"sourceAccountId": null
}
Update an account
Replace the owner profile and asset selection for an account that has not been submitted for review yet.
PATCH
/
v1
/
accounts
/
{accountId}
Update an account
curl --request PATCH \
--url https://api.sandbox.tracefinance.com/v1/accounts/{accountId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: <x-idempotency-key>' \
--data '
{
"owner": {
"type": "COMPANY",
"legalName": "Acme Ltda",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"industry": "SOFTWARE_DEVELOPMENT",
"expectedMonthlyVolume": "FROM_0_TO_50000",
"incorporateDate": "2018-05-12",
"isStartup": false,
"address": {
"addressLine1": "Rua das Flores, 100",
"addressLine2": "Suite 456",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postalCode": "01234-567"
}
}
}
'import requests
url = "https://api.sandbox.tracefinance.com/v1/accounts/{accountId}"
payload = { "owner": {
"type": "COMPANY",
"legalName": "Acme Ltda",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"industry": "SOFTWARE_DEVELOPMENT",
"expectedMonthlyVolume": "FROM_0_TO_50000",
"incorporateDate": "2018-05-12",
"isStartup": False,
"address": {
"addressLine1": "Rua das Flores, 100",
"addressLine2": "Suite 456",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postalCode": "01234-567"
}
} }
headers = {
"X-Idempotency-Key": "<x-idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {
'X-Idempotency-Key': '<x-idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
owner: {
type: 'COMPANY',
legalName: 'Acme Ltda',
taxId: {value: '11222333000181', type: 'CNPJ'},
industry: 'SOFTWARE_DEVELOPMENT',
expectedMonthlyVolume: 'FROM_0_TO_50000',
incorporateDate: '2018-05-12',
isStartup: false,
address: {
addressLine1: 'Rua das Flores, 100',
addressLine2: 'Suite 456',
city: 'São Paulo',
state: 'SP',
country: 'BR',
postalCode: '01234-567'
}
}
})
};
fetch('https://api.sandbox.tracefinance.com/v1/accounts/{accountId}', 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.sandbox.tracefinance.com/v1/accounts/{accountId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'owner' => [
'type' => 'COMPANY',
'legalName' => 'Acme Ltda',
'taxId' => [
'value' => '11222333000181',
'type' => 'CNPJ'
],
'industry' => 'SOFTWARE_DEVELOPMENT',
'expectedMonthlyVolume' => 'FROM_0_TO_50000',
'incorporateDate' => '2018-05-12',
'isStartup' => false,
'address' => [
'addressLine1' => 'Rua das Flores, 100',
'addressLine2' => 'Suite 456',
'city' => 'São Paulo',
'state' => 'SP',
'country' => 'BR',
'postalCode' => '01234-567'
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Idempotency-Key: <x-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.sandbox.tracefinance.com/v1/accounts/{accountId}"
payload := strings.NewReader("{\n \"owner\": {\n \"type\": \"COMPANY\",\n \"legalName\": \"Acme Ltda\",\n \"taxId\": {\n \"value\": \"11222333000181\",\n \"type\": \"CNPJ\"\n },\n \"industry\": \"SOFTWARE_DEVELOPMENT\",\n \"expectedMonthlyVolume\": \"FROM_0_TO_50000\",\n \"incorporateDate\": \"2018-05-12\",\n \"isStartup\": false,\n \"address\": {\n \"addressLine1\": \"Rua das Flores, 100\",\n \"addressLine2\": \"Suite 456\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"postalCode\": \"01234-567\"\n }\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("X-Idempotency-Key", "<x-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.patch("https://api.sandbox.tracefinance.com/v1/accounts/{accountId}")
.header("X-Idempotency-Key", "<x-idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"owner\": {\n \"type\": \"COMPANY\",\n \"legalName\": \"Acme Ltda\",\n \"taxId\": {\n \"value\": \"11222333000181\",\n \"type\": \"CNPJ\"\n },\n \"industry\": \"SOFTWARE_DEVELOPMENT\",\n \"expectedMonthlyVolume\": \"FROM_0_TO_50000\",\n \"incorporateDate\": \"2018-05-12\",\n \"isStartup\": false,\n \"address\": {\n \"addressLine1\": \"Rua das Flores, 100\",\n \"addressLine2\": \"Suite 456\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"postalCode\": \"01234-567\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.sandbox.tracefinance.com/v1/accounts/{accountId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["X-Idempotency-Key"] = '<x-idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"owner\": {\n \"type\": \"COMPANY\",\n \"legalName\": \"Acme Ltda\",\n \"taxId\": {\n \"value\": \"11222333000181\",\n \"type\": \"CNPJ\"\n },\n \"industry\": \"SOFTWARE_DEVELOPMENT\",\n \"expectedMonthlyVolume\": \"FROM_0_TO_50000\",\n \"incorporateDate\": \"2018-05-12\",\n \"isStartup\": false,\n \"address\": {\n \"addressLine1\": \"Rua das Flores, 100\",\n \"addressLine2\": \"Suite 456\",\n \"city\": \"São Paulo\",\n \"state\": \"SP\",\n \"country\": \"BR\",\n \"postalCode\": \"01234-567\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
"customer": {
"id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890"
},
"owner": {
"type": "COMPANY",
"legalName": "Acme Ltda",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"industry": "SOFTWARE_DEVELOPMENT",
"expectedMonthlyVolume": "FROM_0_TO_50000",
"address": {
"addressLine1": "Rua das Flores, 100",
"city": "São Paulo",
"country": "BR",
"postalCode": "01234-567",
"addressLine2": "Suite 456",
"state": "SP"
},
"ubos": [
{
"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"name": "João Silva",
"taxId": {
"value": "11222333000181",
"type": "CNPJ"
},
"address": {
"addressLine1": "Rua das Flores, 100",
"city": "São Paulo",
"country": "BR",
"postalCode": "01234-567",
"addressLine2": "Suite 456",
"state": "SP"
},
"phone": "5511999999999",
"email": "joao.silva@example.com",
"isLegalRepresentative": false,
"currentState": {
"status": "PENDING",
"createdAt": "2026-01-15T10:30:00Z",
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
},
"ownershipPercentage": 50
}
]
},
"assets": [
{
"currency": "BRL",
"allowsVirtualAccounts": false,
"status": "ONBOARDING"
}
],
"requirements": {
"currentlyDue": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"pendingVerification": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"errors": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"satisfied": [
{
"type": "ACCOUNT_DOCUMENT",
"documentType": "ARTICLES_OF_ASSOCIATION",
"documentSubType": "FRONT_SIDE",
"requiredMetadata": [
"country"
],
"metadata": {},
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
]
},
"tags": [
{
"key": "psp",
"value": "Amazon"
},
{
"key": null,
"value": "hidden"
},
{
"key": "compliance-tier",
"value": "high"
}
],
"currentState": {
"status": "ACTION_REQUIRED",
"createdAt": "2026-01-15T10:30:00Z",
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
},
"states": [
{
"status": "ACTION_REQUIRED",
"createdAt": "2026-01-15T10:30:00Z",
"reason": {
"code": "DOCUMENT_REJECTED",
"message": "Document is illegible",
"details": {}
}
}
],
"createdAt": "2026-01-15T10:30:00Z",
"updatedAt": "2026-01-15T10:30:00Z",
"sourceAccountId": null
}
Authorizations
JWT bearer token. Include as Authorization: Bearer <token>. See the Authentication guide for how to obtain one.
Headers
API version. Omit to use the default version.
Example:
"1"
Unique key to ensure idempotent request processing. Required on all POST, PUT, and PATCH requests.
Path Parameters
UUID of the account.
Body
application/json
Request body for updating an account. The supplied owner replaces the current owner profile; assets are not modifiable after creation.
The legal entity that owns the account. Discriminated by type.
- Company
- Individual
Show child attributes
Show child attributes
Response
Account updated.
Example:
"a1b2c3d4-5e6f-7890-abcd-ef1234567890"
Show child attributes
Show child attributes
The legal entity that owns the account. Discriminated by type.
- Company
- Individual
Show child attributes
Show child attributes
Assets enabled on the account, with the onboarding status of the underlying provider account.
Show child attributes
Show child attributes
Requirement buckets grouped by lifecycle stage.
Show child attributes
Show child attributes
System-managed labels attached to the account. Some tags propagate to operations executed against this account.
Show child attributes
Show child attributes
Example:
[ { "key": "psp", "value": "Amazon" }, { "key": null, "value": "hidden" }, { "key": "compliance-tier", "value": "high" } ]
A point-in-time state of the account.
Show child attributes
Show child attributes
Full state history of the account.
Show child attributes
Show child attributes
Example:
"2026-01-15T10:30:00Z"
Example:
"2026-01-15T10:30:00Z"
Parent account ID. Null for named accounts.
Example:
null
Was this page helpful?
⌘I