API Documentation
Parse w2 documents programmatically with our simple REST API.
/api/extract are rejected with a 402.Include your API key in the Authorization header:
curl -X POST https://w2extractor.com/api/extract \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@document.pdf"
Or pass it in the X-Api-Key header:
curl -X POST https://w2extractor.com/api/extract \ -H "X-Api-Key: YOUR_API_KEY" \ -F "file=@document.pdf"
Get your API key from the Dashboard. Every /api/extract request must include a valid key — unauthenticated requests are rejected with a 402. Sign up free to get a key and 3 free documents. (The playground returns pre-canned sample data without a key, for previewing the output shape only.)
Request
Content-Type: multipart/form-data
| Parameter | Type | Description |
|---|---|---|
file | File | PDF, PNG, JPG, or WebP (max 4.5MB) |
Example Request
curl -X POST https://w2extractor.com/api/extract \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@w2.pdf"
Synthetic example response (partial field set)
Values, confidence, and timings are illustrative, not benchmark results. Always inspect needsReview and ocrWarning, and validate required fields against your source before use. An empty needsReview array does not certify accuracy. See the document-specific review checklist.
{
"success": true,
"docType": "w2",
"siteName": "W-2 Extractor",
"data": {
"tax_year": 2025,
"employer_name": "Example Workshop (fictional)",
"employee_name": "Sample Employee",
"employee_ssn_last4": "0000",
"box1_wages": 58000,
"box2_federal_tax": 6500,
"state_wages": 58000,
"state_tax": 2400
},
"confidence": 0.5,
"fieldConfidence": null,
"needsReview": [],
"ocrWarning": null,
"processingTimeMs": 2340
}Request
Content-Type: multipart/form-data
| Parameter | Type | Description |
|---|---|---|
files | File[] | Multiple files (max 20) or a ZIP archive (max 100 files) |
Synthetic example response (partial field set)
Values, confidence, and timings are illustrative, not benchmark results. Always inspect needsReview and ocrWarning, and validate required fields against your source before use. An empty needsReview array does not certify accuracy. See the document-specific review checklist.
{
"success": true,
"docType": "w2",
"totalFiles": 5,
"successful": 4,
"failed": 1,
"results": [
{
"filename": "w2.pdf",
"success": true,
"data": {
"...": "..."
},
"confidence": 0.95,
"processingTimeMs": 2100
},
{
"filename": "corrupted.pdf",
"success": false,
"error": "Could not parse PDF"
}
],
"totalProcessingTimeMs": 8500
}Batch processing runs files in parallel (10 at a time) for faster throughput. ZIP files are automatically extracted.
| Code | Description |
|---|---|
200 | Success - document parsed |
400 | Bad request - invalid file or missing parameters |
401 | Unauthorized - invalid or missing API key |
402 | Unauthenticated - no API key provided. Sign up (free) to get a key and 3 free documents |
429 | Rate limit exceeded, or authenticated quota exhausted (no credits/monthly documents remaining) - wait and retry or upgrade |
500 | Server error - extraction failed |
- Authenticated users: 60 requests per minute (API keys also allow bursts of up to 20 requests per 10 seconds)
- Enterprise: Contact us for higher limits
When a rate limit or quota is hit, responses include a Retry-After header indicating how many seconds to wait before retrying.