openapi: 3.0.3
info:
title: Pinwheel Accounts Verification Reports API
description: Pinwheel is the API for direct deposit switching, bill switching, and income & employment verification.
version: v2025-07-08
contact:
name: Support
email: support@getpinwheel.com
url: https://getpinwheel.com
servers:
- url: https://api.getpinwheel.com/v1
description: production
- url: https://sandbox.getpinwheel.com/v1
description: sandbox
- url: https://development.getpinwheel.com/v1
description: development
security:
- apiSecret: []
tags:
- name: Verification Reports
paths:
/end_users/{end_user_id}/verification_reports/voie:
get:
tags:
- Verification Reports
summary: Get Verification of Income and Employment Report
description: Get a Verification of Income and Employment (VOIE) report associated with your end user ID.
operationId: get_end_user_verification_reports_voie_v1_end_users__end_user_id__verification_reports_voie_get
parameters:
- description: User ID provided by you, to associate Pinwheel users with your user model.
required: true
schema:
type: string
description: User ID provided by you, to associate Pinwheel users with your user model.
name: end_user_id
in: path
- name: Pinwheel-Version
in: header
required: true
description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
schema:
enum:
- '2025-07-08'
- '2023-11-22'
- '2023-07-18'
- '2023-04-18'
- '2022-09-09'
- '2022-06-22'
- '2022-03-02'
default: '2025-07-08'
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/VerificationReportsVOIEObjResponse'
type: object
required:
- data
x-tags:
- Schemas
examples:
example:
value:
data:
id: aea8cc55-93fa-452d-8eac-b83c80b19a41
updated_at: '2021-01-06T15:59:13.530178+00:00'
refreshed_at: '2021-01-06T15:59:13.530178+00:00'
employee:
name:
first_name: Alicia
middle_name: ''
last_name: Green
full_name: Alicia Green
address:
city: Washington
country: US
line1: 1234 Home Road
line2: null
postal_code: '20017'
raw: 1234 Home Road, Washington, DC, 20017, USA
state: DC
last_four_ssn: 0090
date_of_birth: '1987-02-01'
phone_numbers:
- type: mobile
value: '+14155552671'
report_type: voie
employments:
- employer_name: Acme Corporation
employer_address:
city: Washington
country: US
line1: 1234 Main St
line2: Suite 3
postal_code: '20036'
raw: 1234 Main St, Suite 3, Washington, DC, 20036, USA
state: DC
start_date: '2020-06-01'
employment_duration_months: 23
employment_status: employed
employment_type: full time
termination_date: null
title: Engineer
most_recent_pay_date: '2021-01-05'
income:
pay_frequency: bi-weekly
compensation_unit: hourly
compensation_amount: 4000
currency: USD
annual_incomes:
- year: '2022'
gross_pay_ytd: 11000
net_pay_ytd: 9950
total_deductions_ytd: 64704
total_reimbursements_ytd: 7000
total_taxes_ytd: 94407
earnings_ytds:
- amount: 10000
category: salary
- amount: 1000
category: bonus
paystubs:
- id: 497f6eca-6276-4993-bfeb-53cbbbba6f08
account_id: 5c1952df-3a84-4f28-8318-58291452061f
gross_pay_amount: 480720
gross_pay_ytd: 6971151
net_pay_amount: 321609
net_pay_ytd: 4357992
pay_date: '2022-01-05'
pay_period_end: '2021-12-24'
pay_period_start: '2021-12-10'
earnings:
- amount: 380720
category: hourly
hours: 80.0
name: Regular
rate: 4759
- amount: 100000
category: bonus
hours: null
name: Bonus
rate: null
total_deductions: 64704
total_reimbursements: 7000
total_taxes: 94407
currency: USD
created_at: '2021-01-10T19:54:45.745660+00:00'
check_amount: 328609
employer_name: Acme Corporation
external_paystub_id: 821b7d1b-c115-470c-9411-be132f51c19d
- id: 497f6eca-6276-4993-bfeb-53cbbbda6f53
account_id: 5c1952df-3a84-4f28-8318-58291452061f
gross_pay_amount: 480720
gross_pay_ytd: 6490431
net_pay_amount: 321609
net_pay_ytd: 4036383
pay_date: '2021-12-22'
pay_period_end: '2021-12-09'
pay_period_start: '2021-11-26'
earnings:
- amount: 380720
category: hourly
hours: 80.0
name: Regular
rate: 4759
- amount: 100000
category: bonus
hours: null
name: Bonus
rate: null
total_deductions: 64704
total_reimbursements: 7000
total_taxes: 94407
currency: USD
created_at: '2021-01-10T19:54:45.745660+00:00'
check_amount: 328609
employer_name: Acme Corporation
external_paystub_id: 50df7fe0-b818-414f-84b9-b9f5bba06a09
document:
id: 353fb6fb-e704-4112-990a-30058efe2737
download_url: https://pinwheel-cdn.s3.amazonaws.com/assets/pdfs/voie_report.pdf
download_url_expiration: '2024-01-06T17:47:52.782334+00:00'
/end_users/{end_user_id}/verification_reports/voe:
get:
tags:
- Verification Reports
summary: Get Verification of Employment Report
description: Get a Verification of Employment (VOE) report associated with your end user ID.
operationId: get_end_user_verification_reports_voe_v1_end_users__end_user_id__verification_reports_voe_get
parameters:
- description: User ID provided by you, to associate Pinwheel users with your user model.
required: true
schema:
type: string
description: User ID provided by you, to associate Pinwheel users with your user model.
name: end_user_id
in: path
- name: Pinwheel-Version
in: header
required: true
description: Version identifier specifying how the Pinwheel API should behave. See the Change Management page for more information.
schema:
enum:
- '2025-07-08'
- '2023-11-22'
- '2023-07-18'
- '2023-04-18'
- '2022-09-09'
- '2022-06-22'
- '2022-03-02'
default: '2025-07-08'
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
data:
$ref: '#/components/schemas/VerificationReportsVOEObjResponse'
type: object
required:
- data
x-tags:
- Schemas
examples:
example:
value:
data:
id: aea8cc55-93fa-452d-8eac-b83c80b19a41
updated_at: '2021-01-06T15:59:13.530178+00:00'
refreshed_at: '2021-01-06T15:59:13.530178+00:00'
employee:
name:
first_name: Alicia
middle_name: ''
last_name: Green
full_name: Alicia Green
address:
city: Washington
country: US
line1: 1234 Home Road
line2: null
postal_code: '20017'
raw: 1234 Home Road, Washington, DC, 20017, USA
state: DC
last_four_ssn: 0090
date_of_birth: '1987-02-01'
phone_numbers:
- type: mobile
value: '+14155552671'
report_type: voe
employments:
- employer_name: Acme Corporation
employer_address:
city: Washington
country: US
line1: 1234 Main St
line2: Suite 3
postal_code: '20036'
raw: 1234 Main St, Suite 3, Washington, DC, 20036, USA
state: DC
start_date: '2020-06-01'
employment_duration_months: 23
employment_status: employed
employment_type: full time
termination_date: null
title: Engineer
most_recent_pay_date: '2021-01-05'
document:
id: 15bbb566-fb4e-4835-9967-b308c164269e
download_url: https://pinwheel-cdn.s3.amazonaws.com/assets/pdfs/voe_report.pdf
download_url_expiration: '2024-01-06T17:47:52.782334+00:00'
components:
schemas:
PaystubWithEarningsResponseObj:
properties:
id:
type: string
format: uuid
title: id
description: Unique identifier for the object.
created_at:
type: string
format: date-time
title: created_at
description: ISO 8601 timestamp of created time.
account_id:
type: string
format: uuid
title: account_id
description: UUID of the payroll account.
pay_date:
type: string
format: date
title: pay_date
description: The date when the check amount is paid to the employee.
pay_period_start:
type: string
format: date
title: pay_period_start
description: The date when the pay period begins. Some platforms, like unemployment portals, do not have fixed pay periods.
pay_period_end:
type: string
format: date
title: pay_period_end
description: The date when the pay period ends. Some platforms, like unemployment portals, do not have fixed pay periods.
currency:
allOf:
- type: string
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BHD
- BIF
- BMD
- BND
- BOB
- BOV
- BRL
- BSD
- BTN
- BWP
- BYR
- BZD
- CAD
- CDF
- CHE
- CHF
- CHW
- CLF
- CLP
- CNY
- COP
- COU
- CRC
- CUC
- CUP
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ERN
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GHS
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- IQD
- IRR
- ISK
- JMD
- JOD
- JPY
- KES
- KGS
- KHR
- KMF
- KPW
- KRW
- KWD
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- LTL
- LVL
- LYD
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MUR
- MVR
- MWK
- MXN
- MXV
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- OMR
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SDG
- SEK
- SGD
- SHP
- SLL
- SOS
- SRD
- SSP
- STD
- SYP
- SZL
- THB
- TJS
- TMT
- TND
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- USN
- USS
- UYI
- UYU
- UZS
- VEF
- VND
- VUV
- WST
- XAF
- XAG
- XAU
- XBA
- XBB
- XBC
- XBD
- XCD
- XDR
- XOF
- XPD
- XPF
- XPT
- XTS
- XXX
- YER
- ZAR
- ZMW
description: Three-letter ISO 4217 currency code, uppercase. For example, the code for US dollars is USD.
gross_pay_amount:
type: integer
title: gross_pay_amount
description: The total earnings before any deductions are made, in cents.
net_pay_amount:
type: integer
title: net_pay_amount
description: The total earnings after all taxes and deductions are removed, in cents.
check_amount:
type: integer
title: check_amount
description: The amount paid to the employee in this payout, in cents.
gross_pay_ytd:
type: integer
title: gross_pay_ytd
description: The cumulative year to date total earnings before any taxes or deductions are removed, in cents.
net_pay_ytd:
type: integer
title: net_pay_ytd
description: The cumulative year to date total earnings after all taxes and deductions are removed, in cents.
total_taxes:
type: integer
title: total_taxes
description: The total taxes for this pay period, in cents.
total_deductions:
type: integer
title: total_deductions
description: The total deductions for this pay period, in cents.
total_reimbursements:
type: integer
title: total_reimbursements
description: The total reimbursements for this pay period, in cents.
external_paystub_id:
type: string
title: external_paystub_id
description: The external id of a single paystub from the payroll provider.
employer_name:
type: string
title: employer_name
description: The name of the employer that issued the paystub.
earnings:
items:
$ref: '#/components/schemas/EarningObjPublicResponseItem'
type: array
title: earnings
description: The earnings for this pay period, in cents.
type: object
required:
- id
- created_at
- account_id
- pay_date
- currency
- gross_pay_amount
- net_pay_amount
- check_amount
- total_taxes
- total_deductions
- total_reimbursements
- earnings
title: PaystubWithEarningsResponseObj
x-tags:
- Schemas
AnnualIncomeResponseObj:
properties:
year:
type: string
title: year
description: Year for which the income represents.
gross_pay_ytd:
type: integer
title: gross_pay_ytd
description: The cumulative year to date total earnings before any taxes or deductions are removed, in cents.
net_pay_ytd:
type: integer
title: net_pay_ytd
description: The cumulative year to date total earnings after all taxes and deductions are removed, in cents.
total_deductions_ytd:
type: integer
title: total_deductions_ytd
description: The cumulative year to date total deductions, in cents.
total_reimbursements_ytd:
type: integer
title: total_reimbursements_ytd
description: The cumulative year to date total reimbursements, in cents.
total_taxes_ytd:
type: integer
title: total_taxes_ytd
description: The cumulative year to date total taxes, in cents.
earnings_ytds:
items:
$ref: '#/components/schemas/EarningsYtds'
type: array
title: earnings_ytds
description: The cumulative year to date amount for all earnings, in cents.
type: object
required:
- year
- gross_pay_ytd
- net_pay_ytd
- total_deductions_ytd
- total_reimbursements_ytd
- total_taxes_ytd
- earnings_ytds
title: AnnualIncomeResponseObj
x-tags:
- Schemas
AddressGetResponseItem:
properties:
raw:
type: string
title: raw
description: The raw address.
line1:
type: string
title: line1
description: The first line of the address.
line2:
type: string
title: line2
description: The second line of the address.
city:
type: string
title: city
description: The city of the address.
state:
type: string
title: state
description: The state of the address.
postal_code:
type: string
title: postal_code
description: The postal code of the address.
country:
allOf:
- type: string
enum:
- US
description: The country of the address.
type: object
required:
- raw
title: Address
x-tags:
- Schemas
VerificationReportsVOIEObjResponse:
properties:
id:
type: string
format: uuid
title: id
description: Unique identifier for the object.
updated_at:
type: string
format: date-time
title: updated_at
description: ISO 8601 timestamp of the last update to this object.
refreshed_at:
type: string
format: date-time
title: refreshed_at
description: ISO 8601 timestamp of the most recent refresh of this data.
employee:
allOf:
- $ref: '#/components/schemas/EmployeeResponseObj'
title: employee
description: Personal details for the employee.
employments:
items:
$ref: '#/components/schemas/IncomeAndEmploymentResponseObj'
type: array
title: employments
description: Income and Employment details for the employee.
document:
allOf:
- $ref: '#/components/schemas/DocumentObjPublicResponseItem'
title: document
description: A document.
report_type:
allOf:
- type: string
enum:
- voe
- voie
- base
description: The type of report created.
type: object
required:
- id
- updated_at
- refreshed_at
- employee
- employments
- report_type
title: Verification of Income and Employment Report for an end user
x-tags:
- Schemas
EmployeeName:
properties:
first_name:
type: string
title: first_name
description: The first name of the employee.
middle_name:
type: string
title: middle_name
description: The middle name of the employee.
last_name:
type: string
title: last_name
description: The last name of the employee.
full_name:
type: string
title: full_name
description: The full name of the employee.
type: object
required:
- full_name
title: EmployeeName
x-tags:
- Schemas
PhoneNumberGetResponseItem:
properties:
value:
type: string
title: value
description: The E.164 formatted phone number.
type:
allOf:
- type: string
enum:
- home
- work
- mobile
description: home, mobile, work, etc.
type: object
required:
- value
title: Phone
x-tags:
- Schemas
EmploymentResponseObj:
properties:
employer_name:
type: string
title: employer_name
description: Name of employer, e.g., Apple, Disney, Walmart.
employer_address:
allOf:
- $ref: '#/components/schemas/AddressGetResponseItem'
title: employer_address
description: The address of the employer.
start_date:
type: string
format: date
title: start_date
description: The date the employee began their job.
employment_duration_months:
type: integer
title: employment_duration_months
description: The length of time, in months, the employee has been active with the employer.
employment_status:
allOf:
- type: string
enum:
- employed
- terminated
- furloughed
description: The employment status of the employee.
employment_type:
type: string
title: employment_type
description: The employment type e.g. full time, part time, seasonal, contractor.
termination_date:
type: string
format: date
title: termination_date
description: The date the employee was terminated.
title:
type: string
title: title
description: The job title of the employee.
most_recent_pay_date:
type: string
format: date
title: most_recent_pay_date
description: The latest date when the employee received regular pay.
type: object
required:
- employer_name
title: EmploymentResponseObj
x-tags:
- Schemas
IncomeAndEmploymentResponseObj:
properties:
employer_name:
type: string
title: employer_name
description: Name of employer, e.g., Apple, Disney, Walmart.
employer_address:
allOf:
- $ref: '#/components/schemas/AddressGetResponseItem'
title: employer_address
description: The address of the employer.
start_date:
type: string
format: date
title: start_date
description: The date the employee began their job.
employment_duration_months:
type: integer
title: employment_duration_months
description: The length of time, in months, the employee has been active with the employer.
employment_status:
allOf:
- type: string
enum:
- employed
- terminated
- furloughed
description: The employment status of the employee.
employment_type:
type: string
title: employment_type
description: The employment type e.g. full time, part time, seasonal, contractor.
termination_date:
type: string
format: date
title: termination_date
description: The date the employee was terminated.
title:
type: string
title: title
description: The job title of the employee.
most_recent_pay_date:
type: string
format: date
title: most_recent_pay_date
description: The latest date when the employee received regular pay.
income:
allOf:
- $ref: '#/components/schemas/IncomeResponseObj'
title: income
description: Income details for the employment.
type: object
required:
- employer_name
- income
title: IncomeAndEmploymentResponseObj
x-tags:
- Schemas
DocumentObjPublicResponseItem:
properties:
id:
type: string
format: uuid
title: id
description: Unique identifier of the document object.
download_url:
type: string
title: download_url
description: URL from which the document may be downloaded.
download_url_expiration:
type: string
format: date-time
title: download_url_expiration
description: ISO 8601 timestamp of when the download URL will no longer be valid.
type: object
required:
- id
title: Document
x-tags:
- Schemas
EarningsYtds:
properties:
amount:
type: integer
title: amount
description: The year to date earnings amount for an earning category, in cents.
category:
allOf:
- type: string
enum:
- salary
- hourly
- overtime
- double_overtime
- premium
- bonus
- commission
- tips
- vacation
- holiday
- pto
- sick
- employer_contribution
- other
- fare
- unpaid
- parental
- shift_differential
- bereavement
- life_insurance
- stock
- retirement
- medical
- meal_comp
- disability
- retro_pay
description: The category of earning.
type: object
title: EarningsYtds
x-tags:
- Schemas
EmployeeResponseObj:
properties:
name:
allOf:
- $ref: '#/components/schemas/EmployeeName'
title: name
description: The name of the employee.
date_of_birth:
type: string
format: date
title: date_of_birth
description: The date the employee was born.
last_four_ssn:
type: string
title: last_four_ssn
description: The last four digits of the employee's social security number (SSN).
address:
allOf:
- $ref: '#/components/schemas/AddressGetResponseItem'
title: address
description: The address of the employee.
phone_numbers:
items:
$ref: '#/components/schemas/PhoneNumberGetResponseItem'
type: array
title: phone_numbers
description: The phone numbers of the employee.
type: object
required:
- name
title: EmployeeResponseObj
x-tags:
- Schemas
EarningObjPublicResponseItem:
properties:
name:
type: string
title: name
description: The name of the earning.
category:
allOf:
- type: string
enum:
- salary
- hourly
- overtime
- double_overtime
- premium
- bonus
- commission
- tips
- vacation
- holiday
- pto
- sick
- employer_contribution
- other
- fare
- unpaid
- parental
- shift_differential
- bereavement
- life_insurance
- stock
- retirement
- medical
- meal_comp
- disability
- retro_pay
description: The category of earning.
amount:
type: integer
title: amount
description: The amount of earning, in cents.
rate:
type: integer
title: rate
description: The amount earned per hour, in cents.
hours:
type: number
title: hours
description: The hours worked.
type: object
required:
- name
- category
- amount
title: Earning
x-tags:
- Schemas
IncomeResponseObj:
properties:
pay_frequency:
allOf:
- type: string
enum:
- daily
- weekly
- bi-weekly
- monthly
- semi-monthly
- variable
description: Describes how often the employee is paid.
compensation_unit:
allOf:
- type: string
enum:
- hourly
- daily
- weekly
- bi-weekly
- semi-weekly
- monthly
- semi-monthly
- annually
- variable
- per_mile
description: The compensation time frame.
compensation_amount:
type: integer
title: compensation_amount
description: The amount per compensation unit, in cents.
currency:
allOf:
- type: string
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AO
# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/pinwheel/refs/heads/main/openapi/pinwheel-verification-reports-api-openapi.yml