`decisioning` - FCRA credit decisioning
`verification` - Non-FCRA underwriting verifications
`analytics` - Retroactive reports for analytical purposes only | | status | string | Terminal statuses are:
`success`, `failed`, `data_import_error`
A status of `processing` indicates that the report is still being processed. An additional call should be made to the GET endpoint until a terminal status is returned. | | cutoff\_date | string | Latest date of financial activity included in report, typically set to current date or application date, date is in the past for retro-scored reports | | created\_at | string | Date and time of report request | | updated\_at | string | Date and time of report update | | alerts | array of objects | Values present when notifying lender of specific conditions, conditions do not prevent report completion, see [Alerts object](#alerts-object) | | scores | array of objects | Generic or custom scores, only report purpose-applicable scores are returned, see [Scores object](#scores-object) | | metrics | array of objects | See [Metrics object](#metrics-object) | | derived\_incomes | array of objects | See [Derived Incomes object](#derived-incomes-object) | *** ## Alerts object Each alert includes the following fields. | Attribute | Type | Description | | :---------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | alert\_code | integer | Integer indicating alert type, see message field for valid values | | message | string | Message describing alert condition, valid values and alert codes below
`1` - No consistent income sources present
`2` - No consistent payment streams present
`3` - Short transaction history
`4` - Low transaction activity
`5` - Unable to calculate daily balances for all accounts
`6` - Accounts with stale ending balances are present
`7` - Low ratio of debit activity | *** ## Scores object Each score includes the following fields. | Attribute | Type | Description | | :-------- | :------ | :----------------- | | name | string | Model name | | version | float | Model version | | value | integer | Scaled score value | *** ## Metrics object Each metric includes the following fields. | Attribute | Type | Description | | :----------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Metric name, not including period of time | | time\_period | string | Abbreviation for time period of metric, valid values below:
`1m_l0` - Last month
`2m_l0` - Last 2 months
`3m_l0` - Last 3 months
`4m_l0` - Last 4 months
`6m_l0` - Last 6 months
`1w_l0` - Last week
`2w_l0` - Last 2 weeks
`2m_l2` - 2 months (2 month delay)
`2m_l4` - 2 months (4 month delay)
`4m_l2` - 4 months (2 month delay)
`1m_l1` - 1 month (1 month delay)
`2w_l2` - 2 weeks (2 week delay)
`0m_l0` - Current snapshot
`0m_l2` - Snapshot from 2 months ago
`0m_l4` - Snapshot from 4 months ago
`lftm` - Lifetime
`2m_to_1m` - Change from 2 months ago to current month
`3m_to_1m` - Change from 3 months ago to current month | | short\_name | string | Abbreviated form of metric name combined with time period | | unit | string | Measurement type for metric, valid fields `dollars`, `percent`, `boolean`, `count` | | value | number | Numeric value of metric, can contain null values, `null` is not `0` and must be properly parsed
For amounts, returns dollar value with decimals indicating cents, such as `2.99`
For percentages, returns an integer, for example 5% is `5`
For Booleans, `True` is represented as `1` and `False` is represented as `0`
For `counts` such as number of consistent payments, returns integers | *** ## Derived incomes object Each derived income stream includes the following fields. | Attribute | Type | Description | | :------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | description | string | Normalized description for derived income stream, for sensitive information within description, such as health information, description returns as `REDACTED` | | frequency | string | Frequency of income stream, possible values are `monthly`, `semi_monthly`, `bi_weekly`, `weekly` | | days | array | Day or days of week or month for recurring deposits
For `monthly` and `semi-monthly` frequencies, returns day of the month and `-1` indicates end of month
For `weekly` and `bi_weekly` frequencies, returns day of week where `1` indicates Monday and `7` indicates Sunday | | formatted\_frequency | string | Frequency combined with recurrence days | | months | number | Longest period income stream has been recurring from report date
Income streams are only evaluated on whole months and 2, 3, 4 and 6 month intervals | | average\_amount | double | Average amount of each deposit in covered monthly interval | | monthly\_amount | double | Projected monthly amount based on average amount and occurrence frequency | *** ## Endpoints Use the endpoints below to get information on reports for scoring attributes. * [Create a scoring attributes report](/api-reference/scoring-attributes/scoring-attributes-report-create) * [Retrieve a scoring attributes report](/api-reference/scoring-attributes/scoring-attributes-report-retrieve) *** ## Example response ```json theme={null} { "report_id": "string", "source_guid": "2f918810e4b911edb5ea0242ac120002", "refresh": true, "lender_reference": "appl-1234", "customer_identifier": "cust-9999", "purpose": "decisioning", "status": "success", "cutoff_date": "2021-03-31T00:00:00.000Z", "created_at": "2022-03-16 12:56:15 -0700", "updated_at": "2022-03-16 12:56:17 -0700", "alerts": [ { "alert_code": 1, "message": "No consistent income sources present" } ], "scores": [ { "name": "Overdraft Risk Score", "version": 1, "value": 750 } ], "metrics": [ { "name": "derived_nsf_fee_amount", "time_period": "2m_l0", "short_name": "drvd_nsf_fee_amt_2m_l0", "unit": "dollars", "value": 23.99 } ], "derived_incomes": [ { "description": "direct deposit from xyz company", "frequency": "semi_monthly", "days": [15, -1], "formatted_frequency": "Semi-Monthly (15, eom)", "months": 3, "average_amount": 475.99, "monthly_amount": 1003.21 } ] } ``` # Create a scoring attributes report Source: https://truv.com/docs/api-reference/scoring-attributes/scoring-attributes-report-create POST /v1/scoring_attributes/reports # Retrieve a scoring attributes report Source: https://truv.com/docs/api-reference/scoring-attributes/scoring-attributes-report-retrieve GET /v1/scoring_attributes/reports/{report_id} # Webhook Security Source: https://truv.com/docs/api-reference/security Verify webhook deliveries, handle retries safely, and configure webhook security controls Use this page for the security and operational rules around webhook delivery: * verify every delivery with `X-WEBHOOK-SIGN` * respond within the supported timeout window * handle duplicate deliveries safely * process events using `updated_at` for sequencing * allowlist Truv IPs or configure mTLS when your network requires it Use [Webhook Events](/api-reference/webhook-events) only as the event catalog. Use [Webhooks](/api-reference/webhooks/object) for endpoint configuration and payload structure. *** ## Webhook signature verification Every webhook request from Truv includes an `X-WEBHOOK-SIGN` header containing an HMAC-SHA256 hash. Use this to verify that requests are authentic and haven't been tampered with. ### How it works 1. Truv computes an HMAC-SHA256 hash of the raw request body using your Access Secret 2. The hash is sent in the `X-WEBHOOK-SIGN` header with a `v1=` prefix 3. Your server recomputes the hash and compares it to the header value
| Icon | Rating | Payroll | Financial accounts |
|---|---|---|---|
|
|
High | Expected to succeed, send the verification order. | Expected to succeed, send the verification order. |
|
|
Low | May succeed, send if the user knows their payroll provider and is confident. | May succeed, send if the user is confident and knows their login credentials. |
|
|
Unsupported | Verification via payroll is not feasible. Try Truv's Document Upload solution or the next step in your waterfall as an alternative. | Verification with this financial institution is not supported, use an alternative method. |
|
|
Unknown | Not enough attempts to determine success. May succeed if the user knows their payroll provider and it's supported by Truv. | Not enough attempts to determine success. Likely to succeed based on other financial institutions. |