Entity accounts
curl --request GET \
--url http://api.gu1.ai/entities/{id}/accounts \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/accounts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/accounts', 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 => "http://api.gu1.ai/entities/{id}/accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/{id}/accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/accounts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/accounts")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyAPI Reference
Entity accounts
Register and manage financial accounts owned by a person or company entity.
GET
/
entities
/
{id}
/
accounts
Entity accounts
curl --request GET \
--url http://api.gu1.ai/entities/{id}/accounts \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/entities/{id}/accounts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/entities/{id}/accounts', 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 => "http://api.gu1.ai/entities/{id}/accounts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/entities/{id}/accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/entities/{id}/accounts")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/{id}/accounts")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_bodyOverview
Accounts are child resources of person and company entities. Use them to register multiple accounts per customer, including accounts in different currencies. Every account has a client-definedexternalId, an ISO 4217 currency, and at least one payment identifier. Account data is isolated to the current organization.
Endpoints
The same CRUD exists for three entity lookups, matching update by external ID andPATCH /entities/by-tax-id/{taxId}:
| Method | Path | Entity lookup |
|---|---|---|
GET POST | /entities/{id}/accounts | Gu1 UUID |
PATCH DELETE | /entities/{id}/accounts/{accountId} | Gu1 UUID |
GET POST | /entities/by-external-id/{externalId}/accounts | Your externalId (exact match) |
PATCH DELETE | /entities/by-external-id/{externalId}/accounts/{accountId} | Your externalId |
GET POST | /entities/by-tax-id/{taxId}/accounts | Tax ID, denormalized |
PATCH DELETE | /entities/by-tax-id/{taxId}/accounts/{accountId} | Tax ID, denormalized |
{accountId} is always the Gu1 account UUID from create/list.
Tax ID lookup ignores punctuation and letter case (CUIT 20-12345678-9 matches 20123456789). It uses the same alphanumeric key as org-level tax uniqueness (idx_entities_org_norm_tax_id). URL-encode the path segment if the value contains reserved characters.
Reading requires entities:read. Mutations require entities:edit with the legacy entities:write fallback.
Account fields
| Field | Type | Required | Description |
|---|---|---|---|
externalId | string | Yes | Account identifier in your system; unique within the organization |
currency | string | Yes | ISO 4217 code, such as USD, ARS, or BRL |
accountType | enum | No | Canonical account type; see the accepted values below |
status | string | No | active, inactive, frozen, or closed; default active |
countryCode | string | No | ISO 3166-1 alpha-2 country |
accountNumber | string | Conditional | Generic account number |
cbu | string | Conditional | 22-digit CBU |
cvu | string | Conditional | 22-digit CVU |
iban | string | Conditional | IBAN, up to 34 characters |
alias | string | Conditional | Account alias |
bankName | string | No | Bank or financial institution |
bankCode | string | No | Client-defined bank code |
isPrimary | boolean | No | Primary account for the entity and currency |
metadata | object | No | Client-specific additional data |
openedAt | string | No | ISO 8601 opening timestamp |
closedAt | string | No | ISO 8601 closing timestamp |
Accepted account types
accountType accepts only one of these values:
- Generic:
bank_account,personal,business,other - Bank deposits:
checking,savings,business_checking,business_savings,payroll,pension,money_market,fixed_deposit - Investment and custody:
investment,brokerage,custody,escrow - Payments and digital funds:
payment,wallet,virtual_account,prepaid,merchant - Credit:
credit,loan - Institutional operations:
correspondent,settlement,clearing,cash_management
bank_account when you know the account is held at a bank but do not know its product type, and use other only when no category represents it. An unknown enum value returns 400 VALIDATION_ERROR.
At least one of accountNumber, cbu, cvu, iban, or alias is required when creating an account.
Create example
curl -X POST "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/accounts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "account-usd-001",
"currency": "USD",
"accountType": "savings",
"accountNumber": "ACC-001",
"countryCode": "AR",
"isPrimary": true
}'
{
"success": true,
"account": {
"id": "77c2ca62-4528-4d2e-a424-ff7c0ee7ab18",
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"externalId": "account-usd-001",
"currency": "USD",
"accountType": "savings",
"status": "active",
"accountNumber": "ACC-001",
"isPrimary": true
}
}
externalId instead of the Gu1 UUID:
curl -X POST "https://api.gu1.ai/entities/by-external-id/merchant-99/accounts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "account-usd-001",
"currency": "USD",
"accountType": "savings",
"accountNumber": "ACC-001",
"isPrimary": true
}'
curl -X POST "https://api.gu1.ai/entities/by-tax-id/20-12345678-9/accounts" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"externalId": "account-ars-001",
"currency": "ARS",
"cbu": "0000003100000000000001"
}'
isPrimary: true removes the primary flag from other accounts of the same entity and currency.
Errors
| HTTP | Code | When |
|---|---|---|
400 | VALIDATION_ERROR | Input is invalid, accountType is outside the enum, or no payment identifier remains |
404 | NOT_FOUND | Entity or account does not exist in the current organization |
409 | CONFLICT | externalId already exists in the current organization |
Was this page helpful?