--- title: "Retrieve fraud insights for a user's manually uploaded document(s)." method: POST path: "/credit/payroll_income/risk_signals/get" tags: ["plaid"] --- # Retrieve fraud insights for a user's manually uploaded document(s). `POST /credit/payroll_income/risk_signals/get` `/credit/payroll_income/risk_signals/get` can be used as part of the Document Income flow to assess a user-uploaded document for signs of potential fraud or tampering. It returns a risk score for each uploaded document that indicates the likelihood of the document being fraudulent, in addition to details on the individual risk signals contributing to the score. To trigger risk signal generation for an Item, call `/link/token/create` with `parsing_config` set to include `risk_signals`, or call `/credit/payroll_income/parsing_config/update`. Once risk signal generation has been triggered, `/credit/payroll_income/risk_signals/get` can be called at any time after the `INCOME_VERIFICATION_RISK_SIGNALS` webhook has been fired. `/credit/payroll_income/risk_signals/get` is offered as an add-on to Document Income and is billed separately. To request access to this endpoint, submit a product access request or contact your Plaid account manager. ## Request body - CreditPayrollIncomeRiskSignalsGetRequest — CreditPayrollIncomeRiskSignalsGetRequest defines the request schema for `/credit/payroll_income/risk_signals/get` - `client_id` string — Your Plaid API `client_id`. The `client_id` is required and may be provided either in the `PLAID-CLIENT-ID` header or as part of a request body. - `secret` string — Your Plaid API `secret`. The `secret` is required and may be provided either in the `PLAID-SECRET` header or as part of a request body. - `user_token` string — The user token associated with the user for which data is being requested. This field is used only by customers with pre-existing integrations that already use the `user_token` field. All other customers should use the `user_id` instead. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis). - `user_id` string — A unique user identifier, created by `/user/create`. Integrations that began using `/user/create` after December 10, 2025 use this field to identify a user instead of the `user_token`. For more details, see [New User APIs](https://plaid.com/docs/api/users/user-apis). ## Response `200` OK - CreditPayrollIncomeRiskSignalsGetResponse — CreditPayrollIncomeRiskSignalsGetResponse defines the response schema for `/credit/payroll_income/risk_signals/get` - `items` PayrollRiskSignalsItem[], required — Array of payroll items. - `item_id` string, required — The `item_id` of the Item associated with this webhook, warning, or error - `verification_risk_signals` DocumentRiskSignalsObject[], required — Array of payroll income document authenticity data retrieved for each of the user's accounts. - `account_id` string, nullable, required — ID of the payroll provider account. - `single_document_risk_signals` SingleDocumentRiskSignal[], required — Array of document metadata and associated risk signals per document - `document_reference` RiskSignalDocumentReference, required — Object containing metadata for the document - `document_id` string, nullable — An identifier of the document referenced by the document metadata. - `document_name` string — The name of the document - `status` 'PROCESSING' | 'PROCESSING_COMPLETE' | 'PROCESSING_ERROR' | 'PASSWORD_PROTECTED' | 'VIRUS_DETECTED' — Status of a document for risk signal analysis - `document_type` 'UNKNOWN' | 'BANK_STATEMENT' | 'BENEFITS_STATEMENT' | 'BUSINESS_FILING' | 'CHECK' | 'DRIVING_LICENSE' | 'FINANCIAL_STATEMENT' | 'INVOICE' | 'PAYSLIP' | 'SOCIAL_SECURITY_CARD' | 'TAX_FORM' | 'UTILITY_BILL', nullable — Type of a document for risk signal analysis - `file_type` 'UNKNOWN' | 'IMAGE_PDF' | 'SCAN_OCR' | 'TRUE_PDF' | 'IMAGE' | 'MIXED_PAGE_PDF' | 'EMPTY_PDF' | 'FLATTENED_PDF', nullable — The file type for risk signal analysis - `risk_signals` DocumentRiskSignal[], required — Array of attributes that indicate whether or not there is fraud risk with a document - `type` string, nullable, required — The type of risk found in the risk signal check. - `field` string, nullable, required — The field which the risk signal was computed for - `has_fraud_risk` boolean, nullable, required — A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent - `institution_metadata` DocumentRiskSignalInstitutionMetadata, nullable, required — An object which contains additional metadata about the institution used to compute the verification attribute - `item_id` string, required — The `item_id` of the Item associated with this webhook, warning, or error - `expected_value` string, nullable, required — The expected value of the field, as seen on the document - `actual_value` string, nullable, required — The derived value obtained in the risk signal calculation process for this field - `signal_description` string, nullable, required — A human-readable explanation providing more detail into the particular risk signal - `page_number` integer, nullable, required — The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0. - `risk_summary` DocumentRiskSummary, required — A summary across all risk signals associated with a document - `risk_score` number, nullable, required — A number between 0 and 100, inclusive, where a score closer to 0 indicates a document is likely to be trustworthy and a score closer to 100 indicates a document is likely to be fraudulent. You can automatically reject documents with a high risk score, automatically accept documents with a low risk score, and manually review documents in between. We suggest starting with a threshold of 80 for auto-rejection and 20 for auto-acceptance. As you gather more data points on typical risk scores for your use case, you can tune these parameters to reduce the number of documents undergoing manual review. - `multi_document_risk_signals` MultiDocumentRiskSignal[], required — Array of risk signals computed from a set of uploaded documents and the associated documents' metadata - `document_references` RiskSignalDocumentReference[], required — Array of objects containing attributes that could indicate if a document is fraudulent - `document_id` string, nullable — An identifier of the document referenced by the document metadata. - `document_name` string — The name of the document - `status` 'PROCESSING' | 'PROCESSING_COMPLETE' | 'PROCESSING_ERROR' | 'PASSWORD_PROTECTED' | 'VIRUS_DETECTED' — Status of a document for risk signal analysis - `document_type` 'UNKNOWN' | 'BANK_STATEMENT' | 'BENEFITS_STATEMENT' | 'BUSINESS_FILING' | 'CHECK' | 'DRIVING_LICENSE' | 'FINANCIAL_STATEMENT' | 'INVOICE' | 'PAYSLIP' | 'SOCIAL_SECURITY_CARD' | 'TAX_FORM' | 'UTILITY_BILL', nullable — Type of a document for risk signal analysis - `file_type` 'UNKNOWN' | 'IMAGE_PDF' | 'SCAN_OCR' | 'TRUE_PDF' | 'IMAGE' | 'MIXED_PAGE_PDF' | 'EMPTY_PDF' | 'FLATTENED_PDF', nullable — The file type for risk signal analysis - `risk_signals` DocumentRiskSignal[], required — Array of attributes that indicate whether or not there is fraud risk with a set of documents - `type` string, nullable, required — The type of risk found in the risk signal check. - `field` string, nullable, required — The field which the risk signal was computed for - `has_fraud_risk` boolean, nullable, required — A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent - `institution_metadata` DocumentRiskSignalInstitutionMetadata, nullable, required — An object which contains additional metadata about the institution used to compute the verification attribute - `item_id` string, required — The `item_id` of the Item associated with this webhook, warning, or error - `expected_value` string, nullable, required — The expected value of the field, as seen on the document - `actual_value` string, nullable, required — The derived value obtained in the risk signal calculation process for this field - `signal_description` string, nullable, required — A human-readable explanation providing more detail into the particular risk signal - `page_number` integer, nullable, required — The relevant page associated with the risk signal. If the risk signal is not associated with a specific page, the value will be 0. - `error` PlaidError, nullable — Errors are identified by `error_code` and categorized by `error_type`. Use these in preference to HTTP status codes to identify and handle specific errors. HTTP status codes are set and provide the broadest categorization of errors: 4xx codes are for developer- or user-related errors, and 5xx codes are for Plaid-related errors, and the status will be 2xx in non-error cases. An Item with a non-`null` error object will only be part of an API response when calling `/item/get` to view Item status. Otherwise, error fields will be `null` if no error has occurred; if an error has occurred, an error code will be returned instead. - `error_type` 'INVALID_REQUEST' | 'INVALID_RESULT' | 'INVALID_INPUT' | 'INSTITUTION_ERROR' | 'RATE_LIMIT_EXCEEDED' | 'API_ERROR' | 'ITEM_ERROR' | 'ASSET_REPORT_ERROR' | 'BASE_REPORT_ERROR' | 'RECAPTCHA_ERROR' | 'OAUTH_ERROR' | 'PAYMENT_ERROR' | 'BANK_TRANSFER_ERROR' | 'INCOME_VERIFICATION_ERROR' | 'MICRODEPOSITS_ERROR' | 'SANDBOX_ERROR' | 'PARTNER_ERROR' | 'SIGNAL_ERROR' | 'TRANSACTIONS_ERROR' | 'TRANSACTION_ERROR' | 'TRANSFER_ERROR' | 'CHECK_REPORT_ERROR' | 'CONSUMER_REPORT_ERROR' | 'USER_ERROR' | 'IDEMPOTENCY_ERROR' | 'ASSETS_ERROR' | 'CRA_MONITORING_ERROR' | 'CREDIT_PROFILE_REPORT_ERROR' | 'ENCOMPASS_ERROR' | 'ENRICH_ERROR' | 'FRAUD_INSIGHTS_ERROR' | 'FREDDIE_MAC_ERROR' | 'LINK_DELIVERY_ERROR' | 'PROFILE_ERROR' | 'RECURRING_TRANSACTIONS_ERROR' | 'STATEMENTS_ERROR' | 'TRANSFER_RECURRING_ERROR' | 'TRANSFER_REFUND_ERROR', required — A broad categorization of the error. Safe for programmatic use. - `error_code` string, required — The particular error code. Safe for programmatic use. - `error_code_reason` string, nullable — The specific reason for the error code. Currently, reasons are only supported for OAuth-based item errors; `null` will be returned otherwise. Safe for programmatic use. Possible values: `OAUTH_INVALID_TOKEN`: The user's OAuth connection to this institution has been invalidated. `OAUTH_CONSENT_EXPIRED`: The user's access consent for this OAuth connection to this institution has expired. `OAUTH_USER_REVOKED`: The user's OAuth connection to this institution is invalid because the user revoked their connection. - `error_message` string, required — A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use. - `display_message` string, nullable, required — A user-friendly representation of the error code. `null` if the error is not related to user action. This may change over time and is not safe for programmatic use. - `request_id` string — A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks. - `causes` unknown[] — In this product, a request can pertain to more than one Item. If an error is returned for such a request, `causes` will return an array of errors containing a breakdown of these errors on the individual Item level, if any can be identified. `causes` will be provided for the `error_type` `ASSET_REPORT_ERROR` or `CHECK_REPORT_ERROR`. `causes` will also not be populated inside an error nested within a `warning` object. - unknown - `status` integer, nullable — The HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook. - `documentation_url` string — The URL of a Plaid documentation page with more information about the error - `suggested_action` string, nullable — Suggested steps for resolving the error - `required_account_subtypes` string[] — A list of the account subtypes that were requested via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. - `provided_account_subtypes` string[] — A list of the account subtypes that were extracted but did not match the requested subtypes via the `account_filters` parameter in `/link/token/create`. Currently only populated for `NO_ACCOUNTS` errors from Items with `investments_auth` as an enabled product. - `request_id` string, required — A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive. ## Other responses - `default` — Error response --- [API](https://skmtc.net/plaid/apis/the-plaid-api.md) · [All operations](https://skmtc.net/plaid/apis/the-plaid-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/plaid/the-plaid-api/revisions/64c4514ea59b/schema)