API Documentation
Parse w2 documents programmatically with our simple REST API.
Authentication
Most API requests require an API key. A limited demo tier is also available without a key (see below).
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. Unauthenticated requests are allowed on the rate-limited demo tier.
POST /api/extract
Parse a w2 document and extract structured data
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-2025.pdf"
Example Response
{
"success": true,
"docType": "w2",
"siteName": "W-2 Extractor",
"data": {
"tax_year": 2025,
"employer_ein": "12-3456789",
"employer_name": "Acme Corporation",
"employee_ssn_last4": "1234",
"employee_name": "John Smith",
"wages_tips": 85000,
"federal_tax_withheld": 12750,
"social_security_wages": 85000,
"social_security_tax": 5270,
"medicare_wages": 85000,
"medicare_tax": 1232.5,
"state": "CA",
"state_wages": 85000,
"state_tax_withheld": 5100
},
"confidence": 0.95,
"processingTimeMs": 2340
}POST /api/extract/batch
Parse multiple documents at once
Request
Content-Type: multipart/form-data
| Parameter | Type | Description |
|---|---|---|
files | File[] | Multiple files (max 20) or a ZIP archive (max 100 files) |
Example Response
{
"success": true,
"docType": "w2",
"totalFiles": 5,
"successful": 4,
"failed": 1,
"results": [
{
"filename": "w2-2025.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.
Response Codes
| Code | Description |
|---|---|
200 | Success - document parsed |
400 | Bad request - invalid file or missing parameters |
401 | Unauthorized - invalid or missing API key |
402 | Payment required - demo (unauthenticated) tier exhausted |
429 | Rate limit exceeded, or authenticated quota exhausted (no credits/monthly documents remaining) - wait and retry or upgrade |
500 | Server error - extraction failed |
Rate Limits
- Demo (unauthenticated): 5 requests per minute
- Authenticated users: 60 requests per minute
- 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.