Protect

API reference for Protect endpoints

For how-to guidance, see the Protect documentation.

Endpoints
/protect/event/sendSends your backend event to Plaid Protect
/protect/event/getReturns event details and trust index score metadata
/protect/user/insights/getReturns the latest user event details and other metadata
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_sdk_session_id
stringstring
Protect SDK session id should be provided for any event correlated with a frontend user session
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 and example

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 and example

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 and example

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}

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}