Skip to main content

Create Shareholder

POST 
/v1/users/shareholders

Creates a shareholder in the authenticated legal person equity structure.

  • User must be in the legal person onboarding flow
  • The legal person onboarding should already exist
  • Replay with the same document is idempotent and returns the existing shareholder
  • Replay does not merge or update the other fields from the new payload

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

    UUID (v4) of the product that the request should use. Send it explicitly when the authenticated user has more than one product or when the integration must select a specific product. If omitted and the endpoint does not require it, the API uses the authenticated user's default product.

    x-product-target-user-uuid string

    UUID (v4) of the user on whose behalf the request should run within the selected product. If omitted, the request runs as the authenticated user. Requires 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 legal person equity structure.

    participation_percentage number

    Participation percentage in legal person capital (participacao acionaria). Range: 0.00 to 100.00.

    Note: This represents the equity stake in the legal person. 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 legal person 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...