Create a user
curl --request POST \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/users \
--header 'Content-Type: application/json' \
--data '
{
"email": "ana.souza@acme.com.br",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"firstName": "Ana",
"phone": "+5511987654321",
"realm": {
"level": "USER"
},
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"lastName": "Souza",
"customFields": {}
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/users"
payload = {
"email": "ana.souza@acme.com.br",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"firstName": "Ana",
"phone": "+5511987654321",
"realm": { "level": "USER" },
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"lastName": "Souza",
"customFields": {}
}
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({
email: 'ana.souza@acme.com.br',
cpf: '52998224725',
birthdate: '1990-05-17T00:00:00.000Z',
firstName: 'Ana',
phone: '+5511987654321',
realm: {level: 'USER'},
organizations: [{id: 'c4bd3f21-dfbd-44e8-8055-68ba15bed410', level: 'USER'}],
lastName: 'Souza',
customFields: {}
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/users', 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}/users",
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([
'email' => 'ana.souza@acme.com.br',
'cpf' => '52998224725',
'birthdate' => '1990-05-17T00:00:00.000Z',
'firstName' => 'Ana',
'phone' => '+5511987654321',
'realm' => [
'level' => 'USER'
],
'organizations' => [
[
'id' => 'c4bd3f21-dfbd-44e8-8055-68ba15bed410',
'level' => 'USER'
]
],
'lastName' => 'Souza',
'customFields' => [
]
]),
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}/users"
payload := strings.NewReader("{\n \"email\": \"ana.souza@acme.com.br\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"firstName\": \"Ana\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"lastName\": \"Souza\",\n \"customFields\": {}\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}/users")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"ana.souza@acme.com.br\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"firstName\": \"Ana\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"lastName\": \"Souza\",\n \"customFields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/users")
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 \"email\": \"ana.souza@acme.com.br\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"firstName\": \"Ana\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"lastName\": \"Souza\",\n \"customFields\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "8f1c2d3e-4b5a-4c6d-9e7f-a1b2c3d4e5f6",
"email": "ana.souza@acme.com.br",
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"status": "ACTIVE",
"statusCode": "USER_ACTIVE",
"realm": {
"id": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"level": "USER",
"name": ""
},
"hasMfa": true,
"hasPin": true,
"hasFacialBiometric": true,
"pinErrorsCount": 0,
"mfaErrorsCount": 0,
"createdAt": "2026-03-02T14:21:07.512Z",
"updatedAt": "2026-10-13T18:43:50.746Z",
"createdBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"updatedBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"deletedBy": "",
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER",
"legalName": "Acme Comércio de Alimentos Ltda",
"tradingName": "Acme Alimentos"
}
],
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"customFields": {}
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "IDENTITY",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "ORGANIZATION_NOT_FOUND",
"origin": "IDENTITY",
"message": "Organization not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "USER_CONFLICT",
"origin": "IDENTITY",
"message": "User 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": "email",
"message": "Invalid input: expected string, received undefined",
"code": "EMAIL_REQUIRED"
}
]
}Create a user
Creates a user in your realm and e-mails them an invitation to complete onboarding.
POST
/
realms
/
{realmId}
/
users
Create a user
curl --request POST \
--url https://api.identity.v2.portao3.com.br/realms/{realmId}/users \
--header 'Content-Type: application/json' \
--data '
{
"email": "ana.souza@acme.com.br",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"firstName": "Ana",
"phone": "+5511987654321",
"realm": {
"level": "USER"
},
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"lastName": "Souza",
"customFields": {}
}
'import requests
url = "https://api.identity.v2.portao3.com.br/realms/{realmId}/users"
payload = {
"email": "ana.souza@acme.com.br",
"cpf": "52998224725",
"birthdate": "1990-05-17T00:00:00.000Z",
"firstName": "Ana",
"phone": "+5511987654321",
"realm": { "level": "USER" },
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER"
}
],
"lastName": "Souza",
"customFields": {}
}
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({
email: 'ana.souza@acme.com.br',
cpf: '52998224725',
birthdate: '1990-05-17T00:00:00.000Z',
firstName: 'Ana',
phone: '+5511987654321',
realm: {level: 'USER'},
organizations: [{id: 'c4bd3f21-dfbd-44e8-8055-68ba15bed410', level: 'USER'}],
lastName: 'Souza',
customFields: {}
})
};
fetch('https://api.identity.v2.portao3.com.br/realms/{realmId}/users', 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}/users",
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([
'email' => 'ana.souza@acme.com.br',
'cpf' => '52998224725',
'birthdate' => '1990-05-17T00:00:00.000Z',
'firstName' => 'Ana',
'phone' => '+5511987654321',
'realm' => [
'level' => 'USER'
],
'organizations' => [
[
'id' => 'c4bd3f21-dfbd-44e8-8055-68ba15bed410',
'level' => 'USER'
]
],
'lastName' => 'Souza',
'customFields' => [
]
]),
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}/users"
payload := strings.NewReader("{\n \"email\": \"ana.souza@acme.com.br\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"firstName\": \"Ana\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"lastName\": \"Souza\",\n \"customFields\": {}\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}/users")
.header("Content-Type", "application/json")
.body("{\n \"email\": \"ana.souza@acme.com.br\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"firstName\": \"Ana\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"lastName\": \"Souza\",\n \"customFields\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.identity.v2.portao3.com.br/realms/{realmId}/users")
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 \"email\": \"ana.souza@acme.com.br\",\n \"cpf\": \"52998224725\",\n \"birthdate\": \"1990-05-17T00:00:00.000Z\",\n \"firstName\": \"Ana\",\n \"phone\": \"+5511987654321\",\n \"realm\": {\n \"level\": \"USER\"\n },\n \"organizations\": [\n {\n \"id\": \"c4bd3f21-dfbd-44e8-8055-68ba15bed410\",\n \"level\": \"USER\"\n }\n ],\n \"lastName\": \"Souza\",\n \"customFields\": {}\n}"
response = http.request(request)
puts response.read_body{
"id": "8f1c2d3e-4b5a-4c6d-9e7f-a1b2c3d4e5f6",
"email": "ana.souza@acme.com.br",
"firstName": "Ana",
"lastName": "Souza",
"cpf": "52998224725",
"status": "ACTIVE",
"statusCode": "USER_ACTIVE",
"realm": {
"id": "f495ff0c-ab54-4f99-8e92-ca8682e4de9b",
"level": "USER",
"name": ""
},
"hasMfa": true,
"hasPin": true,
"hasFacialBiometric": true,
"pinErrorsCount": 0,
"mfaErrorsCount": 0,
"createdAt": "2026-03-02T14:21:07.512Z",
"updatedAt": "2026-10-13T18:43:50.746Z",
"createdBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"updatedBy": "43230779-2cfb-4525-a40c-77fbf15e68f0",
"deletedBy": "",
"organizations": [
{
"id": "c4bd3f21-dfbd-44e8-8055-68ba15bed410",
"level": "USER",
"legalName": "Acme Comércio de Alimentos Ltda",
"tradingName": "Acme Alimentos"
}
],
"birthdate": "1990-05-17T00:00:00.000Z",
"phone": "+5511987654321",
"customFields": {}
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "INSUFFICIENT_PERMISSIONS",
"origin": "IDENTITY",
"message": "insufficient permissions"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "ORGANIZATION_NOT_FOUND",
"origin": "IDENTITY",
"message": "Organization not found"
}{
"traceId": "1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b",
"code": "USER_CONFLICT",
"origin": "IDENTITY",
"message": "User 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": "email",
"message": "Invalid input: expected string, received undefined",
"code": "EMAIL_REQUIRED"
}
]
}The user is created
IN_ONBOARDING and becomes ACTIVE once they finish the onboarding the invitation links to. They are added to every organization in organizations; you must be an admin of each of them, and only a realm administrator can create a realm ADMIN. The e-mail address can’t be changed afterwards.Path Parameters
ID of your realm. The user is created in it.
Format: UUID
Body
application/json
E-mail address the user will sign in with. The invitation is sent to it, and it can't be changed later.
Pattern:
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Example:
"ana.souza@acme.com.br"
CPF, digits only. Must be a valid CPF.
Minimum string length:
1Example:
"52998224725"
Date of birth, as an ISO 8601 date-time at midnight UTC. A plain YYYY-MM-DD date is also accepted.
Example:
"1990-05-17T00:00:00.000Z"
First name.
Minimum string length:
1Example:
"Ana"
Phone number in E.164 format: +, the country code and the number, digits only. Mobile or landline, Brazilian or not; it must be a real, reachable number.
Minimum string length:
1Pattern:
^\+[1-9]\d{7,14}$Example:
"+5511987654321"
The user's realm access.
Show child attributes
Show child attributes
Organizations the user belongs to. You must be an admin of every organization listed.
Minimum array length:
1Show child attributes
Show child attributes
Last name.
Example:
"Souza"
Values of the realm's user custom fields, keyed by the custom field's slug, for example {"cost-center": "Marketing"}. Every key must be the slug of an active user custom field of one of the listed organizations.
Show child attributes
Show child attributes
Response
Successful response
A user of the realm.
ID of the user.
Example:
"8f1c2d3e-4b5a-4c6d-9e7f-a1b2c3d4e5f6"
E-mail address the user signs in with. It can't be changed.
Example:
"ana.souza@acme.com.br"
First name.
Example:
"Ana"
Last name.
Example:
"Souza"
CPF, digits only.
Example:
"52998224725"
Lifecycle status. IN_ONBOARDING: invited, still completing onboarding. ACTIVE: can sign in. DEACTIVATED: access removed by an administrator. BLOCKED: access suspended, for example after too many wrong PINs. CREATING: being set up.
Available options:
IN_ONBOARDING, CREATING, ACTIVE, DEACTIVATED, BLOCKED Example:
"ACTIVE"
Reason behind status: USER_ACTIVE, USER_DEACTIVATED, ONLY_ONBOARDING, or the cause of a block (BLOCKED_BY_PIN, BLOCKED_BY_MFA, BLOCKED_BY_ADMIN).
Available options:
BLOCKED_BY_PIN, BLOCKED_BY_MFA, BLOCKED_BY_ADMIN, USER_ACTIVE, USER_DEACTIVATED, ONLY_ONBOARDING Example:
"USER_ACTIVE"
The user's realm and their access level in it.
Show child attributes
Show child attributes
Whether the user has set up multi-factor authentication.
Example:
true
Whether the user has created a transaction PIN.
Example:
true
Whether the user's face was validated during onboarding.
Example:
true
Consecutive wrong PIN attempts. At 3 the user is blocked (BLOCKED_BY_PIN).
Example:
0
Consecutive wrong multi-factor codes.
Example:
0
When the user was created.
Example:
"2026-03-02T14:21:07.512Z"
When the user last changed.
Example:
"2026-10-13T18:43:50.746Z"
ID of the user or API client that created this user. Empty when unknown.
Example:
"43230779-2cfb-4525-a40c-77fbf15e68f0"
ID of the user or API client that last changed this user. Empty when unknown.
Example:
"43230779-2cfb-4525-a40c-77fbf15e68f0"
ID of the user or API client that deactivated this user. Empty unless the user was deactivated.
Example:
""
Organizations of the realm the user belongs to.
Show child attributes
Show child attributes
Date of birth, at midnight UTC.
Example:
"1990-05-17T00:00:00.000Z"
Phone number in E.164 format. Omitted when the user has none.
Example:
"+5511987654321"
Values of the realm's user custom fields, keyed by the custom field's slug, for example {"cost-center": "Marketing"}. Omitted when the user has none.
Show child attributes
Show child attributes