How this API works in plain English
A verifier (for example, ADP, a lender, a landlord, a background screener) asks us a question: “Tell me everything you know about this person’s employment and income.” We look the person up across every employer in our database and send back a single, complete answer. The verifier never has to know which employer the person works for — we figure that out for them.
Authentication
Two ways to authenticate every request
Pick whichever fits the verifier's stack. Either credential may be used on any endpoint; both have the same access rules.
Option 1
API key (header)
The simplest option. Issue a verifier API key from the developer console and send it as a header on every request.
- Header:
X-API-Key: vk_live_xxx - Format:
vk_live_*(production) orvk_test_*(sandbox). - Best for quick integrations and internal tooling. Rotate by issuing a new key in the console; the old key keeps working until you revoke it.
curl with API key
POST/v1/verifications/employment-incomebashcurl -X POST https://api.example.com/v1/verifications/employment-income \
-H "X-API-Key: vk_live_xxx" \
-H "Content-Type: application/json" \
-d '{ ... }'Option 2
OAuth 2.0 (client credentials)
Standard OAuth 2.0 client-credentials flow (RFC 6749 §4.4). Recommended for production: secrets are rotated without redeploying client code, and access can be scoped per credential.
- Token endpoint:
POST https://auth.example.com/oauth/token - Send the bearer token on every API call:
Authorization: Bearer <access_token>. - Tokens expire in 1 hour. Cache and re-exchange when
expires_inelapses. - Scopes:
verifications:read,verifications:write,batches:write,webhooks:manage. A token without the right scope is rejected with401 insufficient_scope.
Step 1 — exchange credentials for a token
POSThttps://auth.example.com/oauth/tokenbashcurl -X POST https://auth.example.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=$RYZE_CLIENT_ID" \
-d "client_secret=$RYZE_CLIENT_SECRET" \
-d "scope=verifications:read verifications:write"Token response
json{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600,
"scope": "verifications:read verifications:write"
}Step 2 — call the API with the bearer token
POST/v1/verifications/employment-incomebashcurl -X POST https://api.example.com/v1/verifications/employment-income \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ ... }'What an authentication failure looks like
Both auth methods return the same shape on failure: HTTP 401 with an unauthorized (or insufficient_scope) error code so you can branch on a single handler.
Invalid API key
json{
"error": {
"code": "unauthorized",
"message": "API key is invalid or expired"
}
}Expired bearer token
json{
"error": {
"code": "unauthorized",
"message": "Bearer token is invalid or expired. Re-exchange your client credentials at https://auth.example.com/oauth/token."
}
}Bearer token missing a scope
json{
"error": {
"code": "insufficient_scope",
"message": "This endpoint requires the \`verifications:write\` scope."
}
}Step 1
What we need from the verifier (the request)
The verifier tells us who they're asking about. They don't pick an employer.
Required on every request
- Full Social Security Number— the primary identifier. We will not accept a request without it.
- Date of birth— required alongside the SSN. Used as a second factor so a typo’d SSN can’t accidentally surface someone else’s record.
- A permissible purpose— the legal reason the verifier needs the data. See the next section for the allowed values.
verifier_user_id— opaque identifier of the human at the verifier company who initiated the request (loan officer, underwriter, caseworker). Required on every endpoint for per-seat audit and FCRA / government permissible-purpose attribution. We treat it as opaque and echo it back unchanged in the response.
Optional (helps us match faster and reconcile on the verifier’s side)
- Legal name (first / middle / last)— lets us reject requests where the SSN + DOB resolve to a different person than the verifier expected.
- Last 4 of SSN— redundant when the full SSN is provided, but can be sent for cross-system audit.
- Email address— another tie-breaker.
- Phone number— same idea.
- A reference ID from their system (loan number, case ID, etc.) so they can match our response to their internal file.
Optional preferences they can set
- Whether to include past jobs, or only current ones.
- How many of the most-recent employers to return (
employer_limit): an integer from 1 (just the most recent employer) up to the total number on file. Omit the field, or passnull, to return all employers (default). - How many recent paychecks to include per job (1–24).
- Whether to return paychecks at all (
include_paychecks) or just the employment + summary layers. - Whether to include tax and deduction breakdowns alongside paycheck detail (
include_tax_breakdown/include_deduction_breakdown). - A specific “as of” date to use for year-to-date numbers.
What the actual request looks like
Here are two real examples of the JSON the verifier sends us.
Request — minimum required
POST/v1/verifications/employment-incomeJust the two required identifiers (SSN + date of birth) plus a permissible purpose.
{
"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"
},
"options": {
"include_inactive_employment": true,
"include_paychecks": true,
"include_tax_breakdown": true,
"include_deduction_breakdown": true,
"employer_limit": null,
"paycheck_limit": 6,
"as_of_date": "2026-04-20"
}
}Request — with optional add-ons
POST/v1/verifications/employment-incomeSame required fields, plus optional legal name, email, phone, employer_limit set to 1, and explicit paycheck / tax / deduction detail toggles.
{
"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,
"include_paychecks": true,
"include_tax_breakdown": true,
"include_deduction_breakdown": true
}
}Step 1.5
Permissible purpose (required on every request)
Every verification call must declare why the verifier is allowed to receive the data. The allowed values depend on which endpoint is being called.
Commercial verifier · 7 purposes
Sent to the commercial verification endpoints, including POST /v1/verifications/employment-income and POST /v1/verifications/employment.
- 01
written_instruction
The employee has issued written instruction to obtain this information.
- 02
credit_transaction
Use in connection with a credit transaction involving the employee — extending credit to, or reviewing or collecting an account of, the employee.
- 03
employment_purpose
Use the employee's information for employment purposes.
- 04
insurance_underwriting
Use in connection with the underwriting of insurance involving the employee.
- 05
investor_servicer_or_insurer_review
Use, as a potential investor, servicer, or current insurer, in connection with a valuation of, or assessment of credit or prepayment risks associated with, an existing credit obligation.
- 06
business_transaction_initiated_by_consumer
Use in connection with a business transaction that is initiated by the employee.
- 07
account_review_or_collection
Performing a review or collection of the employee's account.
Government verifier · 3 purposes
Sent to POST /v1/verifications/government-verification.
- 01
court_order_or_grand_jury_subpoena
In response to the order of a court having jurisdiction to issue such an order, or a subpoena issued in connection with proceedings before a Federal grand jury.
- 02
government_benefit_eligibility
Determining the employee's eligibility for a benefit granted by a government agency, where the agency is required by law to consider the employee's financial responsibility or status.
- 03
child_support_enforcement
Determining child support payments — representing a state or local child support enforcement agency.
Submitting a commercial purpose to the government endpoint (or vice versa) is rejected with 400 invalid_permissible_purpose. The accepted purpose is echoed back at the top level of the verification response so the verifier can audit each call.
Step 2
How we find the person
Every request must include both a full SSN and a date of birth. The optional fields decide whether we accept the match or fall back to a safer outcome.
| If they give us… | We say the match is… | What that means |
|---|---|---|
| SSN + DOB (and optional legal name / email matches our record) | High confidence | Single record matches every identifier provided. Full response returned. |
| SSN + DOB only (no optional identifiers) | High confidence | Single record matches both required fields. Full response returned. |
| SSN + DOB match, but optional legal name disagrees | Ambiguous match | We don’t return data — the verifier should double-check that the right person is being looked up. |
| SSN matches no one | No match | We searched the database and no record exists. The verifier should fall back to a different verification method. |
| SSN missing, DOB missing, or either malformed | Rejected | The request is rejected with 400 invalid_request. Both fields are mandatory. |
Step 3
What we send back (the response)
One package containing everything we know about the person across every employer.
A header about the request itself
- A unique ID for this verification (so it can be looked up later).
- Whether the request succeeded.
- The result: verified, no match, or ambiguous (multiple people matched).
- Timestamps of when the request came in and when we answered.
- The verifier's own reference ID (echoed back so they can file it correctly).
- The permissible purpose the verifier declared on the request (echoed back for audit).
Who we matched
- Whether we matched a person at all.
- How confident we are in the match (high / medium / low).
- Which identifiers we used to match.
- The person's legal name, date of birth, and last 4 of SSN.
- Their `residence_address` (line1 / line2 / city / county / state / postal_code / country) as last reported by the source payroll provider — used by verifiers for jurisdiction attribution and to reconcile against their own record. Individual fields may be `null` when the source didn't report them.
One section per employer the person works (or worked) at
If the person has two jobs at the same time, we return two sections. If they had a previous job that ended, we return that too (unless the verifier asked us to skip past employers).
- The employer's name, DBA name, and full FEIN (federal Employer Identification Number).
- Every employment record the person has at that employer (sometimes there's more than one — for example after a transfer or rehire).
For each employment record, the full picture
- Job title and department.
- Whether they're full-time, part-time, contractor, etc.
- Whether they're currently active, on leave, terminated, etc.
- Original hire date, rehire date, and termination date if applicable.
- Work location (site / branch name and address) when that employment record is tied to a specific location.
- Their current pay rate, pay frequency, and annualized base pay.
- An income summary broken out by calendar year, with a `total` row at the bottom that sums every year we have on file.
- A list of recent paychecks (the verifier picks how many: 1 to 24).
The income summary on each employment record
Per-record gross earnings rolled up by calendar year, then summed.
- `by_year[]` — one entry per calendar year (e.g. 2024, 2025, 2026), each with gross pay, the paycheck count for that year, and the same `*_earnings` rollups carried by the underlying paychecks (regular, overtime, bonus, commission, holiday, incentive, miscellaneous, pension, PTO, PTO payout, severance, sick, sick payout, tips, vacation, vacation payout, workers' comp).
- The current year is flagged with `is_year_to_date: true` so consumers know it's still accruing.
- `total` — a single row at the bottom summing every year in `by_year`, used as the at-a-glance career-with-this-employer figure. Carries the full chart of accounts so the rollup matches the per-paycheck and per-year breakdowns line for line.
- **Government endpoint only:** every `by_year` row and the `total` row also include `regular_hours`, `overtime_hours`, `other_hours`, and `total_hours` so agencies can pair earnings with hours-based eligibility math.
For each paycheck, the returned detail
- Identifiers: our canonical `paycheck_id` plus the source provider's `ext_payroll_id`, with `pay_period_start_date`, `pay_period_end_date`, `pay_date`, `check_date`, and `pay_frequency`.
- Gross pay, currency, and a paycheck-level rollup for every earnings category we recognize (regular, overtime, bonus, commission, holiday, incentive, miscellaneous, pension, PTO, PTO payout, severance, sick, sick payout, tips, vacation, vacation payout, workers' comp). The granular `earnings[]` array is still there for line-level rate/hours/description; the rollups are a convenience so consumers don't have to fold the array.
- Optional tax and deduction breakdowns when those response-detail toggles are enabled on the request.
- **Government endpoint only:** paycheck-level `regular_hours`, `overtime_hours`, `other_hours`, and `total_hours` so consumers don't have to sum `earnings[].hours` themselves.
Earnings categories — paycheck rollups and aggregations
- Every `*_earnings` field on `Paycheck` is also rolled up to the same field on `YearTotals` (per-record `by_year[]` and `total`), `IncomeTotals` (cross-employer `aggregate_income_summary.total`), and `LocationIncomeBreakdown` (per-`work_location` rollups on the government endpoint).
- Categories: `regular_earnings` (`regular_wages`), `overtime_earnings` (`ot_wages`), `bonus_earnings`, `commission_earnings`, `holiday_earnings` (`holiday_wages`), `incentive_earnings` (`incentive_wages`), `miscellaneous_earnings` (`miscellaneous_wages`), `pension_earnings` (`pension_wages`), `pto_earnings` (`pto_wages`), `pto_payout_earnings` (`unused_personal_time_wages`), `severance_earnings` (`severance_wages`), `sick_earnings` (`sick_wages`), `sick_payout_earnings` (`unused_sick_time_wages`), `tips_earnings` (`tips_wages`), `vacation_earnings` (`vacation_wages`), `vacation_payout_earnings` (`unused_vacation_time_wages`), `workers_comp_earnings` (`workers_comp_wages`).
- Categories the source payroll provider didn't report come back as `null`, not omitted, so consumers can rely on the field being present.
- The `earnings[].earning_type` enum on the granular line items has been extended to match: `regular`, `overtime`, `bonus`, `commission`, `holiday`, `incentive`, `miscellaneous`, `pension`, `pto`, `pto_payout`, `severance`, `sick`, `sick_payout`, `tips`, `vacation`, `vacation_payout`, `workers_comp`, `reimbursement`, `other`.
A grand total across all employers
- How many employers the person has records at, and how many are currently active.
- `by_year[]` — the same per-calendar-year breakdown as the per-record summary, but summed across every employer the person has a record with. Includes every `*_earnings` rollup so the same chart of accounts works at the cross-employer level.
- `total` — a single row at the bottom summing every year across every employer. Used by lenders to underwrite the person's full income picture.
- **Government endpoint only:** every `by_year` row and the `total` row also include `regular_hours`, `overtime_hours`, `other_hours`, and `total_hours` so agencies can verify hours-based eligibility (e.g. SNAP, Medicaid).
Government endpoint extra: per-work_location aggregation
- Each `EmployerResult` carries a `by_work_location[]` array — one rollup per distinct work_location the subject was paid out of for that employer, with full income + hours + per-year breakdown.
- `aggregate_income_summary.by_work_location[]` is the same rollup at the cross-employer level: one entry per location across every employer, each tagged with its parent `employer_id` so jurisdiction-aware consumers can attribute earnings correctly.
- `aggregate_income_summary.work_location_count` reports the total number of distinct locations.
- Designed for child-support enforcement, government benefit eligibility, and other agency use cases where state- or county-level income attribution matters.
The full JSON we send back
A complete “verified” response for someone with two concurrent jobs — full-time at Acme and part-time at Globex. This is exactly the structure that comes out of the API.
Response — verified, multi-employer
HTTP 200. Two employers, 7 paychecks each, per-record income broken out by calendar year (with a total row), plus a cross-employer aggregate that does the same. Use the toggle below to switch between view density.
All paychecks visible, but each paycheck's earnings are collapsed to a count. (1076 lines)
{
"verification_id": "ver_01JT7K4KT2X2Q1R7PS1D5Q2A6Z",
"status": "completed",
"result_status": "verified",
"verification_type": "employment_income",
"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",
"permissible_purpose": "credit_transaction",
"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-02-27",
"paycheck_count_returned": 4,
"by_year": [
{
"year": 2024,
"is_year_to_date": false,
"paycheck_count": 15,
"gross_pay": 50250,
"regular_earnings": 48900,
"overtime_earnings": 0,
"bonus_earnings": 1350,
"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": 1300.05,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 1300.05
},
{
"year": 2025,
"is_year_to_date": false,
"paycheck_count": 15,
"gross_pay": 54890.25,
"regular_earnings": 52590.25,
"overtime_earnings": 760,
"bonus_earnings": 1540,
"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": 1300.05,
"overtime_hours": 18,
"other_hours": 0,
"total_hours": 1318.05
},
{
"year": 2026,
"is_year_to_date": true,
"paycheck_count": 4,
"gross_pay": 13476.92,
"regular_earnings": 13476.92,
"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": 346.68,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 346.68
}
],
"total": {
"paycheck_count": 34,
"gross_pay": 118617.17,
"regular_earnings": 114967.17,
"overtime_earnings": 760,
"bonus_earnings": 2890,
"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": 2946.78,
"overtime_hours": 18,
"other_hours": 0,
"total_hours": 2964.78
}
},
"paychecks": [
{
"paycheck_id": "pay_acme_01_20260115",
"ext_payroll_id": "ADP-2026-01-15-49281",
"pay_period_start_date": "2026-01-01",
"pay_period_end_date": "2026-01-15",
"pay_date": "2026-01-15",
"check_date": "2026-01-15",
"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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_acme_02_20260130",
"ext_payroll_id": "ADP-2026-01-30-49282",
"pay_period_start_date": "2026-01-16",
"pay_period_end_date": "2026-01-31",
"pay_date": "2026-01-30",
"check_date": "2026-01-30",
"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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_acme_03_20260213",
"ext_payroll_id": "ADP-2026-02-13-49283",
"pay_period_start_date": "2026-02-01",
"pay_period_end_date": "2026-02-15",
"pay_date": "2026-02-13",
"check_date": "2026-02-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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_acme_04_20260227",
"ext_payroll_id": "ADP-2026-02-27-49284",
"pay_period_start_date": "2026-02-16",
"pay_period_end_date": "2026-02-28",
"pay_date": "2026-02-27",
"check_date": "2026-02-27",
"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": "<… 1 earning lines collapsed …>"
}
]
},
{
"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": 3,
"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-49285",
"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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_acme_06_20260331",
"ext_payroll_id": "ADP-2026-03-31-49286",
"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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_acme_07_20260415",
"ext_payroll_id": "ADP-2026-04-15-49287",
"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": "<… 2 earning lines collapsed …>"
}
]
}
]
},
{
"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": 7,
"by_year": [
{
"year": 2024,
"is_year_to_date": false,
"paycheck_count": 8,
"gross_pay": 4730,
"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": 170,
"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": 15372.5,
"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": 552.5,
"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": 4160,
"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": 170,
"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": 24262.5,
"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": 892.5,
"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_globex_01_20260118",
"ext_payroll_id": "GUSTO-2026-01-18-771203",
"pay_period_start_date": "2026-01-05",
"pay_period_end_date": "2026-01-18",
"pay_date": "2026-01-18",
"check_date": "2026-01-18",
"pay_frequency": "biweekly",
"currency": "USD",
"gross_pay": 612.5,
"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": 42.5,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 20,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 20,
"earnings": "<… 2 earning lines collapsed …>"
},
{
"paycheck_id": "pay_globex_02_20260201",
"ext_payroll_id": "GUSTO-2026-02-01-771204",
"pay_period_start_date": "2026-01-19",
"pay_period_end_date": "2026-02-01",
"pay_date": "2026-02-01",
"check_date": "2026-02-01",
"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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_globex_03_20260215",
"ext_payroll_id": "GUSTO-2026-02-15-771205",
"pay_period_start_date": "2026-02-02",
"pay_period_end_date": "2026-02-15",
"pay_date": "2026-02-15",
"check_date": "2026-02-15",
"pay_frequency": "biweekly",
"currency": "USD",
"gross_pay": 612.5,
"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": 42.5,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 20,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 20,
"earnings": "<… 2 earning lines collapsed …>"
},
{
"paycheck_id": "pay_globex_04_20260301",
"ext_payroll_id": "GUSTO-2026-03-01-771206",
"pay_period_start_date": "2026-02-16",
"pay_period_end_date": "2026-03-01",
"pay_date": "2026-03-01",
"check_date": "2026-03-01",
"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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_globex_05_20260315",
"ext_payroll_id": "GUSTO-2026-03-15-771207",
"pay_period_start_date": "2026-03-02",
"pay_period_end_date": "2026-03-15",
"pay_date": "2026-03-15",
"check_date": "2026-03-15",
"pay_frequency": "biweekly",
"currency": "USD",
"gross_pay": 612.5,
"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": 42.5,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 20,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 20,
"earnings": "<… 2 earning lines collapsed …>"
},
{
"paycheck_id": "pay_globex_06_20260329",
"ext_payroll_id": "GUSTO-2026-03-29-771208",
"pay_period_start_date": "2026-03-16",
"pay_period_end_date": "2026-03-29",
"pay_date": "2026-03-29",
"check_date": "2026-03-29",
"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": "<… 1 earning lines collapsed …>"
},
{
"paycheck_id": "pay_globex_07_20260412",
"ext_payroll_id": "GUSTO-2026-04-12-771209",
"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": 612.5,
"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": 42.5,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 20,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 20,
"earnings": "<… 2 earning lines collapsed …>"
}
]
}
]
}
],
"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": 85180,
"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": 170,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 2240.08,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 2240.08
},
{
"year": 2025,
"is_year_to_date": false,
"paycheck_count": 50,
"gross_pay": 101793,
"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": 552.5,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 2600.08,
"overtime_hours": 30,
"other_hours": 0,
"total_hours": 2630.08
},
{
"year": 2026,
"is_year_to_date": true,
"paycheck_count": 14,
"gross_pay": 28029.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": 170,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 746.69,
"overtime_hours": 0,
"other_hours": 0,
"total_hours": 746.69
}
],
"total": {
"paycheck_count": 96,
"gross_pay": 215002.23,
"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": 892.5,
"vacation_earnings": 0,
"vacation_payout_earnings": 0,
"workers_comp_earnings": 0,
"regular_hours": 5586.85,
"overtime_hours": 30,
"other_hours": 0,
"total_hours": 5616.85
}
}
}Step 4
The four possible outcomes
Even when nothing “goes wrong,” the verifier might get one of these results.
Verified
successWe found the person and we have data on them. The full response is included.
No match
emptyWe searched the database and didn't find anyone matching. The verifier should fall back to a different verification method.
Ambiguous match
needs more infoThe SSN + DOB matched a record, but an optional identifier the verifier sent (legal_name, email, etc.) disagrees with our record. We refuse to return data and ask the verifier to confirm the subject.
Error / invalid request
errorThe request was malformed, the API key was missing, or the verifier omitted ssn or date_of_birth — both are mandatory.
Two more result_status values you may see
The single-subject and batch responses share the same result_status enum. In addition to the four outcomes above, the spec defines:
partial_match— legacy fallback. We resolved the subject but only some of the optional identifiers could be cross-checked. Treat this like a verified response with a downgradedmatch_confidence.error— only appears on individualBatchItemResultrows when one subject inside a batch fails after validation (upstream payroll outage, internal exception). The row carrieserror_codeanderror_message; the surrounding batch keeps processing.
What each non-verified outcome looks like in JSON
Response — no match
HTTP 200. We searched everywhere and didn't find this person.
{
"verification_id": "ver_01JT7K9S8D7FW80A2YQF0W2QX2",
"status": "completed",
"result_status": "no_match",
"verification_type": "employment_income",
"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",
"permissible_purpose": "credit_transaction",
"subject_match": {
"matched": false,
"match_confidence": "none",
"match_strategy": null
},
"results": [],
"aggregate_income_summary": null
}Response — ambiguous match
HTTP 200. SSN + DOB hit a record but an optional identifier disagrees. We refuse to return data.
{
"verification_id": "ver_01JT7KBV7Q1MHY0GGD31W4D6S5",
"status": "completed",
"result_status": "ambiguous_match",
"verification_type": "employment_income",
"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",
"permissible_purpose": "business_transaction_initiated_by_consumer",
"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
}Response — invalid request
HTTP 400. The verifier didn't meet our minimum identifier rules.
{
"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"
}
]
}
}Reference
Glossary of terms used in the response
- Verifier
- The external company calling our API (e.g. ADP, a mortgage lender, a landlord, a background screening firm).
- Subject
- The person whose employment and income are being verified.
- Employer
- The company the subject works for. We may have data for them across many employers at once.
- Employment record
- One specific job. A person can have several at the same employer (for example, if they were rehired) or across different employers.
- YTD (Year-to-date)
- Totals from January 1 of the current year through the most recent pay date. Inside `income_summary.by_year`, the current calendar year is flagged with is_year_to_date: true so consumers can tell at a glance which year is still accruing.
- by_year / total
- Every income summary — both per employment record and the cross-employer aggregate_income_summary — ships as an array of per-calendar-year totals (`by_year`) followed by a single `total` row that sums every year returned. This makes multi-year income trending and at-a-glance underwriting both available without a second request.
- Gross pay
- Total pay before any taxes or deductions are taken out. Gross pay is the primary summary number throughout the API. When requested, the paycheck layer can also include tax and deduction breakdowns, but we do not rely on net pay as a summary metric anywhere in the response.
- Earnings categories (*_earnings)
- Every paycheck carries the granular earnings[] array plusa paycheck-level rollup field for each normalized category — regular_earnings, overtime_earnings, bonus_earnings, commission_earnings, holiday_earnings, incentive_earnings, miscellaneous_earnings, pension_earnings, pto_earnings, pto_payout_earnings, severance_earnings, sick_earnings, sick_payout_earnings, tips_earnings, vacation_earnings, vacation_payout_earnings, and workers_comp_earnings. Each maps 1:1 to a source-payroll field (e.g. holiday_earnings ← holiday_wages) and to an earning_type on the line-item array, and each is also rolled up at the year, lifetime, and per-work_location levels.
- Hours fields (regular/overtime/other/total)
- Hours rollups appear on Paycheck, YearTotals, IncomeTotals, and LocationIncomeBreakdown as regular_hours, overtime_hours, other_hours (PTO / holiday / sick / vacation, where the source breaks them out), and total_hours (the sum). Returned only by the government verification endpoint — agencies use them for SNAP, Medicaid, and child-support eligibility math.
- subject_match.residence_address
- The home address of the matched subject, as last reported by the source payroll provider. Returned on every endpoint (commercial, government, batch, upload) whenever matched: true. Includes line1, line2, city, county, state, postal_code, and country— each field maps 1:1 to the source payroll employee.address1 / address2 / city / county / state / zip_codefields. Used for jurisdiction attribution (state-tax nexus, child-support venue, agency benefit eligibility) and for distinguishing between candidates when reconciling our match against the verifier’s own record. Individual fields may be nullwhen the source provider didn’t report them.
- ext_payroll_id
- The external payroll-system identifier for a paycheck, as returned by the source provider (ADP, Gusto, Workday, etc.). Distinct from our canonical paycheck_id— use ours as the stable join key, use ext_payroll_idwhen reconciling against the verifier’s own copy of the source payroll feed.
- FEIN / EIN
- Federal Employer Identification Number — the IRS’s ID for a business. We return the full 9-digit value (formatted XX-XXXXXXX) on every employer so the verifier can match exactly against W-2s and 1099s.
- Permissible purpose
- The legal reason a verifier is allowed to receive employment and income data. Required at the top level of every request. The commercial endpoint accepts 7 purposes; the government endpoint accepts 3. Whatever value the verifier sends is echoed back in the response so it can be logged for audit.
- verifier_user_id
- Stable, opaque identifier of the end user at the verifier company who initiated the request — the loan officer, underwriter, screening analyst, or agency caseworker actually pulling the report. Required on every endpoint (top-level on single-subject and government calls; per-row plus a batch-level fallback on the bulk JSON and CSV/NDJSON upload endpoints) for per-seat audit, FCRA / government permissible-purpose attribution, and downstream user-level rate limiting and billing. Pass any opaque value your IDP issues (employee number, email, OIDC sub, UUID); we treat it as opaque and echo it back unchanged on every response.
- verifier_reference_id
- Optional identifier of the case / fileat the verifier (loan number, screening case ID, tenant application ID). One per subject. Used for reconciliation only — we don’t parse it. Distinct from verifier_user_id, which identifies the human pulling the report.