Verification of Employment Form Data Extractor: Turn VOE Scans into Typed JSON

If you searched for a verification of employment form data extractor, you are not looking for another wall of OCR text. You need named values from a lender’s request form, an employer reply letter, a third-party VOE PDF, or a phone photo of a completed sheet so your mortgage, HR, or background-check system can store and check them. Short answer: treat the extractor as a schema-field OCR step for the keys your catalog actually supports (applicant name, employer name, address parts), run full-page Markdown for pay, tenure, and free-text remarks, then validate and review in your own code. OCRskill does the extraction half with POST /ocr.json?fields=... and POST /ocr. It does not replace a verbal VOE call, an employment-verification vendor, or an underwriting decision.

This post is about the document extraction slice of employment verification. For identity cards and KYC packets, see the KYC form data extractor. For general multi-field forms, see the form data extraction API guide. For the product overview of typed JSON from images, see structured OCR JSON.

What a verification of employment form actually is

In mortgage and lending, a verification of employment (VOE) is evidence that a borrower works where they said they work, and often what they earn. The paperwork comes in a few common shapes:

Form	Who fills it	What OCR usually sees
Written request / reply (classic paper VOE)	Lender sends a form; employer returns it	Labeled blanks for applicant, employer, tenure, pay, signature block
Verbal VOE worksheet	Lender staff after a phone call	Short confirmation: borrower, employer, contact, status, date
Third-party employment verification PDF	Payroll or employment-verification vendor	Electronic layout with name, employer, status, and effective dates
Employer letter on letterhead	HR or payroll	Free-text paragraphs plus a signature, harder to schema

Fannie Mae still documents a Request for Verification of Employment (Form 1005) used for conventional mortgages. That form asks the employer for the applicant’s date of employment, present position, probability of continued employment, gross base pay and period, overtime and bonus, and (for previous employment) hire and termination dates with reason for leaving. Separately, Fannie Mae’s Selling Guide requires a verbal verification of employment for borrowers using employment income, typically no more than 10 business days on or before the note date. Freddie Mac publishes a short Form 90 verbal VOE worksheet with borrower name, employer name, contact, phone, employment status, and verifier details.

Buyers searching for a “verification of employment form data extractor” usually want four properties at once:

Named fields that match their case record (last_name, first_name, company_name, address parts)
Predictable types so dates land as YYYY-MM-DD and strings arrive trimmed
Required vs optional behavior so a missing applicant name fails closed instead of writing a half-empty file
Upload flexibility for scanner PDFs, email attachments, and phone photos of stamped originals

Plain Markdown OCR helps humans and search indexes. Automation needs columns for the stable keys, and a review path for everything else.

Extraction vs employment verification (do not mix the jobs)

Search results for VOE tools often blur two products:

Job	What it answers	Typical owner
Document data extraction	What values are printed or filled on this page?	OCR / document AI API
Employment verification	Is this person still employed, and is the income usable to qualify?	Lender, HR, or a verification vendor

Extraction pulls first_name, company_name, or a street line from pixels. Verification covers calling the employer from an independently sourced phone number, checking a payroll database, applying Selling Guide timing rules, and deciding whether income qualifies. A solid design keeps them separate: extract first, then verify with systems built for those risks.

OCRskill is the extraction layer. Wire it beside your underwriting and case tools; do not treat a successful JSON response as a completed VOE.

What the extractor can return today

Character recognition is not the hard part. The ops desk needs a short, trusted set of values, and only some of them map to a general field catalog:

Applicant identity: family name, given name (and sometimes a badge or employee number in free text)
Employer identity: company or organization name, and often a postal address
Tenure and status: date hired, date terminated, present position, probability of continued employment
Income: gross base pay, pay period, YTD, overtime, commissions, bonus
Verifier block: employer signer name, title, phone, completion date

OCRskill’s documented catalog covers people names, address parts, and company_name well. It does not publish dedicated keys for job title, base pay, hire date, or “probability of continued employment.” Plan on typed JSON for the stable identity and employer keys, and Markdown (plus your own parsing or a clerk) for pay and tenure lines. That honesty matches how bill of lading OCR handles container numbers that are not in the catalog: extract what the schema supports, validate the rest in code.

Schema-field extraction for the VOE keys that fit

Template engines that read fixed coordinates break when a new lender form appears or when someone photographs a crumpled employer reply at an angle. Schema-field APIs flip the contract: you declare the logical keys you need; the model maps readable content onto those keys without a zone file per form.

That matches how OCRskill’s POST /ocr.json works. You pass a comma-separated fields list. Required names fail with 400 when absent. Optional names use a trailing ? and are omitted when missing. Unknown field names also return 400, so you stay inside the documented catalog.

Use discovery mode (omit fields) only while learning a new VOE layout. Freeze a fixed schema before production traffic so response shape stays stable for your validators.

A practical VOE extraction call

Get a test key, declare the identity and employer fields, upload a VOE image or PDF:

curl https://api.ocrskill.com/get-key.json

export API_KEY="sk-your-key-here"

curl "https://api.ocrskill.com/ocr.json?fields=last_name,first_name,company_name,street_name?,street_number?,town_or_city?,region?,country?" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@voe-employer-reply.pdf"

Example response shape (values are fictional):

{
  "last_name": "EXAMPLE",
  "first_name": "JANE",
  "company_name": "Example Logistics Inc.",
  "street_name": "Warehouse Road",
  "street_number": "1200",
  "town_or_city": "Reno",
  "region": "NV",
  "country": "United States"
}

Mark address parts optional with a trailing ? so a letterhead that only prints the company name does not reject the whole request. Dates on other document types come back as YYYY-MM-DD. A required field the API cannot find returns 400 with the extracted input_text, so the review queue can show what was read.

For the pay and tenure block, run Markdown on the same file and keep it next to the JSON:

curl https://api.ocrskill.com/ocr \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@voe-employer-reply.pdf" > voe-employer-reply.md

On a clean scan you typically get labeled lines for present position, date of employment, and gross base pay. Search that Markdown for labels your underwriting checklist cares about, or show the page to a clerk when the amounts must be exact. Do not invent undocumented field names such as base_pay or job_title in the fields query string. The full catalog lives in the OCR JSON API reference.

Both endpoints accept images (PNG, JPEG, WebP, GIF, BMP, TIFF) and documents including PDF, Word, Excel, and common Office and OpenDocument types, up to 20 MB per request.

Pipeline shape for VOE packets

Keep extraction inside a short, auditable path:

Capture. Accept lender or vendor uploads into a staging area with virus scanning and retention that matches your privacy policy. VOE pages contain income and identity data.
Classify. Route written VOE forms, verbal VOE worksheets, vendor PDFs, and free-text employer letters to different field lists (or to Markdown-only for letters).
Extract. Call /ocr.json for name and employer keys. Call /ocr for the full page whenever pay, tenure, or remarks matter.
Validate. Check required keys, cross-check the applicant name against the loan or application file, and flag employer names that do not match the stated employer.
Review. Send 400 failures, blurry pages, and any pay amount that must be hand-confirmed to a human queue with the original scan attached.
Hand off. Pass the typed record into your LOS, HRIS, or case system. Keep the original file for audit. Complete the actual employment verification (call, vendor pull, or Selling Guide verbal VOE) in the systems that own that risk.

Validation patterns that keep VOE extractors honest

One schema per document class. Do not reuse an invoice field list on a VOE. Map each inbound type to its own fields string.
Fail closed on identity-critical keys. Treat missing last_name or first_name as review, not a silent retry loop.
Cross-check employer spelling. If the JSON company_name disagrees with the employer line in Markdown or with the application, escalate. Extraction reports what each page says; it does not reconcile conflicts.
Parse pay in your layer. Amounts, pay periods, and YTD figures belong in your validators after Markdown (or after a clerk). Domain rules for income calculation stay yours.
Respect timing rules outside OCR. Fannie Mae’s verbal VOE window is measured in business days relative to the note date. That clock is underwriting policy, not an OCR concern.
Keep Markdown for free-text letters. Use POST /ocr when an employer letter needs full-page text for review or RAG, not a fixed schema.

A small Python sketch that flags an employer mismatch between typed JSON and Markdown:

import json
import re
import sys
from pathlib import Path


def norm(s: str) -> str:
    return re.sub(r"[^a-z0-9]+", " ", s.lower()).strip()


def employer_ok(record: dict, markdown: str) -> bool:
    company = record.get("company_name") or ""
    if not company:
        return False
    return norm(company) in norm(markdown)


if __name__ == "__main__":
    record = json.loads(Path(sys.argv[1]).read_text())
    markdown = Path(sys.argv[2]).read_text()
    print("employer_match" if employer_ok(record, markdown) else "review")

Run it with python3 check_voe.py voe.json voe.md. A miss means a person should look at the page before the file is marked verified.

Limitations to respect

Blurry or cropped captures. Phone photos with glare, cut-off signature blocks, or heavy stamps still fail. Ask for a rescan instead of burning retries.
Handwriting. Printed vendor PDFs and typed employer replies are the strong case. Messy pen on paper VOEs needs a review path.
Field catalog boundaries. Only documented field names are valid. Pay, job title, hire date, and “probability of continued employment” are not catalog keys today. Pull them from Markdown or enter them in review.
Multi-page packets. A request page and an employer reply may arrive as one PDF. Decide whether one request covers the multipage file or you split pages and merge keys in your code.
Not a full VOE suite. No employer phone lookup, no payroll database match, no Selling Guide clock, no fraud forensics on letterhead. Pair OCRskill with tools that own those controls.
Privacy. Employment and income documents are sensitive. Minimize retention, encrypt at rest, restrict who can download originals, and follow the laws that apply to your customers.

Choosing a verification of employment form data extractor

When you compare options, ask production questions:

Can I declare required and optional fields without prompt engineering?
Do dates and strings arrive normalized?
Is there a field reference and clear 400 behavior when a required value is missing?
Do uploads match how lenders and vendors already send PDFs and photos?
Is discovery available for new form layouts before I freeze schemas?
Does the vendor honesty-check what extraction does not cover (pay lines, verbal VOE, underwriting)?

OCRskill’s answer for the extraction slice is https://api.ocrskill.com/ocr.json with Bearer auth, name vs name? syntax, discovery when you omit fields, and the same upload styles as Markdown /ocr. Grab a key from get-key.json, lock an applicant-plus-employer schema, keep pay and tenure on Markdown plus review, and leave employment decisions to the systems built for them.

Conclusion

A verification of employment form data extractor earns its place when it returns a typed applicant and employer record from messy VOE uploads, fails closed on missing names, and leaves income qualification and verbal VOE timing to the underwriting stack. Schema-field OCR is the practical core of that extractor for the keys the catalog supports: declare the keys, upload the page, validate the JSON, review the failures, and keep Markdown for the pay and tenure lines that still need a human or a second parser.

If you are wiring this week, start with a small holdout set of real Form 1005 scans, vendor PDFs, and employer letters. Run them through a fixed name-and-employer schema, measure how often clerks still correct values, then expand form family by form family. The win is not a prettier OCR dump. It is a VOE record your application can trust enough to pass into verification.