Consumer Insights Integration Guide

August 15, 2024 15:41

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.

Provisioning an API Key

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.
Select Admin, and then Product Configuration.
Select Options for the organization in which you want to create an API key, and then select Create API Key.
Select Create.
Expand the organization.
Copy the API key and save it in a secure location. You will need the API key to create a bearer token.

Note

Use the copy button to copy the API key. If you close the window without copying the API key, you must create a new API key using the options menu. You are allowed two active API keys per customer. To create another API key after creating two API keys, delete one of the existing keys.

Creating a Bearer Token

Following the OAuth 2.0 framework, 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 and Client ID in an HTTP POST to a specific login.kount.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.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/token

API Service Host:

https://api-sandbox.kount.com

Production

Auth Server URL:

https://login.kount.com/oauth2/ausdppksgrbyM0abp357/v1/token

API Service Host:

https://api.kount.com

After obtaining the bearer token, utilize 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. Typically, tokens issued by login.kount.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.

Examples of retrieving and using the bearer token in popular programming languages:

Python

sidebar. Python Code Example

"""sandbox"""
import requests
AUTH_SERVER_URL = "https://login.kount.com/oauth2/ausdppkujzCPQuIrY357/v1/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

sidebar. Bash Code Example

#!/usr/bin/env bash

API='https://api-sandbox.kount.com'
ISSUER='https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
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

sidebar. TypeScript Code Example

const axios = require('axios')

const API = 'https://api-sandbox.kount.com'
const ISSUER = 'https://login.kount.com/oauth2/ausdppkujzCPQuIrY357'
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

sidebar. 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.kount.com/oauth2/ausdppkujzCPQuIrY357",
                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 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.

sidebar. 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.

sidebar. 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