Skip to main content
POST
Assign a user to an organization
If the user already belongs to the organization, nothing changes (to change their level, use PATCH /realms/{realmId}/users/{userId}). A user who is still onboarding gets the wallet when they finish. Answers the user as the organization’s user list shows them, with their userOrgLevel in this organization. Their other organizations are never listed.

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

userId
string<uuid>
required

ID of the user to add to the organization.

Format: UUID

organizationId
string<uuid>
required

ID of the organization to add the user to.

Format: UUID

Body

application/json
level
enum<string>
required

Access level in the organization: ADMIN manages its users and settings, USER uses its wallets and cards.

Available options:
ADMIN,
USER
Example:

"USER"

Response

Successful response

A user of the organization.

id
string<uuid>
required

ID of the user.

Example:

"8f1c2d3e-4b5a-4c6d-9e7f-a1b2c3d4e5f6"

email
string
required

E-mail address the user signs in with. It can't be changed.

Example:

"ana.souza@acme.com.br"

firstName
string
required

First name.

Example:

"Ana"

lastName
string
required

Last name.

Example:

"Souza"

cpf
string
required

CPF, digits only.

Example:

"52998224725"

status
enum<string>
required

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"

statusCode
enum<string>
required

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"

realm
object
required

The user's realm and their access level in it.

hasMfa
boolean
required

Whether the user has set up multi-factor authentication.

Example:

true

hasPin
boolean
required

Whether the user has created a transaction PIN.

Example:

true

hasFacialBiometric
boolean
required

Whether the user's face was validated during onboarding.

Example:

true

pinErrorsCount
number
required

Consecutive wrong PIN attempts. At 3 the user is blocked (BLOCKED_BY_PIN).

Example:

0

mfaErrorsCount
number
required

Consecutive wrong multi-factor codes.

Example:

0

createdAt
string<date-time>
required

When the user was created.

Example:

"2026-03-02T14:21:07.512Z"

updatedAt
string<date-time>
required

When the user last changed.

Example:

"2026-10-13T18:43:50.746Z"

createdBy
string
required

ID of the user or API client that created this user. Empty when unknown.

Example:

"43230779-2cfb-4525-a40c-77fbf15e68f0"

updatedBy
string
required

ID of the user or API client that last changed this user. Empty when unknown.

Example:

"43230779-2cfb-4525-a40c-77fbf15e68f0"

deletedBy
string
required

ID of the user or API client that deactivated this user. Empty unless the user was deactivated.

Example:

""

userOrgLevel
enum<string>
required

The user's access level in the organization of the request. ADMIN manages the organization's users and settings; USER uses its wallets and cards. APP_CLIENT can appear on memberships created with that level.

Available options:
ADMIN,
USER,
APP_CLIENT
Example:

"USER"

birthdate
string<date-time>

Date of birth, at midnight UTC.

Example:

"1990-05-17T00:00:00.000Z"

phone
string

Phone number in E.164 format. Omitted when the user has none.

Example:

"+5511987654321"

customFields
object

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.