Skip to main content

Create Shareholder

POST 
/v1/users/shareholders

Creates a shareholder in the legal person onboarding equity structure.

Important:

  • You can create multiple shareholders (natural person or legal person)
  • Each shareholder can have a participation percentage in company capital
  • Legal representatives must always be natural persons

Shareholder Types:

  • PARTNER - Partner/Shareholder
  • ATTORNEY - Attorney
  • ADMINISTRATOR - Administrator
  • OTHER - Other

Constraints:

  • User must be a legal person with active onboarding
  • If legal person onboarding is being executed, the onboarding record should already exist (POST /users/onboardings/legal-person)

Related endpoint: legal representatives can be linked to shareholders at POST /users/legal-representatives.

Request​

Header Parameters

    x-transaction-uuid stringrequired

    The transaction ID is a UUID (v4) used to uniquely identify the object that will be created. All objects must have an identifier.

    nonce stringrequired

    The nonce ID is a UUID (v4) used to uniquely identify the request. All requests must have an identifier.

    x-lang string

    Possible values: [pt-BR, en-US]

    Indicates the preferred language. Defaults to Brazilian Portuguese if unspecified.

    x-product-uuid string

    The product ID is a UUID (v4) used to identify the Z.ro product configuration.

    x-product-target-user-uuid string

    The product target user ID is a UUID (v4) used to identify what user account this request must be executed. Require: x-product-uuid.

Body

required
    name stringrequired

    Shareholder full name (corporate name for legal person, full name for natural person).

    document stringrequired

    Document number (CPF for natural person, CNPJ for legal person). Only numbers.

    type stringrequired

    Possible values: [PARTNER, ATTORNEY, ADMINISTRATOR, OTHER]

    Shareholder type/qualification in the company (equity structure).

    participation_percentage number

    Participation percentage in company capital (participação acionária). Range: 0.00 to 100.00.

    Note: This represents the equity stake in the company. If this shareholder is a legal person, you will need to create linked legal representatives (natural persons) and link them to this shareholder via the legal representatives endpoint.

    zip_code string

    Zip code (CEP) of the shareholder address. Used in CAF validation for QSA structure.

Responses​

Shareholder created successfully. Proceed to create legal representatives linked to this shareholder.

Schema
    id stringrequired

    Shareholder ID.

    document stringrequired

    Document number (CPF or CNPJ).

    person_type stringrequired

    Possible values: [NATURAL_PERSON, LEGAL_PERSON]

    Person type (natural person or legal person).

    name stringrequired

    Shareholder name.

    participation_percentage number

    Participation percentage in company capital.

    type stringrequired

    Possible values: [PARTNER, ATTORNEY, ADMINISTRATOR, OTHER]

    Shareholder type/qualification.

    zip_code string

    Zip code (CEP) of the shareholder address.

    created_at date-timerequired

    Creation date.

Loading...