VerifAI Smart OCR
AI-powered analysis of generic Brazilian documents that combines OCR (text extraction) with a generative model that classifies the document, extracts structured fields and feeds dedicated validation rules. The service is engineered for documents that the standard Document OCR does not cover (proof of residence, proof of income, social contract, power of attorney and arbitrary documents) and is the only OCR-style service that exposes ready-to-use validation rules out of the box.
Section: smartOcr
Required files: any document file (application/pdf, image/png, image/jpeg, image/bmp, image/webp, image/heic, image/heif).
Verif AI Smart OCR runs only when the transaction template explicitly enables it. Configuration of supported document classes, expiration windows and required terms lives in the template — the request body only carries the runtime parameters listed below.
Request parameters
When the service is enabled, three optional fields can be passed inside the attributes object of POST /transactions. They are forwarded to the Smart OCR validation rules; the extraction itself runs regardless of these values.
attributes.holderName
string
Document Holder
Expected document holder name. Compared (case-insensitive, accent-insensitive, substring match) against the holder name extracted from the document (customerName, employeeName, taxpayerName, shareholderName1, etc., depending on the document class).
attributes.holderCpf
string (only digits, 11 chars)
Document Holder
Expected document holder CPF. Compared (digits only) against the CPF extracted from the document (customerPersonalTaxId, employeePersonalTaxId, taxpayerPersonalTaxId, shareholderPersonalTaxId1). When omitted, falls back to attributes.cpf.
attributes.analysisDate
string (YYYY-MM-DD)
Document Validity
Reference date used to compute the document age. Defaults to the request date when omitted. Documents with an issue date in the future relative to this value are always considered invalid.
All three fields are optional. The Document Holder rule needs at least one of holderName / holderCpf (or cpf) to be informative — when neither is provided, the rule cannot be evaluated and stays PENDING.
Extracted CPF fields (e.g. customerPersonalTaxId) may include formatting characters (dots and dashes); comparisons use digits only. Send attributes.holderCpf with 11 digits only, without punctuation.
Request example:
{
"templateId": "your_template_id",
"attributes": {
"cpf": "12345678901",
"holderName": "Maria Silva Santos",
"holderCpf": "12345678901",
"analysisDate": "2025-08-15"
},
"files": [{ "data": "https://example.com/proof-of-residence.pdf", "type": "ATTACHMENTS" }]
}Document classification
Smart OCR classifies the uploaded document into one of the supported classes before extracting structured fields. Classification combines text features (OCR) and visual features (the generative model), so each document is processed only with the schema relevant to its class.
PROOF_OF_RESIDENCE
—
Utility bills (energy, water, gas), telecom invoices, bank statements, condo bills.
PROOF_OF_INCOME
—
Pay slips (holerite/contracheque), employment letters with income, social security benefit statements.
PROOF_OF_INCOME
INCOME_TAX_RETURN
Income tax return receipts and statements (DIRPF / Recibo de Entrega).
SOCIAL_CONTRACT
—
Company social contracts, articles of association and consolidated amendments.
POWER_OF_ATTORNEY
—
Public, private and digital powers of attorney (procurações).
GENERIC
—
Generic documents that do not match the categories above (invoices, contracts, declarations).
The classification result and the subclass (when applicable) are returned inside the smartOcr section together with the extracted fields, so downstream consumers can decide how to interpret the payload.
Specific attributes (PROOF_OF_RESIDENCE)
relatedMonth
Integer
Reference month of the proof of residence (1-12, no leading zero).
relatedYear
Integer
Reference year of the proof of residence (4 digits).
issueDate
String
Issue date of the document (DD/MM/YYYY).
dueDate
String
Due date of the document (DD/MM/YYYY).
companyName
String
Issuer company legal/fantasy name (Razão Social).
companyBusinessTaxId
String
Issuer company CNPJ (formatting and masking characters preserved).
companyAddress
String
Issuer company address.
customerName
String
Document holder full name.
customerPersonalTaxId
String
Document holder CPF (formatting and masking characters preserved).
customerBusinessTaxId
String
Document holder CNPJ, when applicable.
customerCompleteAddress
String
Holder complete address as printed in the document.
customerAddressStreet
String
Street component of the holder address.
customerAddressNumber
String
Number component of the holder address.
customerAddressNeighborhood
String
Neighborhood (bairro) component of the holder address.
customerAddressCity
String
City component of the holder address.
customerAddressState
String
Brazilian state (UF) component of the holder address.
customerAddressPostalCode
String
CEP component of the holder address.
customerAddressExtraInfo
String
Address extra information / complemento.
Validation rule
Behaviour for PROOF_OF_RESIDENCE
Document Validity
Uses issueDate (or relatedMonth + relatedYear when issue date is missing) compared against attributes.analysisDate. Default expiration window is 180 days; can be customized in the template via documentTypeRules (maxDays, maxMonths, lastMonth, lastYear).
Document Holder
Compares attributes.holderName against customerName (substring, case/accent-insensitive) and/or attributes.holderCpf (or attributes.cpf) against customerPersonalTaxId (digits only). At least one match makes the rule valid.
Required Fields
Validates that every term configured in the template (requiredTerms) is present in the extraction.
Address Completeness
Validates each individual component (customerAddressStreet, customerAddressNumber, customerAddressPostalCode, customerAddressNeighborhood, customerAddressCity). All five must be present and non-empty.
Specific attributes (PROOF_OF_INCOME)
relatedMonth
Integer
Reference month (1-12).
relatedYear
Integer
Reference year (4 digits).
companyName
String
Employer legal/fantasy name (Razão Social).
companyBusinessTaxId
String
Employer CNPJ.
companyCompleteAddress
String
Employer complete address.
companyAddressStreet
String
Employer street component.
companyAddressNumber
String
Employer number component.
companyAddressNeighborhood
String
Employer neighborhood component.
companyAddressCity
String
Employer city component.
companyAddressState
String
Employer Brazilian state (UF).
companyAddressPostalCode
String
Employer CEP.
companyAddressExtraInfo
String
Employer address extra information.
employeeName
String
Employee full name.
employeePersonalTaxId
String
Employee CPF.
employeeCompleteAddress
String
Employee complete address.
employeeRole
String
Employee job position/role.
employeeContractType
String
Contract type (e.g. Prazo indeterminado, Temporário, Prazo determinado).
employeeHireDate
String
Hire date (DD/MM/YYYY).
employeeEndDate
String
Contract end date (empty when employmentStatus is Aberto).
employeeBaseIncome
Float
Base income amount (no R$/symbols).
employeeGrossIncome
Float
Gross income amount.
employeeTotalDeductions
Float
Total deductions amount.
employeeNetIncome
Float
Net income (employeeGrossIncome - employeeTotalDeductions).
employeeBankNumber
String
Bank code/number where the salary is paid.
employeeBankBranchNumber
String
Branch/agency number.
employeeBankAccountNumber
String
Account number.
employeeRetirementIndicative
String
Indicative of retirement status (e.g. Aposentado, Pensão).
employmentStatus
String
Aberto (active) or Encerrado (terminated).
Validation rule
Behaviour for PROOF_OF_INCOME
Document Validity
Uses relatedMonth + relatedYear (end of the reference month) compared against attributes.analysisDate. Default expiration window is 180 days; configurable in the template.
Document Holder
Compares attributes.holderName against employeeName (substring, case/accent-insensitive) and/or attributes.holderCpf (fallback attributes.cpf) against employeePersonalTaxId (digits only).
Required Fields
Validates that every term configured in requiredTerms is present.
Address Completeness
Validates the employee address (employeeCompleteAddress). When the employee address is not extracted, the company address is used and a warning is added.
Specific attributes (PROOF_OF_INCOME · INCOME_TAX_RETURN)
When the document is classified as PROOF_OF_INCOME with subClass = INCOME_TAX_RETURN (Recibo de Entrega da Declaração de Imposto de Renda), a different set of fields is extracted.
fiscalYear
Integer
Fiscal year of the return (e.g. 2024).
calendarYear
Integer
Calendar year of the income reported (e.g. 2023).
taxpayerType
String
Taxpayer type (e.g. personal, business).
taxpayerName
String
Taxpayer full name.
taxpayerPersonalTaxId
String
Taxpayer CPF.
taxpayerBusinessTaxId
String
Taxpayer CNPJ when the return belongs to a legal entity.
taxpayerBirthDate
String
Taxpayer birth date (DD/MM/YYYY).
taxpayerCompleteAddress
String
Taxpayer complete address.
taxpayerEmail
String
Taxpayer e-mail when present.
taxpayerRoleNature
String
Nature of the role (e.g. Empregado, Autônomo).
taxpayerMainRole
String
Taxpayer main role/occupation.
taxpayerTotalTaxableIncome
Float
Total taxable income.
taxpayerTotalNonTaxableIncome
Float
Total non-taxable income.
taxpayerExclusiveTaxableIncome
Float
Exclusive taxable income.
taxpayerCalculatedMontlyIncome
Float
Calculated average monthly income, based on equation (taxpayerTotalTaxableIncome + taxpayerTotalNonTaxableIncome + taxpayerExclusiveTaxableIncome) / 12.
Validation rule
Behaviour for INCOME_TAX_RETURN
Document Validity
Uses the end of fiscalYear (or calendarYear when fiscal year is missing) compared against attributes.analysisDate. Default expiration window is 365 days for tax returns; configurable in the template.
Document Holder
Compares attributes.holderName against taxpayerName and/or attributes.holderCpf (fallback attributes.cpf) against taxpayerPersonalTaxId.
Required Fields
Validates configured requiredTerms.
Address Completeness
Validates taxpayerCompleteAddress as a single string (not component-by-component).
Specific attributes (SOCIAL_CONTRACT)
companyName
String
Company legal/fantasy name (Razão Social).
companyBusinessTaxId
String
Parent company CNPJ.
companyCnae
Array of String
Main activity CNAE codes and descriptions ("o objeto da sociedade").
companyType
String
Company type (e.g. Sociedade Empresária Limitada, Sociedade Simples Limitada).
companyCompleteAddress
String
Company complete address.
companyAddressStreet
String
Company street component.
companyAddressNumber
String
Company number component.
companyAddressNeighborhood
String
Company neighborhood component.
companyAddressCity
String
Company city component.
companyAddressState
String
Company UF.
companyAddressPostalCode
String
Company CEP.
companyAddressExtraInfo
String
Company address extra information.
companyIncorporationDate
String
Company incorporation date (DD/MM/YYYY).
companyIsActive
Boolean
true when the document indicates indefinite duration (no expiration date).
companyQuotasTotal
Integer
Total amount of quotas.
companyQuotasCurrency
String
Currency of the quotas (e.g. BRL).
companyQuotasValue
Float
Value of one quota.
shareholderName{N}
String
Name of shareholder N (1, 2, 3...).
shareholderPersonalTaxId{N}
String
CPF of shareholder N (when shareholder is a person).
shareholderRole{N}
String
Role of shareholder N (e.g. Sócio Administrador, Procurador, Representante Legal).
shareholderPowers{N}
Array of String
Powers granted to shareholder N.
shareholderSignAlone{N}
Boolean
true only when the document explicitly states the shareholder can sign alone.
shareholderSignAloneDescription{N}
String
Textual description of the signing rule.
shareholderRestrictions{N}
Array of String
Restrictions applicable to shareholder N.
shareholderQuotas{N}
Integer
Quotas owned by shareholder N.
shareholderBusinessTaxId{N}
String
CNPJ of shareholder N (when shareholder is a company).
shareholderAddress{N}
String
Address of shareholder N (when shareholder is a company).
shareholderMandateStartDate{N}
String
Mandate start date (when shareholder is a company).
shareholderMandateEndDate{N}
String
Mandate end date (when shareholder is a company).
shareholderSignatureType{N}
String
digital_signature or physical_signature.
shareholderSignatureMet{N}
Boolean
true when the signature was found in the document.
Validation rule
Behaviour for SOCIAL_CONTRACT
Document Validity
Uses companyIncorporationDate compared against attributes.analysisDate. Default window is broader (configurable). Documents whose incorporation date is in the future are always invalid.
Document Holder
Compares attributes.holderName against shareholderName1 (and/or every shareholderName{N}) and attributes.holderCpf (fallback attributes.cpf) against shareholderPersonalTaxId{N}.
Required Fields
Validates configured requiredTerms (typical use: ensure shareholder powers, quotas and incorporation date are present).
Address Completeness
Validates the headquarter address (companyCompleteAddress). When only branch addresses are extracted, an informative warning is added.
Specific attributes (POWER_OF_ATTORNEY)
companyName
String
Granting company name (when applicable).
companyBusinessTaxId
String
Granting company CNPJ.
companyCompleteAddress
String
Company complete address.
companyAddressStreet
String
Company street component.
companyAddressNumber
String
Company number component.
companyAddressNeighborhood
String
Company neighborhood component.
companyAddressCity
String
Company city component.
companyAddressState
String
Company UF.
companyAddressPostalCode
String
Company CEP.
companyAddressExtraInfo
String
Company address extra information.
shareholderName{N}
String
Grantor (outorgante) full name.
shareholderPersonalTaxId{N}
String
Grantor CPF.
shareholderRole{N}
String
Grantor role (e.g. Outorgante, Sócio Administrador).
shareholderPowers{N}
Array of String
Powers granted by grantor N.
shareholderSignAlone{N}
Boolean
Whether grantor N can sign alone.
assigneeName{N}
String
Assignee (outorgado) full name.
assigneeSignsAlone
Boolean
true when the assignee can sign alone after the PoA.
signObservation
String
Observations about the signing rule.
powersGranted
Array of String
Consolidated list of powers granted in the PoA.
type
String
public, private or invalid.
hasExpirationDate
Boolean
true when the PoA has an expiration date.
expirationDate
String
Expiration date (empty when hasExpirationDate is false).
hasNotaryStamps
Boolean
true when at least one notary stamp was found.
notaryStampAuthenticationForm{N}
String
Authentication form of stamp N (Assinado digitalmente via GOV.BR, Reconhecimento de Firma, etc.).
notaryStampName{N}
String
Name on stamp N (when readable).
isValidNotaryStamp{N}
Boolean
Whether stamp N is considered valid.
notaryStampType{N}
String
digital_signature or handwritten_signature.
isValid
Boolean
Final validity decision computed by the model.
textualDecision
String
Textual explanation of isValid.
Validation rule
Behaviour for POWER_OF_ATTORNEY
Document Validity
Uses expirationDate when hasExpirationDate = true; otherwise compares attributes.analysisDate (or the request date when omitted) against the PoA validity window. Documents past expirationDate are always invalid.
Document Holder
Compares attributes.holderName against shareholderName{N} (grantors) and attributes.holderCpf (fallback attributes.cpf) against shareholderPersonalTaxId{N}.
Required Fields
Validates configured requiredTerms (typical use: ensure powers like Abrir conta bancária are explicitly listed).
Address Completeness
Validates companyCompleteAddress as a single string.
Specific attributes (GENERIC)
When the document does not match any of the categories above, Smart OCR falls back to the GENERIC schema with role-based fields. Field names follow the pattern {role}{Property} (e.g. payerName, receiverBusinessTaxId). Fields naming may vary from one document to another;
issueDate
String
Document issue date when present.
dueDate
String
Document due date when present.
payerName
String
Payer / debtor full name.
payerPersonalTaxId
String
Payer CPF.
payerBusinessTaxId
String
Payer CNPJ.
receiverName
String
Receiver / creditor full name.
receiverPersonalTaxId
String
Receiver CPF.
receiverBusinessTaxId
String
Receiver CNPJ.
companyName
String
Company name when applicable.
companyBusinessTaxId
String
Company CNPJ when applicable.
companyAddress
String
Company address when applicable.
companyCompleteAddress
String
Company complete address when applicable.
netAmount
Float
Net monetary amount when present.
grossAmount
Float
Gross monetary amount when present.
Validation rule
Behaviour for GENERIC
Document Validity
Uses issueDate (or dueDate as fallback) compared against attributes.analysisDate. Documents that have neither cannot be validated and stay PENDING.
Document Holder
Compares attributes.holderName against payerName/receiverName and attributes.holderCpf (fallback attributes.cpf) against payerPersonalTaxId/receiverPersonalTaxId.
Required Fields
Validates configured requiredTerms (typical use: ensure that contract clauses are present).
Address Completeness
Validates companyCompleteAddress as a single string when present.
Validation rules
The four smart_ocr rules below can be enabled in the transaction template. The descriptions below document the behaviour exposed publicly; template-only configuration knobs (such as documentTypeRules or requiredTerms) are managed in Trust.
verifai_smart_ocr_document_validity
Document Validity
attributes.analysisDate
VALID, INVALID, PENDING
verifai_smart_ocr_document_holder
Document Holder
attributes.holderName, attributes.holderCpf (fallback attributes.cpf)
VALID, INVALID, PENDING
verifai_smart_ocr_required_fields
Required Fields
— (configured via requiredTerms in the template)
VALID, INVALID, PENDING
verifai_smart_ocr_address_completeness
Address Completeness
—
VALID, INVALID, PENDING
Document Validity (verifai_smart_ocr_document_validity)
Verifies whether the document was issued within the configured maximum window. The rule uses the document issue date, due date or reference month/year (whichever is available for the document class) to compute how many days have passed compared to the analysisDate provided in the request — or the request date when omitted. The default window is 180 days and can be customized per document class via documentTypeRules in the template (maxDays, maxMonths, lastMonth, lastYear). Documents whose date is in the future relative to analysisDate are always considered invalid.
Document Holder (verifai_smart_ocr_document_holder)
Verifies whether the document belongs to the expected holder. The rule compares the holder name and/or CPF extracted from the document with the values informed in attributes.holderName and attributes.holderCpf. Name comparison is case-insensitive and accent-insensitive (substring match); CPF comparison uses digits only. Either match is enough — the rule is VALID when at least one of the provided values matches the corresponding field in the document.
Required Fields (verifai_smart_ocr_required_fields)
Verifies that the terms listed in requiredTerms (configured per document class in the template) are all present in the extraction. A term is considered found when at least one extracted field has a label/metadata correspondence and a non-empty value.
Address Completeness (verifai_smart_ocr_address_completeness)
Verifies whether the document address is complete (street, number, postal code, neighborhood and city). PROOF_OF_RESIDENCE validates each component individually using the dedicated customerAddress* fields, while other document classes validate companyCompleteAddress / taxpayerCompleteAddress as a single string. When PROOF_OF_INCOME or SOCIAL_CONTRACT documents extract only secondary addresses (employee address, branch address), an informative warning is added to the rule output without changing its status.
For configuration of which rules are enabled per template and how availableActions are interpreted, see Validation rules.
Last updated