Skip to main content

Create Shareholder (Step 2 of 6)

POST 
/v1/users/shareholders

Step 2: Create shareholders for company equity structure.

Create a shareholder (partner, administrator, attorney, etc.) for the authenticated legal person account. You must register at least one shareholder before creating legal representatives.

Important:

  • You can create multiple shareholders (PF or PJ)
  • Each shareholder can have a participation percentage in company capital
  • Legal representatives are ALWAYS PF: Every shareholder needs at least one PF legal representative

Shareholder Types:

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

Usage Examples:

Natural Person Shareholder:

{
  "name": "João Silva",
  "document": "02465676008",
  "type": "PARTNER",
  "participation_percentage": 50.0
}

Legal Person Shareholder:

{
  "name": "Empresa ABC LTDA",
  "document": "12345678000199",
  "type": "PARTNER",
  "participation_percentage": 30.0
}

Prerequisites:

  • Legal person onboarding must be created first (POST /legal-person)
  • User must be PJ with active onboarding

Next: Create legal representatives linked to shareholders (POST /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 (razão social for PJ, nome completo for PF).

    document stringrequired

    Document number (CPF for PF, CNPJ for PJ). 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 PJ (legal person), you will need to create legal representatives (PFs) 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 (PF or PJ).

    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...