Change the Name of a Business Subaccount via API

This guide details the process for updating the company name (Legal Name or Trade Name) of a Legal Entity (PJ) subaccount through the API.

The flow is designed to ensure that the name used on the Asaas platform is always consistent with the official records from the Federal Revenue Service, providing security and registration consistency.

The Two-Step Process

Changing the name is a process that consists of two API calls: first, you retrieve the valid and available names for the subaccount, and then you send the update with the chosen name.

Retrieve the Available Names

Before any update attempt, it is mandatory to check which company names are available for the subaccount’s CNPJ.

To do this, make a GET request to the Retrieve Commercial Data endpoint, authenticating with the access_token of the specific subaccount you want to update.

Example:
GET /v3/myAccount/commercialInfo/

The response will contain the availableCompanyNames attribute, which is a list of name options (Legal Name and Trade Name) retrieved directly from the Federal Revenue Service.

Example Response:

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

Store the names returned in availableCompanyNames. You will need one of them for the next step.

Send the Update with the Chosen Name

With the list of valid names in hand, you can now request the update by sending the desired name.

Make a POST request to the same endpoint, also authenticated with the subaccount’s access_token, specifying the companyName field along with the other required attributes to Update the Commercial Data of an account.

In the companyName field, you must provide exactly one of the values returned in the availableCompanyNames list from the previous step.

⚠️ Important: Exact Match Requirement
This is the most important part of the process. For the update to succeed, the value sent in the companyName field must be an exact, identical copy of one of the names returned by Asaas.

Any difference will result in an update failure, including:

• Differences in upper/lowercase.
• Accents.
• Extra spaces.
• Abbreviations or any variation not in the official record.

It is not allowed to provide a custom name or one that was not previously returned by the query.
This mechanism ensures the integrity and compliance of registration data in our platform.