🇧🇷 Brazil eKYB
Earlier in our docs is an overview of our Know Your Business here. Now, this page is focused specifically on eKYB in Brazil. eKYB in Brazil leverages the government source of truth to validate the legitimacy of businesses, including their taxID (CNPJ), business name, business address, along with UBOs.
Integration
User input flow
Module Configuration
Module configuration gives various options to specify different KYB criteria you would like to check (eg. Business name, Business Address, and Business taxID).
Direct API Approach
All module configurations and user data can be forwarded directly in the request for performing an KYB search. This will override existing configuration and data collected about the user.
API Authentication
All endpoints require authentication headers to be specified as stated in Incode API Documentation
POST /omni/externalVerification/ekyb
This endpoint performs an KYB check for the business specified. Note: Endpoint can have empty body {} and in that case information will be pulled from module configuration and session details.
- plugins: must be ["ekyb"]: (mandatory)
- businessName:: (optional) String. Name of the business.
- street: (optional) String. Street name of the business.
- houseNo: (optional) String. Building or house number on the street..
- addressLine2: (optional) String. Address line 2 of the business. (eg. in US apartment or unit number)
- city: (optional) String. City of the business of the business address.
- state: (optional) String. State of the business of the business address
- postalCode: (optional) String. postalCode formatted based on per-country postalCode basis. (BR has 8 digit postal codes)
- country: (mandatory) String. Two letter Alpha-2 country code. (Must be BR)
- taxId: (mandatory) String. Tax ID of the business (14 digit CNPJ which is the Business taxID in Brazil)
- uboNames: (optional) String. Full legal name(s) of Unique Beneficial owners to check against list of legal business associations
REQUEST FORMAT EXAMPLE
{
"plugins" : ["ekyb"], //required field
"businessName" : "RENATA DISTR. DE SUPLEMENTOS LTDA",
"street" : "Rua Curupaiti",
"houseNo" : "225",
"addressLine2" : "",
"city" : "Rio De Janeiro",
"state" : "RJ",
"postalCode" : "20735320",
"country" : "BR", //required field
"taxId" : "41111051548164", //required field
"uboNames" : ["MICHEL RODRIGUES", "ERIC SANTOS", "MICHELLE MUNHOZ"]
}
Response
All module configurations and user data can be forwarded directly in the request for performing an eKYB search. This will override existing configuration and data collected about the user.
API Authentication
All endpoints require authentication headers to be specified as stated in Incode API Documentation
RESPONSE EXAMPLE
{
"kyb": [
{
"key": "name",
"sub_label": "Verified"
},
{
"key": "tin",
"sub_label": "Verified"
},
{
"key": "address_verification",
"sub_label": "Verified"
},
{
"key": "cityMatch",
"sub_label": "Verified"
},
{
"key": "postalCodeMatch",
"sub_label": "Verified"
},
{
"key": "registrationStatus",
"sub_label": "Active"
},
{
"key": "ubo_name_match",
"sub_label": "Verified",
"uboName_input": "MICHEL RODRIGUES",
"nameId_match": "2"
},
{
"key": "ubo_name_match",
"sub_label": "Verified",
"uboName_input": "ERIC SANTOS",
"nameId_match": "1"
},
{
"key": "ubo_name_match",
"sub_label": "Unverified",
"uboName_input": "MICHELLE MUNHOZ",
"nameId_match": "-1"
}
],
"kybSource": {
"uboNames": [
{
"id": "1",
"uboName": "ERIC SANTOS"
},
{
"id": "2",
"uboName": "MICHEL RODRIGUES"
}
]
}
}
Note: NameId_match matches to the id listed in the kybSource section. If "nameId_match": "-1", this means that there is no match to the source of truth. If nameId_match is equal to any of the id's listed in the kybSource part of the response, the name is being matched to this uboName.
Please refer to error response to see conventional HTTP response codes to indicate the success or failure of an API request.
Custom 400 error messages if businessName, taxId, or country is “ “ or null:
message: businessName, taxId, and country are minimum required fields.
BR API Key | Status | Definition |
---|---|---|
name | Verified, Approximate Match, Unverified | Submitted business name is verified, approximate match, or unverified against the business name associated with the CNPJ in the government database. |
tin | Verified, Unverified | Submitted Tax ID (CNPJ) is verified or unverified in the government database. |
address_verification | Verified, Approximate Match, Unverified | Submitted address is verified, approximate match, or unverified against the address associated with the CNPJ in the government database. |
cityMatch | Verified, Approximate Match, Unverified | Submitted city is verified, approximate match, or unverified against the city associated with the CNPJ in the government database. |
postalCodeMatch | Verified, Unverified | Submitted postal code is verified or unverified against the city associated with the CNPJ in the government database. |
registrationStatus | Null, Active, Suspended, Unfit, Written off | Active: This occurs when the CNPJ is active. Suspended: This occurs is when the company did not comply with its tax obligations that year, presented problems with the data submitted to the Federal Revenue Service or is under investigation for possible fraud; Null: represents an invalid CNPJ, because there are registration problems in other instances, such as a duplicate State Registration. Unfit: When there is any tax irregularity or omission of company tax information, the Federal Revenue Service changes the CNPJ status from Active to Unfit, until regularization is made. Written off: The expression "Written Off" in relation to a CNPJ (National Register of Legal Entities) may indicate that the Federal Revenue Service considered the company as "written off" or "cancelled", that is, the registration of the legal entity has been terminated. This can occur for different reasons, such as the closure of the company's activities, serious tax irregularities, failure to submit mandatory declarations or a voluntary request for dismissal by the company itself. |
ubo_name_match | Verified, Approximate Match, Unverified | Submitted UBO is an exact match against the UBO associated with the CNPJ in the government database. In situations where user has submitted multiple ubo names to be verified against the government source of truth, you will see additional fields called ubo_name_match. You can distinguish ubo_name_match when looking at uboName_input |
"kybSource": { "uboNames": [ { "id": "1", "uboName": "XXX" }, { "id": "2", "uboName": "XXX" } ] } | Full names of the UBOs | This will display the full list of uboNames stored within the government source of truth |
Learning more about Approximate Match : Approximate Match is generated through Incode's proprietary fuzzy matching algorithm. If approximate match is returned, the algorithm has identified a similar match with the string submitted in relation to the string stored in the government source of truth for a particular field. Approximate Match is returned when exact matches are not possible due to misspellings, typographical errors, or slight variations in input data.
Single Session Dashboard Results
They are available on Single Session view under eKYB tab
Updated 30 days ago