Protect

API reference for Protect endpoints

For how-to guidance, see the Protect documentation.

Endpoints
/protect/event/sendSend your backend event to Plaid Protect for evaluation
/protect/event/getGet event details and trust index score metadata
/protect/user/insights/getGet the latest user event details and other metadata
/protect/report/createInform Plaid of a potential fraud or risk incident
Webhooks
PROTECT_USER_EVENTSent when an event occurs for a user

Endpoints

=*=*=*=

/protect/event/send

Send a new event to enrich user data

Send a new event to enrich user data and optionally get a Trust Index score for the event.

/protect/event/send

Request fields

client_id
stringstring
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
stringstring
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.
timestamp
stringstring
Timestamp of the event. Might be the current moment or a time in the past. In ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
event
requiredobjectrequired, object
Event data for Protect events.
timestamp
requiredstringrequired, string
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
protect_session_id
stringstring
If present, contains the current Protect Session ID from the Plaid Pixel SDK.
app_visit
objectobject
This event type represents a user visiting the client application.
user_sign_in
objectobject
This event type represents a user signing in to the application.
user_sign_up
objectobject
This event type represents a user signing up for the application.
protect_session_id
stringstring
Protect Session ID should be provided for any event correlated with a frontend user session started via the Protect SDK.
request_trust_index
booleanboolean
Whether this event should be scored with Trust Index. The default is false.
1const request: ProtectEventSendRequest = {
2    event: {
3      user_sign_in: {},
4      timestamp: '2025-05-14T14:42:19.350Z'
5    },
6    user: {
7      client_user_id: 'user-abc'
8    },
9  };
10  try {
11    const response = await client.protectEventSend(request);
12    const eventId = response.data.event_id;
13} catch (error) {
14  // handle error
15}
/protect/event/send

Response fields

event_id
stringstring
The id of the recorded event.
trust_index
nullableobjectnullable, object
Represents a calculate Trust Index Score.
score
integerinteger
The overall trust index score.
model
stringstring
The versioned name of the Trust Index model used for scoring.
subscores
nullableobjectnullable, object
Contains sub-score metadata.
device_and_connection
nullableobjectnullable, object
Represents Trust Index Subscore.
score
integerinteger
The subscore score.
bank_account_insights
nullableobjectnullable, object
Represents Trust Index Subscore.
score
integerinteger
The subscore score.
fraud_attributes
nullableobjectnullable, object
Event fraud attributes as an arbitrary set of key-value pairs.
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "event_id": "protect-event-2be8498f",
3  "trust_index": {
4    "score": 86,
5    "model": "ti-pro-1.0",
6    "subscores": {
7      "device_and_connection": {
8        "score": 87
9      },
10      "bank_account_insights": {
11        "score": 85
12      }
13    },
14    "fraud_attributes": {
15      "num_distinct_names_on_accounts": 3,
16      "identity_match_idv_bank_account": true,
17      "idv_id_doc_passed": true
18    }
19  },
20  "request_id": "saKrIBuEB9qJZng"
21}
=*=*=*=

/protect/event/get

Get information about a user event

Get information about a user event including Trust Index score and fraud attributes.

/protect/event/get

Request fields

client_id
stringstring
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
stringstring
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.
event_id
requiredstringrequired, string
The event ID to retrieve information for.
1const request: ProtectEventGetRequest = {
2  event_id: 'evt_abcdefghij1234567890'
3};
4  try {
5  const response = await client.protectEventGet(request);
6  const trustScore = response.data.trust_index.score;
7} catch (error) {
8  // handle error
9}
/protect/event/get

Response fields

event_id
stringstring
The event ID.
timestamp
stringstring
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
trust_index
nullableobjectnullable, object
Represents a calculate Trust Index Score.
score
integerinteger
The overall trust index score.
model
stringstring
The versioned name of the Trust Index model used for scoring.
subscores
nullableobjectnullable, object
Contains sub-score metadata.
device_and_connection
nullableobjectnullable, object
Represents Trust Index Subscore.
score
integerinteger
The subscore score.
bank_account_insights
nullableobjectnullable, object
Represents Trust Index Subscore.
score
integerinteger
The subscore score.
fraud_attributes
nullableobjectnullable, object
Event fraud attributes as an arbitrary set of key-value pairs.
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "event_id": "protect-event-2be8498f",
3  "timestamp": "2020-07-24T03:26:02Z",
4  "trust_index": {
5    "score": 86,
6    "model": "ti-pro-1.0",
7    "subscores": {
8      "device_and_connection": {
9        "score": 87
10      },
11      "bank_account_insights": {
12        "score": 85
13      }
14    }
15  },
16  "fraud_attributes": {
17    "num_distinct_names_on_accounts": 3,
18    "identity_match_idv_bank_account": true,
19    "idv_id_doc_passed": true,
20    "bank_accounts": [
21      {
22        "account_name": "Premium Checking",
23        "account_type": "checking",
24        "institution_name": "Huntington Credit Union",
25        "account_age_days": 144,
26        "num_distinct_owner_names": 3
27      },
28      {
29        "account_name": "Credit ***8889",
30        "account_type": "credit"
31      }
32    ]
33  },
34  "request_id": "saKrIBuEB9qJZng"
35}
=*=*=*=

/protect/user/insights/get

Get Protect user insights

Use this endpoint to get basic information about a user as it relates to their fraud profile with Protect.

/protect/user/insights/get

Request fields

client_id
stringstring
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
stringstring
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_id
stringstring
The Plaid User ID. Either user_id or client_user_id must be provided.
client_user_id
stringstring
A unique ID representing the end user. Either user_id or client_user_id must be provided.
1const request: ProtectUserInsightsGetRequest = {
2  client_user_id: 'user-abc'
3};
4try {
5  const response = await client.protectUserInsightsGet(request);
6  const trustScore = response.data.latest_scored_event.trust_index.score;
7} catch (error) {
8  // handle error
9}
/protect/user/insights/get

Response fields

user_id
stringstring
The Plaid User ID. If a client_user_id was provided in the request instead of a user_id, a new user_id will be generated if one doesn't already exist for that client_user_id.
latest_scored_event
nullableobjectnullable, object
The latest scored event for a user.
event_id
stringstring
The event ID.
timestamp
stringstring
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
event_type
stringstring
The type of event.
trust_index
nullableobjectnullable, object
Represents a calculate Trust Index Score.
score
integerinteger
The overall trust index score.
model
stringstring
The versioned name of the Trust Index model used for scoring.
subscores
nullableobjectnullable, object
Contains sub-score metadata.
device_and_connection
nullableobjectnullable, object
Represents Trust Index Subscore.
score
integerinteger
The subscore score.
bank_account_insights
nullableobjectnullable, object
Represents Trust Index Subscore.
score
integerinteger
The subscore score.
fraud_attributes
nullableobjectnullable, object
Event fraud attributes as an arbitrary set of key-value pairs.
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "user_id": "plaid-user-6009db6e",
3  "latest_scored_event": {
4    "event_id": "protect-event-2be8498f",
5    "timestamp": "2020-07-24T03:26:02Z",
6    "trust_index": {
7      "score": 86,
8      "model": "ti-pro-1.0",
9      "subscores": {
10        "device_and_connection": {
11          "score": 87
12        },
13        "bank_account_insights": {
14          "score": 85
15        }
16      }
17    },
18    "fraud_attributes": {
19      "num_distinct_names_on_accounts": 3,
20      "identity_match_idv_bank_account": true,
21      "idv_id_doc_passed": true
22    }
23  },
24  "request_id": "saKrIBuEB9qJZng"
25}
=*=*=*=

/protect/report/create

Create a Protect report

Use this endpoint to create a Protect report to document fraud incidents, investigation outcomes, or other risk events. This endpoint allows you to report various types of incidents including account takeovers, identity fraud, unauthorized transactions, and other security events. The reported data helps improve fraud detection models and provides valuable feedback to enhance the overall security of the Plaid network. Reports can be created for confirmed incidents that have been fully investigated, or for suspected incidents that require further review. You can associate reports with specific users, sessions, or transactions to provide comprehensive context about the incident.

/protect/report/create

Request fields

client_id
stringstring
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
stringstring
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_id
stringstring
The Plaid User ID associated with the report.
incident_event
objectobject
details about the incident event.
protect_event_id
stringstring
A globally unique identifier representing a Protect event that may be associated with this incident.
link_session_id
stringstring
A unique identifier for a Link session that may be associated with this incident.
idv_session_id
stringstring
A unique identifier for an Identity Verification session that may be associated with this incident.
signal_client_transaction_id
stringstring
The unique ID used to refer to a Signal transaction evaluation that may be associated with this incident.
internal_reference
stringstring
A unique ID representing the incident in your system. Personally identifiable information, such as an email address or phone number, should not be used in this field.
time
stringstring
The timestamp when the incident occurred, in ISO 8601 format (e.g., '2020-07-24T03:26:02Z').

Format: date-time
amount
objectobject
The monetary amount associated with the incident.
iso_currency_code
stringstring
The ISO-4217 currency code of the incident amount. Defaults to USD if not specified.

Default: USD
value
requirednumberrequired, number
The monetary value of the incident amount.

Format: double
report_confidence
requiredstringrequired, string
The confidence level of the incident report. CONFIRMED indicates the incident has been verified and definitively occurred.
SUSPECTED indicates the incident is believed to have occurred but has not been fully verified.

Possible values: CONFIRMED, SUSPECTED
report_type
requiredstringrequired, string
The type of incident being reported.
USER_ACCOUNT_TAKEOVER - Indicates that a legitimate user's account was accessed or controlled by an unauthorized party.
FALSE_IDENTITY - Indicates that a user created an account using stolen or fabricated identity information.
STOLEN_IDENTITY - Indicates that a user created an account using identity information belonging to a real individual without their consent.
SYNTHETIC_IDENTITY - Indicates that a user created an account using a fake or partially fabricated identity (e.g., combining real and fake information to form a new persona).
MULTIPLE_USER_ACCOUNTS - Indicates that the same individual is operating multiple accounts in violation of policy.
SCAM_VICTIM - Indicates that the user was tricked into authorizing or sending funds as part of a scam.
BANK_ACCOUNT_TAKEOVER - Indicates that a user's linked bank account was accessed or misused by an unauthorized party.
BANK_CONNECTION_REVOKED - Indicates that a linked bank account connection was revoked by the financial institution, often due to suspected misuse, fraud, or security concerns.
CARD_TESTING - Indicates that a card was used in small or repeated transactions to test its validity.
UNAUTHORIZED_TRANSACTION - Indicates that a transaction was made without the user's consent or authorization.
CARD_CHARGEBACK - Indicates that a card transaction was reversed via a chargeback claim.
ACH_RETURN - Indicates that an ACH transaction was returned or reversed by the bank.
DISPUTE - Indicates that a user filed a dispute regarding a transaction or account activity.
FIRST_PARTY_FRAUD - Indicates that a user intentionally misrepresented themselves or their actions for financial gain.
MISSED_PAYMENT - Indicates that a user failed to make a required payment on time.
LOAN_STACKING - Indicates that a user applied for or took out multiple loans simultaneously beyond their ability to repay.
MONEY_LAUNDERING - Indicates that funds are being moved through accounts to obscure their illicit origin.
NO_FRAUD - Indicates that an investigation determined no fraudulent activity occurred on user/event (positive label)
OTHER - Indicates that the case involves fraud or financial risk not covered by other report types. Requires notes describing the report.

Possible values: USER_ACCOUNT_TAKEOVER, FALSE_IDENTITY, STOLEN_IDENTITY, SYNTHETIC_IDENTITY, MULTIPLE_USER_ACCOUNTS, SCAM_VICTIM, BANK_ACCOUNT_TAKEOVER, BANK_CONNECTION_REVOKED, CARD_TESTING, UNAUTHORIZED_TRANSACTION, CARD_CHARGEBACK, ACH_RETURN, DISPUTE, FIRST_PARTY_FRAUD, MISSED_PAYMENT, LOAN_STACKING, MONEY_LAUNDERING, NO_FRAUD, OTHER
report_source
requiredstringrequired, string
The source that identified or reported the incident.
INTERNAL_REVIEW - Incident was identified through internal fraud investigations or review processes.
USER_SELF_REPORTED - Incident was reported directly by the affected user.
BANK_FEEDBACK - Incident was identified through bank feedback, including ACH returns and connection revocations.
NETWORK_FEEDBACK - Incident was identified through card network alerts or chargebacks.
AUTOMATED_SYSTEM - Incident was detected by automated systems such as fraud models or rule engines.
THIRD_PARTY_ALERT - Incident was identified through external vendor or consortium alerts.
OTHER - Incident was identified through a source not covered by other categories.

Possible values: INTERNAL_REVIEW, USER_SELF_REPORTED, BANK_FEEDBACK, NETWORK_FEEDBACK, AUTOMATED_SYSTEM, THIRD_PARTY_ALERT, OTHER
bank_account
objectobject
Bank account information associated with the incident.
account_id
stringstring
Plaid's unique identifier for the account.
account_number
stringstring
Full account number of the bank account.
routing_number
stringstring
Routing number of the bank account. Must be present if account_number is present.
ach_return_code
stringstring
Must be a valid ACH return code (e.g. R01), required if report_type is ACH_RETURN.
notes
stringstring
Additional context or details about the report, required if report_type is OTHER.

Max length: 1024 
1const request: ProtectReportCreateRequest = {
2  user_id: 'plaid-user-6009db6e',
3  incident_event: {
4    protect_event_id: 'protect-event-2be8498f',
5    time: '2025-10-15T10:30:00Z',
6    amount: {
7      iso_currency_code: 'USD',
8      value: 150.00
9    },
10    internal_reference: 'fraud-case-12345'
11  },
12  report_confidence: 'CONFIRMED',
13  report_type: 'UNAUTHORIZED_TRANSACTION',
14  report_source: 'USER_SELF_REPORTED',
15  bank_account: {
16    account_id: 'BxBXxLj1m4HMXBm9WZZmCWVbPjX16EHwv99vp',
17    account_number: '9900009606',
18    routing_number: '011401533'
19  }
20};
21

22try {
23  const response = await plaidClient.protectReportCreate(request);
24  const reportId = response.data.report_id;
25} catch (error) {
26  // handle error
27}
/protect/report/create

Response fields

report_id
stringstring
A unique identifier representing the submitted report.
request_id
stringstring
A unique identifier for the request, which can be used for troubleshooting. This identifier, like all Plaid identifiers, is case sensitive.
1{
2  "report_id": "ptrpt_42cF1MNo42r9Xj",
3  "request_id": "saKrIBuEB9qJZng"
4}

Webhooks

=*=*=*=

PROTECT_USER_EVENT

Fired when there has been a new user event. The webhook payload contains limited information about the event. For full event details, call /protect/event/get.

Properties

webhook_type
stringstring
"PROTECT"
webhook_code
stringstring
PROTECT_USER_EVENT
event_id
stringstring
The event ID of the user event that occurred.
event_type
stringstring
The type of user event that occurred.
timestamp
stringstring
The timestamp of the event, in ISO 8601 format, e.g. "2017-09-14T14:42:19.350Z"

Format: date-time
user_id
stringstring
The Plaid User ID.
1{
2  "webhook_type": "PROTECT",
3  "webhook_code": "PROTECT_USER_EVENT",
4  "user_id": "plaid-user-6009db6e",
5  "event_id": "protect-event-2be8498f",
6  "timestamp": "2020-07-24T03:26:02Z",
7  "event_type": "LINK_COMPLETE"
8}