Change the name of a business subaccount via API

To change the legal name (Razão Social) or trade name (Nome Fantasia) of a business subaccount, first check the names available for the CNPJ and then update the business data using exactly one of the returned values.

Before you start

Make both requests with the access_token of the subaccount that will be changed.

The name cannot be set freely. The value sent must match one of the options available for the subaccount's CNPJ.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Retrieve business data"] --> B["Get availableCompanyNames"]
    B --> C["Choose an available name"]
    C --> D["Update companyName"]
    D --> E["Validate the new name"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    class A inicio
    class B,C,D validacao
    class E sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Check the available names

Retrieve the subaccount's business data:

GET /v3/myAccount/commercialInfo/
See the full reference for this endpoint

The response contains the availableCompanyNames attribute, with the legal name and trade name options available for the CNPJ.

{
  "object": "commercialInfo",
  "email": "[email protected]",
  "companyName": "OLD COMPANY NAME LTDA",
  "availableCompanyNames": [
    "UPDATED COMPANY NAME LTDA",
    "UPDATED TRADE NAME"
  ],
  // ... other fields
}

Choose one of the values returned in availableCompanyNames. This value will be used in the next step.

2. Update the company name

Update the business data of the same subaccount:

POST /v3/myAccount/commercialInfo/
See the full reference for this endpoint

In the companyName field, provide exactly one of the values previously returned in availableCompanyNames, along with the other attributes required to update the business data.

Do not send a custom name that was not returned by the query.

How to validate the change

After the update, confirm that companyName has the chosen value.

If you need to retrieve the current state later, query again:

GET /v3/myAccount/commercialInfo/

The change is complete when the registered name matches the value selected from availableCompanyNames.

Next steps

• Retrieve the subaccount's business data
• Update the business data
• Implement the Annual Business Data Confirmation