Set Up Earnings and Deduction Fields for Paystubs

What this guide helps you do

This guide shows how to configure a paystub parser in PerfectParser, separate earnings and deductions tables, run a test batch, and export payroll data. Use the prompt below only when you need consistent field names across payroll providers — skip it initially for broader discovery.

Why paystubs are hard to parse

Paystubs pack current-period and year-to-date figures side by side in earnings and deductions tables. Auto-detect often grabs the YTD gross when you intended the period gross, or merges federal tax withheld this period with the YTD tax column. Payroll providers use different labels — "Regular", "Base", "Salary" for the same earnings type — and overtime may appear as a separate row or embedded in hours. Deductions span taxes, benefits, garnishments, and 401(k) contributions in one table with inconsistent ordering. Pay period and pay date are distinct fields but appear adjacent in headers. Multi-page stubs attach benefit summaries on page two. A schema without separate earnings_breakdown and deductions_breakdown tables loses the detail income verification workflows require.

Recommended Fields

We suggest configuring the following schema fields for your Paystub Parser to capture all essential earnings and withholding details.

AI Prompt (Optional)

Use this only when you want to guide auto-detect toward a specific set of fields.

If you want PerfectParser to discover additional fields on its own, leave the AI Prompt (Optional) box blank for the first pass, review the detected schema, then add a prompt only if you need tighter consistency.

When you do use a prompt, copy and paste the following instructions into the AI Prompt (Optional) field during setup:

Extract the employer name, employee name, pay period dates, pay check date, gross earnings, and net take-home pay. Also extract the earnings breakdown table (type, hours, rate, amount) and deductions breakdown table (withholding type, amount).

Set up this parser in the dashboard

Create a parser

Go to Parsers → New Parser in the dashboard. Give it a name like "Paystub Parser" and optionally select the document category.

Upload a sample document

Drag and drop a representative paystub (PDF, PNG, or JPEG). Use a stub from your target payroll provider — the AI uses it to learn earnings and deductions table structure.

Detect fields or use standard fields

Paste the AI Prompt from the section above into the AI Prompt (Optional) box if you want tighter field mapping, then click Auto-Detect. To discover more fields automatically, leave the prompt blank and click Auto-Detect. Or skip auto-detect and add fields manually using the Recommended Fields table above.

Review and save your schema

Check that gross_earnings and net_pay reflect current period values, not YTD totals. Confirm earnings_breakdown and deductions_breakdown are separate Table fields. Click Save.

Run a test batch

Navigate to Bulk Extraction, choose how your files are organised, upload a small test set of paystubs, and click Extract All Files. Review the results in Batch History and export to CSV or Excel.

Common mistakes

• Mapping YTD gross into gross_earnings when the header row shows both period and YTD columns.
• Collapsing earnings and deductions into one table — they serve different purposes in underwriting and HR workflows.
• Omitting deductions_breakdown and relying only on net_pay — reviewers cannot verify tax withholding without line detail.
• Confusing pay_date (check date) with pay_period (coverage range) when both appear in the header block.

Next steps

• Create a Parser guide
• Bulk Extraction guide
• Export Results guide