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
Required
CreditPayrollIncomeRiskSignalsGetRequest defines the request schema for /credit/payroll_income/risk_signals/get
Parameters
client_id
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
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
The user token associated with the User data is being requested for.
Response
CreditPayrollIncomeRiskSignalsGetRequest defines the response schema for /credit/payroll_income/risk_signals/get
Response Properties
items
Array of payroll items.
item_id
The
item_id of the Item associated with this webhook, warning, or error
verification_risk_signals
Array of payroll income document authenticity data retrieved for each of the user’s accounts.
account_id
ID of the payroll provider account.
single_document_risk_signals
Array of document metadata and associated risk signals per document
document_reference
Object containing metadata for the document
document_id
An identifier of the document referenced by the document metadata.
document_name
The name of the document
status
Status of a document for risk signal analysis
document_type
Type of a document for risk signal analysis
file_type
The file type for risk signal analysis
risk_signals
Array of attributes that indicate whether or not there is fraud risk with a document
type
The type of risk found in the risk signal check.
field
The field which the risk signal was computed for
has_fraud_risk
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent
institution_metadata
An object which contains additional metadata about the institution used to compute the verification attribute
expected_value
The expected value of the field, as seen on the document
actual_value
The derived value obtained in the risk signal calculation process for this field
signal_description
A human-readable explanation providing more detail into the particular risk signal
page_number
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
A summary across all risk signals associated with a document
risk_score
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
Array of risk signals computed from a set of uploaded documents and the associated documents’ metadata
document_references
Array of objects containing attributes that could indicate if a document is fraudulent
document_id
An identifier of the document referenced by the document metadata.
document_name
The name of the document
status
Status of a document for risk signal analysis
document_type
Type of a document for risk signal analysis
file_type
The file type for risk signal analysis
risk_signals
Array of attributes that indicate whether or not there is fraud risk with a set of documents
type
The type of risk found in the risk signal check.
field
The field which the risk signal was computed for
has_fraud_risk
A flag used to quickly identify if the signal indicates that this field is authentic or fraudulent
institution_metadata
An object which contains additional metadata about the institution used to compute the verification attribute
expected_value
The expected value of the field, as seen on the document
actual_value
The derived value obtained in the risk signal calculation process for this field
signal_description
A human-readable explanation providing more detail into the particular risk signal
page_number
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
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
A broad categorization of the error. Safe for programmatic use.
error_code
The particular error code. Safe for programmatic use.
error_code_reason
The specific reason for the error code. Currently, reasons are only supported 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
A developer-friendly representation of the error code. This may change over time and is not safe for programmatic use.
display_message
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
A unique ID identifying the request, to be used for troubleshooting purposes. This field will be omitted in errors provided by webhooks.
causes
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.
status
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
The URL of a Plaid documentation page with more information about the error
suggested_action
Suggested steps for resolving the error
request_id
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.