Self-Certification

Self-certification lets users review the income and employment data Truv retrieves and either confirm each record as representative or flag a discrepancy. Retrieve the results on the order to see which records the user certified and which they disputed.

When to use

Scenario	Example
Income verification	User confirms retrieved income matches their actual earnings
Employment confirmation	User validates employer name, start date, and pay rate
Asset verification	User reviews account balances and ownership details
Dispute handling	User flags incorrect or outdated data with a reason

Enable self-certification

Turn on self-certification per Customization Template in the dashboard, under Self-certification. The Enable self-employment income toggle chooses what the user certifies:

Configuration	Enable self-employment income	User certifies
Bank accounts	Off	Payroll employments and bank accounts
Bank income	On	Payroll employments and income detected from bank deposits

Retrieve certification results [Server-side]

Certification data is returned by the standard order-read endpoint, gated behind the certification query parameter. Call it after the user completes their review — the certification-completed webhook signals when results are ready.

curl --request GET \
     --url 'https://prod.truv.com/v1/orders/39aa1486ccca4bc19cda071ffc1ba392/?certification=all' \
     --header 'X-Access-Client-Id: YOUR_TRUV_CLIENT_ID' \
     --header 'X-Access-Secret: YOUR_TRUV_CLIENT_SECRET' \
     --header 'Accept: application/json'

GET /v1/orders/{id}/certifications/ is deprecated and does not return bank income. Use the certification query parameter on the order-read endpoint instead.

Certification modes

`certification`	What you get
(omitted)	Standard order response with no certification fields.
`all`	Every certified record with its `certification` object attached, including disputed ones. Use this to show the user’s decision and reason.
`certified`	Only the records safe to rely on: confirmed accurate, or never disputed. Disputed records are removed, and any employer or financial account left empty is dropped.

Records the user flags as not their own income are excluded in both modes.

Response structure

Each retrieved record carries a certification object inline. What’s certified depends on the template configuration — an order is one configuration or the other, never both. Bank income configuration. Payroll employments carry a certification under employers[].employments[]. Bank-detected income carries one under financial_accounts[].bank_income_sources[], and user-added income under financial_accounts[].additional_income_sources[]. Bank accounts[] are not certified in this configuration — they carry no certification object.

{
  "id": "61e60dc75b8a4452b7642c23288a1d48",
  "completed_at": "2026-07-23T21:13:48.841295Z",
  "employers": [
    {
      "id": "d9845c47f78d474c89a76218679f3a51",
      "employments": [
        {
          "id": "e331e2c98182451d975e15fc22a672be",
          "job_title": "PR associate",
          "income": "56269.25",
          "certification": {
            "decision": "representative",
            "rejection_reason": null,
            "rejection_comment": null,
            "certified_data": {
              "type": "employment",
              "is_active": true,
              "monthly_income": null,
              "hours_per_month": "174.00"
            }
          }
        }
      ]
    }
  ],
  "financial_accounts": [
    {
      "id": "222595ae97f445de8d5da4f975e9ace6",
      "accounts": [
        {
          "id": "fd1db20bdf0f4335a5374f6506b00706",
          "type": "CHECKING",
          "mask": "0685",
          "balance": "49635.00"
        }
      ],
      "bank_income_sources": [
        {
          "account_id": "fd1db20bdf0f4335a5374f6506b00706",
          "income_description": "doordashinc",
          "income_category": "GIG_ECONOMY",
          "total_amount": "14609.21",
          "certification": {
            "decision": "representative",
            "rejection_reason": null,
            "rejection_comment": null,
            "certified_data": {
              "type": "self_employment",
              "is_active": true,
              "monthly_income": "1223.27",
              "hours_per_month": "169.00"
            }
          }
        }
      ],
      "additional_income_sources": []
    }
  ]
}

Bank accounts configuration. Payroll employments are certified as above, and bank accounts[] carry a certification. Account certifications hold decision, rejection_reason, and rejection_comment only — they never include certified_data, and bank_income_sources / additional_income_sources are not certified.

{
  "financial_accounts": [
    {
      "id": "222595ae97f445de8d5da4f975e9ace6",
      "accounts": [
        {
          "id": "fd1db20bdf0f4335a5374f6506b00706",
          "type": "CHECKING",
          "mask": "0685",
          "balance": "49635.00",
          "certification": {
            "decision": "representative",
            "rejection_reason": null,
            "rejection_comment": null
          }
        }
      ]
    }
  ]
}

certified_data is the user-attested snapshot. Its numeric fields can be null — a payroll employment may report hours_per_month while leaving monthly_income empty.

Decision values

Decision	Meaning
`representative`	User confirmed the record is accurate
`not_representative`	User flagged the record as inaccurate — see `rejection_reason`

Rejection reasons

When the decision is not_representative, the certification object includes a rejection_reason:

Reason	Description
`employment_no_longer_active`	User is no longer employed at this company
`incorrect_amount`	Income or balance amount is wrong
`duplicate_entry`	Employer or account appears more than once
`outdated_information`	Data is stale or no longer current
`other`	User provided a custom explanation in `rejection_comment`

Certified data

Where present, certified_data is the user-attested snapshot recorded at certification time.

Field	Description
`type`	Income type declared by the user: `employment`, `self_employment`, or `other`
`is_active`	Whether the income source was active at certification time
`monthly_income`	Declared monthly income amount
`hours_per_month`	Declared hours per month

Read the income figure

Mirror the logic the certification screen uses to pick the income amount:

If certified_data.type is self_employment, use certified_data.monthly_income (gig and bank-detected income).
Otherwise (type: employment), use employments[].pay_rate; if it’s null (typically hourly), fall back to the latest statement’s gross_pay (employments[].statements[0].gross_pay). Always read this amount together with employments[].pay_frequency — pay_rate and gross_pay are per-pay-period values, so they’re only meaningful paired with the frequency (W, BW, SM, M, …).

certified_data.monthly_income is populated only for self_employment; for W-2 it’s null, which is why step 2 reads the amount from the report.

Hours per month

certified_data.hours_per_month can be null if it can’t be calculated. Truv calculates it as follows. “Recent pay stubs” below means every pay stub dated in the last 6 weeks with a non-zero hours value. There’s no cap on how many pay stubs that can include. Payroll employees (salaried or hourly): If the employee has a known hourly rate and has recent pay stubs, hours_per_month is the total hours from those pay stubs, extrapolated to a 30-day month. Pay frequency doesn’t matter here, even if it’s known: this check runs first and overrides everything below. Otherwise:

If there are recent pay stubs, average their hours per pay stub, then × pay frequency ÷ 12 if pay frequency is known. If frequency isn’t known, use the total recent-pay-stub hours extrapolated to a 30-day month instead.
If there are no recent pay stubs but the hourly rate is known: monthly income ÷ hourly rate.
If only a pay rate is known (no recent pay stubs or hourly rate): assume a standard full-time month, 174 hours (40 hrs/week × 52 weeks ÷ 12 = 173.33, rounded up).
If monthly income is known: monthly income ÷ federal minimum wage ($7.25/hour), rounded up.
Otherwise: null.

Gig workers: the same recent-pay-stub extrapolation as step 1 above, with no pay-frequency or standard-hours fallback. null if there are no recent pay stubs with hours. Volunteers:

If they have pay stubs older than the last 30 days: sum of hours reported within the last 30 days.
If not, and they’ve been active more than 30 days: total logged hours since they started, pro-rated to 30 days (e.g., 60 hours over 60 days = 30 hours/month).
Otherwise (active 30 days or less, or no start date on file): total logged hours, as-is.

Bank-detected income (no pay stub, just deposits identified as income): monthly income ÷ federal minimum wage ($7.25/hour), rounded up. null if there’s no income amount to estimate from.

Get Started

Start Building

Implementation

Bridge SDK

Testing & Launch

Dashboard & Configuration

Coverage

Self-Certification

When to use

Enable self-certification

Retrieve certification results [Server-side]

Certification modes

Response structure

Decision values

Rejection reasons

Certified data

Read the income figure

Hours per month

Next steps

Follow-up

Embedded Orders

​When to use

​Enable self-certification

​Retrieve certification results [Server-side]

​Certification modes

​Response structure

​Decision values

​Rejection reasons

​Certified data

​Read the income figure

​Hours per month

​Next steps

Follow-up

Embedded Orders

When to use

Enable self-certification

Retrieve certification results [Server-side]

Certification modes

Response structure

Decision values

Rejection reasons

Certified data

Read the income figure

Hours per month

Next steps