# Extract W-2, 1099 and pay stub data to JSON with an API

> Pull employer, pay period, gross and net pay, deductions and every W-2 or 1099 box into JSON with the Reducto Extract API.

Canonical: https://reducto.ai/cookbooks/w2-1099-paystub-extraction

Send the income documents to Reducto Extract with a schema for pay stubs and tax forms. The response has each pay stub (employer, pay date, period, gross, net and deductions, current and year to date) and each W-2 or 1099 with every filled box, in the same JSON every time. Use it for income verification in lending, payroll audits and tax intake.

## What you'll build

Synthetic pay stub and W-2 (or your own file)

- Upload the file or pass a public URL; a borrower packet can mix stubs and forms.
- Send it to /extract with the pay stub and tax form schema.
- Read result.pay_stubs and result.tax_forms.
- Compare year-to-date gross on the latest stub with W-2 box 1 for the prior year to check income.

## Setup

Grab an API key from <a href="https://studio.reducto.ai" rel="noopener noreferrer" target="_blank">studio.reducto.ai</a> -> API Keys -> Create new API key, then set it and install the SDK:

```bash
export REDUCTO_API_KEY="your-api-key-here"
pip install reductoai   # or: npm install reductoai
```

## Step 1: Call `/extract`

The options that matter for this job:

- `instructions.schema`: One shape for stubs and forms, so a mixed file returns both.
- `parsing.settings.model`: Reads scans and phone photos of forms.
- `settings.citations.enabled`: Adds page and bounding box for every value, for reviewer checks.

```python
# pip install reductoai
from pathlib import Path
from reducto import Reducto

client = Reducto()  # reads REDUCTO_API_KEY

upload = client.upload(file=Path("income-docs.pdf"))
result = client.extract.run(
    input=upload.file_id,
    instructions={
        "schema": {
            "type": "object",
            "properties": {
                "pay_stubs": {
                    "type": "array",
                    "description": "Every pay stub or earnings statement in the file.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "employer": {
                                "type": "string",
                                "description": "Employer name.",
                            },
                            "employee": {
                                "type": "string",
                                "description": "Employee name.",
                            },
                            "pay_date": {
                                "type": "string",
                                "description": "Pay date, YYYY-MM-DD.",
                            },
                            "period_start": {
                                "type": "string",
                                "description": "Pay period start, YYYY-MM-DD.",
                            },
                            "period_end": {
                                "type": "string",
                                "description": "Pay period end, YYYY-MM-DD.",
                            },
                            "gross_pay_current": {
                                "type": "number",
                                "description": "Gross pay this period.",
                            },
                            "gross_pay_ytd": {
                                "type": "number",
                                "description": "Gross pay year to date.",
                            },
                            "net_pay": {
                                "type": "number",
                                "description": "Net pay this period.",
                            },
                            "deductions": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "name": {
                                            "type": "string",
                                            "description": "Deduction name.",
                                        },
                                        "current": {
                                            "type": "number",
                                            "description": "This period.",
                                        },
                                        "ytd": {
                                            "type": "number",
                                            "description": "Year to date.",
                                        },
                                    },
                                },
                            },
                        },
                    },
                },
                "tax_forms": {
                    "type": "array",
                    "description": "Every W-2 or 1099 form in the file.",
                    "items": {
                        "type": "object",
                        "properties": {
                            "form_type": {
                                "type": "string",
                                "description": "W-2, 1099-NEC, 1099-MISC, 1099-INT, etc.",
                            },
                            "tax_year": {
                                "type": "string",
                                "description": "Tax year.",
                            },
                            "payer": {
                                "type": "string",
                                "description": "Employer or payer name.",
                            },
                            "payer_tin_last4": {
                                "type": "string",
                                "description": "Last 4 digits of the employer or payer EIN/TIN only.",
                            },
                            "recipient": {
                                "type": "string",
                                "description": "Employee or recipient name.",
                            },
                            "recipient_tin_last4": {
                                "type": "string",
                                "description": "Last 4 digits of the SSN or TIN only.",
                            },
                            "boxes": {
                                "type": "array",
                                "description": "Every filled box.",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "box": {
                                            "type": "string",
                                            "description": "Box number, e.g. 1, 12a.",
                                        },
                                        "label": {
                                            "type": "string",
                                            "description": "Box label.",
                                        },
                                        "amount": {
                                            "type": "number",
                                            "description": "Amount.",
                                        },
                                    },
                                },
                            },
                        },
                    },
                },
            },
        },
    },
    parsing={
        "settings": {
            "model": "r-1",
        },
    },
)
print(result)
```

```javascript
// npm install reductoai

const client = new Reducto(); // reads REDUCTO_API_KEY

const upload = await client.upload({ file: fs.createReadStream("income-docs.pdf") });
const result = await client.extract.run({
  input: upload.file_id,
  instructions: {
    schema: {
      type: "object",
      properties: {
        pay_stubs: {
          type: "array",
          description: "Every pay stub or earnings statement in the file.",
          items: {
            type: "object",
            properties: {
              employer: {
                type: "string",
                description: "Employer name.",
              },
              employee: {
                type: "string",
                description: "Employee name.",
              },
              pay_date: {
                type: "string",
                description: "Pay date, YYYY-MM-DD.",
              },
              period_start: {
                type: "string",
                description: "Pay period start, YYYY-MM-DD.",
              },
              period_end: {
                type: "string",
                description: "Pay period end, YYYY-MM-DD.",
              },
              gross_pay_current: {
                type: "number",
                description: "Gross pay this period.",
              },
              gross_pay_ytd: {
                type: "number",
                description: "Gross pay year to date.",
              },
              net_pay: {
                type: "number",
                description: "Net pay this period.",
              },
              deductions: {
                type: "array",
                items: {
                  type: "object",
                  properties: {
                    name: {
                      type: "string",
                      description: "Deduction name.",
                    },
                    current: {
                      type: "number",
                      description: "This period.",
                    },
                    ytd: {
                      type: "number",
                      description: "Year to date.",
                    },
                  },
                },
              },
            },
          },
        },
        tax_forms: {
          type: "array",
          description: "Every W-2 or 1099 form in the file.",
          items: {
            type: "object",
            properties: {
              form_type: {
                type: "string",
                description: "W-2, 1099-NEC, 1099-MISC, 1099-INT, etc.",
              },
              tax_year: {
                type: "string",
                description: "Tax year.",
              },
              payer: {
                type: "string",
                description: "Employer or payer name.",
              },
              payer_tin_last4: {
                type: "string",
                description: "Last 4 digits of the employer or payer EIN/TIN only.",
              },
              recipient: {
                type: "string",
                description: "Employee or recipient name.",
              },
              recipient_tin_last4: {
                type: "string",
                description: "Last 4 digits of the SSN or TIN only.",
              },
              boxes: {
                type: "array",
                description: "Every filled box.",
                items: {
                  type: "object",
                  properties: {
                    box: {
                      type: "string",
                      description: "Box number, e.g. 1, 12a.",
                    },
                    label: {
                      type: "string",
                      description: "Box label.",
                    },
                    amount: {
                      type: "number",
                      description: "Amount.",
                    },
                  },
                },
              },
            },
          },
        },
      },
    },
  },
  parsing: {
    settings: {
      model: "r-1",
    },
  },
});
console.log(JSON.stringify(result, null, 2));
```

Or with curl:

```bash
# 1. Upload the file (or pass a public URL as "input" and skip this step)
curl -s https://platform.reducto.ai/upload \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -F file=@income-docs.pdf
# => {"file_id": "reducto://..."}

# 2. Run extract
curl -s https://platform.reducto.ai/extract \
  -H "Authorization: Bearer $REDUCTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "input": "reducto://FILE_ID",
  "instructions": {
    "schema": {
      "type": "object",
      "properties": {
        "pay_stubs": {
          "type": "array",
          "description": "Every pay stub or earnings statement in the file.",
          "items": {
            "type": "object",
            "properties": {
              "employer": {"type": "string", "description": "Employer name."},
              "employee": {"type": "string", "description": "Employee name."},
              "pay_date": {"type": "string", "description": "Pay date, YYYY-MM-DD."},
              "period_start": {"type": "string", "description": "Pay period start, YYYY-MM-DD."},
              "period_end": {"type": "string", "description": "Pay period end, YYYY-MM-DD."},
              "gross_pay_current": {"type": "number", "description": "Gross pay this period."},
              "gross_pay_ytd": {"type": "number", "description": "Gross pay year to date."},
              "net_pay": {"type": "number", "description": "Net pay this period."},
              "deductions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "name": {"type": "string", "description": "Deduction name."},
                    "current": {"type": "number", "description": "This period."},
                    "ytd": {"type": "number", "description": "Year to date."}
                  }
                }
              }
            }
          }
        },
        "tax_forms": {
          "type": "array",
          "description": "Every W-2 or 1099 form in the file.",
          "items": {
            "type": "object",
            "properties": {
              "form_type": {"type": "string", "description": "W-2, 1099-NEC, 1099-MISC, 1099-INT, etc."},
              "tax_year": {"type": "string", "description": "Tax year."},
              "payer": {"type": "string", "description": "Employer or payer name."},
              "payer_tin_last4": {"type": "string", "description": "Last 4 digits of the employer or payer EIN/TIN only."},
              "recipient": {"type": "string", "description": "Employee or recipient name."},
              "recipient_tin_last4": {"type": "string", "description": "Last 4 digits of the SSN or TIN only."},
              "boxes": {
                "type": "array",
                "description": "Every filled box.",
                "items": {
                  "type": "object",
                  "properties": {
                    "box": {"type": "string", "description": "Box number, e.g. 1, 12a."},
                    "label": {"type": "string", "description": "Box label."},
                    "amount": {"type": "number", "description": "Amount."}
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "parsing": {"settings": {"model": "r-1"}}
}'
```

## Step 2: Read the result

On the sample (a synthetic pay stub and W-2), the job-specific part of the response:

```json
{
  "pay_stubs": [
    {
      "employer": "Orrin Fabrication Co.",
      "pay_date": "2026-10-31",
      "gross_pay_current": 3054.72,
      "gross_pay_ytd": 59281.6,
      "net_pay": 2204.59
    }
  ],
  "tax_forms": [
    {
      "form_type": "W-2",
      "tax_year": "2025",
      "boxes": [
        {
          "box": "1",
          "label": "Wages, tips, other compensation",
          "amount": 68412.55
        },
        {
          "box": "2",
          "label": "Federal income tax withheld",
          "amount": 7904.1
        }
      ]
    }
  ]
}
```

Pay stubs and tax forms come back in separate arrays, with each W-2 or 1099 box as a labelled amount.

[Full response format ->](https://docs.reducto.ai/extract/response-format)

## When to use something else

- **Extract**: when you need named values from each document.
- **Split, then Extract**: when one PDF holds a whole applicant packet.
- **Classify**: when you only need to know which document each file is.

## Where this goes next

- [Classify documents with an API](/cookbooks/classify-documents-api)
- [Split a PDF by document type](/cookbooks/split-pdf-by-document-type)
- [Bank statement to Excel](/tools/bank-statement-to-excel)
- [Extract docs](https://docs.reducto.ai/extract)

Try one PDF free, no signup, with the [PDF to JSON tool](/tools/pdf-to-json).
