🇧🇷 Overview

In this section, you will find information on the input data required for the profile of a person in Brazil, the reports available, the report settings and how to perform queries to create a person, get a person’s status and its reports details.

Have you read our intro?

This section contains the specifics about the input profile and the reports available in Brazil. To better understand it, we recommend you take a look at our Getting Started section too. 😊

Profile

Input field	Description	Example
city_locode	The UN LOCODE of the city where the person is located (or another city according to your needs to direct the BGC process). Always required.	BR CWB
document_id	Document ID Number for Brazil. Cadastro de Pessoa Física (CPF) digits.	000.000.000-00
document_id_alt	Alternate Document ID Number for Brazil. Registro Geral (RG) number.	00000000
dob	ISO 8601 representation of the date the person was born.	1985-08-13
full_name	Full Name of the person to be checked.	ANTONIO DOE
mothers_full_name	Full Name of the Person’s mother. Optional field. If provided, it’s used for homonyms check.	JANE DOE
fathers_full_name	Full Name of the Person’s father. Optional field. If provided, it’s used for homonyms check.	RICHARD ROE

Available reports

Report name	Description	Source/database
CPF Status	Validates a CPF number (document_id) and retrieves the personal data from Receita Federal database.	Receita Federal
Name Check	Checks full_name provided against full_name registered in the Receita Federal database.	Receita Federal
DOB Check	Checks dob provided against dob registered in the Receita Federal database.	Receita Federal
Arrest Warrants	Checks for active arrest warrants issued for the candidate.	Banco Nacional de Medidas Penais e Prisões (BNMP)
Criminal Records	Checks for criminal sentence execution processes (execução de pena) across all state, federal and military courts of the country.	SEEU
State Records	Search for criminal records by CPF in all of the state courts (TJs).	State Courts (TJs)

Want to jump into action?

Check out our API Reference section and start using it right away! 😄

Report settings

The report_settings object is the place for you to customize specific behaviours of the reports available. In Brazil, the report name_check can be customized to determine the best rule for your users/candidates pipeline according to the data you have available from them.

Name Check report

There are two available settings for the name_check report:

1. name_score_min: This is a float number that ranges from 0 to 1, considering up two decimal places. It determines the minimum required score for the full_name provided in order to return a PASSED outcome. Default value is 1 (100%). Example: if name_score_min=0.98, it means the full_name provided needs to have at least 98% similarity with the full_name associated with the document_id (when name_fragment_check is not enabled).

2. name_fragment_check: This is a boolean value (either True or False) that will determine if the score should be calculated by a direct comparison of the whole full_name provided against the full_name found in the database for the document_id. When set to False, the score will be the result of a string comparison between full_name provided and full_name found in the document_id database. If set to True, the score will be the average of the scores of each fragment of the full_name provided, where the score of each fragment is the highest score for each input full_name fragment from the comparisons with each fragment of the full_name found in the document_id database. Default value is False).

Emptorite Tips 🕵️‍♀️

How to calculate the score in with name_fragment_check

Input Full Name: JUAN DOE Document ID Full Name: JUAN ANTONIO DOE

Step 1:

Get the scores between of the comparison between each fragment of the Input Full Name and each fragment of the Document ID Full Name.

1st fragment (JUAN): JUAN x JUAN: 1.0 JUAN x ANTONIO: 0.36 JUAN x DOE: 0.0 Highest value: 1.0

---

2nd fragment (DOE): DOE x JUAN: 0.0 DOE x ANTONIO: 0.2 DOE x DOE: 1.0 Highest value: 1.0

---

Step 2:

Get the score for each fragment of the full_name provided from the highest score for each fragment calculated in the previous step:

1st fragment (JUAN) score: 1.0 2nd fragment (DOE) score: 1.0

---

Step 3:

Get the final score by the average between the scores of each fragment score:

1st fragment (JUAN) score + 2nd fragment (DOE) score / 2 => 1.0 + 1.0 / 2 => 2/2 = 1.0

---

Final score: 1.0

Example requests

Create a Person

To create a person, copy and paste the following command or code, replacing the dummy data with the person’s data you want to use and the YOUR_API_KEY string with your API Key, respectively:

curl --request POST \
  --url https://api.emptor.io/v3/br/persons/ \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"reports":{"national_criminal_record":"enabled"},"city_locode":"BR CWB","document_id":"000.000.000-00","document_id_alt":"00000000","dob":"1985-08-13","full_name":"ANTONIO DOE","mothers_full_name":"JANE DOE","fathers_full_name":"RICHARD ROE"}'

const fetch = require('node-fetch');

let url = 'https://api.emptor.io/v3/br/persons/';

let options = {
  method: 'POST',
  headers: {Accept: 'application/json', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    reports: {national_criminal_record: 'enabled'},
    city_locode: 'BR CWB',
    document_id: '000.000.000-00',
    document_id_alt: '00000000',
    dob: '1985-08-13',
    full_name: 'ANTONIO DOE',
    mothers_full_name: 'JANE DOE',
    fathers_full_name: 'RICHARD ROE'
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.emptor.io/v3/br/persons/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Post.new(url)
request["Accept"] = 'application/json'
request["Content-Type"] = 'application/json'
request.body = "{\"reports\":{\"national_criminal_record\":\"enabled\"},\"city_locode\":\"BR CWB\",\"document_id\":\"000.000.000-00\",\"document_id_alt\":\"00000000\",\"dob\":\"1985-08-13\",\"full_name\":\"ANTONIO DOE\",\"mothers_full_name\":\"JANE DOE\",\"fathers_full_name\":\"RICHARD ROE\"}"

response = http.request(request)
puts response.read_body

import requests

url = "https://api.emptor.io/v3/br/persons/"

payload = {
    "reports": {"national_criminal_record": "enabled"},
    "city_locode": "BR CWB",
    "document_id": "000.000.000-00",
    "document_id_alt": "00000000",
    "dob": "1985-08-13",
    "full_name": "ANTONIO DOE",
    "mothers_full_name": "JANE DOE",
    "fathers_full_name": "RICHARD ROE"
}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

response = requests.request("POST", url, json=payload, headers=headers)

print(response.text)

Get person’s status

To get a person’s status, you will need the person_id returned by our API in the Create a Person step. Use that with your API Key inside the following command or code (in the example below, the person_id is 0597f9f8-2ea5-4557-b3a1-5a590ed96ef4):

curl --request GET \
  --url https://api.emptor.io/v3/br/persons/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4/status \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY'

const fetch = require('node-fetch');

let url = 'https://api.emptor.io/v3/br/persons/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4/status';

let options = {
  method: 'GET',
  headers: {Accept: 'application/json', 'X-Api-Key': 'YOUR_API_KEY'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.emptor.io/v3/br/persons/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'
request["X-Api-Key"] = 'YOUR_API_KEY'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.emptor.io/v3/br/persons/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4/status"

headers = {
    "Accept": "application/json",
    "X-Api-Key": "YOUR_API_KEY"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

Get reports details

To get the details for the person’s reports, you will need the person_id returned in the Create a Person step. Use that with your API Key inside the following command or code (in the example below, the person_id is 0597f9f8-2ea5-4557-b3a1-5a590ed96ef4):

curl --request GET \
  --url https://api.emptor.io/v3/br/details/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4 \
  --header 'Accept: application/json' \
  --header 'X-Api-Key: YOUR_API_KEY'

const fetch = require('node-fetch');

let url = 'https://api.emptor.io/v3/br/details/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4';

let options = {
  method: 'GET',
  headers: {Accept: 'application/json', 'X-Api-Key': 'YOUR_API_KEY'}
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error('error:' + err));

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api.emptor.io/v3/br/details/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Get.new(url)
request["Accept"] = 'application/json'
request["X-Api-Key"] = 'YOUR_API_KEY'

response = http.request(request)
puts response.read_body

import requests

url = "https://api.emptor.io/v3/br/details/0597f9f8-2ea5-4557-b3a1-5a590ed96ef4"

headers = {
    "Accept": "application/json",
    "X-Api-Key": "YOUR_API_KEY"
}

response = requests.request("GET", url, headers=headers)

print(response.text)

How to get an API Key

The API Key is the token you will need to authenticate at our systems. If you still need to get one, please contact us.