API - Document Validations (CPF)
Introduction
Document validation is an essential step to ensure the integrity and reliability of the information provided by individuals in various transactions. In Brazil, the CPF (Cadastro de Pessoa Física) is widely used as a unique identifier for individuals.
The CPF consists of 11 digits and can be sent in plain numeric format or with punctuation (dots and dashes). The API supports both formats and offers endpoints that allow verifying the existence and validity of the information associated with this document.
Examples of valid CPFs:
-
12345678901 -
123.456.789-01
Validation Rules
-
Format:
-
The CPF can be sent with or without formatting.
-
If the CPF is invalid (example:
12345678900), the API will return an error 422 - Unprocessable Entity.
-
The API provides the following endpoints for CPF validation:
-
Basic Registration Data Validation: Returns essential information associated with the CPF.
-
KYC and Compliance Validation: Provides detailed information related to regulatory requirements.
-
Compliance Validation for Online Betting: Returns information on legal or regulatory restrictions associated with the CPF, especially related to the online betting sector.
Endpoints
1. Basic Registration Data Validation
Endpoint: POST /api/validations_documents/basic_data/{cpf}
Description
This endpoint returns basic registration information associated with the queried CPF. It is used for initial validations and identification of fundamental information.
Request
-
Path Parameter:
cpf(string): CPF in a valid format, with or without dots and dashes.Example:
123.456.789-01or12345678901. -
Headers:
Authorization(string, required): Authentication token in Bearer format. -
Request Body:
Not applicable.
Example Request
Basic Data
Error Behavior
-
Invalid CPF: Returns 422 - Unprocessable Entity.
-
Nonexistent CPF in Receita Federal: Returns 200 OK with a message indicating that the CPF is not registered.
Responses
200 - Example: Nonexistent CPF in Receita Federal's database
{
"Result": [
{
"MatchKeys": "doc{02106092888}",
"BasicData": {
"TaxIdStatusDate": "0001-01-01T00:00:00"
}
}
],
"QueryId": "0c8814c9-977b-43bf-8bb8-bcdfea940ce7",
"ElapsedMilliseconds": 86,
"QueryDate": "2024-12-11T20:23:16.6152517Z",
"Status": {
"basic_data": [
{
"Code": -114,
"Message": "INVALID DOC PARAMETER"
}
]
},
"Evidences": {}
}
200 - Example: Valid CPF with Data
{
"Result": [
{
"MatchKeys": "doc**********84}",
"BasicData": {
"TaxIdNumber": "140*****254",
"TaxIdCountry": "BRAZIL",
"AlternativeIdNumbers": {},
"ExtendedDocumentInformation": {
"RG": {
"DocumentLast4Digits": "1225",
"CreationDate": "2020-11-28T23:03:40.212Z",
"LastUpdateDate": "2020-11-28T23:03:40.212Z",
"Sources": [
"ENADE"
]
}
},
"Name": "JOS************MAR",
"Aliases": {
"CommonName": "JOSE******MAR",
"StandardizedName": "JOS************MAR"
},
"Gender": "M",
"NameWordCount": 3,
"NumberOfFullNameNamesakes": 1,
"NameUniquenessScore": 1,
"FirstNameUniquenessScore": 0.001,
"FirstAndLastNameUniquenessScore": 0.001,
"BirthDate": "1986-08-05T00:00:00Z",
"Age": 28,
"ZodiacSign": "LEAO",
"ChineseSign": "Rat",
"BirthCountry": "BRASILEIRA",
"MotherName": "LED****************IRA",
"FatherName": "",
"MaritalStatusData": {},
"TaxIdStatus": "REGULAR",
"TaxIdOrigin": "RECEITA FEDERAL",
"TaxIdFiscalRegion": "ES-RJ",
"HasObitIndication": false,
"TaxIdStatusDate": "2024-08-11T00:00:00",
"TaxIdStatusRegistrationDate": "2009-12-14T00:00:00Z",
"CreationDate": "2016-08-23T00:00:00Z",
"LastUpdateDate": "2024-09-10T00:00:00Z"
}
}
],
"QueryId": "9b57e2c0-9324-43cb-a200-c986eb841912",
"ElapsedMilliseconds": 70,
"QueryDate": "2024-09-24T18:47:32.3585033Z",
"Status": {
"basic_data": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
200 - Example: Valid CPF without Data
{
"Result": [
{
"MatchKeys": "doc**********87}",
"BasicData": {
"TaxIdStatusDate": "0001-01-01T00:00:00"
}
}
],
"QueryId": "84c33c28-2865-41fe-a520-90dbc1d047f4",
"ElapsedMilliseconds": 13458,
"QueryDate": "2024-01-05T10:58:59.5867667Z",
"Status": {
"basic_data": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
2. KYC and Compliance Validation
Endpoint: POST /api/validations_documents/kyc/{cpf}
Description
This endpoint performs advanced KYC (Know Your Customer) validation, returning detailed information such as PEPs (Politically Exposed Persons) history and sanctions.
Request
-
Path Parameter:
cpf(string): CPF in a valid format, with or without dots and dashes.Example:
123.456.789-01or12345678901. -
Headers:
Authorization(string, required): Authentication token in Bearer format. -
Request Body:
query_parameters(object, optional): Additional configurations for the analysis.minmatch(integer, optional): Minimum expected match level.Default value: `95`
Example Request
KYC e Compliance - minmatch = 95
Exemplo de Requisição
KYC e Compliance - minmatch = 100
- The
minmatchparameter defines the minimum match level expected for validation, with valid values ranging from 0 to 100.
Error Behavior
-
Invalid CPF: Returns 422 - Unprocessable Entity.
-
Nonexistent CPF in Receita Federal: Returns 200 OK, but with empty information in the response.
Responses
200 - Example: Nonexistent CPF
200 - Example: Valid CPF with Data
{
"Result": [
{
"MatchKeys": "doc**********11}",
"KycData": {
"PEPHistory": [
{
"Level": "1",
"JobTitle": "PRESIDENTE",
"Department": "COMPANHIA DE TESTE (2011)",
"Motive": "STATE EMPLOYEE",
"Source": "QSA",
"TaxId": "122*****301",
"StartDate": "2023-08-16T00:00:00Z",
"EndDate": "2029-10-11T00:00:00Z"
}
],
"IsCurrentlyPEP": true,
"SanctionsHistory": [
{
"Source": "ofac",
"Type": "Money Laundering",
"StandardizedSanctionType": "FINANCIAL CRIMES",
"MatchRate": 51,
"NameUniquenessScore": "0,125",
"Details": {
"OriginalName": "LUC**************MES",
"SanctionName": "LUC*************NES",
"BirthDate": "15 Dec 1975",
"StandardizedBirthDate": "1975-12-15T00:00:00",
"SourcePossibleDateOfBirthScore": "0",
"SanctionAliases|MatchRate": "El Borrego|5",
"remarks": "(linked to: LA TEST)"
},
"NormalizedDetails": {
"OriginalName": "LUC**************MAR",
"SanctionName": "LUC*************MAR",
"SanctionAliasesAndMatchRate": "El Borrego|5",
"BirthDate": "12 Dec 1978",
"StandardizedBirthDate": "1975-12-15T00:00:00",
"SourcePossibleDateOfBirthScore": "0"
},
"StartDate": "0001-01-01T00:00:00",
"EndDate": "9999-12-31T23:59:59.9999999",
"CreationDate": "2024-11-01T03:04:52.705",
"LastUpdateDate": "2024-11-01T03:04:52.705",
"IsCurrentlyPresentOnSource": true,
"WasRecentlyPresentOnSource": true
},
{
"Source": "ofac",
"Type": "Money Laundering",
"StandardizedSanctionType": "FINANCIAL CRIMES",
"MatchRate": 50,
"NameUniquenessScore": "0,125",
"Details": {
"OriginalName": "LUC**************MES",
"SanctionName": "LUC*****************ANO",
"BirthDate": "13 Dec 1946",
"StandardizedBirthDate": "1946-12-13T00:00:00",
"SourcePossibleDateOfBirthScore": "0"
},
"NormalizedDetails": {
"OriginalName": "LUC**************MES",
"SanctionName": "LUC*****************ANO",
"BirthDate": "13 Dec 1946",
"StandardizedBirthDate": "1946-12-13T00:00:00",
"SourcePossibleDateOfBirthScore": "0"
},
"StartDate": "0001-01-01T00:00:00",
"EndDate": "9999-12-31T23:59:59.9999999",
"CreationDate": "2024-11-01T03:03:46.034",
"LastUpdateDate": "2024-11-01T03:03:46.034",
"IsCurrentlyPresentOnSource": true,
"WasRecentlyPresentOnSource": true
}
],
"IsCurrentlySanctioned": false,
"WasPreviouslySanctioned": false,
"Last30DaysSanctions": 0,
"Last90DaysSanctions": 0,
"Last180DaysSanctions": 0,
"Last365DaysSanctions": 0,
"LastYearPEPOccurence": 1,
"Last3YearsPEPOccurence": 0,
"Last5YearsPEPOccurence": 0,
"Last5PlusYearsPEPOccurence": 0,
"FirstPEPOccurenceDate": "2023-08-16T00:00:00Z",
"LastPEPOccurenceDate": "2023-08-16T00:00:00Z",
"FirstSanctionDate": "0001-01-01T00:00:00",
"LastSanctionDate": "0001-01-01T00:00:00",
"IsCurrentlyElectoralDonor": false,
"IsHistoricalElectoralDonor": true,
"TotalElectoralDonations": 2,
"TotalElectoralDonationAmount": 30000,
"ElectoralDonations": {
"2016": {
"DonationsCount": 2,
"AmountDonated": 30000
}
}
}
}
],
"QueryId": "1f88c0fb-c648-4a92-88ac-c5769e9f28e2",
"ElapsedMilliseconds": 147,
"QueryDate": "2023-10-01T17:19:13.7795502Z",
"Status": {
"kyc": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
200 - Example: Valid CPF without Data
{
"Result": [
{
"MatchKeys": "doc**********64}",
"KycData": {
"PEPHistory": [],
"IsCurrentlyPEP": false,
"SanctionsHistory": [],
"IsCurrentlySanctioned": false,
"WasPreviouslySanctioned": false,
"Last30DaysSanctions": 0,
"Last90DaysSanctions": 0,
"Last180DaysSanctions": 0,
"Last365DaysSanctions": 0,
"LastYearPEPOccurence": 0,
"Last3YearsPEPOccurence": 0,
"Last5YearsPEPOccurence": 0,
"Last5PlusYearsPEPOccurence": 0,
"IsCurrentlyElectoralDonor": false,
"IsHistoricalElectoralDonor": false,
"TotalElectoralDonations": 0,
"TotalElectoralDonationAmount": 0,
"ElectoralDonations": {}
}
}
],
"QueryId": "f6ccee7f-da9b-4282-b588-15e6cc917777",
"ElapsedMilliseconds": 150,
"QueryDate": "2024-11-01T17:19:16.2869226Z",
"Status": {
"kyc": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
3. Compliance Validation for Online Betting
Endpoint: POST /api/validations_documents/check_aptitude/{cpf}
Description
This endpoint checks if the provided CPF is associated with legal or regulatory restrictions specific to the online betting sector. It is used to determine an individual's eligibility to participate in betting activities based on self-exclusion lists and other relevant restrictions.
Request
-
Path Parameter:
cpf(string): CPF in a valid format, with or without dots and dashes.Example:
123.456.789-01or12345678901. -
Headers:
Authorization(string, required): Authentication token in Bearer format. -
Request Body:
Not applicable.
Example Request
Compliance for Online Betting
Error Behavior
-
Invalid CPF: Returns 422 - Unprocessable Entity.
-
Nonexistent CPF in Receita Federal: Returns 200 OK, but with information indicating that the CPF has no associated restrictions.
Responses
200 - Example: Nonexistent CPF
{
"Result": [
{
"MatchKeys": "doc{01406092888}",
"OnlineBettingCompliance": {}
}
],
"QueryId": "3fca8f74-bd1e-467f-b777-6cf6f6115e94",
"ElapsedMilliseconds": 95,
"QueryDate": "2024-12-11T22:35:45.680699Z",
"Status": {
"online_betting_compliance": [
{
"Code": -114,
"Message": "INVALID DOC PARAMETER"
}
]
},
"Evidences": {}
}
200 - Example: CPF with Restrictions
{
"Result": [
{
"MatchKeys": "doc**********77}",
"OnlineBettingCompliance": {
"SportsExposure": {
"Sports": [
{
"SportName": "SO**QR",
"Region": "BRAZIL",
"TotalRelatedEntities": 1,
"RelatedEntities": [
{
"DocNumber": "808*****850",
"DocType": "CPF",
"RelationshipLevel": "BUSINESS PARTNER",
"InstitutionName": "FLA**NGO",
"InstitutionActivity": "CLUBES SOCIAIS, ESPORTIVOS E SIMILARES",
"Role": "MANAGER",
"IsActive": true,
"StartDate": "0001-01-01T00:00:00",
"EndDate": "9999-12-31T23:59:59.9999999",
"Source": "FLAMENGOCOUNCIL"
}
]
}
]
},
"ForbiddenBet": {
"Name": "PED*************************AES",
"Age": "53",
"TaxIdStatus": "REGULAR",
"IsFromMinisterioDaFazenda": false,
"IsBookmakerOwner": true,
"BookmakerOwnerMotives": [
{
"Source": "SIGAP",
"CNPJ": "46786961000174",
"CompanyName": "KAI********************DA.",
"EconomicActivityCodes": "6463800;7319004;9200399",
"AdditionalDetails": {
"SIGAPApplicationNumber": "000**024",
"SIGAPRegistrationDate": "2024-05-26 22:35:16"
}
}
],
"MinisterioDaFazendaMotives": {}
}
}
}
],
"QueryId": "fb90339c-787a-4001-a30f-dfecc5a21a4b",
"ElapsedMilliseconds": 854,
"QueryDate": "2024-12-10T17:41:30.6211076Z",
"Status": {
"online_betting_compliance": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}
200 - Example: CPF Without Restrictions
{
"Result": [
{
"MatchKeys": "doc**********88}",
"OnlineBettingCompliance": {
"SportsExposure": {
"Sports": []
},
"ForbiddenBet": {
"Name": "JOA*****************************MAR",
"Age": "1",
"TaxIdStatus": "REGULAR",
"IsFromMinisterioDaFazenda": false,
"IsBookmakerOwner": false,
"BookmakerOwnerMotives": [],
"MinisterioDaFazendaMotives": {}
}
}
}
],
"QueryId": "708fa54e-488e-4778-a090-297a82f2f959",
"ElapsedMilliseconds": 136,
"QueryDate": "2024-12-10T17:41:31.507089Z",
"Status": {
"online_betting_compliance": [
{
"Code": 0,
"Message": "OK"
}
]
},
"Evidences": {}
}