Alternate Risk Score

Overview

This API document highlights the steps using which Businesses can integrate the Alt Data Workflow . The API returns the raw and derived signals behind Phone, Email and Name.

Authentication

For Authentication, we will be using Basic Authentication. A header will be attached to each API request to authenticate the user making the API request. The value of the header is generated by
base64(CredentialID:CredentialSecret). The key of the header is Authorization

Authorization: Basic 2122ojojoasdioasidjaoi

Below are the steps outlining the process flow for integrating with the Bureau's Alt Data WorkFlow:
This API consists of two steps:

API Gateway URL

Test Mode : https://api.overwatch.stg.bureau.id/
Live Mode : https://api.overwatch.bureau.id/

Flow

  1. Initiate - To begin with the first API call has to be made to submit the details like Phone, Email, and Name. If the request is successful, the status in the response will be AWAITING and a transactionID will be returned in the response, which will be used in the consecutive step.

  2. Fetch Result - Around 30 seconds after the previous step, the fetch results has be called to check the status and get the final result. This API is a polling API, retries have to be made until the status changes to ACCEPTED, which indicates that the processing has been completed on the parameters provided and response is ready to be consumed. This API exposes the individual service level details along with the combined outcome.

    Note
    The “outcome” key indicates the current status of the request. It contains the following values:
    AWAITING - when the process is in progress
    COMPLETED - when the detection of all the websites is completed

Initiate

Request

curl --location 'https://api.overwatch.stg.bureau.id/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ZDdkZDIxxxxxxxJjZDljYTdhZA==' \
--data-raw '{
    "workflowId": "1111zzzz-1111-1aa1-8a08-a1a085aebb9b",
    "data": {
        "email": "[email protected]",
        "name": "User Name",
        "phoneNumber": "919999999999",
        "countryCode": "IND",
        "derivedSignals":true,
        "enhancedCoverage":true
    }
}'

Request Body Description

KeyValueDescription
workflowIdUUID(M)Unique ID will be shared by Bureau team.
emailstring(M)Email ID of the user
namestring(M)Name of the user
phoneNumberstring(M)Phone Number of the user
countryCodestring(M)IND for India
derivedSignalsboolean(O)True/False, Although it is optional, we recommend to send this with the value as true for optimal results
enhancedCoverageboolean(O)True/False, Although it is optional, we recommend to send this with the value as true for optimal results

Response

{
    "statusCode": 200,
    "error": "",
    "status": "AWAITING",
    "timestamp": 1684999151234,
    "transactionId": "c7f3b313-1111-1111-aaaa-12ca28f7e68e",
    "merchantId": "auth0|61dfbb6dfd33420071be7021",
    "entityId": "32b86cfb-1991-44f5-9f57-8e4385d8861a",
    "entityType": "",
    "workflowId": "30f4a31f-aaaa-11aa-11aa-a1a085aebb9b",
    "entityName": "User Name",
    "workflowName": "Test-alternate-score",
    "tags": {},
    "outcome": "AWAITING",
    "transactionTimeline": [
        {
            "index": 1,
            "updatedAt": 1684999151234,
            "updatedBy": "",
            "outcome": "AWAITING",
            "comments": ""
        }
    ],
    "services": {
        "Email Attributes": {
            "status": "NOT_EXECUTED",
            "response": null
        },
        "Email Name Attributes": {
            "status": "NOT_EXECUTED",
            "response": null
        },
        "Email Social Basic Report": {
            "status": "PENDING",
            "response": {
                "amazon": null,
                "awaitedOnThis": true,
                "email": null,
                "error": null,
                "flipkart": null,
                "instagram": null,
                "paytm": null,
                "referenceId": null
            }
        },
        "Email Social Basic Submit": {
            "status": "OK",
            "response": {
                "conditionsEvaluationStatus": true,
                "error": null,
                "referenceId": "85d31f1c-a222-4caf-9323-b6f7e75377de",
                "status": "OK"
            }
        },
        "Mobile Network Intelligence (Without Consent)": {
            "status": "NOT_EXECUTED",
            "response": null
        },
        "Phone Name Attributes": {
            "status": "NOT_EXECUTED",
            "response": null
        },
        "Phone Social Basic Report": {
            "status": "NOT_EXECUTED",
            "response": null
        },
        "Phone Social Basic Submit": {
            "status": "NOT_EXECUTED",
            "response": null
        },
        "Risk Model": {
            "status": "NOT_EXECUTED",
            "response": null
        }
    },
    "awaits": {
        "Email Social Basic Report": {
            "status": "PENDING",
            "response": {
                "awaitedOnThis": true,
                "data": []
            }
        }
    },
    "outcomeReasons": [],
    "transactionRawInput": {
        "countryCode": "IND",
        "derivedSignals": true,
        "email": "[email protected]",
        "name": "User Name",
        "phoneNumber": "919999999999"
    },
    "documents": [],
    "devices": []
}
{
  "data": "string",
  "errors": {
    "status": 401,
    "errorCode": "UNAUTHORIZED",
    "service": "Overwatch"
  },
  "message": " ",
  "meta": {
    "length": 0,
    "took": 0,
    "total": 0
  }
}
{
  "errors": {
    "code": 503,
    "description": " ",
    "message": "INTERNAL_SERVICE_UNAVAILABLE",
    "metadata": " ",
    "referenceId": "b090f2a1-ebf4-4fdc-bcdc-296cfc7e4ea1",
    "type": "NO_RECORD_FOUND"
  },
  "merchantId": "auth0|61df1111107111021",
  "requestId": "d46ff15d-1111-4568-1111-b21bbdd3962f",
  "statusCode": 503,
  "timestamp": 1657794502770
}

Fetch Results

Request

curl --location 'https://api.overwatch.stg.bureau.id/transactions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ZDdkZDIxxxxxxxJjZDljYTdhZA==' \
--data-raw '{
    "workflowId": "1111zzzz-1111-1aa1-8a08-a1a085aebb9b",
    "transactionId": "c7f3b313-11aa-1a11-a111-12ca28f7e68e",
    "data": {
        "email": "[email protected]",
        "name": "User Name",
        "phoneNumber": "919999999999",
        "countryCode": "IND",
        "derivedSignals":true,
        "enhancedCoverage":true
    }
}'

Request Body Description

KeyValueDescription
workflowIdUUID(M)Unique ID will be shared by Bureau team.
emailstring(M)Email ID of the user
namestring(M)Name of the user
phoneNumberstring(M)Phone Number of the user
countryCodestring(M)IND for India
transactionIdstring(M)Value from the previous API
derivedSignalsboolean(O)True/False, Although it is optional, we recommend to send this with the value as true for optimal results
enhancedCoverageboolean(O)True/False, Although it is optional, we recommend to send this with the value as true for optimal results

Response

{
    "statusCode": 200,
    "error": "",
    "status": "OK",
    "timestamp": 1685004095033,
    "transactionId": "b6819bf9-a1aa-a11a-a11a-e7bb7ae2cd07",
    "merchantId": "auth0|61dfbb6dfd33420071be7021",
    "entityId": "82911714-111a-1111-1111-faa21e748341",
    "entityType": "",
    "workflowId": "30f4a31f-1111-11a1-1a11-a1a085aebb9b",
    "entityName": "User Name",
    "workflowName": "Test-alternate-score",
    "tags": {},
    "outcome": "ACCEPTED",
    "transactionTimeline": [
        {
            "index": 1,
            "updatedAt": 1685004095033,
            "updatedBy": "",
            "outcome": "ACCEPTED",
            "comments": ""
        }
    ],
    "services": {
        "Email Attributes": {
            "status": "OK",
            "response": {
                "conditionsEvaluationStatus": true,
                "digitalAge": 6,
                "domainExists": true,
                "domainRiskLevel": "Moderate",
                "domaincategory": "Webmail",
                "domaincorporate": "No",
                "emailExists": true,
                "emailFinalRecommendation": "No Data",
                "error": null,
                "firstVerificationDate": "2023-05-18T07:30:32Z",
                "footprint": "NO_RECORDS",
                "lastVerificationDate": "2023-05-18T07:30:32Z",
                "status": "OK",
                "uniqueHits": 1
            }
        },
        "Email Name Attributes": {
            "status": "OK",
            "response": {
                "address": null,
                "businessNameDetected": false,
                "conditionsEvaluationStatus": true,
                "digitalage": -1,
                "emailDigits": 4,
                "emailFootprintStrength": "",
                "emailNameDigitalAge": -1,
                "emailSpclChars": 0,
                "error": null,
                "firstNameMatch": false,
                "lastNameMatch": false,
                "multiplePhoneAttached": false,
                "nameEmailMatch": -1,
                "nameMatchScore": 0,
                "ndrScore": -1,
                "phoneNumber": -1,
                "status": "OK",
                "unrScore": -1
            }
        },
        "Email Social Basic Report": {
            "status": "OK",
            "response": {
                "amazon": "Account Found",
                "awaitedOnThis": false,
                "email": "[email protected]",
                "error": null,
                "flipkart": "Account Found",
                "instagram": "Account Found",
                "paytm": "Account Found",
                "referenceId": "ad40658c-5fc0-4325-b6ae-c5221c75501f"
            }
        },
        "Email Social Basic Submit": {
            "status": "OK",
            "response": {
                "conditionsEvaluationStatus": true,
                "error": null,
                "referenceId": "ad40658c-5fc0-4325-b6ae-c5221c75501f",
                "status": "OK"
            }
        },
        "Mobile Network Intelligence (Without Consent)": {
            "status": "OK",
            "response": {
                "conditionsEvaluationStatus": true,
                "currentNetworkCountryCodeIso2": null,
                "currentNetworkName": "Reliance Jio",
                "currentNetworkRegion": "Gujarat",
                "error": null,
                "imsi": "4058575280",
                "isPhoneReachable": true,
                "isValidPhoneNumber": true,
                "numberBillingType": "prepaid",
                "numberHasPortingHistory": true,
                "portedFromNetworkCountryCodeIso2": null,
                "portedFromNetworkName": "Airtel",
                "portedFromNetworkRegion": "Gujarat",
                "roaming": false,
                "roamingNetworkCountryCodeIso2": null,
                "roamingNetworkName": null,
                "roamingNetworkRegion": null,
                "status": "OK"
            }
        },
        "Phone Name Attributes": {
            "status": "OK",
            "response": {
                "address": "",
                "businessNameDetected": false,
                "conditionsEvaluationStatus": true,
                "digitalage": 1556,
                "error": null,
                "firstNameMatch": true,
                "lastNameMatch": true,
                "nameMatchScore": 100,
                "ndrScore": 1,
                "phoneFootprintStrengthOverall": "Low",
                "phoneNameDigitalAge": -1,
                "status": "OK",
                "unrScore": 0
            }
        },
        "Phone Social Basic Report": {
            "status": "OK",
            "response": {
                "amazon": "Error",
                "awaitedOnThis": false,
                "error": null,
                "flipkart": "Account Found",
                "instagram": "Account Not Found",
                "isWhatsappBusiness": null,
                "mobile": "9999999999",
                "paytm": "Account Found",
                "referenceId": "36c0c803-6744-4f90-8c08-60a4222cbf7a",
                "whatsapp": "Account Found"
            }
        },
        "Phone Social Basic Submit": {
            "status": "OK",
            "response": {
                "conditionsEvaluationStatus": true,
                "error": null,
                "referenceId": "36c0c803-6744-4f90-8c08-60a4222cbf7a",
                "status": "OK"
            }
        },
        "Risk Model": {
            "status": "OK",
            "response": {
                "address1": "",
                "address2": "",
                "addressCompletenessScore": 0,
                "addressInsights": "Unit/Rooftop information ambiguous or not found\nArea or society name ambiguous or not found\nStreet name ambiguous or not found\nLandmark name ambiguous or not found",
                "addressRisk": "High",
                "alternateRiskScore": 57.47126436781605,
                "areaName": [],
                "areaPincode": [],
                "cityName": [],
                "conditionsEvaluationStatus": true,
                "digitalFootprint": "High",
                "emailUNRScore": 0,
                "error": null,
                "identityConfidence": "High",
                "landmark": [],
                "message": "Success",
                "negativeInsights": [
                    "Address seems to be incomplete.",
                    "Email may not belong to the same person, does not match partially with name."
                ],
                "phoneUNRScore": 0,
                "positiveInsights": [
                    "Person's name matched against multiple sources.",
                    "Person's has significant internet presence.",
                    "Person has high social media presence.",
                    "Person's name matches against bank records."
                ],
                "responseStatusCode": 200,
                "societyName": [],
                "stateName": [],
                "status": "OK",
                "streetName": [],
                "telecomRisk": "Low",
                "unit": [],
                "upiPhoneNameMatch": 1,
                "upiPhoneNameMatchScore": 100
            }
        }
    },
    "awaits": {
        "Email Social Basic Report": {
            "status": "OK",
            "response": {
                "awaitedOnThis": false,
                "data": []
            }
        },
        "Phone Social Basic Report": {
            "status": "OK",
            "response": {
                "awaitedOnThis": false,
                "data": []
            }
        }
    },
    "outcomeReasons": [],
    "transactionRawInput": {
        "countryCode": "IND",
        "derivedSignals": true,
        "email": "[email protected]",
        "name": "User Name",
        "phoneNumber": "919999999999"
    },
    "documents": [],
    "devices": []
}

API Responses Description

ServiceFeatureDescription
Mobile Network Intelligence Without ConsentcurrentNetworkNameName of the current telecom provider.
currentNetworkRegionRegion where the SIM was purchased or is active from.
currentNetworkcountryCodeIso2SIM Region Country ISO code
imsiA global unique identifier for SIM cards.
isPhoneReachableIs the phone reachable at the time of the API query?
isValidPhoneNumberIs it a valid phone number?
numberBillingTypeBilling Type
numberHasPortingHistoryHas SIM been ported in the past?
portedFromNetworkNameThe network of SIM it was ported from
portedFromNetworkRegionThe region of SIM it was ported from
portedFromNetworkcountryCodeIso2Pre-porting SIM Region Country ISO code
roamingIs the SIM currently roaming?
roamingNetworkNameName of roaming network
roamingNetworkRegionRegion of roaming network
roamingNetworkcountryCodeIso2Country of roaming network
Phone Name AttributesphoneDigitalageThe digital age for the phone number in Bureau and partner network.
phoneNameMatchScoreThe name match score for the input name and the name behind the phone number.
phoneNdrScoreMeasure of uniqueness of names found against Phones. More than 0.7 indicates higher identity confidence. Less than 0.3 indicates poor identity confidence.
phoneFootprintStrengthOverallThe phone digital footprint strength.
phoneNameDigitalAgeThe digital age for the phone number in Bureau and partner network.
phoneUnrScoreRatio of number of names that were unmatched to the total no. of names found.
firstNameMatchFlag to indicate if the first name matches
lastNameMatchFlag to indicate if the last name matches
unrScoreRatio of number of names that were unmatched to the total no. of names found.
Phone Social BasicamazonSocial platform the Phone is registered.
flipkartSocial platform the Phone is registered.
instagramSocial platform the Phone is registered.
whatsappSocial platform the Phone is registered.
isWhatsappBusinessFlag to indicate if the whatsapp account is a business account
mobileThe phone number that was provided as part of the input.
paytmSocial platform the Phone is registered.
UPI Nameupi_nameName associated with UPI Account.
upi_name_similarityName Similarity score between the application name and UPI Name.
Email AttributesdomainCategoryCategory of email's domain
emailFinalRecommendationRecommendation based on email.
footprintDigital footprint of email.
domainExistsSignal to indicate if the domain exists
emailExistsSignal to indicate if the email is valid
Email name attributesemailDigitalageThe digital age for the email in Bureau and partner network.
emailDigitsThe total number of digits in the email.
emailFootprintStrengthThe email footprint strength.
emailNameDigitalAgeThe digital age for the combination of the name and email number in the Bureau network.
emailSpclCharsThe total number of special characters in the email.
multiplePhoneAttachedFlag to indicate of multiple phone numbers are attached to the email.
nameEmailMatchThe name match score for the input name and the email.
nameMatchScoreThe name match score for the input name and the name behind the email.
ndrScoreMaximum similarity score between names found against email and the name in the application.
unrScoreRatio of number of names that were unmatched to the total no. of names found.
Email social signal basicamazonSocial platforms the email is registered.
instagramSocial platforms the email is registered.
paytmSocial platforms the email is registered.
flipkartSocial platforms the email is registered.
Derived Signalstelecom riskMeasure of risk associated with telecom networks and associated metadata. For example Postpaid users are likely to be Low-Risk as compared to Prepaid users, similarly possessing a non-ported jio SIM may be an indicator of higher risk because of ease of SIM acquisition etc.
digital footprintOverall digital footprint of users based on presence on social media and digital age.
identity confidenceMeasure of certainty of the identity belonging to the same person it is claimed to be. Calculated as a combination of phone name match, phone lookup name match and distinct names ratio.
Alternate risk ScoreAlternative scoring models incorporate alternative data that is essentially derived from the above raw signals.