Signal endpoints
API Reference guide for the Signal product
Endpoints | |
---|---|
/signal/evaluate | Retrieve Signal scores |
/signal/decision/report | Report whether you initiated an ACH transaction |
/signal/return/report | Report a return for an ACH transaction |
/signal/prepare | Add Signal to a newly linked item |
See also | |
---|---|
/processor/token/create | Create a token for using Signal with a processing partner |
/processor/signal/evaluate | Retrieve Signal scores as a processor partner |
/processor/signal/decision/report | Report whether you initiated an ACH transaction as a processor partner |
/processor/signal/return/report | Report a return for an ACH transaction as a processor partner |
/processor/signal/prepare | Prepare a processor token for Signal |
/signal/evaluate
Evaluate a planned ACH transaction
Use /signal/evaluate
to evaluate a planned ACH transaction to get a return risk assessment (such as a risk score and risk tier) and additional risk signals.
In order to obtain a valid score for an ACH transaction, Plaid must have an access token for the account, and the Item must be healthy (receiving product updates) or have recently been in a healthy state. If the transaction does not meet eligibility requirements, an error will be returned corresponding to the underlying cause. If /signal/evaluate
is called on the same transaction multiple times within a 24-hour period, cached results may be returned. For more information please refer to the error documentation on Item errors and Link in Update Mode.
Note: This request may take some time to complete if Signal is being added to an existing Item. This is because Plaid must communicate directly with the institution when retrieving the data for the first time.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_token
account_id
account_id
of the account that is the funding source for the proposed transaction. The account_id
is returned in the /accounts/get
endpoint as well as the onSuccess
callback metadata.This will return an
INVALID_ACCOUNT_ID
error if the account has been removed at the bank or if the account_id
is no longer valid.client_transaction_id
1
36
amount
102.05
)double
user_present
true
if the end user is present while initiating the ACH transfer and the endpoint is being called; false
otherwise (for example, when the ACH transfer is scheduled and the end user is not present, or you call this endpoint after the ACH transfer but before submitting the Nacha file for ACH processing).client_user_id
client_user_id
.is_recurring
true
if the ACH transaction is a recurring transaction; false
otherwisedefault_payment_method
SAME_DAY_ACH
: Same Day ACH by NACHA. The debit transaction is processed and settled on the same day
NEXT_DAY_ACH
: Next Day ACH settlement for debit transactions, offered by some payment processors
STANDARD_ACH
: standard ACH by NACHA
REAL_TIME_PAYMENTS
: real-time payments such as RTP and FedNow
DEBIT_CARD
: if the default payment is over debit card networks
MULTIPLE_PAYMENT_METHODS
: if there is no default debit rail or there are multiple payment methods
Possible values: SAME_DAY_ACH
, NEXT_DAY_ACH
, STANDARD_ACH
, REAL_TIME_PAYMENTS
, DEBIT_CARD
, MULTIPLE_PAYMENT_METHODS
user
/signal/evaluate
or /signal/processor/evaluate
, this field is optional, but strongly recommended to increase the accuracy of Signal results.name
prefix
given_name
middle_name
family_name
suffix
phone_number
email_address
device
/signal/evaluate
or /signal/processor/evaluate
, this field is optional, but strongly recommended to increase the accuracy of Signal results.ip_address
user_agent
ruleset_key
1const eval_request = {2 access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',3 account_id: '3gE5gnRzNyfXpBK5wEEKcymJ5albGVUqg77gr',4 client_transaction_id: 'txn12345',5 amount: 123.45,6 client_user_id: 'user1234',7 user: {8 name: {9 prefix: 'Ms.',10 given_name: 'Jane',11 middle_name: 'Leah',12 family_name: 'Doe',13 suffix: 'Jr.',14 },15 phone_number: '+14152223333',16 email_address: 'jane.doe@example.com',17 address: {18 street: '2493 Leisure Lane',19 city: 'San Matias',20 region: 'CA',21 postal_code: '93405-2255',22 country: 'US',23 },24 },25 device: {26 ip_address: '198.30.2.2',27 user_agent:28 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Mobile/15E148 Safari/604.1',29 },30 user_present: true,31};3233try {34 const eval_response = await plaidClient.signalEvaluate(eval_request);35 const core_attributes = eval_response.data.core_attributes;36 const scores = eval_response.data.scores;37} catch (error) {38 // handle error39}
Response fields and example
request_id
scores
customer_initiated _return_risk
score
1
99
risk_tier
In the
customer_initiated_return_risk
object, there are five risk tiers corresponding to the scores:
1: Predicted customer-initiated return incidence rate between 0.00% - 0.02%
2: Predicted customer-initiated return incidence rate between 0.02% - 0.05%
3: Predicted customer-initiated return incidence rate between 0.05% - 0.1%
4: Predicted customer-initiated return incidence rate between 0.1% - 0.5%
5: Predicted customer-initiated return incidence rate greater than 0.5%1
5
bank_initiated_return _risk
score
1
99
risk_tier
bank_initiated_return_risk
object, there are eight risk tiers corresponding to the scores:
1: Predicted bank-initiated return incidence rate between 0.0% - 0.5%
2: Predicted bank-initiated return incidence rate between 0.5% - 1.5%
3: Predicted bank-initiated return incidence rate between 1.5% - 3%
4: Predicted bank-initiated return incidence rate between 3% - 5%
5: Predicted bank-initiated return incidence rate between 5% - 10%
6: Predicted bank-initiated return incidence rate between 10% - 15%
7: Predicted bank-initiated return incidence rate between 15% and 50%
8: Predicted bank-initiated return incidence rate greater than 50%1
8
core_attributes
days_since_first_plaid_connection
: The number of days since the first time the Item was connected to an application via Plaid
plaid_connections_count_7d
: The number of times the Item has been connected to applications via Plaid over the past 7 days
plaid_connections_count_30d
: The number of times the Item has been connected to applications via Plaid over the past 30 days
total_plaid_connections_count
: The number of times the Item has been connected to applications via Plaid
is_savings_or_money_market_account
: Indicates whether the ACH transaction funding account is a savings/money market accountFor the full list and detailed documentation of core attributes available, or to request that core attributes not be returned, contact Sales or your Plaid account manager
ruleset
ruleset_key
is not provided, this field will be omitted. This feature is currently in closed beta; to request access, contact your account manager.ruleset_key
outcome
warnings
warning_type
warning_code
ITEM_LOGIN_REQUIRED
warning, we recommend re-authenticating your user by implementing Link's update mode. This will guide your user to fix their credentials, allowing Plaid to start fetching data again for future Signal requests.warning_message
1{2 "scores": {3 "customer_initiated_return_risk": {4 "score": 9,5 "risk_tier": 16 },7 "bank_initiated_return_risk": {8 "score": 72,9 "risk_tier": 710 }11 },12 "core_attributes": {13 "days_since_first_plaid_connection": 510,14 "plaid_connections_count_7d": 6,15 "plaid_connections_count_30d": 7,16 "total_plaid_connections_count": 15,17 "is_savings_or_money_market_account": false18 },19 "warnings": [],20 "request_id": "mdqfuVxeoza6mhu"21}
Was this helpful?
/signal/decision/report
Report whether you initiated an ACH transaction
After calling /signal/evaluate
(or /accounts/balance/get
, for participants in the Balance Plus beta), call /signal/decision/report
to report whether the transaction was initiated.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.client_transaction_id
client_transaction_id
supplied when calling /signal/evaluate
1
36
initiated
true
if the ACH transaction was initiated, false
otherwise.This field must be returned as a boolean. If formatted incorrectly, this will result in an
INVALID_FIELD
error.days_funds_on_hold
For example, use 0 if you make funds available to your customers instantly or the same day following the debit transaction, or 1 if you make funds available the next day following the debit initialization.
0
decision_outcome
APPROVE
: approve the transaction without requiring further actions from your customers. For example, use this field if you are placing a standard hold for all the approved transactions before making funds available to your customers. You should also use this field if you decide to accelerate the fund availability for your customers.REVIEW
: the transaction requires manual reviewREJECT
: reject the transactionTAKE_OTHER_RISK_MEASURES
: for example, placing a longer hold on funds than those approved transactions or introducing customer frictions such as step-up verification/authenticationNOT_EVALUATED
: if only logging the Signal results without using themPossible values:
APPROVE
, REVIEW
, REJECT
, TAKE_OTHER_RISK_MEASURES
, NOT_EVALUATED
APPROVE
, REVIEW
, REJECT
, TAKE_OTHER_RISK_MEASURES
, NOT_EVALUATED
payment_method
SAME_DAY_ACH
: Same Day ACH by NACHA. The debit transaction is processed and settled on the same dayNEXT_DAY_ACH
: Next Day ACH settlement for debit transactions, offered by some payment processorsSTANDARD_ACH
: standard ACH by NACHAREAL_TIME_PAYMENTS
: real-time payments such as RTP and FedNowDEBIT_CARD
: if the default payment is over debit card networksMULTIPLE_PAYMENT_METHODS
: if there is no default debit rail or there are multiple payment methodsPossible values:
SAME_DAY_ACH
, NEXT_DAY_ACH
, STANDARD_ACH
, REAL_TIME_PAYMENTS
, DEBIT_CARD
, MULTIPLE_PAYMENT_METHODS
SAME_DAY_ACH
, NEXT_DAY_ACH
, STANDARD_ACH
, REAL_TIME_PAYMENTS
, DEBIT_CARD
, MULTIPLE_PAYMENT_METHODS
amount_instantly _available
double
1const decision_report_request = {2 client_transaction_id: 'txn12345',3 initiated: true,4 days_funds_on_hold: 3,5};67try {8 const decision_report_response = await plaidClient.signalDecisionReport(9 decision_report_request,10 );11 const decision_request_id = decision_report_response.data.request_id;12} catch (error) {13 // handle error14}
Response fields and example
request_id
1{2 "request_id": "mdqfuVxeoza6mhu"3}
Was this helpful?
/signal/return/report
Report a return for an ACH transaction
Call the /signal/return/report
endpoint to report a returned transaction that was previously sent to the /signal/evaluate
or (for participants in the Balance Plus beta) the /accounts/balance/get
endpoint. Your feedback will be used by the model to incorporate the latest risk trend in your portfolio.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.client_transaction_id
client_transaction_id
supplied when calling /signal/evaluate
or /accounts/balance/get
.1
36
return_code
If formatted incorrectly, this will result in an
INVALID_FIELD
error.returned_at
YYYY-MM-DDTHH:mm:ssZ
).date-time
1const return_report_request = {2 client_transaction_id: 'txn12345',3 return_code: 'R01',4};56try {7 const return_report_response = await plaidClient.signalReturnReport(8 return_report_request,9 );10 const request_id = return_report_response.data.request_id;11 console.log(request_id);12} catch (error) {13 // handle error14}
Response fields and example
request_id
1{2 "request_id": "mdqfuVxeoza6mhu"3}
Was this helpful?
/signal/prepare
Opt-in an Item to Signal
When Link is not initialized with Signal, call /signal/prepare
to opt-in that Item to the Signal data collection process, developing a Signal score.
If run on an Item that is already initialized with Signal, this endpoint will return a 200 response and will not modify the Item.
client_id
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
secret
. The secret
is required and may be provided either in the PLAID-SECRET
header or as part of a request body.access_token
1const prepare_request = {2 client_id: '7f57eb3d2a9j6480121fx361',3 secret: '79g03eoofwl8240v776r2h667442119',4 access_token: 'access-sandbox-71e02f71-0960-4a27-abd2-5631e04f2175',5};67try {8 const prepare_response = await plaidClient.signalPrepare(prepare_request);9 const request_id = prepare_response.data.request_id;10 console.log(request_id);11} catch (error) {12 // handle error13}
Response fields and example
request_id
1{2 "request_id": "mdqfuVxeoza6mhu"3}