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.",
  }
}

📘
How to parse login_error_message
We recommend using a library like dompurify to parse the login_error_message value and set the target="_blank" & rel="noopener noreferrer". Here is an example of parsing and setting the login_error_message.

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",
    "mfa_options": { // The mfa options that should be displayed to the user to allow for a selection to be made
      "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`. Is an object where the key is the option identifier and the value is the option text. These options should be shown to the user and allow them to select one option. The option identifier for option selected by the user will be 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: If this display value is nil, show a default prompt based on the input type (Ie: EMAIL_OTP default could be "Enter the MFA code sent to your email"; CARRIER_PIN default could be "Enter your <carrier_name> pin") If this display value is defined, use it within the prompt (Ie: EMAIL_OTP could be "Enter the MFA code emailed to <mfa_input_display>"; SMS_OTP could be "Enter the MFA code texted to <mfa_input_display>)

Webhook Request Format

How to parse login_error_message

How to parse `login_error_message`