AUTH_STATUS

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 keyData description
auth_statusThe auth status the pull is currently in. Possible values: NOT_AUTHENTICATED, IDENTITY_VERIFICATION_OPTIONS, IDENTITY_VERIFICATION, SUCCESS
login_error_messageIncluded 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 tags).
mfa_optionsIncluded 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_typeIncluded in IDENTITY_VERIFICATION. Possible values: CARRIER_PIN, EMAIL_OTP, SMS_OTP, SECURITY_QUESTION, OTHER_OTP, VOICE_OTP
mfa_input_displayIncluded 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>)