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

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

Next steps

New User

Data Refresh

​When to use

​Enable self-certification

​Retrieve certification results [Server-side]

​Certification modes

​Response structure

​Decision values

​Rejection reasons

​Certified data

​Next steps

New User

Data Refresh

When to use

Enable self-certification

Retrieve certification results [Server-side]

Certification modes

Response structure

Decision values

Rejection reasons

Certified data

Next steps