Create an Account

Creates an account in the company's chart of accounts, optionally linked to one or more cost or profit centers.

Identify the owning company with exactly one of company_id or company_account_external_id. Sending both, or neither, is rejected.

Unknown fields are rejected, so check field names carefully.

Creates an account in the company's chart of accounts. In the same call you can link it to reference accounts (account_mappings), attach classification codes (code_mappings) and link cost or profit centers (centers).

Identify the owning company with exactly one of company_id or company_account_external_id. Sending both, or neither, is rejected.

Unknown fields are rejected, so check field names carefully.

Creating, not updating

This endpoint only creates accounts. Sending an account_external_id that already exists for the company is rejected. To change an existing account, including its mappings, use Account Management in the dashboard.

Create parent accounts before their children: parent_account must point to an account that already exists.

Hierarchy rules

RuleError
The parent exists in the same companyParent account not found for <code> (404)
The parent code is unique in the companyMore than one account with code <code> in the company
The parent is synthetic (type: "S")Parent account must be of type SYNTHETIC (S)
The parent is ACTIVEParent account must be ACTIVE
level is greater than the parent's levelParent account level must be lower than the account level
end_date is not before start_date (same day accepted)End date cannot be before the start date

nature

nature is a Brinta code with one meaning for every obligation. Each obligation translates it into its own code, and some obligations accept only part of the list. It can be omitted or sent as null.

natureMeaning
1Asset (Ativo)
2Liability (Passivo)
3Equity (Patrimônio Líquido)
4Revenue (Receita)
5Expense (Despesa)
6Memorandum (Compensação)
7Other (Outras)

Mappings

account_mappings: reference accounts

Links the account to an account in a reference group, such as a referential chart of accounts. Each item names the group and the account code inside it.

"account_mappings": [
  { "group": "COSIF", "account": "1.1.1.10.00.00-8" }
]
  • Send the group name and the account code exactly as they appear in the group, with dots and dashes. 1111000008 instead of 1.1.1.10.00.00-8 answers Account 1111000008 not found in group COSIF.
  • Groups currently available: COSIF, DESIF, SUSEP, CodTrib IBS/CBS - DeRe, L100A, L100B, L100C, L300A, L300B, L300C. Contact Brinta for other groups or for the list of accounts in a group.
  • Each group accepts a limited number of mapped accounts per account, usually one.

code_mappings: classification codes

Attaches a code value to the account, one value per type.

"code_mappings": [
  { "type": "dere_ind_trib_iss", "value": "0" }
]
  • Types currently available: dere_ind_trib_iss (DeRE ISS indicator, 0 or 1), cod_det, cod_comp, field_number. Contact Brinta for the values each type accepts.
  • Each type can be sent only once per account.

Checking mappings

The response does not return account_mappings or code_mappings. To check them after the load, use Account Management in the dashboard.

For obligation-specific mappings, see the obligation guides, for example DeRE: chart of accounts via the Accounts API.

Errors

Format errors always answer 400, before any rule is applied. details carries only the first error found.

{
  "status_code": 400,
  "error": "Bad Request",
  "message": "Validation error: The provided data does not match the required format",
  "details": {
    "code": "INVALID_PARAMETERS",
    "message": "'split_code' must be 3 digits, from 000 to 999",
    "invalid_params": ["split_code"]
  }
}
details.codeWhen
INVALID_PARAMETERSBoth or neither company identifiers were sent, account_external_id is missing, split_code does not have three digits, or nature is not empty or 1 to 7
INVALID_ENUM_VALUEstatus or sub_nature outside its list (including sub_nature as null)
REQUIRED_FIELDA required field is missing, or type/value is missing in a code mapping, or group/account in an account mapping
No codeAny other format error: an unknown field, a wrong type, an invalid date or a text longer than the maximum

Business-rule errors answer with this body, without an error code: the message says which rule failed.

{ "response_data_body": "Parent account must be of type SYNTHETIC (S)", "status_code": 400 }
Statusresponse_data_bodyWhen
404Company not found or not related to parent companyThe company does not exist or is not in your token's group
400National account already exists with account <code> and company <company>The code already exists in that company
400Only parentCompanyExternalId or parentCompanyId can be sent, not bothBoth parent company identifiers were sent
400Location not foundlocation is not a valid country
404 / 400Hierarchy errorsSee Hierarchy rules
400Account <code> not found in group <group>The group, or the account in the group, does not exist
400More than one account <code> in group <group>The code is duplicated inside the group
400Account mapping sent more than once: <group>/<code>The same pair is repeated in account_mappings
400Too many accounts mapped for the groupMore accounts were mapped than the group allows
400Unknown code mapping type: <types>A type in code_mappings does not exist
400Code mapping type sent more than once: <types>A type is repeated in code_mappings
400indTribISS must be 0 or 1dere_ind_trib_iss has another value
500Error creating national accountSaving failed
500Error processing centersThe centers failed, but the account was already created: a retry returns the duplicate-account error
500Account created but could not be retrievedThe account was created, but could not be read for the response
Body Params
string
required

Code of the account on the client's system. Must be unique per company.

string

Id of the company on BRINTA's system (UUID). Mandatory if company_account_external_id is not present. Do not send both.

string

Id of the company on the client's system. Mandatory if company_id is not present. Do not send both.

string

Id of the parent company on BRINTA's system (UUID). Used to verify that the company belongs to this parent. Cannot be sent together with parent_company_external_id.

string

Id of the parent company on the client's system. Used to verify that the company belongs to this parent. Cannot be sent together with parent_company_id.

string
required

ISO code of the location of the account, e.g. BR.

string
required

Name of the account.

string

Alternative name of the account.

string
required
length ≤ 300

Description of the account.

string
length ≤ 300

Alternative description of the account.

string
required

Account type. Send A (analytical, a posting account) or S (synthetic, a grouping account). Only a synthetic account can be the parent of other accounts.

integer
required

Depth of the account in the chart of accounts hierarchy. Must be greater than the level of parent_account.

integer
required

Display and sort order of the account.

integer | null
enum

Nature of the account, as a Brinta code with the same meaning for every obligation: 1 asset (Ativo), 2 liability (Passivo), 3 equity (Patrimônio Líquido), 4 revenue (Receita), 5 expense (Despesa), 6 memorandum (Compensação), 7 other (Outras). Any other value is rejected with INVALID_NATURE. Each obligation may accept only some of these values.

string
enum

Usual side of the balance: C (credit), D (debit) or V (variable). If you don't have the value, omit the field: an empty value or null is rejected.

Allowed:
string

Alternative account code, e.g. a local or referential chart of accounts code.

string

Id of the account group on the client's system.

string

Hierarchy code of the account.

string

account_external_id of the parent account in the same company. The parent must already exist, be synthetic (S), be ACTIVE, and have a lower level than this account. Create parents before their children.

string
^([0-9]{3})?$

Split code of the account: three digits, from 000 to 999, sent as text. Any other value is rejected with INVALID_SPLIT_CODE.

number

Rate associated with the account.

string

Free-text comments.

string
enum
Defaults to ACTIVE

Status of the account.

Allowed:
date-time

Start date of the account (ISO 8601 date-time).

date-time

End date of the account (ISO 8601 date-time). Cannot be before start_date; the same day is accepted.

date-time

Start of the validity period (ISO 8601 date-time). If you send only one of start_date and valid_from, the other takes the same value.

date-time

End of the validity period (ISO 8601 date-time). If you send only one of end_date and valid_until, the other takes the same value.

account_mappings
array of objects

Reference accounts this account maps to, such as the equivalent account in a referential chart of accounts. Each item names a group and the code of an account in that group. Group names and codes must be sent exactly as they appear in the group, including dots and dashes.

Groups currently available: COSIF, DESIF, SUSEP, CodTrib IBS/CBS - DeRe, L100A, L100B, L100C, L300A, L300B, L300C. Contact Brinta for other groups or for the list of accounts in a group.

Each group accepts a limited number of mapped accounts per account (usually one). The response does not return the mappings: check them in Account Management in the dashboard.

account_mappings
code_mappings
array of objects

Classification codes attached to the account, one value per type. Each type can be sent only once.

Types currently available: dere_ind_trib_iss (ISS indicator for the DeRE: 0 or 1), cod_det, cod_comp, field_number. Contact Brinta for the values each type accepts.

The response does not return the mappings: check them in Account Management in the dashboard.

code_mappings
centers
array of objects

Cost or profit centers linked to the account. Created if they do not exist.

centers
Responses

500

Saving failed. If the error is Error processing centers, the account was already created: a retry returns the duplicate-account error.

Language
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json