🪪 CPF Status

The CPF Status report validates Brazil’s national tax identification number (Cadastro de Pessoas Físicas) and retrieves associated personal data from the official Receita Federal database.

Overview

CPF Status validation is the foundation of identity verification in Brazil. This report validates the CPF format, confirms its existence in the national tax registry, and retrieves associated personal information for cross-verification with other reports.

Input Requirements

Required Fields

Field	Type	Description	Example
`document_id`	string	11-digit CPF number	`12345678901`
`city_locode`	string	UN LOCODE of the city	`BR SAO`

Optional Fields

Field	Type	Description	Default
`full_name`	string	Expected full name for verification	`null`
`date_of_birth`	string	Expected date of birth (YYYY-MM-DD)	`null`

CPF Format Specification

The CPF follows a specific 11-digit format with check digits:

000.000.000-00

Format Breakdown

Position	Characters	Description	Example
1-9	Numbers	Sequential identification digits	`123456789`
10	Number	First check digit	`0`
11	Number	Second check digit	`1`

Check Digit Algorithm

The CPF uses a specific algorithm to validate the last two digits:

// CPF check digit calculation
function validateCPF(cpf) {
  // Remove formatting
  cpf = cpf.replace(/[^\d]/g, '');

  if (cpf.length !== 11) return false;

  // Calculate first check digit
  let sum = 0;
  for (let i = 0; i < 9; i++) {
    sum += parseInt(cpf[i]) * (10 - i);
  }
  let firstDigit = 11 - (sum % 11);
  if (firstDigit >= 10) firstDigit = 0;

  // Calculate second check digit
  sum = 0;
  for (let i = 0; i < 10; i++) {
    sum += parseInt(cpf[i]) * (11 - i);
  }
  let secondDigit = 11 - (sum % 11);
  if (secondDigit >= 10) secondDigit = 0;

  return parseInt(cpf[9]) === firstDigit && parseInt(cpf[10]) === secondDigit;
}

Data Source

Registry: Receita Federal do Brasil (Brazilian Federal Revenue Service) Authority: Ministério da Fazenda (Ministry of Finance) Coverage: All Brazilian citizens and legal residents with tax obligations Update Frequency: Real-time

Response Schemas

Successful Validation - Active CPF

{
  "id": "f170bf78-9309-46d4-8723-3e964ed7844d",
  "reports": {
    "cpf_status": {
      "state": "COMPLETED",
      "created_at": "2021-03-30T04:48:11.144178",
      "updated_at": "2021-03-30T04:48:24.050517",
      "outcome": "PASSED",
      "details": {
        "cpf": "12345678901",
        "cpf_status": "REGULAR",
        "full_name": "JUAN MIGUEL DOE ROE",
        "date_of_birth": "1985-08-13",
        "validation": {
          "format_valid": true,
          "check_digit_valid": true,
          "registry_found": true
        }
      }
    }
  }
}

Deceased Person Response

{
  "id": "f170bf78-9309-46d4-8723-3e964ed7844d",
  "reports": {
    "cpf_status": {
      "state": "COMPLETED",
      "created_at": "2021-03-30T04:48:11.144178",
      "updated_at": "2021-03-30T04:48:24.050517",
      "outcome": "FAILED",
      "details": {
        "cpf": "12345678901",
        "cpf_status": "TITULAR FALECIDO",
        "full_name": "JUAN MIGUEL DOE ROE",
        "date_of_birth": "1900-01-01",
        "validation": {
          "format_valid": true,
          "check_digit_valid": true,
          "registry_found": true,
          "status_reason": "DECEASED"
        }
      }
    }
  }
}

Pending Regularization Response

{
  "id": "f170bf78-9309-46d4-8723-3e964ed7844d",
  "reports": {
    "cpf_status": {
      "state": "COMPLETED",
      "created_at": "2021-03-30T04:48:11.144178",
      "updated_at": "2021-03-30T04:48:24.050517",
      "outcome": "FAILED",
      "details": {
        "cpf": "12345678901",
        "cpf_status": "PENDENTE DE REGULARIZAÇÃO",
        "full_name": "ELIELSON LINO DE JESUS",
        "date_of_birth": "1975-05-20",
        "validation": {
          "format_valid": true,
          "check_digit_valid": true,
          "registry_found": true,
          "status_reason": "PENDING_REGULARIZATION"
        }
      }
    }
  }
}

Invalid CPF Response

{
  "id": "f170bf78-9309-46d4-8723-3e964ed7844d",
  "reports": {
    "cpf_status": {
      "state": "COMPLETED",
      "created_at": "2021-03-30T04:48:11.144178",
      "updated_at": "2021-03-30T04:48:24.050517",
      "outcome": "FAILED",
      "details": {
        "cpf": "INVALID12345",
        "validation": {
          "format_valid": false,
          "check_digit_valid": false,
          "registry_found": false,
          "errors": [
            "Invalid CPF format",
            "Check digit mismatch",
            "Not found in Receita Federal registry"
          ]
        }
      }
    }
  }
}

CPF Status Types

Regular Status (REGULAR)

Meaning: CPF is active and in good standing
Outcome: PASSED
Usage: Can be used for all transactions and verifications

Deceased (TITULAR FALECIDO)

Meaning: CPF holder is deceased
Outcome: FAILED
Usage: CPF should not be used for new transactions

Pending Regularization (PENDENTE DE REGULARIZAÇÃO)

Meaning: CPF has issues requiring resolution with Receita Federal
Outcome: FAILED
Usage: CPF holder must resolve issues before normal use

Suspended (SUSPENSO)

Meaning: CPF is temporarily suspended
Outcome: FAILED
Usage: Requires resolution with tax authorities

Cancelled (CANCELADO)

Meaning: CPF has been cancelled
Outcome: FAILED
Usage: Cannot be used for any transactions

Validation Process

Format Validation Steps

Length Check: Must be exactly 11 digits
Character Validation: Only numeric characters allowed
Sequential Check: Cannot be all same digits (e.g., 11111111111)
Check Digit Validation: Both check digits must be correct
Known Invalid Patterns: Reject known invalid sequences

Registry Validation

Receita Federal Lookup: Check existence in official database
Status Verification: Confirm current CPF status
Data Retrieval: Extract associated personal information
Cross-Reference: Validate against provided data if available

CPF Status enables and validates other Brazil reports:

Name Check Report

Validates provided full_name against Receita Federal data:

{
  "name_check": {
    "outcome": "PASSED",
    "details": {
      "score": 1.0,
      "full_name": "JUAN MIGUEL DOE ROE",
      "name_fragment_check": false,
      "name_score_min": 1.0
    }
  }
}

DOB Check Report

Validates provided date_of_birth against Receita Federal data:

{
  "dob_check": {
    "outcome": "PASSED",
    "details": {
      "provided_dob": "1985-08-13",
      "registry_dob": "1985-08-13",
      "match": true
    }
  }
}

Name Check Configuration

The name_check report can be customized with specific settings:

Configuration Parameters

name_score_min

Type: Float (0.0 to 1.0)
Default: 1.0 (100% match required)
Description: Minimum similarity score for name matching
Example: 0.98 requires 98% similarity

name_fragment_check

Type: Boolean
Default: false
Description: Enable fragment-based name comparison
Usage: Compares individual name parts separately

Fragment Matching Example

Input Name: “JUAN DOE” Registry Name: “JUAN ANTONIO DOE”

Fragment Scoring Process:

Compare “JUAN” against [“JUAN”, “ANTONIO”, “DOE”] → Score: 1.0
Compare “DOE” against [“JUAN”, “ANTONIO”, “DOE”] → Score: 1.0
Final Score: (1.0 + 1.0) / 2 = 1.0

API Integration Examples

Create Person with CPF Validation

curl -X POST "https://api.emptor.io/v3/br/persons" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "12345678901",
    "city_locode": "BR SAO",
    "full_name": "JUAN MIGUEL DOE ROE",
    "date_of_birth": "1985-08-13",
    "pipeline": {
      "name": "standard_id_check"
    }
  }'

CPF Validation with Custom Name Settings

curl -X POST "https://api.emptor.io/v3/br/persons" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "12345678901",
    "city_locode": "BR SAO",
    "full_name": "JUAN DOE",
    "pipeline": {
      "name": "standard_id_check"
    },
    "report_settings": {
      "name_check": {
        "name_score_min": 0.98,
        "name_fragment_check": true
      }
    }
  }'

Get CPF Report Details

curl -X GET "https://api.emptor.io/v3/br/details/{person_id}/cpf_status" \
  -H "X-Api-Key: YOUR_API_KEY"

Common Validation Errors

Error Type	Description	Resolution
`INVALID_FORMAT`	CPF doesn’t match 11-digit pattern	Verify CPF format (000.000.000-00)
`INVALID_CHECK_DIGIT`	Check digit calculation fails	Verify CPF was entered correctly
`SEQUENTIAL_DIGITS`	All digits are the same	Use a valid CPF number
`NOT_FOUND_IN_REGISTRY`	CPF not found in Receita Federal	Verify CPF exists and is issued
`REGISTRY_TIMEOUT`	Receita Federal database timeout	Retry after a few minutes
`DECEASED_HOLDER`	CPF holder is deceased	Cannot use deceased person’s CPF
`PENDING_REGULARIZATION`	CPF requires tax resolution	Resolve issues with Receita Federal

Use Cases and Applications

Primary Applications

Identity Verification: Primary identity check for Brazilian individuals
Tax Compliance: Verify tax registration and status
Financial Services: Account opening and KYC compliance
Employment Verification: Validate employee tax registration
Government Services: Citizen service verification

Integration Workflows

Basic Identity Check

CPF Status → Name Check → DOB Check

Standard Background Check

CPF Status → Name Check → DOB Check → Criminal Records → Employment History

Financial KYC

CPF Status → Name Check → DOB Check → Credit Check → Risk Assessment

Create Person - Initiate CPF validation
Get Reports - Retrieve CPF results
Get Report Details - Detailed CPF data
Update Reports - Refresh CPF validation

Name Check Reference - Name validation
DOB Check Reference - Date of birth validation
Brazil Country Guide - Brazil-specific information
Legal Glossary - Legal terminology