1. Identity and Fraud Developer
  2. Kount 360
  3. Consumer Insights
Quick Links

Consumer Insights v1.0 Integration Guide

Get actionable insights into consumer behavior by integrating with Kount Consumer Insights, built on the Kount 360 platform. Integrate to gain access to the REST API endpoint, view your account in the portal, manage users, and more.

Note

Go to Consumer Insights v2.0 Integration Guide if you are using V2 of the Consumer Insights API.

Generate an API Key

In Kount 360, after you have activated your organization, you can generate API keys to send data securely to Equifax. Only users with the Owner role permissions can generate, delete, or edit API keys.

Caution

You must have an initialized client before you can create an API key.

  1. Sign in to Kount 360.

    There are two integration environments: sandbox and production. Only integrate into our sandbox environment if you are integrating a pre-production environment without production data for testing.

  2. Select Admin, and then Product Configuration.

  3. In System Settings, select API Keys.

    All initialized clients display.

  4. For the client you want to create an API key, select Generate API Key.

    The new API key is generated. A prompt displays with the ability to copy the API key and add a description.

  5. Copy the API key, and then store it in a secure location.

    Note

    The API key is not provided again. You must store it in a secure location for future reference. If the API key is compromised or lost, create a new API key and delete the compromised one.

  6. Enter a description detailing the store used for the API key, and then select Confirm.

API keys are organized under each client on the API Keys page. Expand the client to view your API keys, the descriptions, and when client details were created.

Create a Bearer Token

After you have provisioned your API credentials in the portal, retrieve a temporary bearer token to authenticate calls to the Kount 360 API. Provide the API key in an HTTP POST to a specific login.equifax.com URL.

With a successful exchange, the returned JSON provides a special bearer token, which is the access_token property. The exchange also provides an expiration date, the expires_in property, provided in seconds until expiration. The API to retrieve the bearer token depends on if you are calling the sandbox or production environment.

The values are:

Sandbox

Auth Server URL:

https://login-uat.equifax.com/as/token

API Service Host:

https://api-sandbox.kount.com

Production

Auth Server URL:

https://login.equifax.com/as/token

API Service Host:

https://api.kount.com

After obtaining the bearer token, use it to authenticate requests to the Kount 360 API. Include the token in the Authorization header of your HTTP API request, prefixed with Bearer {bearer token}.

To prevent authentication issues, refresh the token before it expires. Tokens issued by login.equifax.com expire after 20 minutes, but client credentials remain valid unless revoked. Minimize calls to the /token endpoint by implementing token expiration handling in your customer applications. Always check if a token has expired before requesting a new one, as excessive calls to the /token endpoint could result in rate limiting.

Python

Python Code Example

"""sandbox"""
import requests
AUTH_SERVER_URL = "https://login-uat.equifax.com/as/token"
API_URL = "https://api-sandbox.kount.com"
API_KEY = "YOUR API KEY HERE"
CLIENT_ID = "YOUR CLIENT_ID HERE"

r = requests.post(AUTH_SERVER_URL,
                  params={"grant_type": "client_credentials",
                          "scope": "k1_integration_api"},
                  headers={"Authorization": "Basic" + API_KEY,
                           "Content-Type":
                           "application/x-www-form-urlencoded"})

t = r.json()["access_token"]

r = requests.post(API_URL + "/identity/evaluate/v1",
                  headers={'Authorization': "Bearer " + t},
                  json={
                      "clientId": CLIENT_ID,
                      "useCase": "fraudInsights,walletInsights",
                      "firstName": "John",
                      "lastName": "Doe",
                      "deviceId": "0123456789ABCDEF0000000000000000",
                      "address": {
                          "line1": "1600 Pennsylvania Ave NW",
                          "line2": "",
                          "city": "Washington",
                          "state": "DC",
                          "countryCode": "US",
                          "postalCode": "20500",
                      },
                      "emailAddress": "john.doe@kount.com",
                      "phoneNumber": "2088675309",
                      "payment": {
                          "paymentToken": "4242424242424242",
                          "paymentType": "CARD"
                      }
                  })
print("Response:", r.json())

Bash

Bash Code Example

#!/usr/bin/env bash

API='https://api-sandbox.kount.com'
ISSUER='https://login-uat.equifax.com/as/token'
CLIENT_ID='<Your client ID here!>'
API_KEY='<Your client credentials here!>'

# Get our token (it is valid for 20 minutes)
RESPONSE=$(curl -s -X POST "${ISSUER}/v1/token?grant_type=client_credentials&scope=k1_integration_api" -H "Authorization: Basic ${API_KEY}" -H "Content-Type: application/x-www-form-urlencoded")
TOKEN=$(echo $RESPONSE | jq -r .access_token)

# Make our evaluation request
REQUEST_DATA="{ \"clientId\": \"$CLIENT_ID\", \"useCase\": \"fraudInsights,walletInsights\", \"firstName\": \"John\", \"lastName\": \"Doe\", \"deviceId\": \"0123456789ABCDEF0000000000000000\", \"address\": { \"line1\": \"1600 Pennsylvania Ave NW\", \"line2\": \"\", \"city\": \"Washington\", \"state\": \"DC\", \"countryCode\": \"US\", \"postalCode\": \"20500\" }, \"emailAddress\": \"john.doe@kount.com\", \"phoneNumber\": \"2088675309\", \"payment\": { \"paymentToken\": \"4242424242424242\", \"paymentType\": \"CARD\" } }"
RESPONSE=$(curl -s -X POST ${API}/identity/evaluate/v1 -H "Authorization: Bearer ${TOKEN}" -d "$REQUEST_DATA")
echo "$RESPONSE" | jq

TypeScript

TypeScript Code Example

const axios = require('axios')

const API = 'https://api-sandbox.kount.com'
const ISSUER = 'https://login-uat.equifax.com/as/token'
const CLIENT_ID = 'YOUR CLIENT ID HERE'
const API_KEY = 'YOUR API KEY HERE'

async function getBearerToken() {

    const auth = await axios({
        url: `${ISSUER}/v1/token`,
        method: 'post',
        headers: {
            'authorization': `Basic ${API_KEY}`,
            'Content-Type': 'application/x-www-form-urlencoded'
        },
        params: {
            'grant_type': 'client_credentials',
            'scope': 'k1_integration_api'
        }
    })

    return auth.data.access_token
}

async function evaluateIdentity(token: string) {

    const resp = await axios({
        url: `${API}/identity/evaluate/v1`,
        method: 'post',
        headers: {
            authorization: `Bearer ${token}`,
        },
        data: {
            clientId: CLIENT_ID,
            useCase: "fraudInsights,walletInsights",
            firstName: "John",
            lastName: "Doe",
            deviceId: "0123456789ABCDEF0000000000000000",
            address: {
                line1: "1600 Pennsylvania Ave NW",
                line2: "",
                city: "Washington",
                state: "DC",
                countryCode: "US",
                postalCode: "20500",
            },
            emailAddress: "john.doe@kount.com",
            phoneNumber: "2088675309",
            payment: {
                paymentToken: "4242424242424242",
                paymentType: "CARD"
            }
        }
    })

    return resp.data
}
const main = async () => {
    const token = await getBearerToken();
    const resp = await evaluateIdentity(token);
    console.log(JSON.stringify(resp, null, 4))
}

main()

Go

Go Code Example

package main
import (
        "bytes"
        "encoding/json"
        "fmt"
        "io"
        "net/http"
)
type config struct {
        API      string
        Issuer   string
        ClientId string
        APIKey   string
}
func getToken(c *http.Client, issuer, creds string) string {
        req, _ := http.NewRequest(http.MethodPost, issuer+"/v1/token", nil)
        req.Header.Add("Authorization", "Basic "+creds)
        req.Header.Add("Content-Type", "application/x-www-form-urlencoded")
        q := req.URL.Query()
        q.Add("grant_type", "client_credentials")
        q.Add("scope", "k1_integration_api")
        req.URL.RawQuery = q.Encode()
        resp, _ := c.Do(req)
        defer resp.Body.Close()
        t := struct {
                TokenType   string `json:"token_type"`
                ExpiresIn   int    `json:"expires_in"`
                AccessToken string `json:"access_token"`
        }{}
        json.NewDecoder(resp.Body).Decode(&t)
        return t.AccessToken
}
func evaluate(c *http.Client, api string, payload IdentityEvalRequest, token string) string {
        j, _ := json.Marshal(payload)
        req, _ := http.NewRequest(http.MethodPost, api+"/identity/evaluate/v1", bytes.NewBuffer(j))
        req.Header.Add("Authorization", "Bearer "+token)
        resp, _ := c.Do(req)
        defer resp.Body.Close()
        b, _ := io.ReadAll(resp.Body)
        s := string(b)
        return s
}
type IdentityEvalRequest struct {
        ClientId     string         `json:"clientId"`
        UseCase      string         `json:"useCase"`
        FirstName    string         `json:"firstName"`
        LastName     string         `json:"lastName"`
        DeviceId     string         `json:"deviceId"`
        Address      AddressRequest `json:"address"`
        EmailAddress string         `json:"emailAddress"`
        PhoneNumber  string         `json:"phoneNumber"`
        Payment      PaymentRequest `json:"payment"`
}
type AddressRequest struct {
        Line1       string `json:"line1"`
        Line2       string `json:"line2"`
        City        string `json:"city"`
        State       string `json:"state"`
        CountryCode string `json:"countryCode"`
        PostalCode  string `json:"postalCode"`
}
type PaymentRequest struct {
        PaymentToken string `json:"paymentToken"`
        PaymentType  string `json:"paymentType"`
}
func main() {
        config := config{
                API:      "https://api-sandbox.kount.com",
                Issuer:   "https://login-uat.equifax.com/as/token",
                ClientId: "<Your client ID here!>",
                APIKey:   "<Your client credentials here!>",
        }
        client := &http.Client{}
        token := getToken(client, config.Issuer, config.APIKey)
        payload := IdentityEvalRequest{
                ClientId:  config.ClientId,
                UseCase:   "fraudInsights,walletInsights",
                FirstName: "John",
                LastName:  "Doe",
                DeviceId:  "0123456789ABCDEF0000000000000000",
                Address: AddressRequest{
                        Line1:       "1600 Pennsylvania Ave NW",
                        Line2:       "",
                        City:        "Washington",
                        State:       "DC",
                        CountryCode: "US",
                        PostalCode:  "20500",
                },
                EmailAddress: "john.doe@kount.com",
                PhoneNumber:  "2088675309",
                Payment: PaymentRequest{
                        PaymentToken: "4242424242424242",
                        PaymentType:  "CARD",
                },
        }
        resp := evaluate(client, config.API, payload, token)
        fmt.Printf("%s\n", resp)
}

Specifications for the Consumer Insights v1.0 API

Endpoints:

Sandbox

api-sandbox.kount.com/identity/evaluate/v1

Production

api.kount.com/identity/evaluate/v1

Method: POST

Header Authorization: Bearer <token>

Header Content-Type: application/json

Note

All data sent to Kount with the upload API must be in a JSON string format that is capable of parsing back to JSON. See the Standard Request Data Elements table for additional information.

Standard Request Data Elements Table

Attribute

Type

Parameters

Description

Required/Optional

clientId

string (clientId) ^[a-zA-Z0-9]{1,64}$

Kount's unique identifier for a Client

Required

usecase

string

Use Case determines response payload (can be any comma-separated combination of payerInsights, walletInsights, fraudInsights, inputvalidation)

Required

deviceId

string (deviceId) ^[\w-]{0,64}$

Device identifier

Optional

phoneNumber

string (phoneNumber)

Phone number for a Client’s user

Optional

emailAddress

string <email> (emailAddress) ^.+@.+\..+$

Email address for a Client’s user

Optional

firstName

string (firstName)

First name for a Client’s user

Optional

lastName

string (lastName)

Last name for a Client’s user

Optional

address

object (v1Address)

Optional

line1

string (line1) ^[\w-]{0,256}$

Street address - Line 1

Optional

line2

string (line2) ^[\w-]{0,256}$

Street address - Line 2

Optional

city

string (city) ^[\w-]{0,256}$

Street address - City

Optional

state

string (state) ^[\w-]{0,256}$

Street address - State/Province

Optional

postalCode

string (postalCode) ^[\w-]{0,20}$

Street address - Postal Code

Optional

plus4

string (plus4) ^[\w-]{0,4}$

Street address - Last 4 Digits of a full 9-Digit US Postal code

Optional

countryCode

string (countryCode) ^[A-Z]{0,2}$

Street address - Country

Optional

payment

object (v1Payment)

Optional

paymentType

string (paymentType) ^[A-Z_]{1,12}$

Enum: "APAY" "CARD" "PYPL" "CHEK" "NONE" "TOKEN" "GDMP" "GOOG""BLML" "GIFT" "BPAY" "NETELLER" "GIROPAY" "ELV" "MERCADE_PAGO""SEPA" "INTERAC" "CARTE_BLEUE" "POLI" "SKRILL" "SOFORT" "AMZN""SAMPAY" "ALIPAY" "WCPAY" "CRYPTO" "KLARNA" "AFTRPAY" "AFFIRM""SPLIT" "FBPAY"

Optional

paymentToken

string (paymentToken) ^[\w-]{0,64}$

Payment token submitted by merchant for order (credit card, payer ID, routing/transit, MIC`R, and account number).

Optional

Receive data from Consumer Insights

For additional support, review the API help documentation. Expand each section to review the responses available and associated fields.

JSON Payload Example

Request:
{
   "clientId": "${CLIENT_ID}",
   "useCase": "fraudInsights,walletInsights,payerInsights,inputValidation",
   "firstName": "John",
   "lastName": "Doe",
   "address": {
       "line1": "1600 Pennsylvania Ave NW",
       "city": "Washington",
       "state": "DC",
       "countryCode": "US",
       "postalCode": "20500"
   },
   "emailAddress": "john.doe@kount.com",
   "phoneNumber": "2088675309",
   "payment": {
       "paymentToken": "4242424242424242",
       "paymentType": "CARD"
   }
}
Response:
{
   "fraudInsights": {
       "attributes": {
           "chargebackRatio": 0,
           "chargebacks": 0,
           "dateFirstSeen": "1334352061",
           "dateLastSeen": "1650475877",
           "daysSinceFirstSeen": 4015,
           "daysSinceLastSeen": 356,
           "declineAuthRatio": 0,
           "declineNonAuthRatio": 0,
           "declinesAuth": 0,
           "declinesNonAuth": 0,
           "distinctBillAddresses": 5,
           "distinctBillCities": 2,
           "distinctBillCountryCodes": 2,
           "distinctBillEmails": 5,
           "distinctBillNames": 6,
           "distinctBillPhones": 3,
           "distinctBillPostalCodes": 5,
           "distinctBillStates": 2,
           "distinctBins": 4,
           "distinctCurrencies": 1,
           "distinctDates": 20,
           "distinctDays": 6,
           "distinctIpAddresses": 9,
           "distinctLatLons": 5,
           "distinctMerchantIds": 12,
           "distinctMonths": 19,
           "distinctPaymentTokens": 4,
           "distinctPaymentTypes": 4,
           "distinctQuarters": 16,
           "distinctShipAddresses": 8,
           "distinctShipCities": 2,
           "distinctShipCountryCodes": 2,
           "distinctShipEmails": 3,
           "distinctShipNames": 3,
           "distinctShipPhones": 4,
           "distinctShipPostalCodes": 6,
           "distinctShipStates": 2,
           "distinctWeeks": 20,
           "distinctYears": 9,
           "occurrence": 24,
           "occurrence30Days": 0,
           "occurrenceMostCommonBillAddress": 12,
           "occurrenceMostCommonBillCity": 19,
           "occurrenceMostCommonBillCountryCode": 20,
           "occurrenceMostCommonBillEmail": 17,
           "occurrenceMostCommonBillName": 7,
           "occurrenceMostCommonBillPhone": 6,
           "occurrenceMostCommonBillPostalCode": 14,
           "occurrenceMostCommonBillState": 5,
           "occurrenceMostCommonBin": 10,
           "occurrenceMostCommonCurrency": 24,
           "occurrenceMostCommonIpAddress": 16,
           "occurrenceMostCommonLatLon": 2,
           "occurrenceMostCommonMerchantId": 8,
           "occurrenceMostCommonPaymentToken": 10,
           "occurrenceMostCommonPaymentType": 19,
           "occurrenceMostCommonShipAddress": 3,
           "occurrenceMostCommonShipCity": 12,
           "occurrenceMostCommonShipCountryCode": 11,
           "occurrenceMostCommonShipEmail": 1,
           "occurrenceMostCommonShipName": 9,
           "occurrenceMostCommonShipPhone": 3,
           "occurrenceMostCommonShipPostalCode": 4,
           "occurrenceMostCommonShipState": 6,
           "occurrenceWeekday": 23,
           "occurrenceWeekend": 1,
           "proportionWeekday": 0.95833,
           "proportionWeekend": 0.04167,
           "refundRatio": 0,
           "refunds": 0
       },
       "scores": {
           "identityFraudScore": 0,
           "identityReasonCodes": [
               "LS05",
               "US03"
           ],
           "identityTrustworthinessScore": 0.75902,
           "legitimacyScores": [
               {
                   "legitimacyScore": 0.35703,
                   "reasonCodes": [
                       "LS05"
                   ]
               },
               {
                   "legitimacyScore": 0.4288,
                   "reasonCodes": [
                       "LS05"
                   ]
               },
               {
                   "legitimacyScore": 0.46921,
                   "reasonCodes": [
                       "LS05",
                       "LS02"
                   ]
               },
               {
                   "legitimacyScore": 0.45556,
                   "reasonCodes": []
               }
           ],
           "maxOmniscore": 89.1,
           "meanOmniscore": 79.225,
           "minOmniscore": 54.8
       }
   },
   "inputValidation": {
       "addressValidated": true,
       "emailValidated": true,
       "nameValidated": true,
       "paymentTokenValidated": true,
       "phoneValidated": true
   }
}
Was this article helpful?
2 out of 2 found this helpful
Consumer Insights
Consumer Insights v1.0 Integration Guide
Consumer Insights v2.0 Integration Guide