Skip to navigation
APIPaystubs

Retrieve a paystub

Retrieves a single extracted paystub. 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-10-07. 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-10-07.

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
employer_namestring or null
The employer's name.
employer_addressstring or null

The employer's address on one line: street, city, state and postal code.

employee_namestring or null
The employee's name.
employee_addressstring or null

The employee's address on one line: street, city, state and postal code.

employee_ssn_last4string or null

The last four digits of the employee's social security number; the rest of the number is never served.

marital_statusstring or null
The employee's marital status for tax withholding, lower case as stated.
pay_datestring or nullformat: "^\d{4}-\d{2}-\d{2}$"

The date the pay was issued, as YYYY-MM-DD.

period_startstring or nullformat: "^\d{4}-\d{2}-\d{2}$"

The first day of the pay period, as YYYY-MM-DD.

period_endstring or nullformat: "^\d{4}-\d{2}-\d{2}$"

The last day of the pay period, as YYYY-MM-DD.

pay_frequencystring or null

How often the employee is paid: weekly, biweekly, semimonthly, monthly, quarterly, annual, or unknown when the frequency stated is none of these.

pay_basisstring or null
How the employee is paid, for example salary or hourly, lower case as stated.
rate_of_pay_amountstring or nullformat: "^-?\d+\.\d{2}$"

The employee's rate of pay, in the unit rate_of_pay_basis names.

rate_of_pay_basisstring or null
The unit of the rate of pay, for example annual or hourly, lower case as stated.
gross_currentstring or nullformat: "^-?\d+\.\d{2}$"
Gross pay for the pay period.
gross_ytdstring or nullformat: "^-?\d+\.\d{2}$"
Gross pay for the year to date.
net_currentstring or nullformat: "^-?\d+\.\d{2}$"
Net pay for the pay period.
net_ytdstring or nullformat: "^-?\d+\.\d{2}$"
Net pay for the year to date.
deductions_total_currentstring or nullformat: "^-?\d+\.\d{2}$"
Total deductions for the pay period.
deductions_total_ytdstring or nullformat: "^-?\d+\.\d{2}$"
Total deductions for the year to date.
hours_currentstring or nullformat: "^-?\d+(\.\d+)?$"
Hours worked in the pay period, as a decimal string.
earningslist of objects
The earnings rows the stub lists, one per kind of pay, in the order stated.
deductionslist of objects
The deductions rows the stub lists, one per tax or withholding, in the order stated.
distributionslist of objects
Where the net pay was deposited, one row per receiving account.
status"EXTRACTED"

Always EXTRACTED on a paystub the API returns.

signalslist of objects

Notes about the paystub; empty when there are none.

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