Update a custom field
curl --request PUT \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId} \
--header 'Content-Type: application/json' \
--data '
{
"label": "Centro de custo",
"slug": "centro-de-custo",
"location": [
"TRANSACTION"
],
"type": "SELECT",
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"required": true,
"description": "Centro de custo responsável pela despesa"
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId}"
payload = {
"label": "Centro de custo",
"slug": "centro-de-custo",
"location": ["TRANSACTION"],
"type": "SELECT",
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"required": True,
"description": "Centro de custo responsável pela despesa"
}
headers = {"Content-Type": "application/json"}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
label: 'Centro de custo',
slug: 'centro-de-custo',
location: ['TRANSACTION'],
type: 'SELECT',
values: [
{
value: 'marketing',
label: 'Marketing',
description: 'Campanhas e eventos',
status: 'ACTIVE'
}
],
mask: 'BRL',
required: true,
description: 'Centro de custo responsável pela despesa'
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId}', 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/{customFieldId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'label' => 'Centro de custo',
'slug' => 'centro-de-custo',
'location' => [
'TRANSACTION'
],
'type' => 'SELECT',
'values' => [
[
'value' => 'marketing',
'label' => 'Marketing',
'description' => 'Campanhas e eventos',
'status' => 'ACTIVE'
]
],
'mask' => 'BRL',
'required' => true,
'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/{customFieldId}"
payload := strings.NewReader("{\n \"label\": \"Centro de custo\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"type\": \"SELECT\",\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"required\": true,\n \"description\": \"Centro de custo responsável pela despesa\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId}")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Centro de custo\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"type\": \"SELECT\",\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"required\": true,\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/{customFieldId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"Centro de custo\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"type\": \"SELECT\",\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"required\": true,\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_NOT_FOUND",
"origin": "IDENTITY",
"message": "Custom field not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "CUSTOM_FIELD_CONCURRENT_UPDATE",
"origin": "IDENTITY",
"message": "Custom field was modified by another request — reload it and try again"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "CUSTOM_FIELD_SLUG_IMMUTABLE",
"origin": "IDENTITY",
"message": "Custom field slug cannot be changed after creation"
}Update a custom field
Updates a custom-field definition. Only the properties you send change.
PUT
/
realms
/
{realmId}
/
organizations
/
{organizationId}
/
custom-fields
/
{customFieldId}
Update a custom field
curl --request PUT \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId} \
--header 'Content-Type: application/json' \
--data '
{
"label": "Centro de custo",
"slug": "centro-de-custo",
"location": [
"TRANSACTION"
],
"type": "SELECT",
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"required": true,
"description": "Centro de custo responsável pela despesa"
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId}"
payload = {
"label": "Centro de custo",
"slug": "centro-de-custo",
"location": ["TRANSACTION"],
"type": "SELECT",
"values": [
{
"value": "marketing",
"label": "Marketing",
"description": "Campanhas e eventos",
"status": "ACTIVE"
}
],
"mask": "BRL",
"required": True,
"description": "Centro de custo responsável pela despesa"
}
headers = {"Content-Type": "application/json"}
response = requests.put(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PUT',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
label: 'Centro de custo',
slug: 'centro-de-custo',
location: ['TRANSACTION'],
type: 'SELECT',
values: [
{
value: 'marketing',
label: 'Marketing',
description: 'Campanhas e eventos',
status: 'ACTIVE'
}
],
mask: 'BRL',
required: true,
description: 'Centro de custo responsável pela despesa'
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId}', 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/{customFieldId}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PUT",
CURLOPT_POSTFIELDS => json_encode([
'label' => 'Centro de custo',
'slug' => 'centro-de-custo',
'location' => [
'TRANSACTION'
],
'type' => 'SELECT',
'values' => [
[
'value' => 'marketing',
'label' => 'Marketing',
'description' => 'Campanhas e eventos',
'status' => 'ACTIVE'
]
],
'mask' => 'BRL',
'required' => true,
'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/{customFieldId}"
payload := strings.NewReader("{\n \"label\": \"Centro de custo\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"type\": \"SELECT\",\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"required\": true,\n \"description\": \"Centro de custo responsável pela despesa\"\n}")
req, _ := http.NewRequest("PUT", 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.put("https://api.identity.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/custom-fields/{customFieldId}")
.header("Content-Type", "application/json")
.body("{\n \"label\": \"Centro de custo\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"type\": \"SELECT\",\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"required\": true,\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/{customFieldId}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Put.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"label\": \"Centro de custo\",\n \"slug\": \"centro-de-custo\",\n \"location\": [\n \"TRANSACTION\"\n ],\n \"type\": \"SELECT\",\n \"values\": [\n {\n \"value\": \"marketing\",\n \"label\": \"Marketing\",\n \"description\": \"Campanhas e eventos\",\n \"status\": \"ACTIVE\"\n }\n ],\n \"mask\": \"BRL\",\n \"required\": true,\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_NOT_FOUND",
"origin": "IDENTITY",
"message": "Custom field not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "CUSTOM_FIELD_CONCURRENT_UPDATE",
"origin": "IDENTITY",
"message": "Custom field was modified by another request — reload it and try again"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "CUSTOM_FIELD_SLUG_IMMUTABLE",
"origin": "IDENTITY",
"message": "Custom field slug cannot be changed after creation"
}slug and type may be echoed with their stored values but never changed. values is merged by option value: existing options are edited in place, new ones are appended, and a stored option missing from the list is rejected — retire it with status: "DEACTIVATED" instead. status of the field itself is not writable here; use the activate and deactivate endpoints.Path Parameters
ID of your realm.
Format: UUID
ID of your organization.
Format: UUID
ID of the custom field.
Format: UUID
Body
application/json
New human-readable name of the field. Omit to keep the current one.
Required string length:
1 - 50Example:
"Centro de custo"
Immutable. May be echoed with the stored value (for example when resending the whole definition); a different value answers 422 CUSTOM_FIELD_SLUG_IMMUTABLE.
Required string length:
2 - 80Pattern:
^[a-z0-9]+(?:-[a-z0-9]+)*$Example:
"centro-de-custo"
Replaces the full list of entities the field is attached to. Omit to keep the current one.
Example: ["TRANSACTION","CARD"]
Available options:
TRANSACTION, CARD, WALLET, CUSTOMER, TRIP, TRAVEL_PASSENGER, USER, VEHICLE Immutable. May be echoed with the stored value; a different value answers 422 CUSTOM_FIELD_TYPE_IMMUTABLE.
Available options:
TEXT, NUMBER, DATE, BOOLEAN, SELECT, MULTI_SELECT, CUSTOMER, FILE, MULTI_FILE Example:
"SELECT"
The complete option list of a SELECT / MULTI_SELECT field, merged by value: existing options are edited in place, new ones are appended, and a stored option that is missing from the list is rejected — deactivate it instead. Omit to leave the options untouched.
Show child attributes
Show child attributes
Display format of a NUMBER field: NONE, BRL, USD or PERCENT. A NUMBER field's existing mask cannot be cleared (422 CUSTOM_FIELD_MASK_REQUIRED).
Example:
"BRL"
Whether a value must be provided on every entity listed in location.
Example:
true
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"