On-Demand Step-Ups

July 22, 2026 21:44

Step-ups automatically trigger based on risk assessments. With the introduction of on-demand step-ups, customers can pause their authentication strategy after rules execution and invoke specific step-up methods explicitly via the API.

Prerequisites

In order to integrate, Equifax provides you with the following:

A Client ID that is the same for both sandbox and production environments.
A strategy name that can be the same for both sandbox and production, or different if needed.
Either an API key or access to the Kount 360 portal to get it (this key is different for sandbox and production).

The strategy is configured with one or more step-up methods:

EMAIL/SMS OTH - Kount 360 drives verification and informs completion via webhook.
Document Verification - Kount 360 drives verification and informs completion via webhook.
EMAIL/SMS OTP - Client driven verification or Kount 360 drives verification and informs completion via webhook.
Knowledge Based Authentication (KBA) - Client driven verification.

Strategies can be set up with the following options:

Step-up On Demand set ON. It This pauses the authentication strategy after rules execution. Configured step-up methods run only when explicitly invoked via the API.
MFA Waterfall set OFF. In this instance, the platform does not automatically attempt running the next method configured if the step-up fails.

Flow

Equifax goes through the following steps to set up this functionality:

Authentication
Assessment (to get trusted channels)
Run OTP, OTH, Document Verification, or Knowledge Based Authentication (KBA). One or more of these can be run as needed.

Authentication—bearer token API

Before calling any functional Equifax APIs, you must use your static credentials to obtain a temporary bearer token. This allows you to authenticate and authorize all subsequent requests to the Kount 360 API environment.

To obtain the token, you must perform an HTTP POST request to the authentication server, exchanging your Client ID and API key for an access_token. The tokens are valid for 20 minutes.

Example

curl --request POST \
  --url 'https://login-uat.equifax.com/as/token?grant_type=client_credentials&scope=k1_integration_api' \
  --header 'authorization: Basic <API KEY>' \
  --header 'content-type: application/x-www-form-urlencoded'

Assessment

The assessment is the initial evaluation of all provided personally Identifiable Information (PII). The response includes a decision, tags, and insights.

Depending on the environment, the request is sent to one of the following URLs:

Sandbox: https://api-sandbox.kount.com/business/identity-proofing/v1/assess
Production: https://api.kount.com/business/identity-proofing/v1/assess

Request header code example

Authorization: Bearer {{TOKEN-FROM-PINGID}}
Content-Type: application/json
X-Client-ID: {{CLIENT-ID from Kount360}}

Request body code example

{
  "inquiryId": "TEST-00001",
  "strategy": "<STRATEGY-NAME>",
  "channel": "My Portal",
  "creationDateTime": "",
  "deviceSessionId": "110a9bf3c9744aaaa311d9b1629f0d67",
  "userIp": "10.102.12.11",
  "applicant": {
    "name": {
      "first": "John",
      "middle": "",
      "last": "Doe",
      "secondLast": "",
      "suffix": "",
      "preferred": ""
    },
    "dateOfBirth": "1982-01-25",
    "email": "john@gmail.com",
    "phoneNumber": "99999999999",
    "addresses": [
      {
        "type": "HOME",
        "line1": "1435 Windward Concourse",
        "line2": "",
        "city": "Alpharetta",
        "region": "GA",
        "countryCode": "US",
        "postalCode": "30009"
      }
    ],
    "governmentId": [
      {
        "type": "SSN",
        "value": "999999999",
        "countryCode": "US",
        "state": "",
        "issuedDate": "",
        "expirationDate": ""
      }
    ],
    "employment": [
      {
        "employer": {
          "name": "Equifax",
          "address": {
            "type": "BUSINESS",
            "line1": "1550 Peachtree St NE",
            "line2": "",
            "city": "Atlanta",
            "region": "GA",
            "countryCode": "US",
            "postalCode": "30309"
          }
        },
        "employeeTitle": "Software Engineer",
        "startDate": "2019-08-24",
        "endDate": "",
        "currentEmployee": true,
        "contractType": "FULL_TIME"
      }
    ],
    "income": {
      "period": "ANNUAL",
      "amount": 10000
    }
  },
  "customFields": {
    "field1": "x",
    "fieldx": true,
    "other": 199
  },
  
  "product": {
    "productName": "Credit Card X"
  }
}

Response body code example

{
  "inquiryId": "TEST-000001",
  "authenticationId": "715dd6db-abba-4eea-be17-dac40f2e5f6a",
  "deviceSessionId": "110a9bf3c9744aaaa311d9b1629f0d67",
  "decision": "Challenge",
  "userSegment": "Demo",
  "tags": [
    "phoneTrust",
    "emailTrust"
  ],
  "scoreCards": [
    {
      "name": "phoneTrust",
      "description": "",
      "segmentCount": 0,
      "policyCount": 0,
      "weight": 0,
      "activeSegmentCount": 0,
      "activePolicyCount": 0
    }
  ],
  "entityId": "",
  "insights": {
    "coApplicant": null,
    "identityVerification": {
      "identityTrust": "N",
      "identityVerification": "N",
      "identityVerificationReason": "identityNoMatch,lastNameNoMatch,firstNameNoMatch",
      "identityResolution": "N",
      "identityResolutionReason": "identityLowCorroboration",
      "identityRisk": "N",
      "identityRiskReason": "identityRiskLow",
      "phoneTrust": "N",
      "phoneVerification": "N",
      "phoneVerificationReason": "Unverifiable",
      "phoneAffiliation": "N",
      "phoneAffiliationReason": "AffiliationNotConfirmed",
      "phoneInsights": "Y",
      "phoneInsightsReason": "NoInsightsReturned",
      "emailTrust": "N",
      "emailVerification": "N",
      "emailVerificationReason": "emailUnknown",
      "emailAffiliation": "N",
      "emailAffiliationReason": "AffiliationNotConfirmed",
      "emailInsights": "Y",
      "emailInsightsReason": "NoInsightsReturned",
      "SSNTrust": "N",
      "SSNVerification": "Y",
      "SSNVerificationReason": "SSN Found",
      "SSNAffiliation": "N",
      "SSNAffiliationReason": "No SSN Affiliation",
      "SSNInsights": "Y",
      "SSNInsightsReason": "",
      "addressTrust": "N",
      "addressVerification": "Y",
      "addressVerificationReason": "addressValid",
      "addressAffiliation": "N",
      "addressAffiliationReason": "addressPhoneNoMatch,addressEmailNoMatch,addressNameNoMatch,addressNoMatch",
      "addressInsights": "Y",
      "addressInsightsReason": "NoInsightsReturned",
      "dobTrust": "N",
      "dobVerification": "N",
      "dobVerificationReason": "DOB Not Verified",
      "dobAffiliation": "N",
      "dobAffiliationReason": "No Data Found",
      "dobInsights": "Y",
      "dobInsightsReason": "DOB > 20",
      "deceased": "N",
      "riskAssessment": "Fail"
    },
    "regulatoryPackage": {}
  },
  "strategy": null,
  "errorResponses": {
    "deviceSignalErrorResponse": "activity timeout reached",
    "hashingErrorResponse": "activity timeout reached",
    "stepupErrorResponse": "stepup service invocation is skipped due to configuration"
  },
  "applicantCustomerIdentifier": "N9FcDXSos2iOL3JT1Ky9BK05aLSbjKiexzrya/pFnzE=",
  "coApplicantCustomerIdentifier": ""
}

Run OTP, OTH, or Document Verification

One-time passcode (OTP), one-time hyperlink (OTH), and Document Verification are initiated the same way, but the verification is different:

The OTP result is provided in the API response when the personal identification number (PIN) is sent via API.
The OTP result is provided via webhook event if Kount 360 is configured to host the PIN input page.
When the OTH is complete, Kount 360 delivers a webhook event.
Document Verification is initiated as an OTH with a Document Verification link. When completed, Kount 360 delivers a webhook event.

Independent to the decision outcome, you can initiate any configured step-up method in any order. The following example shows OTP being run:

Initiate OTP_SMS (or EMAIL) the first time example

POST /business/step-up/v1/verify HTTP/1.1
Content-Type: application/json
X-Client-Id: <<Client ID>>
Content-Type: application/json
Host: api-sandbox.kount.com
Content-Length: 251
{
  "inquiryId": "{{inquiryId}}",
  "authenticationId":"{{authId}}",
  "strategy": {
    "strategyName": "AnytimeStrategy",
    "actions": [
      {
        "method": "OTP_SMS",  //KBA or OTH_SMS (for OTH only or Document Verification)
        "data": {
          "resend": false
        }
      }`
    ]
  }
}

Initiate OTP_SMS a second time example

POST /business/step-up/v1/verify HTTP/1.1
Content-Type: application/json
X-Client-Id: <<Client ID>>
Content-Type: application/json
Host: api-sandbox.kount.com
Content-Length: 251

{
  "inquiryId": "{{inquiryId}}",
  "authenticationId":"{{authId}}",
  "strategy": {
    "strategyName": "AnytimeStrategy",
    "nextAction": true, //This forces running the second method
    "actions": [
      {
        "method": "OTP_SMS",
        "data": {
          "resend": false
        }
      }
    ]
  }
}

Verify OTP_SMS example

POST /business/step-up/v1/verify HTTP/1.1
Content-Type: application/json
X-Client-Id: <<Client ID>>
Content-Type: application/json
Host: api-sandbox.kount.com
Content-Length: 277

{
  "inquiryId": "{{inquiryId}}",
  "authenticationId":"{{authId}}",
  "strategy": {
    "strategyName": "AnytimeStrategy",
    "actions": [
      {
        "method": "OTP_SMS",
        "data": {
          "otp": "443119"
        }
      }
    ]
  }
}

Run KBA

After requesting the knowledge based authorization (KBA) method, the API returns the questionnaire to be offered to the final user and get their responses.

KBA request example

POST /business/step-up/v1/verify HTTP/1.1
Content-Type: application/json
X-Client-Id: <<Client ID>>
Content-Type: application/json
Host: api-sandbox.kount.com
Content-Length: 296

{
  "inquiryId": "{{inquiryId}}",
  "authenticationId":"{{authId}}",
  "strategy": {
    "strategyName": "AnytimeStrategy",
    "nextAction": true,
    "actions": [
      {
        "method": "KBA",
        "data": {
          "resend": false
        }
      }
    ]
  }
}

KBA response example

{
  "inquiryId": "{{inquiryId}}",
  "authenticationId":"{{authId}}",
  "decision": "Challenge",
  "strategy": {
    "strategyName": "AnytimeStrategy",
    "description": "",
    "status": "active",
    "actions": [
      {
        "method": "OTH_SMS",
        "status": "TERMINATED"
      },
      {
        "method": "KBA",
        "status": "challenge",
        "data": {
          "questionnaireId": 1,
          "questions": [
            {
              "questionId": 1,
              "questionText": "Your credit file indicates you may have a mortgage loan, opened in or around December 2020. Who is the credit provider for this account?",
              "choiceType": {
                "type": "SINGLE_CHOICE"
              },
              "choices": [
                {
                  "choiceId": 1,
                  "choiceText": "Business 01"
                },
                {
                  "choiceId": 2,
                  "choiceText": "Business 02"
                },
                {
                  "choiceId": 3,
                  "choiceText": "Business 03"
                },
                {
                  "choiceId": 4,
                  "choiceText": "Business 04"
                },
                {
                  "choiceId": 5,
                  "choiceText": "NONE OF THE ABOVE"
                }
              ]
            },
            {
              "questionId": 2,
              "questionText": "What is the total monthly payment for the above-referenced account?",
              "choiceType": {
                "type": "SINGLE_CHOICE"
              },
              "choices": [
                {
                  "choiceId": 1,
                  "choiceText": "$580 - $679"
                },
                {
                  "choiceId": 2,
                  "choiceText": "$680 - $779"
                },
                {
                  "choiceId": 3,
                  "choiceText": "$780 - $879"
                },
                {
                  "choiceId": 4,
                  "choiceText": "$880 - $979"
                },
                {
                  "choiceId": 5,
                  "choiceText": "NONE OF THE ABOVE"
                }
              ]
            },
            {
              "questionId": 3,
              "questionText": "Your credit file indicates you may have an auto loan/lease, opened in or around February 2024. Who is the credit provider for this account?",
              "choiceType": {
                "type": "SINGLE_CHOICE"
              },
              "choices": [
                {
                  "choiceId": 1,
                  "choiceText": "Business 01"
                },
                {
                  "choiceId": 2,
                  "choiceText": "Business 02"
                },
                {
                  "choiceId": 3,
                  "choiceText": "Business 03"
                },
                {
                  "choiceId": 4,
                  "choiceText": "Business 04"
                },
                {
                  "choiceId": 5,
                  "choiceText": "NONE OF THE ABOVE"
                }
              ]
            },
            {
              "questionId": 4,
              "questionText": "What is the total monthly payment for the above-referenced account?",
              "choiceType": {
                "type": "SINGLE_CHOICE"
              },
              "choices": [
                {
                  "choiceId": 1,
                  "choiceText": "$516 - $565"
                },
                {
                  "choiceId": 2,
                  "choiceText": "$566 - $615"
                },
                {
                  "choiceId": 3,
                  "choiceText": "$616 - $665"
                },
                {
                  "choiceId": 4,
                  "choiceText": "$666 - $715"
                },
                {
                  "choiceId": 5,
                  "choiceText": "NONE OF THE ABOVE"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

KBA verification example

POST /business/step-up/v1/verify HTTP/1.1
Content-Type: application/json
X-Client-Id: <<Client ID>>
Content-Type: application/json
Host: api-sandbox.kount.com
Content-Length: 642

{
  "inquiryId": "{{inquiryId}}",
  "authenticationId":"{{authId}}",
  "strategy": {
    "strategyName": "AnytimeStrategy",
    "actions": [
      {
        "method": "KBA",
        "data": {
          "questions": [
            {
              "questionId": 1,
              "answer": [
                5
              ]
            },
            {
              "questionId": 2,
              "answer": [
                5
              ]
            },
            {
              "questionId": 3,
              "answer": [
                5
              ]
            }
          ]
        }
      }
    ]
  }
}

Was this article helpful?

0 out of 0 found this helpful