Skip to navigation
APIW-2s

Retrieve a W-2

Retrieves a single extracted Form W-2. Requesting a document of any other type returns a 404.

Requires the extractions:read scope. Rate limit: 200 requests per minute per key (the api lane).

Authentication

AuthorizationBearer

Bearer token. Use ss_live_… for live data or ss_test_… for the sandbox (test mode). See Authentication.

Path parameters

borrower_idstringRequired
The borrower's id.
doc_idstringRequired
The document's id.

Headers

SpreadSpace-VersionstringOptionalformat: "^\d{4}-\d{2}-\d{2}$"

Pin the API version, e.g. 2026-07-19. Omit to get the latest. See Versioning.

Response headers

X-Request-IDstringOptional
Correlation ID for this request. Quote it in support tickets.
SpreadSpace-VersionstringOptional

The API surface version the server resolved for this request. Always present, regardless of whether the client supplied the request-side SpreadSpace-Version header. Default: 2026-07-19.

RateLimit-Limitinteger

Request budget of the endpoint's rate-limit policy per 60-second sliding window. See Rate limits.

RateLimit-Remaininginteger

Requests left in the current window. Suppressed on 429 responses produced outside the rate limiter (for example a usage throttle), where a remaining budget would be misleading.

RateLimit-Resetinteger

Seconds until a guaranteed-fresh window.

RateLimit-PolicystringOptional

The active policy in limit;w=window-seconds form.

Response

OK
form"w2"

Always w2.

dataobject

The boxes of the first statement in the file, with every statement of the file under forms_w2.

metadataobject
How the file was read.
k1_partnerslist of strings

Always empty on a Form W-2.

statementslist of strings

Always empty on a Form W-2.

depreciation_reportsobject or nullOptional

Always null on a Form W-2.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error
500
Internal Server Error