Tax ID Validation - How To

Send a tax ID to POST /tax-id-validations/. Brinta checks it against the official sources of that country and returns what they hold about the taxpayer. Depending on the country this can include:

• legal name and address;
• tax condition;
• activities;
• related registrations;
• provincial registries (padrones) with their rates.

Use it to:

• onboard customers and suppliers with clean data;
• block invalid tax IDs before you invoice;
• keep each counterpart's tax profile up to date, so /sales and /transfers calculate the right taxes.

1. Choose what to validate

Send exactly one of company_id, company_external_id or company.

A company already in Brinta

curl -X POST https://api.brinta.com/tax-id-validations/ \
  -H "Authorization: Bearer $BRINTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": ["AR"],
    "company_id": "456c6c4f-f64a-4069-9988-8164c015cf80",
    "update_company": true
  }'

Brinta validates the registration stored on the company. If it holds several that can be validated, choose one with a top-level tax_registration.

A tax ID on its own

curl -X POST https://api.brinta.com/tax-id-validations/ \
  -H "Authorization: Bearer $BRINTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": ["CO"],
    "company": {
      "type": "business",
      "legal_name": "Acme S.A.S.",
      "tax_registration": { "number": "901701266", "type": "NIT", "level": "country", "location": "CO" }
    }
  }'

2. Request fields

company (inline)

Some checks require extra fields. If any are missing, the request is rejected before anything runs, with 400 and the list of missing fields:

{
  "message": "Missing data required by the providers that validate this request: MX: company.legal_name is required; MX: company.address.postal_code is required",
  "data": [ { "errors": ["MX: company.legal_name is required", "MX: company.address.postal_code is required"] } ]
}

3. Get the result

The POST answers right away:

{ "id": "tiv2-188be839-bd78-4692-9fd4-53e67e2d28bc", "status": "in_process" }

Keep the id. Brinta then queries the official sources in the background. It usually takes seconds, and longer when an authority answers asynchronously.

Webhook. When the validation succeeds, Brinta notifies your validation webhook with the validation id. Then read it:

curl https://api.brinta.com/tax-id-validations/tiv2-188be839-bd78-4692-9fd4-53e67e2d28bc \
  -H "Authorization: Bearer $BRINTA_TOKEN"

Polling. If you don't use webhooks, or haven't received one, call GET /tax-id-validations/{id} until status is no longer in_process. Wait a few seconds between calls. Always handle failed this way as well.

Response

{
  "id": "tiv2-188be839-bd78-4692-9fd4-53e67e2d28bc",
  "status": "succeeded",
  "data": [
    {
      "locationIsoCode": "CO",
      "status": "succeeded",
      "company": {
        "legal_name": "ACME S.A.S.",
        "tax_registrations": [
          { "number": "901701266", "type": "NIT", "level": "country", "location": "CO", "activities": ["8299"] }
        ],
        "address": { "state": "CO-BOL", "city": "CARTAGENA" }
      },
      "registry_lists": []
    }
  ]
}

Fields with no value are left out of the response.

4. Using the result

With "update_company": true, Brinta stores the result on the company. Reference that company in your transactions with company_id or company_external_id, and the stored data is used automatically:

• buyer on /sales;

• counterpart on /transfers.

• Data the source returns replaces what the company had. That includes the legal name. Empty values never overwrite existing data.

• Validate again when the source changes. Argentina's padrones change monthly; see the Argentina guide.

• Recent results may be reused. An identical query is answered from the last result for a short time, up to 24 hours. In Argentina, national data is kept until the end of the month.

Errors

Common mistakes