{ "openapi": "3.1.0", "info": { "title": "Employment & Income Verification API", "version": "1.0.0", "description": "Verifier-facing REST API. External verifiers (ADP, lenders, landlords, background screeners) query our database with a subject's identifiers to retrieve employment and income data across **all employers** we have records for. A person can have concurrent or historical records at multiple employers — all of them are returned in one response.\n\n## Authentication\n\nEvery request must be authenticated with **one** of the following:\n\n1. **API key** — send the verifier's key as the `X-API-Key` header (`vk_live_xxx` for production, `vk_test_xxx` for sandbox). Simplest to integrate.\n2. **OAuth 2.0 (client credentials)** — exchange your `client_id` + `client_secret` at `POST https://auth.example.com/oauth/token` for a short-lived bearer token, then send `Authorization: Bearer ` on every request. Tokens expire after 1 hour. Recommended for production: secrets can be rotated without redeploying client code, and access can be scoped per credential (`verifications:read`, `verifications:write`, `batches:write`, `webhooks:manage`).\n\nMissing or invalid credentials return `401 unauthorized`. A bearer token that lacks a required scope returns `401 insufficient_scope`.\n\n## How matching works\n\nThe verifier provides a `subject_lookup` payload. Two identifiers are **always required** on every request:\n\n1. Full `ssn` (9 digits)\n2. `date_of_birth`\n\nAll other identifiers (`legal_name`, `ssn_last4`, `email`, `phone`) are optional. When provided, optional identifiers are cross-checked against our record — a mismatch downgrades the response to `ambiguous_match` and no data is returned. Requests missing either `ssn` or `date_of_birth` are rejected with `400 invalid_request`.\n\n## What gets returned\n\nWe identify the matched person across our entire database, then return every employment record we hold for that person — grouped by employer. Each employment record includes the latest paychecks with line-level earnings, plus per-employer and cross-employer income summaries broken out by year.", "contact": { "name": "API Support", "email": "api@example.com" } }, "servers": [ { "url": "https://api.example.com/v1", "description": "Production" }, { "url": "https://sandbox.api.example.com/v1", "description": "Sandbox" } ], "tags": [ { "name": "Verifications", "description": "Create and retrieve single-subject employment and income verifications." }, { "name": "Government Verification", "description": "Government-grade single-subject verification. Same matching behavior as the standard employment + income endpoint, surfaced separately for agency/regulator integrations." }, { "name": "Batches (JSON)", "description": "Async batch verifications for 1–500 subjects per request. Submit a JSON array, poll for status, receive a webhook when complete." }, { "name": "Batches (File Upload)", "description": "Async batch verifications for up to 100,000 subjects via CSV upload. Used for portfolio re-verification, screening sweeps, and audits." }, { "name": "Webhooks", "description": "Server-to-server callbacks delivered when async work completes." } ], "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:read", "verifications:write" ] } ], "paths": { "/verifications/employment-income": { "post": { "tags": [ "Verifications" ], "summary": "Create a combined employment + income verification", "description": "Searches across **all employers in the database** for the subject described in `subject_lookup`. Returns the matched person plus every employment record (active and historical) grouped by employer, with paychecks, taxes, and deductions.", "operationId": "createEmploymentIncomeVerification", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" }, "examples": { "ssnLookup": { "summary": "Lookup by full SSN (highest confidence)", "value": { "verifier_reference_id": "MORTGAGE-2026-000981", "verifier_user_id": "user_alex.jordan@verifier.example.com", "permissible_purpose": "credit_transaction", "subject_lookup": { "ssn": "123-45-6789", "date_of_birth": "1989-04-17", "legal_name": { "first_name": "Jordan", "last_name": "Miles" } }, "options": { "include_inactive_employment": true, "paycheck_limit": 6, "as_of_date": "2026-04-20" } } }, "fullLookup": { "summary": "Required SSN + DOB plus optional legal_name, email, phone", "value": { "verifier_reference_id": "BACKGROUND-2026-44012", "verifier_user_id": "user_morgan.lee@screening.example.com", "permissible_purpose": "employment_purpose", "subject_lookup": { "ssn": "123-45-6789", "date_of_birth": "1989-04-17", "legal_name": { "first_name": "Jordan", "middle_name": "T", "last_name": "Miles" }, "email": "jordan.miles@example.com", "phone": "+15125550199" }, "options": { "employer_limit": 1, "paycheck_limit": 4 } } }, "ambiguousLookup": { "summary": "SSN + DOB match a record but optional legal_name disagrees (returns ambiguous_match)", "value": { "verifier_reference_id": "TENANT-2026-00115", "verifier_user_id": "user_chris.osei@landlord.example.com", "permissible_purpose": "credit_transaction", "subject_lookup": { "ssn": "123-45-6789", "date_of_birth": "1989-04-17", "legal_name": { "first_name": "Jordan", "last_name": "Vance" } } } } } } } }, "responses": { "200": { "description": "Verification completed. The body's `result_status` indicates the business outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" }, "examples": { "verifiedMultiEmployer": { "summary": "Verified person with concurrent jobs at two employers", "value": { "verification_id": "ver_01JT7K4KT2X2Q1R7PS1D5Q2A6Z", "status": "completed", "result_status": "verified", "verification_type": "employment_income", "permissible_purpose": "credit_transaction", "requested_at": "2026-04-20T16:12:11Z", "completed_at": "2026-04-20T16:12:11Z", "verifier_reference_id": "MORTGAGE-2026-000981", "verifier_user_id": "user_alex.jordan@verifier.example.com", "subject_match": { "matched": true, "match_confidence": "high", "match_strategy": "ssn_full", "legal_name": { "first_name": "Jordan", "middle_name": "T", "last_name": "Miles" }, "date_of_birth": "1989-04-17", "ssn_last4": "6789", "residence_address": { "line1": "412 Maplewood Ave", "line2": "Apt 3B", "city": "Nashville", "county": "Davidson", "state": "TN", "postal_code": "37206", "country": "US" } }, "results": [ { "employer": { "employer_id": "emp_01JT7J6X8V0H2H6H7QJ4A9D1K2", "external_employer_id": "ACME-001", "legal_name": "Acme Distribution Holdings, Inc.", "dba_name": "Acme Distribution", "fein": "12-3451234", "currency": "USD" }, "employment_records": [ { "employee_number": "E102944", "status": "active", "employment_type": "full_time", "compensation_type": "salary", "job_title": "Senior Operations Analyst", "department": "Operations", "work_location": { "location_id": "loc_01JT7M6B8W9Y3E4R5T6U7V8W9X", "name": "Nashville Distribution Center", "address": { "line1": "200 Logistics Way", "city": "Nashville", "state": "TN", "postal_code": "37211", "country": "US" } }, "dates": { "original_hire_date": "2020-05-04", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2025-11-01", "pay_rate": 87500, "pay_frequency": "annual", "annualized_base_pay": 87500, "standard_hours": 40, "currency": "USD" }, "income_summary": { "currency": "USD", "latest_pay_date": "2026-04-15", "paycheck_count_returned": 1, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 80450, "regular_earnings": 78200, "overtime_earnings": 0, "bonus_earnings": 2250, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 86420.5, "regular_earnings": 82660.5, "overtime_earnings": 1265, "bonus_earnings": 2495, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 23869.23, "regular_earnings": 23584.61, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } ], "total": { "paycheck_count": 55, "gross_pay": 190739.73, "regular_earnings": 184445.11, "overtime_earnings": 1265, "bonus_earnings": 5029.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } }, "paychecks": [ { "paycheck_id": "pay_01JT7JS7VAD0H7EKR1D4XZ6S0A", "ext_payroll_id": "ADP-2026-04-15-49281", "pay_period_start_date": "2026-04-01", "pay_period_end_date": "2026-04-15", "pay_date": "2026-04-15", "check_date": "2026-04-15", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3653.85, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 }, { "earning_type": "bonus", "description": "Performance Bonus", "hours": null, "rate": null, "amount": 284.62 } ] } ] }, { "employee_number": "E102944", "status": "active", "employment_type": "full_time", "compensation_type": "salary", "job_title": "Regional Operations Analyst", "department": "Operations", "work_location": { "location_id": "loc_01JT7M6Z4N5P6Q7R8S9T0U1V2W", "name": "Memphis Fulfillment Hub", "address": { "line1": "4100 Distribution Pkwy", "city": "Memphis", "state": "TN", "postal_code": "38118", "country": "US" } }, "dates": { "original_hire_date": "2020-05-04", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2025-11-01", "pay_rate": 87500, "pay_frequency": "annual", "annualized_base_pay": 87500, "standard_hours": 40, "currency": "USD" }, "income_summary": { "currency": "USD", "latest_pay_date": "2026-04-15", "paycheck_count_returned": 1, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 30200, "regular_earnings": 29300, "overtime_earnings": 0, "bonus_earnings": 900, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 31530.25, "regular_earnings": 30070.25, "overtime_earnings": 505, "bonus_earnings": 955, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 3, "gross_pay": 10392.31, "regular_earnings": 10107.69, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } ], "total": { "paycheck_count": 21, "gross_pay": 72122.56, "regular_earnings": 69477.94, "overtime_earnings": 505, "bonus_earnings": 2139.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } }, "paychecks": [ { "paycheck_id": "pay_acme_05_20260313", "ext_payroll_id": "ADP-2026-03-13-49286", "pay_period_start_date": "2026-03-01", "pay_period_end_date": "2026-03-15", "pay_date": "2026-03-13", "check_date": "2026-03-13", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3369.23, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 } ] }, { "paycheck_id": "pay_acme_06_20260331", "ext_payroll_id": "ADP-2026-03-31-49287", "pay_period_start_date": "2026-03-16", "pay_period_end_date": "2026-03-31", "pay_date": "2026-03-31", "check_date": "2026-03-31", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3369.23, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 } ] }, { "paycheck_id": "pay_acme_07_20260415", "ext_payroll_id": "ADP-2026-04-15-49288", "pay_period_start_date": "2026-04-01", "pay_period_end_date": "2026-04-15", "pay_date": "2026-04-15", "check_date": "2026-04-15", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3653.85, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 }, { "earning_type": "bonus", "description": "Performance Bonus", "hours": null, "rate": null, "amount": 284.62 } ] } ] } ] }, { "employer": { "employer_id": "emp_01JT7H2ABC9XK1P0R8VQYTS3M4", "external_employer_id": "GLOBEX-014", "legal_name": "Globex Logistics, Inc.", "dba_name": null, "fein": "88-1235678", "currency": "USD" }, "employment_records": [ { "employee_number": "G-77310", "status": "active", "employment_type": "part_time", "compensation_type": "hourly", "job_title": "Weekend Driver", "department": "Fleet", "work_location": { "location_id": "loc_01JT7N1G2H3J4K5L6M7N8P9Q0R", "name": "Dallas Fleet Yard", "address": { "line1": "8901 Commerce Park Dr", "city": "Dallas", "state": "TX", "postal_code": "75247", "country": "US" } }, "dates": { "original_hire_date": "2024-09-12", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2024-09-12", "pay_rate": 28.5, "pay_frequency": "biweekly", "annualized_base_pay": 17784, "standard_hours": 12, "currency": "USD" }, "income_summary": { "currency": "USD", "latest_pay_date": "2026-04-12", "paycheck_count_returned": 1, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 8, "gross_pay": 4560, "regular_earnings": 4560, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 26, "gross_pay": 14820, "regular_earnings": 14820, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 3990, "regular_earnings": 3990, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } ], "total": { "paycheck_count": 41, "gross_pay": 23370, "regular_earnings": 23370, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } }, "paychecks": [ { "paycheck_id": "pay_01JT7HVZJ1A3R9T8K3L5DM7QP2", "ext_payroll_id": "GUSTO-2026-04-12-771210", "pay_period_start_date": "2026-03-30", "pay_period_end_date": "2026-04-12", "pay_date": "2026-04-12", "check_date": "2026-04-12", "pay_frequency": "biweekly", "currency": "USD", "gross_pay": 570, "regular_earnings": 570, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "earnings": [ { "earning_type": "regular", "description": "Hourly Wages", "hours": 20, "rate": 28.5, "amount": 570 } ] } ] } ] } ], "aggregate_income_summary": { "employer_count": 2, "active_employer_count": 2, "employment_record_count": 3, "active_employment_record_count": 3, "currency": "USD", "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 32, "gross_pay": 85010, "regular_earnings": 82760, "overtime_earnings": 0, "bonus_earnings": 2250, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 50, "gross_pay": 101240.5, "regular_earnings": 97480.5, "overtime_earnings": 1265, "bonus_earnings": 2495, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 14, "gross_pay": 27859.23, "regular_earnings": 27574.61, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } ], "total": { "paycheck_count": 96, "gross_pay": 214109.73, "regular_earnings": 207815.11, "overtime_earnings": 1265, "bonus_earnings": 5029.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0 } } } }, "noMatch": { "summary": "No subject match found in our database", "value": { "verification_id": "ver_01JT7K9S8D7FW80A2YQF0W2QX2", "status": "completed", "result_status": "no_match", "verification_type": "employment_income", "permissible_purpose": "credit_transaction", "requested_at": "2026-04-20T16:18:40Z", "completed_at": "2026-04-20T16:18:40Z", "verifier_reference_id": "MORTGAGE-2026-000982", "verifier_user_id": "user_alex.jordan@verifier.example.com", "subject_match": { "matched": false, "match_confidence": "none", "match_strategy": null }, "results": [], "aggregate_income_summary": null } }, "ambiguous": { "summary": "Ambiguous - SSN + DOB matched but optional legal_name disagrees with our record", "value": { "verification_id": "ver_01JT7KBV7Q1MHY0GGD31W4D6S5", "status": "completed", "result_status": "ambiguous_match", "verification_type": "employment_income", "permissible_purpose": "credit_transaction", "requested_at": "2026-04-20T16:25:04Z", "completed_at": "2026-04-20T16:25:04Z", "verifier_reference_id": "TENANT-2026-00115", "verifier_user_id": "user_chris.osei@landlord.example.com", "message": "SSN + date of birth matched a subject, but the optional legal_name disagreed with our record. Refusing to return data — the verifier should confirm they are looking up the right person.", "match_candidates": 1, "conflicting_fields": [ "legal_name" ], "subject_match": { "matched": false, "match_confidence": "low", "match_strategy": "ssn_full + date_of_birth" }, "results": [], "aggregate_income_summary": null } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:write" ] } ] } }, "/verifications/employment": { "post": { "tags": [ "Verifications" ], "summary": "Create an employment-only verification", "description": "Same matching behavior as `/verifications/employment-income`, but the response omits paycheck and income detail. Returns the matched person's employment records grouped by employer.", "operationId": "createEmploymentVerification", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationRequest" } } } }, "responses": { "200": { "description": "Verification completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmploymentVerificationResponse" }, "examples": { "verifiedMultiEmployer": { "summary": "Verified person with concurrent jobs at two employers", "value": { "verification_id": "ver_01JT7K4KT2X2Q1R7PS1D5Q2A6Z", "status": "completed", "result_status": "verified", "verification_type": "employment", "permissible_purpose": "credit_transaction", "requested_at": "2026-04-20T16:12:11Z", "completed_at": "2026-04-20T16:12:11Z", "verifier_reference_id": "MORTGAGE-2026-000981", "verifier_user_id": "user_alex.jordan@verifier.example.com", "subject_match": { "matched": true, "match_confidence": "high", "match_strategy": "ssn_full", "legal_name": { "first_name": "Jordan", "middle_name": "T", "last_name": "Miles" }, "date_of_birth": "1989-04-17", "ssn_last4": "6789", "residence_address": { "line1": "412 Maplewood Ave", "line2": "Apt 3B", "city": "Nashville", "county": "Davidson", "state": "TN", "postal_code": "37206", "country": "US" } }, "results": [ { "employer": { "employer_id": "emp_01JT7J6X8V0H2H6H7QJ4A9D1K2", "external_employer_id": "ACME-001", "legal_name": "Acme Distribution Holdings, Inc.", "dba_name": "Acme Distribution", "fein": "12-3451234", "currency": "USD" }, "employment_records": [ { "employee_number": "E102944", "status": "active", "employment_type": "full_time", "compensation_type": "salary", "job_title": "Senior Operations Analyst", "department": "Operations", "work_location": { "location_id": "loc_01JT7M6B8W9Y3E4R5T6U7V8W9X", "name": "Nashville Distribution Center", "address": { "line1": "200 Logistics Way", "city": "Nashville", "state": "TN", "postal_code": "37211", "country": "US" } }, "dates": { "original_hire_date": "2020-05-04", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2025-11-01", "pay_rate": 87500, "pay_frequency": "annual", "annualized_base_pay": 87500, "standard_hours": 40, "currency": "USD" } }, { "employee_number": "E102944", "status": "active", "employment_type": "full_time", "compensation_type": "salary", "job_title": "Regional Operations Analyst", "department": "Operations", "work_location": { "location_id": "loc_01JT7M6Z4N5P6Q7R8S9T0U1V2W", "name": "Memphis Fulfillment Hub", "address": { "line1": "4100 Distribution Pkwy", "city": "Memphis", "state": "TN", "postal_code": "38118", "country": "US" } }, "dates": { "original_hire_date": "2020-05-04", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2025-11-01", "pay_rate": 87500, "pay_frequency": "annual", "annualized_base_pay": 87500, "standard_hours": 40, "currency": "USD" } } ] }, { "employer": { "employer_id": "emp_01JT7H2ABC9XK1P0R8VQYTS3M4", "external_employer_id": "GLOBEX-014", "legal_name": "Globex Logistics, Inc.", "dba_name": null, "fein": "88-1235678", "currency": "USD" }, "employment_records": [ { "employee_number": "G-77310", "status": "active", "employment_type": "part_time", "compensation_type": "hourly", "job_title": "Weekend Driver", "department": "Fleet", "work_location": { "location_id": "loc_01JT7N1G2H3J4K5L6M7N8P9Q0R", "name": "Dallas Fleet Yard", "address": { "line1": "8901 Commerce Park Dr", "city": "Dallas", "state": "TX", "postal_code": "75247", "country": "US" } }, "dates": { "original_hire_date": "2024-09-12", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2024-09-12", "pay_rate": 28.5, "pay_frequency": "biweekly", "annualized_base_pay": 17784, "standard_hours": 12, "currency": "USD" } } ] } ] } }, "noMatch": { "summary": "No subject match found in our database", "value": { "verification_id": "ver_01JT7K9S8D7FW80A2YQF0W2QX2", "status": "completed", "result_status": "no_match", "verification_type": "employment", "permissible_purpose": "credit_transaction", "requested_at": "2026-04-20T16:18:40Z", "completed_at": "2026-04-20T16:18:40Z", "verifier_reference_id": "MORTGAGE-2026-000982", "verifier_user_id": "user_alex.jordan@verifier.example.com", "subject_match": { "matched": false, "match_confidence": "none", "match_strategy": null }, "results": [] } }, "ambiguous": { "summary": "Ambiguous - SSN + DOB matched but optional legal_name disagrees with our record", "value": { "verification_id": "ver_01JT7KBV7Q1MHY0GGD31W4D6S5", "status": "completed", "result_status": "ambiguous_match", "verification_type": "employment", "permissible_purpose": "credit_transaction", "requested_at": "2026-04-20T16:25:04Z", "completed_at": "2026-04-20T16:25:04Z", "verifier_reference_id": "TENANT-2026-00115", "verifier_user_id": "user_chris.osei@landlord.example.com", "message": "SSN + date of birth matched a subject, but the optional legal_name disagreed with our record. Refusing to return data — the verifier should confirm they are looking up the right person.", "match_candidates": 1, "conflicting_fields": [ "legal_name" ], "subject_match": { "matched": false, "match_confidence": "low", "match_strategy": "ssn_full + date_of_birth" }, "results": [] } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:write" ] } ] } }, "/verifications/government-verification": { "post": { "tags": [ "Government Verification" ], "summary": "Create a government verification", "description": "Government-grade single-subject verification. Searches across **all employers in the database** for the subject described in `subject_lookup`. Matching behavior is identical to `/verifications/employment-income`; this endpoint is exposed separately so agency/regulator integrations can be metered, logged, and audited independently from commercial verifier traffic.", "operationId": "createGovernmentVerification", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GovernmentVerificationRequest" }, "examples": { "ssnLookup": { "summary": "Lookup by full SSN (highest confidence)", "value": { "verifier_reference_id": "MORTGAGE-2026-000981", "verifier_user_id": "caseworker_3892@agency.example.gov", "permissible_purpose": "child_support_enforcement", "subject_lookup": { "ssn": "123-45-6789", "date_of_birth": "1989-04-17", "legal_name": { "first_name": "Jordan", "last_name": "Miles" } }, "options": { "include_inactive_employment": true, "paycheck_limit": 6, "as_of_date": "2026-04-20" } } }, "fullLookup": { "summary": "Required SSN + DOB plus optional legal_name, email, phone", "value": { "verifier_reference_id": "BACKGROUND-2026-44012", "verifier_user_id": "investigator_4421@agency.example.gov", "permissible_purpose": "benefit_eligibility_determination", "subject_lookup": { "ssn": "123-45-6789", "date_of_birth": "1989-04-17", "legal_name": { "first_name": "Jordan", "middle_name": "T", "last_name": "Miles" }, "email": "jordan.miles@example.com" }, "options": { "employer_limit": 1, "paycheck_limit": 4 } } }, "ambiguousLookup": { "summary": "SSN + DOB match a record but optional legal_name disagrees (returns ambiguous_match)", "value": { "verifier_reference_id": "TENANT-2026-00115", "verifier_user_id": "caseworker_2017@agency.example.gov", "permissible_purpose": "child_support_enforcement", "subject_lookup": { "ssn": "123-45-6789", "date_of_birth": "1989-04-17", "legal_name": { "first_name": "Jordan", "last_name": "Vance" } } } } } } } }, "responses": { "200": { "description": "Verification completed. The body's `result_status` indicates the business outcome.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" }, "examples": { "verifiedMultiEmployer": { "summary": "Verified person with concurrent jobs at two employers", "value": { "verification_id": "ver_01JT7K4KT2X2Q1R7PS1D5Q2A6Z", "status": "completed", "result_status": "verified", "verification_type": "employment_income", "permissible_purpose": "child_support_enforcement", "requested_at": "2026-04-20T16:12:11Z", "completed_at": "2026-04-20T16:12:11Z", "verifier_reference_id": "MORTGAGE-2026-000981", "verifier_user_id": "caseworker_3892@agency.example.gov", "subject_match": { "matched": true, "match_confidence": "high", "match_strategy": "ssn_full", "legal_name": { "first_name": "Jordan", "middle_name": "T", "last_name": "Miles" }, "date_of_birth": "1989-04-17", "ssn_last4": "6789", "residence_address": { "line1": "412 Maplewood Ave", "line2": "Apt 3B", "city": "Nashville", "county": "Davidson", "state": "TN", "postal_code": "37206", "country": "US" } }, "results": [ { "employer": { "employer_id": "emp_01JT7J6X8V0H2H6H7QJ4A9D1K2", "external_employer_id": "ACME-001", "legal_name": "Acme Distribution Holdings, Inc.", "dba_name": "Acme Distribution", "fein": "12-3451234", "currency": "USD" }, "employment_records": [ { "employee_number": "E102944", "status": "active", "employment_type": "full_time", "compensation_type": "salary", "job_title": "Senior Operations Analyst", "department": "Operations", "work_location": { "location_id": "loc_01JT7M6B8W9Y3E4R5T6U7V8W9X", "name": "Nashville Distribution Center", "address": { "line1": "200 Logistics Way", "city": "Nashville", "state": "TN", "postal_code": "37211", "country": "US" } }, "dates": { "original_hire_date": "2020-05-04", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2025-11-01", "pay_rate": 87500, "pay_frequency": "annual", "annualized_base_pay": 87500, "standard_hours": 40, "currency": "USD" }, "income_summary": { "currency": "USD", "latest_pay_date": "2026-04-15", "paycheck_count_returned": 1, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 80450, "regular_earnings": 78200, "overtime_earnings": 0, "bonus_earnings": 2250, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 2080.08, "overtime_hours": 0, "other_hours": 0, "total_hours": 2080.08 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 86420.5, "regular_earnings": 82660.5, "overtime_earnings": 1265, "bonus_earnings": 2495, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 2080.08, "overtime_hours": 30, "other_hours": 0, "total_hours": 2110.08 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 23869.23, "regular_earnings": 23584.61, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 606.69, "overtime_hours": 0, "other_hours": 0, "total_hours": 606.69 } ], "total": { "paycheck_count": 55, "gross_pay": 190739.73, "regular_earnings": 184445.11, "overtime_earnings": 1265, "bonus_earnings": 5029.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 4766.85, "overtime_hours": 30, "other_hours": 0, "total_hours": 4796.85 } }, "paychecks": [ { "paycheck_id": "pay_01JT7JS7VAD0H7EKR1D4XZ6S0A", "ext_payroll_id": "ADP-2026-04-15-49281", "pay_period_start_date": "2026-04-01", "pay_period_end_date": "2026-04-15", "pay_date": "2026-04-15", "check_date": "2026-04-15", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3653.85, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 86.67, "overtime_hours": 0, "other_hours": 0, "total_hours": 86.67, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 }, { "earning_type": "bonus", "description": "Performance Bonus", "hours": null, "rate": null, "amount": 284.62 } ] } ] }, { "employee_number": "E102944", "status": "active", "employment_type": "full_time", "compensation_type": "salary", "job_title": "Regional Operations Analyst", "department": "Operations", "work_location": { "location_id": "loc_01JT7M6Z4N5P6Q7R8S9T0U1V2W", "name": "Memphis Fulfillment Hub", "address": { "line1": "4100 Distribution Pkwy", "city": "Memphis", "state": "TN", "postal_code": "38118", "country": "US" } }, "dates": { "original_hire_date": "2020-05-04", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2025-11-01", "pay_rate": 87500, "pay_frequency": "annual", "annualized_base_pay": 87500, "standard_hours": 40, "currency": "USD" }, "income_summary": { "currency": "USD", "latest_pay_date": "2026-04-15", "paycheck_count_returned": 1, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 30200, "regular_earnings": 29300, "overtime_earnings": 0, "bonus_earnings": 900, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 780.03, "overtime_hours": 0, "other_hours": 0, "total_hours": 780.03 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 31530.25, "regular_earnings": 30070.25, "overtime_earnings": 505, "bonus_earnings": 955, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 780.03, "overtime_hours": 12, "other_hours": 0, "total_hours": 792.03 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 3, "gross_pay": 10392.31, "regular_earnings": 10107.69, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 260.01, "overtime_hours": 0, "other_hours": 0, "total_hours": 260.01 } ], "total": { "paycheck_count": 21, "gross_pay": 72122.56, "regular_earnings": 69477.94, "overtime_earnings": 505, "bonus_earnings": 2139.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 1820.07, "overtime_hours": 12, "other_hours": 0, "total_hours": 1832.07 } }, "paychecks": [ { "paycheck_id": "pay_acme_05_20260313", "ext_payroll_id": "ADP-2026-03-13-49286", "pay_period_start_date": "2026-03-01", "pay_period_end_date": "2026-03-15", "pay_date": "2026-03-13", "check_date": "2026-03-13", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3369.23, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 86.67, "overtime_hours": 0, "other_hours": 0, "total_hours": 86.67, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 } ] }, { "paycheck_id": "pay_acme_06_20260331", "ext_payroll_id": "ADP-2026-03-31-49287", "pay_period_start_date": "2026-03-16", "pay_period_end_date": "2026-03-31", "pay_date": "2026-03-31", "check_date": "2026-03-31", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3369.23, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 86.67, "overtime_hours": 0, "other_hours": 0, "total_hours": 86.67, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 } ] }, { "paycheck_id": "pay_acme_07_20260415", "ext_payroll_id": "ADP-2026-04-15-49288", "pay_period_start_date": "2026-04-01", "pay_period_end_date": "2026-04-15", "pay_date": "2026-04-15", "check_date": "2026-04-15", "pay_frequency": "semimonthly", "currency": "USD", "gross_pay": 3653.85, "regular_earnings": 3369.23, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 86.67, "overtime_hours": 0, "other_hours": 0, "total_hours": 86.67, "earnings": [ { "earning_type": "regular", "description": "Regular Salary", "hours": 86.67, "rate": 42.16, "amount": 3369.23 }, { "earning_type": "bonus", "description": "Performance Bonus", "hours": null, "rate": null, "amount": 284.62 } ] } ] } ], "by_work_location": [ { "work_location": { "location_id": "loc_01JT7M6B8W9Y3E4R5T6U7V8W9X", "name": "Nashville Distribution Center", "address": { "line1": "200 Logistics Way", "city": "Nashville", "state": "TN", "postal_code": "37211", "country": "US" } }, "currency": "USD", "first_pay_date": "2024-01-15", "latest_pay_date": "2026-04-15", "paycheck_count": 55, "gross_pay": 190739.73, "regular_earnings": 184445.11, "overtime_earnings": 1265, "bonus_earnings": 5029.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 4766.85, "overtime_hours": 30, "other_hours": 0, "total_hours": 4796.85, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 80450, "regular_earnings": 78200, "overtime_earnings": 0, "bonus_earnings": 2250, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 2080.08, "overtime_hours": 0, "other_hours": 0, "total_hours": 2080.08 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 86420.5, "regular_earnings": 82660.5, "overtime_earnings": 1265, "bonus_earnings": 2495, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 2080.08, "overtime_hours": 30, "other_hours": 0, "total_hours": 2110.08 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 23869.23, "regular_earnings": 23584.61, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 606.69, "overtime_hours": 0, "other_hours": 0, "total_hours": 606.69 } ] }, { "work_location": { "location_id": "loc_01JT7M6Z4N5P6Q7R8S9T0U1V2W", "name": "Memphis Fulfillment Hub", "address": { "line1": "4100 Distribution Pkwy", "city": "Memphis", "state": "TN", "postal_code": "38118", "country": "US" } }, "currency": "USD", "first_pay_date": "2024-04-30", "latest_pay_date": "2026-04-15", "paycheck_count": 21, "gross_pay": 72122.56, "regular_earnings": 69477.94, "overtime_earnings": 505, "bonus_earnings": 2139.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 1820.07, "overtime_hours": 12, "other_hours": 0, "total_hours": 1832.07, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 30200, "regular_earnings": 29300, "overtime_earnings": 0, "bonus_earnings": 900, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 780.03, "overtime_hours": 0, "other_hours": 0, "total_hours": 780.03 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 31530.25, "regular_earnings": 30070.25, "overtime_earnings": 505, "bonus_earnings": 955, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 780.03, "overtime_hours": 12, "other_hours": 0, "total_hours": 792.03 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 3, "gross_pay": 10392.31, "regular_earnings": 10107.69, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 260.01, "overtime_hours": 0, "other_hours": 0, "total_hours": 260.01 } ] } ] }, { "employer": { "employer_id": "emp_01JT7H2ABC9XK1P0R8VQYTS3M4", "external_employer_id": "GLOBEX-014", "legal_name": "Globex Logistics, Inc.", "dba_name": null, "fein": "88-1235678", "currency": "USD" }, "employment_records": [ { "employee_number": "G-77310", "status": "active", "employment_type": "part_time", "compensation_type": "hourly", "job_title": "Weekend Driver", "department": "Fleet", "work_location": { "location_id": "loc_01JT7N1G2H3J4K5L6M7N8P9Q0R", "name": "Dallas Fleet Yard", "address": { "line1": "8901 Commerce Park Dr", "city": "Dallas", "state": "TX", "postal_code": "75247", "country": "US" } }, "dates": { "original_hire_date": "2024-09-12", "rehire_date": null, "termination_date": null }, "current_compensation": { "effective_start_date": "2024-09-12", "pay_rate": 28.5, "pay_frequency": "biweekly", "annualized_base_pay": 17784, "standard_hours": 12, "currency": "USD" }, "income_summary": { "currency": "USD", "latest_pay_date": "2026-04-12", "paycheck_count_returned": 1, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 8, "gross_pay": 4560, "regular_earnings": 4560, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 160, "overtime_hours": 0, "other_hours": 0, "total_hours": 160 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 26, "gross_pay": 14820, "regular_earnings": 14820, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 520, "overtime_hours": 0, "other_hours": 0, "total_hours": 520 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 3990, "regular_earnings": 3990, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 140, "overtime_hours": 0, "other_hours": 0, "total_hours": 140 } ], "total": { "paycheck_count": 41, "gross_pay": 23370, "regular_earnings": 23370, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 820, "overtime_hours": 0, "other_hours": 0, "total_hours": 820 } }, "paychecks": [ { "paycheck_id": "pay_01JT7HVZJ1A3R9T8K3L5DM7QP2", "ext_payroll_id": "GUSTO-2026-04-12-771210", "pay_period_start_date": "2026-03-30", "pay_period_end_date": "2026-04-12", "pay_date": "2026-04-12", "check_date": "2026-04-12", "pay_frequency": "biweekly", "currency": "USD", "gross_pay": 570, "regular_earnings": 570, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 20, "overtime_hours": 0, "other_hours": 0, "total_hours": 20, "earnings": [ { "earning_type": "regular", "description": "Hourly Wages", "hours": 20, "rate": 28.5, "amount": 570 } ] } ] } ], "by_work_location": [ { "work_location": { "location_id": "loc_01JT7N1G2H3J4K5L6M7N8P9Q0R", "name": "Dallas Fleet Yard", "address": { "line1": "8901 Commerce Park Dr", "city": "Dallas", "state": "TX", "postal_code": "75247", "country": "US" } }, "currency": "USD", "first_pay_date": "2024-09-21", "latest_pay_date": "2026-04-12", "paycheck_count": 41, "gross_pay": 23370, "regular_earnings": 23370, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 820, "overtime_hours": 0, "other_hours": 0, "total_hours": 820, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 8, "gross_pay": 4560, "regular_earnings": 4560, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 160, "overtime_hours": 0, "other_hours": 0, "total_hours": 160 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 26, "gross_pay": 14820, "regular_earnings": 14820, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 520, "overtime_hours": 0, "other_hours": 0, "total_hours": 520 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 3990, "regular_earnings": 3990, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 140, "overtime_hours": 0, "other_hours": 0, "total_hours": 140 } ] } ] } ], "aggregate_income_summary": { "employer_count": 2, "active_employer_count": 2, "employment_record_count": 3, "active_employment_record_count": 3, "work_location_count": 3, "currency": "USD", "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 41, "gross_pay": 115210, "regular_earnings": 112060, "overtime_earnings": 0, "bonus_earnings": 3150, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 3020.11, "overtime_hours": 0, "other_hours": 0, "total_hours": 3020.11 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 59, "gross_pay": 132770.75, "regular_earnings": 127550.75, "overtime_earnings": 1770, "bonus_earnings": 3450, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 3380.11, "overtime_hours": 42, "other_hours": 0, "total_hours": 3422.11 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 17, "gross_pay": 38251.54, "regular_earnings": 37682.3, "overtime_earnings": 0, "bonus_earnings": 569.24, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 1006.7, "overtime_hours": 0, "other_hours": 0, "total_hours": 1006.7 } ], "total": { "paycheck_count": 117, "gross_pay": 286232.29, "regular_earnings": 277293.05, "overtime_earnings": 1770, "bonus_earnings": 7169.24, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 7406.92, "overtime_hours": 42, "other_hours": 0, "total_hours": 7448.92 }, "by_work_location": [ { "work_location": { "location_id": "loc_01JT7M6B8W9Y3E4R5T6U7V8W9X", "name": "Nashville Distribution Center", "address": { "line1": "200 Logistics Way", "city": "Nashville", "state": "TN", "postal_code": "37211", "country": "US" } }, "employer_id": "emp_01JT7J6X8V0H2H6H7QJ4A9D1K2", "currency": "USD", "first_pay_date": "2024-01-15", "latest_pay_date": "2026-04-15", "paycheck_count": 55, "gross_pay": 190739.73, "regular_earnings": 184445.11, "overtime_earnings": 1265, "bonus_earnings": 5029.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 4766.85, "overtime_hours": 30, "other_hours": 0, "total_hours": 4796.85, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 80450, "regular_earnings": 78200, "overtime_earnings": 0, "bonus_earnings": 2250, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 2080.08, "overtime_hours": 0, "other_hours": 0, "total_hours": 2080.08 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 24, "gross_pay": 86420.5, "regular_earnings": 82660.5, "overtime_earnings": 1265, "bonus_earnings": 2495, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 2080.08, "overtime_hours": 30, "other_hours": 0, "total_hours": 2110.08 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 23869.23, "regular_earnings": 23584.61, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 606.69, "overtime_hours": 0, "other_hours": 0, "total_hours": 606.69 } ] }, { "work_location": { "location_id": "loc_01JT7M6Z4N5P6Q7R8S9T0U1V2W", "name": "Memphis Fulfillment Hub", "address": { "line1": "4100 Distribution Pkwy", "city": "Memphis", "state": "TN", "postal_code": "38118", "country": "US" } }, "employer_id": "emp_01JT7J6X8V0H2H6H7QJ4A9D1K2", "currency": "USD", "first_pay_date": "2024-04-30", "latest_pay_date": "2026-04-15", "paycheck_count": 21, "gross_pay": 72122.56, "regular_earnings": 69477.94, "overtime_earnings": 505, "bonus_earnings": 2139.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 1820.07, "overtime_hours": 12, "other_hours": 0, "total_hours": 1832.07, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 30200, "regular_earnings": 29300, "overtime_earnings": 0, "bonus_earnings": 900, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 780.03, "overtime_hours": 0, "other_hours": 0, "total_hours": 780.03 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 9, "gross_pay": 31530.25, "regular_earnings": 30070.25, "overtime_earnings": 505, "bonus_earnings": 955, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 780.03, "overtime_hours": 12, "other_hours": 0, "total_hours": 792.03 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 3, "gross_pay": 10392.31, "regular_earnings": 10107.69, "overtime_earnings": 0, "bonus_earnings": 284.62, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 260.01, "overtime_hours": 0, "other_hours": 0, "total_hours": 260.01 } ] }, { "work_location": { "location_id": "loc_01JT7N1G2H3J4K5L6M7N8P9Q0R", "name": "Dallas Fleet Yard", "address": { "line1": "8901 Commerce Park Dr", "city": "Dallas", "state": "TX", "postal_code": "75247", "country": "US" } }, "employer_id": "emp_01JT7H2ABC9XK1P0R8VQYTS3M4", "currency": "USD", "first_pay_date": "2024-09-21", "latest_pay_date": "2026-04-12", "paycheck_count": 41, "gross_pay": 23370, "regular_earnings": 23370, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 820, "overtime_hours": 0, "other_hours": 0, "total_hours": 820, "by_year": [ { "year": 2024, "is_year_to_date": false, "paycheck_count": 8, "gross_pay": 4560, "regular_earnings": 4560, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 160, "overtime_hours": 0, "other_hours": 0, "total_hours": 160 }, { "year": 2025, "is_year_to_date": false, "paycheck_count": 26, "gross_pay": 14820, "regular_earnings": 14820, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 520, "overtime_hours": 0, "other_hours": 0, "total_hours": 520 }, { "year": 2026, "is_year_to_date": true, "paycheck_count": 7, "gross_pay": 3990, "regular_earnings": 3990, "overtime_earnings": 0, "bonus_earnings": 0, "commission_earnings": 0, "holiday_earnings": 0, "incentive_earnings": 0, "miscellaneous_earnings": 0, "pension_earnings": 0, "pto_earnings": 0, "pto_payout_earnings": 0, "severance_earnings": 0, "sick_earnings": 0, "sick_payout_earnings": 0, "tips_earnings": 0, "vacation_earnings": 0, "vacation_payout_earnings": 0, "workers_comp_earnings": 0, "regular_hours": 140, "overtime_hours": 0, "other_hours": 0, "total_hours": 140 } ] } ] } } }, "noMatch": { "summary": "No subject match found in our database", "value": { "verification_id": "ver_01JT7K9S8D7FW80A2YQF0W2QX2", "status": "completed", "result_status": "no_match", "verification_type": "employment_income", "permissible_purpose": "child_support_enforcement", "requested_at": "2026-04-20T16:18:40Z", "completed_at": "2026-04-20T16:18:40Z", "verifier_reference_id": "MORTGAGE-2026-000982", "verifier_user_id": "investigator_4421@agency.example.gov", "subject_match": { "matched": false, "match_confidence": "none", "match_strategy": null }, "results": [], "aggregate_income_summary": null } }, "ambiguous": { "summary": "Ambiguous - SSN + DOB matched but optional legal_name disagrees with our record", "value": { "verification_id": "ver_01JT7KBV7Q1MHY0GGD31W4D6S5", "status": "completed", "result_status": "ambiguous_match", "verification_type": "employment_income", "permissible_purpose": "child_support_enforcement", "requested_at": "2026-04-20T16:25:04Z", "completed_at": "2026-04-20T16:25:04Z", "verifier_reference_id": "TENANT-2026-00115", "verifier_user_id": "caseworker_2017@agency.example.gov", "message": "SSN + date of birth matched a subject, but the optional legal_name disagreed with our record. Refusing to return data — the verifier should confirm they are looking up the right person.", "match_candidates": 1, "conflicting_fields": [ "legal_name" ], "subject_match": { "matched": false, "match_confidence": "low", "match_strategy": "ssn_full + date_of_birth" }, "results": [], "aggregate_income_summary": null } } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:write" ] } ] } }, "/verifications/{verification_id}": { "get": { "tags": [ "Verifications" ], "summary": "Retrieve a previously created verification", "operationId": "getVerification", "parameters": [ { "name": "verification_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "ver_01JT7K4KT2X2Q1R7PS1D5Q2A6Z" } ], "responses": { "200": { "description": "Verification record.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VerificationResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:read" ] } ] } }, "/verifications/batches": { "post": { "tags": [ "Batches (JSON)" ], "summary": "Create an async JSON batch (1–500 subjects)", "description": "Submits up to **500 subjects** in a single JSON payload for asynchronous verification. Returns immediately with a `batch_id`. Each subject is processed independently and produces its own `VerificationResponse`. Notification options:\n\n- Poll `GET /verifications/batches/{batch_id}` for progress.\n- Provide a `webhook_url` to receive `verification.batch.completed` when the entire batch finishes.\n\nFor batches larger than 500, use the file upload endpoint.", "operationId": "createBatchJson", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchJsonRequest" }, "examples": { "smallBatch": { "summary": "3-subject batch with webhook", "value": { "verification_type": "employment_income", "permissible_purpose": "credit_transaction", "verifier_user_id": "user_alex.jordan@verifier.example.com", "webhook_url": "https://verifier.example.com/hooks/ryze-batches", "options": { "include_inactive_employment": true, "employer_limit": null, "paycheck_limit": 6 }, "subjects": [ { "verifier_reference_id": "MORTGAGE-2026-000981", "verifier_user_id": "user_alex.jordan@verifier.example.com", "subject_lookup": { "ssn": "123-45-6789", "date_of_birth": "1989-04-17", "legal_name": { "first_name": "Jordan", "last_name": "Miles" } } }, { "verifier_reference_id": "MORTGAGE-2026-000982", "verifier_user_id": "user_alex.jordan@verifier.example.com", "subject_lookup": { "ssn": "234-56-7890", "date_of_birth": "1992-11-02", "legal_name": { "first_name": "Casey", "last_name": "Nguyen" } } }, { "verifier_reference_id": "MORTGAGE-2026-000983", "verifier_user_id": "user_priya.shah@verifier.example.com", "subject_lookup": { "ssn": "345-67-4421", "date_of_birth": "1985-07-29", "legal_name": { "first_name": "Robin", "last_name": "Patel" } } } ] } } } } } }, "responses": { "202": { "description": "Batch accepted and queued for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" }, "example": { "batch_id": "bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "status": "queued", "source": "json", "verification_type": "employment_income", "subject_count": 3, "completed_count": 0, "verified_count": 0, "no_match_count": 0, "ambiguous_count": 0, "failed_count": 0, "webhook_url": "https://verifier.example.com/hooks/ryze-batches", "created_at": "2026-04-20T17:02:11Z", "started_at": null, "completed_at": null, "expires_at": "2026-05-20T17:02:11Z", "links": { "self": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "results": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD/results" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "description": "Batch exceeds the 500-subject limit. Use the file upload endpoint for larger batches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "batch_too_large", "message": "JSON batch limit is 500 subjects. Submitted 1023. Use POST /verifications/batches/uploads for larger batches." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:write" ] } ] } }, "/verifications/batches/uploads": { "post": { "tags": [ "Batches (File Upload)" ], "summary": "Create an async batch by uploading a CSV (up to 100,000 subjects)", "description": "Upload a CSV (or NDJSON) file containing one subject per row. Suited for mortgage portfolio re-verification, background-screening sweeps, and audits.\n\n**Required columns** (header row): `verifier_reference_id`, `ssn` (full 9-digit), and `date_of_birth` (ISO 8601). Both `ssn` and `date_of_birth` are mandatory on every row.\n\n**Optional columns**: `verifier_user_id` (per-row identifier of the user at the verifier company responsible for that subject; falls back to the form-level `verifier_user_id` if omitted), `first_name`, `middle_name`, `last_name`, `suffix`, `ssn_last4`, `email`, `phone`. When provided, optional identifiers are cross-checked against our record; a mismatch downgrades the row to `ambiguous_match`.\n\n**File-level form fields**: in addition to the file itself, the multipart form accepts `permissible_purpose` (required), `verification_type`, `webhook_url`, `options`, and `verifier_user_id` (default user attribution applied to every row that does not carry its own `verifier_user_id`).\n\n**File limits**: max 100,000 rows, max 50 MB. UTF-8, RFC 4180 CSV.\n\nResults are made available as a downloadable NDJSON or CSV file once processing finishes. A webhook is fired on completion if `webhook_url` is provided.", "operationId": "createBatchUpload", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "verification_type" ], "properties": { "file": { "type": "string", "format": "binary", "description": "CSV or NDJSON file. UTF-8 encoded. Max 100,000 rows / 50 MB." }, "verification_type": { "type": "string", "enum": [ "employment", "employment_income" ] }, "file_format": { "type": "string", "enum": [ "csv", "ndjson" ], "default": "csv" }, "webhook_url": { "type": "string", "format": "uri", "description": "Optional. Where to POST the `verification.batch.completed` event." }, "result_format": { "type": "string", "enum": [ "csv", "ndjson" ], "default": "ndjson", "description": "Format the verifier wants the downloadable results file in." }, "options": { "type": "string", "description": "Optional. JSON-encoded `VerificationOptions` applied to every row in the batch.", "example": "{\"include_inactive_employment\": true, \"employer_limit\": null, \"paycheck_limit\": 4}" }, "verifier_user_id": { "type": "string", "description": "Batch-level identifier for the **end user at the verifier company** who submitted the upload. Applied as the default `verifier_user_id` for every row in the file that does not carry its own (CSV column or NDJSON field). Required unless every row in the file provides its own `verifier_user_id`. Uploads where any row resolves to no `verifier_user_id` are rejected with `400 invalid_request` before any subject is processed.", "example": "user_alex.jordan@verifier.example.com" } } } } } }, "responses": { "202": { "description": "Upload accepted and queued for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" }, "example": { "batch_id": "bat_01JT8B5M0VKD3Q4HX2P7N9F1A6", "status": "queued", "source": "csv", "verification_type": "employment_income", "subject_count": 18432, "completed_count": 0, "verified_count": 0, "no_match_count": 0, "ambiguous_count": 0, "failed_count": 0, "result_format": "ndjson", "file_name": "wells-fargo-portfolio-2026-04.csv", "file_size_bytes": 2148304, "webhook_url": "https://verifier.example.com/hooks/ryze-batches", "created_at": "2026-04-20T17:14:08Z", "started_at": null, "completed_at": null, "expires_at": "2026-05-20T17:14:08Z", "links": { "self": "/v1/verifications/batches/bat_01JT8B5M0VKD3Q4HX2P7N9F1A6", "download": "/v1/verifications/batches/bat_01JT8B5M0VKD3Q4HX2P7N9F1A6/download", "errors": "/v1/verifications/batches/bat_01JT8B5M0VKD3Q4HX2P7N9F1A6/errors" } } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "description": "File exceeds size or row limits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "file_too_large", "message": "Upload exceeds 100,000-row limit. Split the file and submit multiple batches." } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "batches:write" ] } ] } }, "/verifications/batches/{batch_id}": { "get": { "tags": [ "Batches (JSON)" ], "summary": "Get the status of a batch", "description": "Returns current progress, counts, and links. Works for both JSON and file-upload batches.", "operationId": "getBatchStatus", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" }, "example": "bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD" } ], "responses": { "200": { "description": "Batch status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" }, "examples": { "processing": { "summary": "Processing — partial progress", "value": { "batch_id": "bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "status": "processing", "source": "json", "verification_type": "employment_income", "subject_count": 3, "completed_count": 1, "verified_count": 1, "no_match_count": 0, "ambiguous_count": 0, "failed_count": 0, "created_at": "2026-04-20T17:02:11Z", "started_at": "2026-04-20T17:02:13Z", "completed_at": null, "expires_at": "2026-05-20T17:02:11Z", "links": { "self": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "results": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD/results" } } }, "completed": { "summary": "Completed", "value": { "batch_id": "bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "status": "completed", "source": "json", "verification_type": "employment_income", "subject_count": 3, "completed_count": 3, "verified_count": 2, "no_match_count": 0, "ambiguous_count": 1, "failed_count": 0, "created_at": "2026-04-20T17:02:11Z", "started_at": "2026-04-20T17:02:13Z", "completed_at": "2026-04-20T17:02:24Z", "expires_at": "2026-05-20T17:02:11Z", "webhook_status": "delivered", "links": { "self": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "results": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD/results" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:read" ] } ] } }, "/verifications/batches/{batch_id}/results": { "get": { "tags": [ "Batches (JSON)" ], "summary": "List per-subject results for a batch", "description": "Returns one `BatchItemResult` per submitted subject. Cursor-paginated. Each item links to its underlying single-subject `verification_id` so the full `VerificationResponse` can be fetched via `GET /verifications/{verification_id}`.\n\nSet the `Accept` header to `application/x-ndjson` to stream results as newline-delimited JSON, ideal for very large batches.", "operationId": "getBatchResults", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "result_status", "in": "query", "schema": { "type": "string", "enum": [ "verified", "partial_match", "no_match", "ambiguous_match", "error" ] }, "description": "Filter results by outcome." }, { "name": "include_full_response", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "When true, embeds the full `VerificationResponse` for each item. Default is just summaries with links." } ], "responses": { "200": { "description": "Paginated batch results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResultsPage" }, "example": { "data": [ { "position": 1, "verifier_reference_id": "MORTGAGE-2026-000981", "verifier_user_id": "user_alex.jordan@verifier.example.com", "verification_id": "ver_01JT8ABK0H1QF82Y6X8N0R5MV2", "result_status": "verified", "match_confidence": "high", "employer_count": 2, "active_employer_count": 2, "ytd_gross_pay": 29746.84, "currency": "USD", "processed_at": "2026-04-20T17:02:18Z", "links": { "verification": "/v1/verifications/ver_01JT8ABK0H1QF82Y6X8N0R5MV2" } }, { "position": 2, "verifier_reference_id": "MORTGAGE-2026-000982", "verifier_user_id": "user_alex.jordan@verifier.example.com", "verification_id": "ver_01JT8ABM2A0R3SVDM6CJ5KQ8XT", "result_status": "verified", "match_confidence": "high", "employer_count": 1, "active_employer_count": 1, "ytd_gross_pay": 41208.55, "currency": "USD", "processed_at": "2026-04-20T17:02:21Z", "links": { "verification": "/v1/verifications/ver_01JT8ABM2A0R3SVDM6CJ5KQ8XT" } }, { "position": 3, "verifier_reference_id": "MORTGAGE-2026-000983", "verifier_user_id": "user_priya.shah@verifier.example.com", "verification_id": "ver_01JT8ABNZ7H4P0X8DM2J9KQ4YE", "result_status": "ambiguous_match", "match_confidence": "low", "match_candidates": 1, "conflicting_fields": [ "legal_name" ], "processed_at": "2026-04-20T17:02:24Z", "links": { "verification": "/v1/verifications/ver_01JT8ABNZ7H4P0X8DM2J9KQ4YE" } } ], "next_cursor": null } }, "application/x-ndjson": { "schema": { "type": "string", "description": "Newline-delimited JSON. One `BatchItemResult` per line." } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:read" ] } ] } }, "/verifications/batches/{batch_id}/download": { "get": { "tags": [ "Batches (File Upload)" ], "summary": "Download the results file for an upload batch", "description": "Returns a downloadable file (`text/csv` or `application/x-ndjson`, depending on the `result_format` chosen at upload time) containing one row per submitted subject. Available once `status` is `completed`.\n\nFor failed rows (validation errors, malformed identifiers), use `GET /verifications/batches/{batch_id}/errors`.", "operationId": "downloadBatchResults", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Results file.", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "verifier_reference_id,verifier_user_id,verification_id,result_status,match_confidence,employer_count,active_employer_count,ytd_gross_pay,currency,latest_pay_date\nMORTGAGE-2026-000981,user_alex.jordan@verifier.example.com,ver_01JT8ABK0H1QF82Y6X8N0R5MV2,verified,high,2,2,29746.84,USD,2026-04-15\nMORTGAGE-2026-000982,user_alex.jordan@verifier.example.com,ver_01JT8ABM2A0R3SVDM6CJ5KQ8XT,verified,high,1,1,41208.55,USD,2026-04-15\nMORTGAGE-2026-000983,user_priya.shah@verifier.example.com,ver_01JT8ABNZ7H4P0X8DM2J9KQ4YE,ambiguous_match,low,,,,USD,\n" }, "application/x-ndjson": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Batch is not yet completed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "batch_not_ready", "message": "Batch is still processing. Try again later." } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:read" ] } ] } }, "/verifications/batches/{batch_id}/errors": { "get": { "tags": [ "Batches (File Upload)" ], "summary": "List rows that failed validation or processing in an upload batch", "description": "Returns one entry per row that could not be processed (e.g., malformed SSN, missing required identifiers, duplicate `verifier_reference_id`). These rows are not counted in `verified_count`/`no_match_count`/`ambiguous_count`; they appear in `failed_count`.", "operationId": "getBatchErrors", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "maximum": 500 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated list of failed rows.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItemError" } }, "next_cursor": { "type": "string", "nullable": true } } }, "example": { "data": [ { "position": 47, "verifier_reference_id": "MORTGAGE-2026-001027", "verifier_user_id": "user_alex.jordan@verifier.example.com", "error_code": "invalid_identifier", "error_message": "ssn is not 9 digits", "raw_row": { "ssn": "12345", "first_name": "Pat", "last_name": "Lee", "date_of_birth": "1990-02-11" } }, { "position": 102, "verifier_reference_id": "MORTGAGE-2026-001082", "verifier_user_id": "user_priya.shah@verifier.example.com", "error_code": "missing_required_identifiers", "error_message": "Both ssn and date_of_birth are required on every row.", "raw_row": { "first_name": "Sam", "ssn_last4": "9911" } } ], "next_cursor": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:read" ] } ] } }, "/verifications/batches/{batch_id}/cancel": { "post": { "tags": [ "Batches (JSON)" ], "summary": "Cancel a batch that is queued or processing", "description": "Already-completed items remain accessible. Items not yet processed are abandoned. Idempotent; safe to call multiple times.", "operationId": "cancelBatch", "parameters": [ { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancellation accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Batch is already in a terminal state (completed, failed, or cancelled).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "batch_already_terminal", "message": "Cannot cancel a batch in status `completed`." } } } } } }, "security": [ { "ApiKeyAuth": [] }, { "OAuth2ClientCredentials": [ "verifications:write" ] } ] } } }, "webhooks": { "verification.batch.completed": { "post": { "tags": [ "Webhooks" ], "summary": "Fired when a batch finishes processing", "description": "Sent to the `webhook_url` provided at batch creation. Includes a signature header `X-Ryze-Signature: t=,v1=` computed over the raw request body using your verifier-account webhook secret.\n\nYour endpoint must respond with 2xx within 10 seconds. We retry with exponential backoff for up to 24 hours on non-2xx responses.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JT8AC2P8QH4F2C3KL9R7N5V0", "type": "verification.batch.completed", "created_at": "2026-04-20T17:02:24Z", "data": { "batch_id": "bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "status": "completed", "source": "json", "verification_type": "employment_income", "subject_count": 3, "completed_count": 3, "verified_count": 2, "no_match_count": 0, "ambiguous_count": 1, "failed_count": 0, "links": { "self": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD", "results": "/v1/verifications/batches/bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD/results" } } } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } }, "verification.batch.failed": { "post": { "tags": [ "Webhooks" ], "summary": "Fired when a batch fails to process at all (e.g., file unreadable)", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_01JT8AD9N4VFK2D7H1XR4P0M2X", "type": "verification.batch.failed", "created_at": "2026-04-20T17:14:51Z", "data": { "batch_id": "bat_01JT8B5M0VKD3Q4HX2P7N9F1A6", "status": "failed", "error_code": "csv_parse_error", "error_message": "Row 5: missing required column `last_name`." } } } } }, "responses": { "2XX": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your verifier API key. Format: `vk_live_xxx` for production, `vk_test_xxx` for sandbox. Sent on every request as the `X-API-Key` header. Use this for quick integrations and server-to-server traffic that does not need short-lived credentials." }, "OAuth2ClientCredentials": { "type": "oauth2", "description": "Standard OAuth 2.0 **client credentials** flow (RFC 6749, Section 4.4). The verifier exchanges a `client_id` + `client_secret` issued from the developer console for a short-lived bearer token, then sends it as `Authorization: Bearer ` on every API call. Tokens expire after 1 hour; refresh by re-running the token exchange. Recommended for production integrations because secrets can be rotated without redeploying client code, and access can be scoped per credential.", "flows": { "clientCredentials": { "tokenUrl": "https://auth.example.com/oauth/token", "scopes": { "verifications:read": "Retrieve previously created verifications and batch results.", "verifications:write": "Create single-subject verifications and submit JSON batches.", "batches:write": "Create file-upload batches.", "webhooks:manage": "Create, update, and delete webhook subscriptions." } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID. Replaying the same key with the same payload returns the original verification.", "schema": { "type": "string", "format": "uuid" }, "example": "5d8a3d0e-7c0a-4f16-b1b6-6b2f8d8b1e98" } }, "responses": { "InvalidRequest": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missingRequiredIdentifiers": { "summary": "Missing one or both required identifiers", "value": { "error": { "code": "invalid_request", "message": "subject_lookup must include both `ssn` and `date_of_birth`. Both fields are mandatory.", "details": [ { "field": "subject_lookup.ssn", "issue": "missing" }, { "field": "subject_lookup.date_of_birth", "issue": "missing" } ] } } } } } } }, "Unauthorized": { "description": "Missing, invalid, or expired credentials. Returned when the `X-API-Key` header is absent/incorrect, or when the OAuth bearer token is missing, malformed, expired, or lacks a scope required for the requested endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "invalidApiKey": { "summary": "API key is invalid or expired", "value": { "error": { "code": "unauthorized", "message": "API key is invalid or expired" } } }, "invalidBearerToken": { "summary": "OAuth bearer token is invalid or expired", "value": { "error": { "code": "unauthorized", "message": "Bearer token is invalid or expired. Re-exchange your client credentials at https://auth.example.com/oauth/token." } } }, "insufficientScope": { "summary": "OAuth bearer token is missing a required scope", "value": { "error": { "code": "insufficient_scope", "message": "This endpoint requires the `verifications:write` scope." } } } } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "not_found", "message": "Verification not found" } } } } }, "IdempotencyConflict": { "description": "Idempotency-Key reused with a different payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "idempotency_conflict", "message": "This Idempotency-Key has already been used with a different request payload" } } } } }, "RateLimited": { "description": "Too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "rate_limited", "message": "Too many requests", "retry_after_seconds": 30 } } } } }, "ServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "error": { "code": "internal_error", "message": "An unexpected error occurred" } } } } } }, "schemas": { "VerificationRequest": { "type": "object", "required": [ "subject_lookup", "permissible_purpose", "verifier_user_id" ], "properties": { "verifier_reference_id": { "type": "string", "description": "Optional reference for your own system (loan number, file ID, screening case ID, etc.).", "example": "MORTGAGE-2026-000981" }, "verifier_user_id": { "type": "string", "description": "**Required.** Stable identifier for the end user at the verifier company who initiated this request (loan officer, underwriter, agent, agency caseworker, etc.). Used for per-seat audit, FCRA permissible-purpose attribution, and downstream user-level rate limiting / billing. Pass any opaque ID your IDP issues (employee number, email, OIDC `sub`, UUID); we treat it as opaque and echo it back on the response unchanged. Requests missing `verifier_user_id` are rejected with `400 invalid_request`.", "example": "user_alex.jordan@verifier.example.com" }, "permissible_purpose": { "$ref": "#/components/schemas/CommercialPermissiblePurpose" }, "subject_lookup": { "$ref": "#/components/schemas/SubjectLookup" }, "options": { "$ref": "#/components/schemas/VerificationOptions" } } }, "SubjectLookup": { "type": "object", "description": "Identifiers used to find the subject across our entire database.\n\n**Always required on every request:**\n- `ssn` (full 9-digit SSN)\n- `date_of_birth`\n\nAll other fields are optional add-ons. When an optional identifier is provided, it is cross-checked against our record; a disagreement downgrades the response to `ambiguous_match` (no data returned).", "required": [ "ssn", "date_of_birth" ], "properties": { "ssn": { "type": "string", "description": "Full Social Security Number. **Required.** Accepted formats: `123-45-6789` or `123456789`.", "example": "123-45-6789" }, "date_of_birth": { "type": "string", "format": "date", "description": "Subject's date of birth. **Required.** ISO 8601 (`YYYY-MM-DD`).", "example": "1989-04-17" }, "legal_name": { "type": "object", "description": "Optional. When provided, the name is cross-checked against our record. A mismatch produces `ambiguous_match`.", "properties": { "first_name": { "type": "string", "example": "Jordan" }, "middle_name": { "type": "string", "nullable": true, "example": "T" }, "last_name": { "type": "string", "example": "Miles" }, "suffix": { "type": "string", "nullable": true } }, "required": [ "first_name", "last_name" ] }, "ssn_last4": { "type": "string", "description": "Optional. Redundant with the full SSN, accepted for cross-system audit.", "example": "6789" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Optional. Used as a tie-breaker when present." }, "phone": { "type": "string", "nullable": true, "description": "Optional. E.164 preferred." } } }, "VerificationOptions": { "type": "object", "properties": { "include_inactive_employment": { "type": "boolean", "default": true, "description": "If true, terminated and inactive employment records are also returned. If false, only currently active records." }, "include_paychecks": { "type": "boolean", "default": true }, "include_tax_breakdown": { "type": "boolean", "default": true }, "include_deduction_breakdown": { "type": "boolean", "default": true }, "employer_limit": { "type": "integer", "nullable": true, "minimum": 1, "default": null, "description": "Maximum number of employers to return for the matched subject, counted from the most recent employer (sorted by latest paycheck date, with active employers first). For example, `1` returns only the most-recent employer. Omit the field or pass `null` to return **all** employers on file (default). The cross-employer `aggregate_income_summary` is computed over the employers that are actually returned." }, "paycheck_limit": { "type": "integer", "default": 6, "minimum": 1, "maximum": 24, "description": "Maximum paychecks to include per employment record." }, "as_of_date": { "type": "string", "format": "date", "description": "Treat YTD figures and active/inactive employment as of this date.", "example": "2026-04-20" } } }, "VerificationResponse": { "type": "object", "required": [ "verification_id", "status", "result_status", "verification_type", "requested_at", "completed_at" ], "properties": { "verification_id": { "type": "string", "example": "ver_01JT7K4KT2X2Q1R7PS1D5Q2A6Z" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "result_status": { "type": "string", "enum": [ "verified", "partial_match", "no_match", "ambiguous_match", "error" ] }, "verification_type": { "type": "string", "enum": [ "employment", "employment_income" ] }, "requested_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "verifier_reference_id": { "type": "string", "nullable": true }, "verifier_user_id": { "type": "string", "nullable": true, "description": "Echo of the `verifier_user_id` declared on the request. Stored on the verification record so per-seat activity can be audited without joining back to the verifier's own logs." }, "permissible_purpose": { "type": "string", "description": "Echo of the `permissible_purpose` declared on the request. One of the commercial or government purpose enums.", "example": "credit_transaction" }, "message": { "type": "string", "nullable": true, "description": "Human-readable detail; populated for `ambiguous_match` and `error`." }, "match_candidates": { "type": "integer", "nullable": true, "description": "For `ambiguous_match`: number of distinct people that matched the required identifiers (ssn + date_of_birth). Typically 1 — ambiguity now usually comes from optional-field disagreement rather than multiple SSN matches." }, "conflicting_fields": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "For `ambiguous_match`: optional `subject_lookup` fields the verifier sent that disagree with our record (for example `legal_name`, `email`, `phone`). The verifier should confirm they are looking up the right person before retrying." }, "subject_match": { "$ref": "#/components/schemas/SubjectMatch" }, "results": { "type": "array", "description": "One entry per employer the matched person has records at. Sorted: active employers first, then by most-recent paycheck date desc.", "items": { "$ref": "#/components/schemas/EmployerResult" } }, "aggregate_income_summary": { "$ref": "#/components/schemas/AggregateIncomeSummary" } } }, "EmploymentVerificationResponse": { "type": "object", "required": [ "verification_id", "status", "result_status", "verification_type", "requested_at", "completed_at" ], "properties": { "verification_id": { "type": "string", "example": "ver_01JT7K4KT2X2Q1R7PS1D5Q2A6Z" }, "status": { "type": "string", "enum": [ "completed", "failed" ] }, "result_status": { "type": "string", "enum": [ "verified", "partial_match", "no_match", "ambiguous_match", "error" ] }, "verification_type": { "type": "string", "enum": [ "employment" ] }, "requested_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time" }, "verifier_reference_id": { "type": "string", "nullable": true }, "verifier_user_id": { "type": "string", "nullable": true, "description": "Echo of the `verifier_user_id` declared on the request. Stored on the verification record so per-seat activity can be audited without joining back to the verifier's own logs." }, "permissible_purpose": { "type": "string", "description": "Echo of the `permissible_purpose` declared on the request. One of the commercial or government purpose enums.", "example": "credit_transaction" }, "message": { "type": "string", "nullable": true, "description": "Human-readable detail; populated for `ambiguous_match` and `error`." }, "match_candidates": { "type": "integer", "nullable": true, "description": "For `ambiguous_match`: number of distinct people that matched the required identifiers (ssn + date_of_birth). Typically 1 — ambiguity now usually comes from optional-field disagreement rather than multiple SSN matches." }, "conflicting_fields": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "For `ambiguous_match`: optional `subject_lookup` fields the verifier sent that disagree with our record (for example `legal_name`, `email`, `phone`). The verifier should confirm they are looking up the right person before retrying." }, "subject_match": { "$ref": "#/components/schemas/SubjectMatch" }, "results": { "type": "array", "description": "One entry per employer the matched person has records at. Sorted: active employers first, then by most-recent paycheck date desc.", "items": { "$ref": "#/components/schemas/EmploymentEmployerResult" } } } }, "SubjectMatch": { "type": "object", "description": "Identity attributes of the matched subject. Returned on every endpoint (commercial, government, batch, upload). Populated only when `matched: true`; on `no_match` and `ambiguous_match` only `matched`, `match_confidence`, and `match_strategy` are set.", "properties": { "matched": { "type": "boolean" }, "match_confidence": { "type": "string", "enum": [ "high", "medium", "low", "none" ] }, "match_strategy": { "type": "string", "nullable": true, "description": "Which identifiers produced the match.", "example": "ssn_full" }, "legal_name": { "type": "object", "nullable": true, "properties": { "first_name": { "type": "string" }, "middle_name": { "type": "string", "nullable": true }, "last_name": { "type": "string" } } }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "ssn_last4": { "type": "string", "nullable": true, "example": "6789" }, "residence_address": { "type": "object", "nullable": true, "description": "Home / residence address of the matched subject, as last reported by the source payroll provider. Useful for jurisdiction attribution (state-tax nexus, child-support venue, agency benefit eligibility) and for distinguishing between candidates when a verifier is reconciling our match against their own record. Returned only when `matched: true`; individual fields may be `null` when the source provider didn't report them.", "properties": { "line1": { "type": "string", "nullable": true, "description": "Street address line 1. Source field: `employee.address1`.", "example": "412 Maplewood Ave" }, "line2": { "type": "string", "nullable": true, "description": "Street address line 2 (apt, suite, unit, etc.). Source field: `employee.address2`.", "example": "Apt 3B" }, "city": { "type": "string", "nullable": true, "description": "Source field: `employee.city`.", "example": "Nashville" }, "county": { "type": "string", "nullable": true, "description": "County name (no `County` suffix). Source field: `employee.county`.", "example": "Davidson" }, "state": { "type": "string", "nullable": true, "description": "Two-letter US state / territory code. Source field: `employee.state`.", "example": "TN" }, "postal_code": { "type": "string", "nullable": true, "description": "ZIP / postal code. Source field: `employee.zip_code`.", "example": "37206" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 country code.", "example": "US" } } } } }, "EmployerResult": { "type": "object", "description": "All employment + income data the matched person has at a single employer.", "properties": { "employer": { "$ref": "#/components/schemas/Employer" }, "employment_records": { "type": "array", "description": "One or more employment records under this employer FEIN. In practice these are often location-scoped records for the same employee.", "items": { "$ref": "#/components/schemas/EmploymentRecord" } }, "by_work_location": { "type": "array", "nullable": true, "description": "Per-employer rollup of paychecks, earnings, and hours grouped by `work_location`. One entry per distinct location the subject was paid out of for this employer. **Returned only by the government verification endpoint.**", "items": { "$ref": "#/components/schemas/LocationIncomeBreakdown" } } } }, "EmploymentEmployerResult": { "type": "object", "description": "All employment data the matched person has at a single employer.", "properties": { "employer": { "$ref": "#/components/schemas/Employer" }, "employment_records": { "type": "array", "description": "One or more employment records under this employer FEIN. In practice these are often location-scoped records for the same employee.", "items": { "$ref": "#/components/schemas/EmploymentOnlyRecord" } } } }, "Employer": { "type": "object", "description": "The top-level employer identity for the result group. This FEIN is the primary employer grouping key; each employer can have one or more location-scoped `employment_records` beneath it.", "properties": { "employer_id": { "type": "string", "example": "emp_01JT7J6X8V0H2H6H7QJ4A9D1K2" }, "external_employer_id": { "type": "string", "nullable": true, "description": "Our external ID for the employer, if assigned.", "example": "ACME-001" }, "legal_name": { "type": "string", "example": "Acme Distribution Holdings, Inc." }, "dba_name": { "type": "string", "nullable": true, "example": "Acme Distribution" }, "fein": { "type": "string", "nullable": true, "example": "12-3451234", "description": "Full 9-digit Federal Employer Identification Number, formatted `XX-XXXXXXX`.", "pattern": "^\\d{2}-\\d{7}$" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "USD" } } }, "WorkLocation": { "type": "object", "nullable": true, "description": "Optional. The physical work location, branch, site, or facility associated with this employment record and its paychecks.", "properties": { "location_id": { "type": "string", "nullable": true, "example": "loc_01JT7M6B8W9Y3E4R5T6U7V8W9X" }, "name": { "type": "string", "nullable": true, "example": "Nashville Distribution Center" }, "address": { "type": "object", "nullable": true, "properties": { "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true } } } } }, "EmploymentRecord": { "type": "object", "properties": { "employee_number": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "terminated", "leave_of_absence", "suspended", "retired" ] }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "temporary", "seasonal", "contractor" ] }, "compensation_type": { "type": "string", "nullable": true, "enum": [ "salary", "hourly", "other" ] }, "job_title": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "work_location": { "$ref": "#/components/schemas/WorkLocation" }, "dates": { "type": "object", "properties": { "original_hire_date": { "type": "string", "format": "date", "nullable": true }, "rehire_date": { "type": "string", "format": "date", "nullable": true }, "termination_date": { "type": "string", "format": "date", "nullable": true } } }, "current_compensation": { "$ref": "#/components/schemas/CompensationSnapshot" }, "income_summary": { "$ref": "#/components/schemas/IncomeSummary" }, "paychecks": { "type": "array", "items": { "$ref": "#/components/schemas/Paycheck" } } } }, "EmploymentOnlyRecord": { "type": "object", "properties": { "employee_number": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "terminated", "leave_of_absence", "suspended", "retired" ] }, "employment_type": { "type": "string", "enum": [ "full_time", "part_time", "temporary", "seasonal", "contractor" ] }, "compensation_type": { "type": "string", "nullable": true, "enum": [ "salary", "hourly", "other" ] }, "job_title": { "type": "string", "nullable": true }, "department": { "type": "string", "nullable": true }, "work_location": { "$ref": "#/components/schemas/WorkLocation" }, "dates": { "type": "object", "properties": { "original_hire_date": { "type": "string", "format": "date", "nullable": true }, "rehire_date": { "type": "string", "format": "date", "nullable": true }, "termination_date": { "type": "string", "format": "date", "nullable": true } } }, "current_compensation": { "$ref": "#/components/schemas/CompensationSnapshot" } } }, "CompensationSnapshot": { "type": "object", "nullable": true, "properties": { "effective_start_date": { "type": "string", "format": "date" }, "effective_end_date": { "type": "string", "format": "date", "nullable": true }, "pay_rate": { "type": "number", "format": "double" }, "pay_frequency": { "type": "string", "enum": [ "weekly", "biweekly", "semimonthly", "monthly", "quarterly", "annual" ] }, "annualized_base_pay": { "type": "number", "format": "double" }, "standard_hours": { "type": "number", "format": "double", "nullable": true }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 } } }, "IncomeSummary": { "type": "object", "description": "Income figures for a single employment record, broken out per calendar year with a `total` row at the bottom that sums every year on file.", "properties": { "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "latest_pay_date": { "type": "string", "format": "date", "nullable": true }, "paycheck_count_returned": { "type": "integer" }, "by_year": { "type": "array", "description": "One entry per calendar year, ordered ascending.", "items": { "$ref": "#/components/schemas/YearTotals" } }, "total": { "$ref": "#/components/schemas/IncomeTotals" } } }, "AggregateIncomeSummary": { "type": "object", "nullable": true, "description": "Income figures rolled up across **all employers** for the matched person. Same `by_year[] + total` shape as the per-record summary.", "properties": { "employer_count": { "type": "integer" }, "active_employer_count": { "type": "integer" }, "employment_record_count": { "type": "integer" }, "active_employment_record_count": { "type": "integer" }, "work_location_count": { "type": "integer", "nullable": true, "description": "Distinct work_locations the subject was paid out of, summed across every employer. **Returned only by the government verification endpoint.**" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "by_year": { "type": "array", "description": "Per-calendar-year totals, summed across every employer.", "items": { "$ref": "#/components/schemas/YearTotals" } }, "total": { "$ref": "#/components/schemas/IncomeTotals" }, "by_work_location": { "type": "array", "nullable": true, "description": "Cross-employer rollup keyed by `work_location`. One entry per distinct location the subject was paid out of, summed across every employer. Each entry includes its parent `employer_id` so jurisdiction-aware consumers can attribute earnings to the right employer + site. **Returned only by the government verification endpoint.**", "items": { "$ref": "#/components/schemas/LocationIncomeBreakdown" } } } }, "Paycheck": { "type": "object", "description": "A single paycheck on the subject's record. The `earnings[]` array is the granular per-line breakdown, but every dollar and hours category that the source payroll provider reports is also rolled up to a paycheck-level field below so consumers do not have to fold `earnings[]` themselves. Earnings rollups are returned on every endpoint; hours rollups (`*_hours`) are **returned only by the government verification endpoint**.", "properties": { "paycheck_id": { "type": "string", "description": "Our canonical, stable identifier for this paycheck. Use this for de-duplication and as the join key against `links.paycheck`.", "example": "pay_acme_07_20260415" }, "ext_payroll_id": { "type": "string", "nullable": true, "description": "External payroll-system identifier for this paycheck, as returned by the source provider. Useful when reconciling the response against the verifier's own copy of the source payroll feed. Source field: `ext_payroll_id`.", "example": "ADP-2026-04-15-49281" }, "pay_period_start_date": { "type": "string", "format": "date", "nullable": true, "description": "First day of the pay period this paycheck covers. Source field: `period_start`." }, "pay_period_end_date": { "type": "string", "format": "date", "nullable": true, "description": "Last day of the pay period this paycheck covers. Source field: `period_end`." }, "pay_date": { "type": "string", "format": "date", "description": "Date the funds were paid (ACH date / check issue date)." }, "check_date": { "type": "string", "format": "date", "nullable": true, "description": "Issue date printed on the physical check, when different from `pay_date`." }, "pay_frequency": { "type": "string", "nullable": true, "enum": [ "weekly", "biweekly", "semimonthly", "monthly", "quarterly", "annual", "other" ], "description": "How often this paycheck's pay period repeats for the subject's pay schedule. Source field: `pay_frequency`.", "example": "semimonthly" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "gross_pay": { "type": "number", "format": "double", "description": "Total earnings on this paycheck before any taxes or deductions. Equal to the sum of every `earnings[].amount`. Source field: `gross_pay`." }, "regular_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total regular / base wages paid on this paycheck. Rollup of `earnings[]` entries with `earning_type: \"regular\"`. Source field: `regular_wages`." }, "overtime_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total overtime wages paid on this paycheck. Rollup of `earnings[]` entries with `earning_type: \"overtime\"`. Source field: `ot_wages`." }, "bonus_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total bonus paid on this paycheck. Rollup of `earnings[]` entries with `earning_type: \"bonus\"`." }, "commission_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total commission paid on this paycheck. Rollup of `earnings[]` entries with `earning_type: \"commission\"`." }, "holiday_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid for holiday hours used on this paycheck. Source field: `holiday_wages`." }, "incentive_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount of incentive pay (SPIFFs, performance incentives, etc.) on this paycheck. Source field: `incentive_wages`." }, "miscellaneous_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount of earnings the source payroll system tagged as miscellaneous / other and that do not fit any other category. Source field: `miscellaneous_wages`." }, "pension_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid as pension on this paycheck (typical for retiree paystubs from a former employer). Source field: `pension_wages`." }, "pto_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid for paid-time-off hours used on this paycheck. Source field: `pto_wages`." }, "pto_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid out as a PTO / personal-time payout (e.g. unused PTO at termination). Source field: `unused_personal_time_wages`." }, "severance_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid as severance on this paycheck. Source field: `severance_wages`." }, "sick_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid for sick hours used on this paycheck. Source field: `sick_wages`." }, "sick_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid out as an unused-sick-time payout (typical at termination in jurisdictions where sick time is required to be cashed out). Source field: `unused_sick_time_wages`." }, "tips_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount of declared / reported tips on this paycheck. Source field: `tips_wages`." }, "vacation_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid for vacation hours used on this paycheck. Source field: `vacation_wages`." }, "vacation_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid out as an unused-vacation-time payout. Source field: `unused_vacation_time_wages`." }, "workers_comp_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Total dollar amount paid as workers' compensation on this paycheck. Source field: `workers_comp_wages`." }, "regular_hours": { "type": "number", "nullable": true, "description": "Sum of regular hours on this paycheck. Source field: `reg_hours`. **Returned only by the government verification endpoint.**", "example": 80 }, "overtime_hours": { "type": "number", "nullable": true, "description": "Sum of overtime hours on this paycheck. Source field: `ot_hours`. **Returned only by the government verification endpoint.**", "example": 6.67 }, "other_hours": { "type": "number", "nullable": true, "description": "Sum of any non-regular and non-overtime hours on this paycheck (PTO, holiday, sick, vacation, etc., where the source provider breaks them out separately). Source field: `other_hours`. **Returned only by the government verification endpoint.**", "example": 0 }, "total_hours": { "type": "number", "nullable": true, "description": "Sum of `hours` across every earning line on this paycheck (regular + overtime + PTO + holiday + sick, where reported). Equal to `regular_hours + overtime_hours + other_hours`. Provided as a paycheck-level convenience so consumers do not have to fold the `earnings[]` array themselves. Source field: `tot_hours`. **Returned only by the government verification endpoint.**", "example": 86.67 }, "earnings": { "type": "array", "description": "Per-line breakdown of every earning on this paycheck. Use the paycheck-level `*_earnings` rollups above when you only need totals.", "items": { "$ref": "#/components/schemas/PaycheckEarning" } } } }, "PaycheckEarning": { "type": "object", "description": "A single line on the paycheck's earnings stub. The `earning_type` is normalized to a stable enum so consumers can roll up across employers without parsing free-form descriptions.", "properties": { "earning_type": { "type": "string", "description": "Normalized category for this earnings line. Maps 1:1 to a paycheck-level `*_earnings` rollup field (for example, `earning_type: \"holiday\"` rolls up to `Paycheck.holiday_earnings` and `YearTotals.holiday_earnings`).", "enum": [ "regular", "overtime", "bonus", "commission", "holiday", "incentive", "miscellaneous", "pension", "pto", "pto_payout", "severance", "sick", "sick_payout", "tips", "vacation", "vacation_payout", "workers_comp", "reimbursement", "other" ] }, "description": { "type": "string", "nullable": true }, "hours": { "type": "number", "nullable": true }, "rate": { "type": "number", "nullable": true }, "amount": { "type": "number", "format": "double" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry_after_seconds": { "type": "integer", "nullable": true }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "issue": { "type": "string" } } } } } } } }, "BatchJsonRequest": { "type": "object", "description": "Batch submission. Every subject must end up with a `verifier_user_id` after fallback: either set `verifier_user_id` at the batch level (applied to every row), or set it on each `BatchJsonSubject` individually, or both (per-row overrides batch-level). Batches where any row resolves to no `verifier_user_id` are rejected with `400 invalid_request` before any subject is processed.", "required": [ "verification_type", "subjects", "permissible_purpose" ], "properties": { "verification_type": { "type": "string", "enum": [ "employment", "employment_income" ], "description": "Verification type applied to every subject in the batch." }, "verifier_user_id": { "type": "string", "description": "Batch-level identifier for the **end user at the verifier company** who submitted the batch. Used as the default `verifier_user_id` for every subject in `subjects[]` that does not carry its own. Required unless every row in `subjects[]` provides its own `verifier_user_id`. Use this when one operator submitted the entire batch (the most common case).", "example": "user_alex.jordan@verifier.example.com" }, "permissible_purpose": { "$ref": "#/components/schemas/CommercialPermissiblePurpose" }, "webhook_url": { "type": "string", "format": "uri", "nullable": true, "description": "Optional. POST `verification.batch.completed` here when the batch finishes. Signed with HMAC-SHA256 using your account webhook secret." }, "options": { "$ref": "#/components/schemas/VerificationOptions" }, "subjects": { "type": "array", "minItems": 1, "maxItems": 500, "items": { "$ref": "#/components/schemas/BatchJsonSubject" } } } }, "BatchJsonSubject": { "type": "object", "required": [ "subject_lookup" ], "properties": { "verifier_reference_id": { "type": "string", "description": "Strongly recommended. Your row-level identifier so you can reconcile results back to your records." }, "verifier_user_id": { "type": "string", "description": "Per-row identifier for the **end user at the verifier company** who is responsible for this specific subject (loan officer assigned to the file, caseworker assigned to the household, etc.). Optional on the row only when `BatchJsonRequest.verifier_user_id` is set, in which case the batch-level value is inherited. When both are set, the per-row value wins. Every processed row carries a `verifier_user_id` after fallback; rows that resolve to none are rejected at submit time. Echoed back unchanged on `BatchItemResult`.", "example": "user_alex.jordan@verifier.example.com" }, "subject_lookup": { "$ref": "#/components/schemas/SubjectLookup" } } }, "BatchStatus": { "type": "object", "description": "Snapshot of a batch at a point in time. Use to poll progress.", "properties": { "batch_id": { "type": "string", "example": "bat_01JT8AAQ7C3Z2YK6MN4FW3R0PD" }, "status": { "type": "string", "enum": [ "queued", "processing", "completed", "failed", "cancelled" ] }, "source": { "type": "string", "enum": [ "json", "csv", "ndjson" ] }, "verification_type": { "type": "string", "enum": [ "employment", "employment_income" ] }, "subject_count": { "type": "integer" }, "completed_count": { "type": "integer" }, "verified_count": { "type": "integer" }, "no_match_count": { "type": "integer" }, "ambiguous_count": { "type": "integer" }, "failed_count": { "type": "integer", "description": "Rows that could not be processed (validation errors, malformed identifiers)." }, "result_format": { "type": "string", "enum": [ "csv", "ndjson" ], "nullable": true, "description": "Only set for upload batches." }, "file_name": { "type": "string", "nullable": true, "description": "Original uploaded filename. Upload batches only." }, "file_size_bytes": { "type": "integer", "nullable": true }, "webhook_url": { "type": "string", "format": "uri", "nullable": true }, "webhook_status": { "type": "string", "nullable": true, "enum": [ "pending", "delivered", "failed" ] }, "error_code": { "type": "string", "nullable": true, "description": "Set when status = `failed`." }, "error_message": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "description": "When results will be purged. Default 30 days." }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "results": { "type": "string", "description": "Per-item results listing endpoint." }, "download": { "type": "string", "description": "Downloadable file. Upload batches only." }, "errors": { "type": "string", "description": "Failed rows listing endpoint." } } } } }, "BatchResultsPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/BatchItemResult" } }, "next_cursor": { "type": "string", "nullable": true } } }, "BatchItemResult": { "type": "object", "description": "Summary of a single subject's verification within a batch. Use `links.verification` to fetch the full `VerificationResponse`.", "properties": { "position": { "type": "integer", "description": "1-based row number from the original payload or file." }, "verifier_reference_id": { "type": "string", "nullable": true }, "verifier_user_id": { "type": "string", "nullable": true, "description": "Echo of the per-row `verifier_user_id` that was effective for this subject (the row's own value, or the batch-level fallback)." }, "verification_id": { "type": "string", "nullable": true }, "result_status": { "type": "string", "enum": [ "verified", "partial_match", "no_match", "ambiguous_match", "error" ] }, "match_confidence": { "type": "string", "nullable": true, "enum": [ "high", "medium", "low", "none" ] }, "match_candidates": { "type": "integer", "nullable": true, "description": "Set for ambiguous_match." }, "conflicting_fields": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "For ambiguous_match: optional `subject_lookup` fields the verifier sent that disagree with our record." }, "employer_count": { "type": "integer", "nullable": true }, "active_employer_count": { "type": "integer", "nullable": true }, "ytd_gross_pay": { "type": "number", "nullable": true }, "currency": { "type": "string", "nullable": true }, "latest_pay_date": { "type": "string", "format": "date", "nullable": true }, "processed_at": { "type": "string", "format": "date-time", "nullable": true }, "error_code": { "type": "string", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "verification_response": { "$ref": "#/components/schemas/VerificationResponse", "description": "Only present when `?include_full_response=true`." }, "links": { "type": "object", "properties": { "verification": { "type": "string" } } } } }, "BatchItemError": { "type": "object", "description": "A row from an upload batch that failed validation or processing.", "properties": { "position": { "type": "integer" }, "verifier_reference_id": { "type": "string", "nullable": true }, "verifier_user_id": { "type": "string", "nullable": true, "description": "Echo of the per-row `verifier_user_id` that was effective for this subject (the row's own value, or the batch-level fallback)." }, "error_code": { "type": "string", "enum": [ "missing_required_identifiers", "invalid_identifier", "invalid_date_format", "duplicate_verifier_reference_id", "row_parse_error", "internal_error" ] }, "error_message": { "type": "string" }, "raw_row": { "type": "object", "description": "The original row contents (with sensitive fields redacted).", "additionalProperties": true } } }, "WebhookEvent": { "type": "object", "required": [ "id", "type", "created_at", "data" ], "properties": { "id": { "type": "string", "example": "evt_01JT8AC2P8QH4F2C3KL9R7N5V0" }, "type": { "type": "string", "enum": [ "verification.batch.completed", "verification.batch.failed" ] }, "created_at": { "type": "string", "format": "date-time" }, "data": { "$ref": "#/components/schemas/BatchStatus" } } }, "CommercialPermissiblePurpose": { "type": "string", "description": "Permissible purpose for commercial verifiers. Required on every POST /verifications/employment-income request. Echoed back in the response.", "enum": [ "written_instruction", "credit_transaction", "employment_purpose", "insurance_underwriting", "investor_servicer_or_insurer_review", "business_transaction_initiated_by_consumer", "account_review_or_collection" ], "example": "credit_transaction" }, "GovernmentPermissiblePurpose": { "type": "string", "description": "Permissible purpose for government / agency verifiers. Required on every POST /verifications/government-verification request. Echoed back in the response.", "enum": [ "court_order_or_grand_jury_subpoena", "government_benefit_eligibility", "child_support_enforcement" ], "example": "child_support_enforcement" }, "GovernmentVerificationRequest": { "type": "object", "description": "Single-subject verification request for the government endpoint. Identical to `VerificationRequest` but constrained to government-permitted purposes.", "required": [ "permissible_purpose", "subject_lookup", "verifier_user_id" ], "properties": { "verifier_reference_id": { "type": "string", "description": "Optional reference for the agency's own system.", "example": "AGENCY-2026-000981" }, "verifier_user_id": { "type": "string", "description": "**Required.** Stable identifier for the agency caseworker / investigator who initiated this request. Used for per-seat audit and government permissible-purpose attribution. Pass any opaque ID your IDP issues (employee number, email, OIDC `sub`, UUID); we treat it as opaque and echo it back on the response unchanged. Requests missing `verifier_user_id` are rejected with `400 invalid_request`.", "example": "caseworker_3892@agency.gov" }, "permissible_purpose": { "$ref": "#/components/schemas/GovernmentPermissiblePurpose" }, "subject_lookup": { "$ref": "#/components/schemas/SubjectLookup" }, "options": { "$ref": "#/components/schemas/VerificationOptions" } } }, "YearTotals": { "type": "object", "description": "Income totals for a single calendar year. The current year is flagged with `is_year_to_date: true`.", "required": [ "year", "is_year_to_date", "gross_pay" ], "properties": { "year": { "type": "integer", "example": 2026 }, "is_year_to_date": { "type": "boolean", "description": "True for the current calendar year while it is still accruing." }, "paycheck_count": { "type": "integer", "example": 7 }, "gross_pay": { "type": "number", "format": "double", "example": 23869.23 }, "regular_earnings": { "type": "number", "format": "double", "example": 23584.61 }, "overtime_earnings": { "type": "number", "format": "double", "example": 0 }, "bonus_earnings": { "type": "number", "format": "double", "example": 284.62 }, "commission_earnings": { "type": "number", "format": "double", "example": 0 }, "holiday_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.holiday_earnings` for this employer. Source field: `holiday_wages`." }, "incentive_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.incentive_earnings`. Source field: `incentive_wages`." }, "miscellaneous_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.miscellaneous_earnings`. Source field: `miscellaneous_wages`." }, "pension_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.pension_earnings`. Source field: `pension_wages`." }, "pto_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.pto_earnings`. Source field: `pto_wages`." }, "pto_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.pto_payout_earnings`. Source field: `unused_personal_time_wages`." }, "severance_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.severance_earnings`. Source field: `severance_wages`." }, "sick_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.sick_earnings`. Source field: `sick_wages`." }, "sick_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.sick_payout_earnings`. Source field: `unused_sick_time_wages`." }, "tips_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.tips_earnings`. Source field: `tips_wages`." }, "vacation_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.vacation_earnings`. Source field: `vacation_wages`." }, "vacation_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.vacation_payout_earnings`. Source field: `unused_vacation_time_wages`." }, "workers_comp_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Annual sum of `Paycheck.workers_comp_earnings`. Source field: `workers_comp_wages`." }, "regular_hours": { "type": "number", "format": "double", "nullable": true, "description": "Sum of regular hours worked in the year, derived from each paycheck's `earnings[].hours`. **Returned only by the government verification endpoint.**", "example": 1820 }, "overtime_hours": { "type": "number", "format": "double", "nullable": true, "description": "Sum of overtime hours worked in the year. **Returned only by the government verification endpoint.**", "example": 24.5 }, "other_hours": { "type": "number", "format": "double", "nullable": true, "description": "Sum of any non-regular and non-overtime hours in the year (PTO, holiday, sick, vacation, etc.). Source field: `other_hours`. **Returned only by the government verification endpoint.**", "example": 56 }, "total_hours": { "type": "number", "format": "double", "nullable": true, "description": "Sum of every hours line on every paycheck in the year (regular + overtime + PTO + holiday + sick where reported). Equal to `regular_hours + overtime_hours + other_hours`. **Returned only by the government verification endpoint.**", "example": 1900.5 } } }, "IncomeTotals": { "type": "object", "description": "Sum of every entry in `by_year`. Provides at-a-glance access to the full multi-year picture without iterating over `by_year[]`.", "properties": { "paycheck_count": { "type": "integer" }, "gross_pay": { "type": "number", "format": "double" }, "regular_earnings": { "type": "number", "format": "double" }, "overtime_earnings": { "type": "number", "format": "double" }, "bonus_earnings": { "type": "number", "format": "double" }, "commission_earnings": { "type": "number", "format": "double" }, "holiday_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of holiday earnings across every year in `by_year`." }, "incentive_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of incentive earnings across every year in `by_year`." }, "miscellaneous_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of miscellaneous / other earnings across every year in `by_year`." }, "pension_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of pension earnings across every year in `by_year`." }, "pto_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of PTO earnings across every year in `by_year`." }, "pto_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of PTO-payout earnings across every year in `by_year`." }, "severance_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of severance earnings across every year in `by_year`." }, "sick_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of sick earnings across every year in `by_year`." }, "sick_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of unused-sick-time-payout earnings across every year in `by_year`." }, "tips_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of declared tips across every year in `by_year`." }, "vacation_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of vacation earnings across every year in `by_year`." }, "vacation_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of unused-vacation-time-payout earnings across every year in `by_year`." }, "workers_comp_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of workers' compensation earnings across every year in `by_year`." }, "regular_hours": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of regular hours across every year in `by_year`. **Returned only by the government verification endpoint.**" }, "overtime_hours": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of overtime hours. **Returned only by the government verification endpoint.**" }, "other_hours": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of non-regular / non-overtime hours (PTO, holiday, sick, vacation, etc.). **Returned only by the government verification endpoint.**" }, "total_hours": { "type": "number", "format": "double", "nullable": true, "description": "Lifetime sum of every hours line across every paycheck. **Returned only by the government verification endpoint.**" } } }, "LocationIncomeBreakdown": { "type": "object", "description": "Per-`work_location` rollup of paychecks, earnings, and hours. **Returned only by the government verification endpoint.** Used to support agency benefit-eligibility and child-support calculations that need to see where the subject actually earned each dollar (for example, jurisdiction-specific income).", "properties": { "work_location": { "$ref": "#/components/schemas/WorkLocation" }, "employer_id": { "type": "string", "nullable": true, "description": "When this rollup appears inside `aggregate_income_summary.by_work_location` (cross-employer), `employer_id` identifies which employer owns the work_location. When this rollup appears under a single `EmployerResult.by_work_location`, `employer_id` is omitted because it is implied by the parent.", "example": "emp_01JT7J6X8V0H2H6H7QJ4A9D1K2" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "first_pay_date": { "type": "string", "format": "date", "nullable": true, "description": "Earliest pay_date observed at this work_location." }, "latest_pay_date": { "type": "string", "format": "date", "nullable": true }, "paycheck_count": { "type": "integer" }, "gross_pay": { "type": "number", "format": "double" }, "regular_earnings": { "type": "number", "format": "double" }, "overtime_earnings": { "type": "number", "format": "double" }, "bonus_earnings": { "type": "number", "format": "double" }, "commission_earnings": { "type": "number", "format": "double" }, "holiday_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.holiday_earnings`." }, "incentive_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.incentive_earnings`." }, "miscellaneous_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.miscellaneous_earnings`." }, "pension_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.pension_earnings`." }, "pto_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.pto_earnings`." }, "pto_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.pto_payout_earnings`." }, "severance_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.severance_earnings`." }, "sick_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.sick_earnings`." }, "sick_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.sick_payout_earnings`." }, "tips_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.tips_earnings`." }, "vacation_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.vacation_earnings`." }, "vacation_payout_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.vacation_payout_earnings`." }, "workers_comp_earnings": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of `Paycheck.workers_comp_earnings`." }, "regular_hours": { "type": "number", "format": "double", "nullable": true }, "overtime_hours": { "type": "number", "format": "double", "nullable": true }, "other_hours": { "type": "number", "format": "double", "nullable": true, "description": "Per-`work_location` sum of non-regular / non-overtime hours." }, "total_hours": { "type": "number", "format": "double", "nullable": true }, "by_year": { "type": "array", "description": "Per-calendar-year breakdown of earnings and hours at this work_location.", "items": { "$ref": "#/components/schemas/YearTotals" } } } } } } }