Create a custom field
curl --request POST \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields \
--header 'Content-Type: application/json' \
--data '
{
"label": "Centro de custo",
"type": "SELECT",
"slug": "centro-de-custo",
"location": [
"TRANSACTION"
],
"required": true,
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"description": "Centro de custo responsável pela despesa"
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields"
payload = {
"label": "Centro de custo",
"type": "SELECT",
"slug": "centro-de-custo",
"location": ["TRANSACTION"],
"required": True,
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"description": "Centro de custo responsável pela despesa"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
label: 'Centro de custo',
type: 'SELECT',
slug: 'centro-de-custo',
location: ['TRANSACTION'],
required: true,
values: [
{
value: 'marketing',
label: 'Marketing',
description: 'Campanhas e eventos',
status: 'ACTIVE'
}
],
mask: 'BRL',
description: 'Centro de custo responsável pela despesa'
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields', 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.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields",
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([
'label' => 'Centro de custo',
'type' => 'SELECT',
'slug' => 'centro-de-custo',
'location' => [
'TRANSACTION'
],
'required' => true,
'values' => [
[
'value' => 'marketing',
'label' => 'Marketing',
'description' => 'Campanhas e eventos',
'status' => 'ACTIVE'
]
],
'mask' => 'BRL',
'description' => 'Centro de custo responsável pela despesa'
]),
CURLOPT_HTTPHEADER => [
"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.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields"
payload := strings.NewReader("{\n \"label\": \"Centro de custo\",\n \"type\": \"SELECT\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"required\": true,\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"description\": \"Centro de custo responsável pela despesa\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Centro de custo\",\n \"type\": \"SELECT\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"required\": true,\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"description\": \"Centro de custo responsável pela despesa\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"Centro de custo\",\n \"type\": \"SELECT\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"required\": true,\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"description\": \"Centro de custo responsável pela despesa\"\n}"
response = http.request(request)
puts response.read_body{
"id": "9c4f0a2e-7b3d-4e8a-a1f5-2d6c8b0e4a71",
"status": "ACTIVE",
"realm": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
"organization": "0b8e7d6c-5a4f-4e3d-9c2b-1a0f9e8d7c6b",
"label": "Centro de custo",
"slug": "centro-de-custo",
"type": "SELECT",
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE",
"_id": "68d3f1a2c4b5e6f7a8b9c0d1"
}
],
"location": [
"TRANSACTION"
],
"mask": "BRL",
"required": true,
"description": "Centro de custo responsável pela despesa",
"createdBy": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
"updatedBy": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
"createdAt": "2026-09-02T14:21:05.318Z",
"updatedAt": "2026-09-18T09:07:44.902Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "CUSTOM_FIELD_CONFLICT_ERROR",
"origin": "IDENTITY",
"message": "Custom field already exists"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "IDENTITY",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "label",
"message": "Invalid input: expected string, received undefined",
"code": "LABEL_REQUIRED"
}
]
}Create a custom field
Creates a custom-field definition for the organization.
POST
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
custom-fields
Create a custom field
curl --request POST \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields \
--header 'Content-Type: application/json' \
--data '
{
"label": "Centro de custo",
"type": "SELECT",
"slug": "centro-de-custo",
"location": [
"TRANSACTION"
],
"required": true,
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"description": "Centro de custo responsável pela despesa"
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields"
payload = {
"label": "Centro de custo",
"type": "SELECT",
"slug": "centro-de-custo",
"location": ["TRANSACTION"],
"required": True,
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"description": "Centro de custo responsável pela despesa"
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
label: 'Centro de custo',
type: 'SELECT',
slug: 'centro-de-custo',
location: ['TRANSACTION'],
required: true,
values: [
{
value: 'marketing',
label: 'Marketing',
description: 'Campanhas e eventos',
status: 'ACTIVE'
}
],
mask: 'BRL',
description: 'Centro de custo responsável pela despesa'
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields', 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.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields",
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([
'label' => 'Centro de custo',
'type' => 'SELECT',
'slug' => 'centro-de-custo',
'location' => [
'TRANSACTION'
],
'required' => true,
'values' => [
[
'value' => 'marketing',
'label' => 'Marketing',
'description' => 'Campanhas e eventos',
'status' => 'ACTIVE'
]
],
'mask' => 'BRL',
'description' => 'Centro de custo responsável pela despesa'
]),
CURLOPT_HTTPHEADER => [
"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.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields"
payload := strings.NewReader("{\n \"label\": \"Centro de custo\",\n \"type\": \"SELECT\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"required\": true,\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"description\": \"Centro de custo responsável pela despesa\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Centro de custo\",\n \"type\": \"SELECT\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"required\": true,\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"description\": \"Centro de custo responsável pela despesa\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"Centro de custo\",\n \"type\": \"SELECT\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"required\": true,\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"description\": \"Centro de custo responsável pela despesa\"\n}"
response = http.request(request)
puts response.read_body{
"id": "9c4f0a2e-7b3d-4e8a-a1f5-2d6c8b0e4a71",
"status": "ACTIVE",
"realm": "6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c",
"organization": "0b8e7d6c-5a4f-4e3d-9c2b-1a0f9e8d7c6b",
"label": "Centro de custo",
"slug": "centro-de-custo",
"type": "SELECT",
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE",
"_id": "68d3f1a2c4b5e6f7a8b9c0d1"
}
],
"location": [
"TRANSACTION"
],
"mask": "BRL",
"required": true,
"description": "Centro de custo responsável pela despesa",
"createdBy": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
"updatedBy": "3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b",
"createdAt": "2026-09-02T14:21:05.318Z",
"updatedAt": "2026-09-18T09:07:44.902Z"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "CUSTOM_FIELD_CONFLICT_ERROR",
"origin": "IDENTITY",
"message": "Custom field already exists"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "BAD_REQUEST",
"origin": "IDENTITY",
"message": "Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields.",
"fields": [
{
"field": "label",
"message": "Invalid input: expected string, received undefined",
"code": "LABEL_REQUIRED"
}
]
}slug and type are immutable afterwards. SELECT and MULTI_SELECT fields need at least one option in values; NUMBER fields need a mask. The new field is created ACTIVE.Path Parameters
ID of your realm.
Format: UUID
ID of your organization.
Format: UUID
Body
application/json
Human-readable name shown wherever the field is rendered.
Required string length:
1 - 50Example:
"Centro de custo"
Value type the field accepts. SELECT and MULTI_SELECT need at least one option in values; NUMBER needs a mask. Immutable after creation.
Available options:
TEXT, NUMBER, DATE, BOOLEAN, SELECT, MULTI_SELECT, CUSTOMER, FILE, MULTI_FILE Example:
"SELECT"
Stable key of the field: the property name under which its value is stored in the customFields map of the entities in location. Lowercase letters, digits and single hyphens, 2–80 characters. Unique per organization and immutable after creation.
Required string length:
2 - 80Pattern:
^[a-z0-9]+(?:-[a-z0-9]+)*$Example:
"centro-de-custo"
Entities the field is attached to. A value is accepted — and, when required is true, demanded — on each listed entity.
Example: ["TRANSACTION","CARD"]
Available options:
TRANSACTION, CARD, WALLET, CUSTOMER, TRIP, TRAVEL_PASSENGER, USER, VEHICLE Whether a value must be provided on every entity listed in location.
Example:
true
Selectable options of a SELECT / MULTI_SELECT field (at least one). An option's value must be unique. Options are append-only after creation — see the update endpoint.
Show child attributes
Show child attributes
Display format of a NUMBER field: NONE (plain number), BRL (Brazilian reais), USD (US dollars) or PERCENT. Required when type is NUMBER.
Available options:
NONE, BRL, USD, PERCENT Example:
"BRL"
Optional help text shown alongside the field.
Maximum string length:
512Example:
"Centro de custo responsável pela despesa"
Response
Successful response
A custom-field definition.
Unique identifier of the custom field.
Example:
"9c4f0a2e-7b3d-4e8a-a1f5-2d6c8b0e4a71"
ACTIVE fields are rendered and validated on the entities listed in location. DEACTIVATED fields are hidden from new entries while their stored values stay readable. Changed only through the activate and deactivate endpoints.
Available options:
ACTIVE, DEACTIVATED Example:
"ACTIVE"
Realm the field belongs to.
Example:
"6f1d2c3b-4a5e-4f60-9b7c-8d9e0f1a2b3c"
Organization the field belongs to.
Example:
"0b8e7d6c-5a4f-4e3d-9c2b-1a0f9e8d7c6b"
Human-readable name shown wherever the field is rendered.
Example:
"Centro de custo"
Stable key of the field: the property name under which its value is stored in the customFields map of transactions, cards, wallets, users and the other entities in location. Unique per organization and immutable after creation.
Example:
"centro-de-custo"
Value type the field accepts. Immutable after creation.
Available options:
TEXT, NUMBER, DATE, BOOLEAN, SELECT, MULTI_SELECT, CUSTOMER, FILE, MULTI_FILE Example:
"SELECT"
Selectable options of a SELECT / MULTI_SELECT field. Normally empty for the other types.
Show child attributes
Show child attributes
Entities the field is attached to. A value is accepted — and, when required is true, demanded — on each listed entity.
Example: ["TRANSACTION","CARD"]
Available options:
TRANSACTION, CARD, WALLET, CUSTOMER, TRIP, TRAVEL_PASSENGER, USER, VEHICLE Display format of a NUMBER field: NONE (plain number), BRL (Brazilian reais), USD (US dollars) or PERCENT. Empty for the other types.
Example:
"BRL"
Whether a value must be provided on every entity listed in location.
Example:
true
Optional help text shown alongside the field. Empty when none was given.
Example:
"Centro de custo responsável pela despesa"
ID of the user who created the field.
Example:
"3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b"
ID of the user who last changed the field.
Example:
"3e2d1c0b-9a8f-4e7d-8c6b-5a4f3e2d1c0b"
When the field was created (ISO 8601, UTC).
Example:
"2026-09-02T14:21:05.318Z"
When the field was last changed (ISO 8601, UTC).
Example:
"2026-09-18T09:07:44.902Z"