This event is triggered when a Pull transitions to a new authentication state. The webhook request body includes a sequence value. The sequence value is an incrementing number that you can use to avoid issues when webhook requests arrive out of order over the network. The sequence number will always go up by at least one for each authentication state change that occurs on a Pull. When designing your user interface, you only need to go "backwards" when hitting a status that requires user input. Those statuses are NOT_AUTHENTICATED, IDENTITY_VERIFICATION_OPTIONS and IDENTITY_VERIFICATION.
Read the auth_status value from the webhook request body.
- If
NOT_AUTHENTICATED: Prompt end-user to submit carrier login - If
IDENTITY_VERIFICATION_OPTIONS: Prompt end-user to select an identity verification method from one of the available options returned in the webhook request body - If
IDENTITY_VERIFICATION: Prompt end-user to submit their 2-factor authentication code - If
SUCCESS: You can exit the flow now if your application processes insurance information in the background.
Webhook Request Format
The webhook is a POST request with a JSON body that will look like the following, based on the auth_status:
NOT_AUTHENTICATED
With the default bad credentials error:
{
"widget_id": "<WIDGET_ID>",
"team_id": "<TEAM_ID>",
"pull_id": "<PULL_ID>",
"status": "NOT_AUTHENTICATED",
"meta_data": {... developer-supplied JSON-serializable metadata ...},
"event_type": "AUTH_STATUS",
"account_identifier": "<ACCOUNT_IDENTIFIER>",
"data": {
"auth_status": "NOT_AUTHENTICATED",
// Show your default, bad credentials error message
"login_error_message": null,
}
}With a carrier specific credentials error:
{
"widget_id": "<WIDGET_ID>",
"team_id": "<TEAM_ID>",
"pull_id": "<PULL_ID>",
"status": "NOT_AUTHENTICATED",
"meta_data": {... developer-supplied JSON-serializable metadata ...},
"event_type": "AUTH_STATUS",
"account_identifier": "<ACCOUNT_IDENTIFIER>",
"data": {
"auth_status": "NOT_AUTHENTICATED",
// Parse and show this html text as the error message (will only contain <a> tags)
"login_error_message": "Please login to Carrier Name at <a href=\"https://www.sandboxcarrier.com\">www.sandboxcarrier.com</a> to unlock your account, then come back to try again.",
}
}IDENTITY_VERIFICATION_OPTIONS
{
"widget_id": "<WIDGET_ID>",
"team_id": "<TEAM_ID>",
"pull_id": "<PULL_ID>",
"status": "IDENTITY_VERIFICATION_OPTIONS",
"meta_data": {... developer-supplied JSON-serializable metadata ...},
"event_type": "AUTH_STATUS",
"account_identifier": "<ACCOUNT_IDENTIFIER>",
"data": {
"auth_status": "IDENTITY_VERIFICATION_OPTIONS",
// Display each value to the user exactly as provided — these are ready-to-show labels.
// The keys and the label text/format vary by carrier, so don't hardcode or assume a fixed set.
"mfa_options": {
"email": "Email [email protected]",
"sms0": "Text 111-222-3333",
"sms1": "Text 222-333-4444",
"voice": "Call 111-222-3333",
"securityQuestion": "Answer Security Question",
"pin": "Use my PIN",
"token": "Use my Carrier Mobile App"
},
}
}IDENTITY_VERIFICATION
{
"widget_id": "<WIDGET_ID>",
"team_id": "<TEAM_ID>",
"pull_id": "<PULL_ID>",
"status": "IDENTITY_VERIFICATION",
"meta_data": {... developer-supplied JSON-serializable metadata ...},
"event_type": "AUTH_STATUS",
"account_identifier": "<ACCOUNT_IDENTIFIER>",
"data": {
"auth_status": "IDENTITY_VERIFICATION",
"mfa_input_type": "EMAIL_OTP",
"mfa_input_display": "[email protected]",
}
}SUCCESS
{
"widget_id": "<WIDGET_ID>",
"team_id": "<TEAM_ID>",
"pull_id": "<PULL_ID>",
"status": "GETTING_CONSUMERS", // May also be PULLING_DATA
"meta_data": {... developer-supplied JSON-serializable metadata ...},
"event_type": "AUTH_STATUS",
"account_identifier": "<ACCOUNT_IDENTIFIER>",
"data": {
"auth_status": "SUCCESS",
}
}| Data key | Data description |
|---|---|
| auth_status | The auth status the pull is currently in. Possible values: NOT_AUTHENTICATED, IDENTITY_VERIFICATION_OPTIONS, IDENTITY_VERIFICATION, SUCCESS |
| login_error_message | Included in NOT_AUTHENTICATED. If nil, show your default bad credentials login error message. Otherwise, if defined, parse the html text and display it to the user as the error message (Would only contain <a> tags). |
| mfa_options | Included in IDENTITY_VERIFICATION_OPTIONS. An object where each key is the option identifier and each value is a user-friendly label. Display each value to the user exactly as provided — the labels are dynamic and generated per-carrier, so both the set of keys and the text/format of the values vary by carrier and should not be hardcoded or assumed to be consistent across carriers. In most cases the label also includes the destination it will be sent to, e.g. "Text 111-222-3333" or "Email [email protected]". Show these options to the user and allow them to select one; the option identifier (key) for the option the user selects is sent as the optionKey to POST /idvoptions. |
| mfa_input_type | Included in IDENTITY_VERIFICATION. Possible values: CARRIER_PIN, EMAIL_OTP, SMS_OTP, SECURITY_QUESTION, OTHER_OTP, VOICE_OTP |
| mfa_input_display | Included in IDENTITY_VERIFICATION.If mfa_input_type is OTHER_OTP this display value should be shown as the prompt with no additional text.For all other mfa_input_type's:
|