Account Users

This page explains how to manage users linked to one or more accounts on Fits. It covers creating a user with linked accounts, what happens when an account in the list returns an error and White Label behavior.

Create a user with multiple linked accounts (CreateUser)

The CreateUser method lets you link several accounts to a single user at creation time, using the AccountsTaxNumber[] field. Request examples are in the API Reference. The Method, PartnerId and BusinessUnitId fields are common to all methods and are described in Getting Started. CreateUser only creates users: if a record with the given CPF already exists, the method returns an error and does not update the existing user.

Request fields

In the Requirement column, Mandatory means the field must be sent, Optional means it can be omitted, and Conditional means it depends on another field, as stated in the Description.

FieldRequirementDescription
MethodMandatoryMethod to be used (CreateUser).
PartnerIdMandatoryInformation provided by Fits.
BusinessUnitIdMandatoryInformation provided by Fits.
TaxNumberMandatoryUser CPF.
NameMandatoryUser name.
MailOptionalUser email. Only the format is validated.
CellphoneOptionalUser mobile phone. Not validated.
BirthDateOptionalUser date of birth, in the format dd/MM/yyyy.
ProfileTypeOptionalUser profile.
TypeOptionalUser type.
AccountsTaxNumber[]MandatoryList of texts with the CPF/CNPJ of the accounts to be linked to the user. Provide at least one account holder (required for a new user).

Response fields

The response returns the fields below. The success message is in the Success Catalogue.

FieldDescription
Success"true" on success and "false" on error (text, not a boolean).
MessageReturn message. On error, it gives the reason.
LoginLogin of the created user (the CPF, digits only). Returned on success.
ValidationList of texts with the validation details. Returned only on a validation error.

The errors returned by this method are listed in the Error Catalogue, in the section CreateUser.

How linking works

  • accounts are linked at the moment the user is created; there is no separate method to link accounts to a user that already exists;
  • the AccountsTaxNumber[] list does not follow any priority order: there is no concept of a "primary account" among the accounts provided;
  • the accounts provided can belong to different CPFs or CNPJs, that is, they do not need to belong to the same account holder.

Adding and removing accounts after creation

  • it is not possible to add new accounts to an already created user through the API; linking only happens at creation;
  • removing accounts linked to an existing user is done through the Admin Portal, with help from the support team; there is no API method for this action;
  • there is no API method to list the accounts linked to a user.

Invalid accounts in the list

If an error occurs on any CPF/CNPJ in the AccountsTaxNumber[] list, the request returns an error and the creation of the user is undone: no link from the call is kept. A successful response indicates that the requested links were completed.

  • the response does not return a list of completed or failed links;
  • on a validation error, the response includes Validation with a list of texts;
  • some errors identify the account holder with the problem, but others do not.

Example: in a request with 5 CPFs/CNPJs, if the error happens on the third item, the call returns an error and none of the five is linked.

CreateUser flow summary

The flow below summarizes the possible results of a CreateUser call.

flowchart TD
  A["CreateUser"] --> B{"User CPF already exists?"}
  B -->|Yes| E1["Error: the existing user is not updated"]
  B -->|No| C{"Any CPF or CNPJ in AccountsTaxNumber invalid?"}
  C -->|Yes| E2["Error"]
  C -->|No| D["User created"]
  D --> L["Response with Login"]

Account selection and switching in White Label

White Label supports selecting and switching accounts for users with several linked accounts. The switch is handled by the front end: it is behavior that already exists in the interface, and the BU does not need to implement it through the API.

  • switching accounts does not affect the authentication token or the session; there is no need to authenticate again;
  • there is no difference in behavior between White Label and the native Fits environment: account switching works the same way in both.

Did this page help you?