> For the complete documentation index, see [llms.txt](https://docs.caf.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.caf.io/caf-api/core-api/transaction-details/services/verif-ai-smart-ocr.md). # 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](/caf-api/core-api/transaction-details/services/document-ocr.md) 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`). {% hint style="info" %} Verif AI Smart OCR runs only when the [transaction template](/caf-api/core-api/available-resources/transaction.md) 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. {% endhint %} ## 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. | Field | Type | Used by | Description | | ------------------------- | ------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `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. | {% hint style="info" %} 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. {% endhint %} **Request example:** ```json { "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" }] } ``` ## 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. | Class | Subclass | Typical documents | | -------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ | | `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) {% tabs %} {% tab title="Schema" %} | Attribute | Type | Description | | --------------------------- | ------- | ------------------------------------------------------------------ | | 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. | | {% endtab %} | | | {% tab title="Example" %} ```json { "smartOcr": { "documentClass": "PROOF_OF_RESIDENCE", "subClass": null, "relatedMonth": 3, "relatedYear": 2025, "issueDate": "01/03/2025", "dueDate": "10/03/2025", "companyName": "ENEL DISTRIBUIDORA SP", "companyBusinessTaxId": "61.695.227/0001-93", "companyAddress": "AV PRES JUSCELINO KUBITSCHEK, 222 - SP", "customerName": "Maria Silva Santos", "customerPersonalTaxId": "123.456.789-01", "customerBusinessTaxId": "", "customerCompleteAddress": "RUA OSVALDO ARANHA, 123 BAIRRO CENTRO - SP 01310-000", "customerAddressStreet": "RUA OSVALDO ARANHA", "customerAddressNumber": "123", "customerAddressNeighborhood": "CENTRO", "customerAddressCity": "SAO PAULO", "customerAddressState": "SP", "customerAddressPostalCode": "01310000", "customerAddressExtraInfo": "APTO 501" } } ``` {% endtab %} {% tab title="Validation Rules" %} | 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. | | {% endtab %} | | | {% endtabs %} | | ## Specific attributes (PROOF\_OF\_INCOME) {% tabs %} {% tab title="Schema" %} | Attribute | Type | Description | | ---------------------------- | ------- | ------------------------------------------------------------------------------ | | 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). | | {% endtab %} | | | {% tab title="Example" %} ```json { "smartOcr": { "documentClass": "PROOF_OF_INCOME", "subClass": null, "relatedMonth": 8, "relatedYear": 2025, "companyName": "EMPRESA EXEMPLO LTDA", "companyBusinessTaxId": "12.345.678/0001-90", "companyCompleteAddress": "AV PAULISTA, 1000 BELA VISTA - SP 01310-100", "companyAddressStreet": "AV PAULISTA", "companyAddressNumber": "1000", "companyAddressNeighborhood": "BELA VISTA", "companyAddressCity": "SAO PAULO", "companyAddressState": "SP", "companyAddressPostalCode": "01310100", "companyAddressExtraInfo": "", "employeeName": "Maria Silva Santos", "employeePersonalTaxId": "123.456.789-01", "employeeCompleteAddress": "RUA DAS FLORES, 50 - SP", "employeeRole": "Analista de Sistemas", "employeeContractType": "Prazo indeterminado", "employeeHireDate": "01/02/2020", "employeeEndDate": "", "employeeBaseIncome": 7500.0, "employeeGrossIncome": 8250.0, "employeeTotalDeductions": 1320.5, "employeeNetIncome": 6929.5, "employeeBankNumber": "341", "employeeBankBranchNumber": "1234-5", "employeeBankAccountNumber": "67890-1", "employeeRetirementIndicative": "", "employmentStatus": "Aberto" } } ``` {% endtab %} {% tab title="Validation Rules" %} | 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. | | {% endtab %} | | | {% endtabs %} | | ## 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. {% tabs %} {% tab title="Schema" %} | Attribute | Type | Description | | ------------------------------ | ------- | -------------------------------------------------------- | | 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. `Titular`, `Dependente`). | | 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. | | {% endtab %} | | | {% tab title="Example" %} ```json { "smartOcr": { "documentClass": "PROOF_OF_INCOME", "subClass": "INCOME_TAX_RETURN", "fiscalYear": 2024, "calendarYear": 2023, "taxpayerType": "Titular", "taxpayerName": "Maria Silva Santos", "taxpayerPersonalTaxId": "123.456.789-01", "taxpayerBusinessTaxId": "", "taxpayerBirthDate": "12/05/1985", "taxpayerCompleteAddress": "RUA OSVALDO ARANHA, 123 CENTRO - SP 01310-000", "taxpayerEmail": "maria.silva@example.com", "taxpayerRoleNature": "Empregado", "taxpayerMainRole": "Analista de Sistemas", "taxpayerTotalTaxableIncome": 99000.0, "taxpayerTotalNonTaxableIncome": 12000.0, "taxpayerExclusiveTaxableIncome": 1500.0, "taxpayerCalculatedMontlyIncome": 8250.0 } } ``` {% endtab %} {% tab title="Validation Rules" %} | 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). | | {% endtab %} | | | {% endtabs %} | | ## Specific attributes (SOCIAL\_CONTRACT) {% tabs %} {% tab title="Schema" %} | Attribute | Type | Description | | ---------------------------------- | --------------- | ---------------------------------------------------------------------------------------- | | 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. | | {% endtab %} | | | {% tab title="Example" %} ```json { "smartOcr": { "documentClass": "SOCIAL_CONTRACT", "subClass": null, "companyName": "EMPRESA EXEMPLO LTDA", "companyBusinessTaxId": "12.345.678/0001-90", "companyCnae": [ "62.01-5-01 - Desenvolvimento de programas de computador sob encomenda" ], "companyType": "Sociedade Empresária Limitada", "companyCompleteAddress": "AV PAULISTA, 1000 BELA VISTA - SP 01310-100", "companyAddressStreet": "AV PAULISTA", "companyAddressNumber": "1000", "companyAddressNeighborhood": "BELA VISTA", "companyAddressCity": "SAO PAULO", "companyAddressState": "SP", "companyAddressPostalCode": "01310100", "companyAddressExtraInfo": "", "companyIncorporationDate": "15/01/2018", "companyIsActive": true, "companyQuotasTotal": 100000, "companyQuotasCurrency": "BRL", "companyQuotasValue": 1.0, "shareholderName1": "Maria Silva Santos", "shareholderPersonalTaxId1": "123.456.789-01", "shareholderRole1": "Sócio Administrador", "shareholderPowers1": [ "Abertura e movimentação de contas bancárias", "Assinatura de contratos" ], "shareholderSignAlone1": true, "shareholderSignAloneDescription1": "Assina isoladamente", "shareholderRestrictions1": [], "shareholderQuotas1": 60000, "shareholderBusinessTaxId1": "", "shareholderAddress1": "", "shareholderMandateStartDate1": "", "shareholderMandateEndDate1": "", "shareholderSignatureType1": "digital_signature", "shareholderSignatureMet1": true, "shareholderName2": "João Oliveira", "shareholderPersonalTaxId2": "987.654.321-00", "shareholderRole2": "Sócio", "shareholderQuotas2": 40000, "shareholderSignAlone2": false, "shareholderSignAloneDescription2": "Assina em conjunto com Maria Silva Santos" } } ``` {% endtab %} {% tab title="Validation Rules" %} | 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. | | {% endtab %} | | | {% endtabs %} | | ## Specific attributes (POWER\_OF\_ATTORNEY) {% tabs %} {% tab title="Schema" %} | Attribute | Type | Description | | -------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------- | | 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`. | | {% endtab %} | | | {% tab title="Example" %} ```json { "smartOcr": { "documentClass": "POWER_OF_ATTORNEY", "subClass": null, "companyName": "EMPRESA EXEMPLO LTDA", "companyBusinessTaxId": "12.345.678/0001-90", "companyCompleteAddress": "AV PAULISTA, 1000 BELA VISTA - SP 01310-100", "shareholderName1": "Maria Silva Santos", "shareholderPersonalTaxId1": "123.456.789-01", "shareholderRole1": "Outorgante", "shareholderPowers1": ["Abrir contas bancárias", "Assinar contratos"], "shareholderSignAlone1": true, "assigneeName1": "João Oliveira", "assigneeSignsAlone": true, "signObservation": "Outorgante com poderes para assinar isoladamente.", "powersGranted": [ "Abrir contas bancárias", "Movimentar contas bancárias", "Assinar contratos" ], "type": "public", "hasExpirationDate": true, "expirationDate": "31/12/2026", "hasNotaryStamps": true, "notaryStampAuthenticationForm1": "Reconhecimento de Firma", "notaryStampName1": "Maria Silva Santos", "isValidNotaryStamp1": true, "notaryStampType1": "handwritten_signature", "isValid": true, "textualDecision": "Procuração pública com firma reconhecida e poderes claros para movimentação bancária." } } ``` {% endtab %} {% tab title="Validation Rules" %} | 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. | | {% endtab %} | | | {% endtabs %} | | ## 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`). {% tabs %} {% tab title="Schema" %} | Attribute | Type | Description | | ---------------------- | ------ | ----------------------------------------- | | 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. | | {% endtab %} | | | {% tab title="Example" %} ```json { "smartOcr": { "documentClass": "GENERIC", "subClass": null, "issueDate": "15/08/2025", "dueDate": "26/09/2025", "payerName": "JOÃO DA SILVA", "payerPersonalTaxId": "486.884.452-13", "receiverName": "EMBALAGENS DO SUL LTDA", "receiverBusinessTaxId": "98.765.432/0001-10", "companyName": "EMBALAGENS DO SUL LTDA", "companyBusinessTaxId": "98.765.432/0001-10", "companyAddress": "RUA OSVALDO ARANHA, 123 BAIRRO CENTRO - RS 96800-215", "companyCompleteAddress": "RUA OSVALDO ARANHA, 123 BAIRRO CENTRO - RS 96800-215", "netAmount": 1850.0, "grossAmount": 2000.0 } } ``` {% endtab %} {% tab title="Validation Rules" %} | 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. | | {% endtab %} | | | {% endtabs %} | | ## Validation rules The four `smart_ocr` rules below can be enabled in the [transaction template](/caf-api/core-api/transaction-details/validation-rules.md). The descriptions below document the behaviour exposed publicly; template-only configuration knobs (such as `documentTypeRules` or `requiredTerms`) are managed in Trust. | Rule key | Title | Request parameters | Status values | | ---------------------------------------- | -------------------- | --------------------------------------------------------------------------- | ----------------------------- | | `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](/caf-api/core-api/transaction-details/validation-rules.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.caf.io/caf-api/core-api/transaction-details/services/verif-ai-smart-ocr.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.