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.sandbox.bureau.id/
Live Mode: https://api.bureau.id/
Flow
-
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
statusin the response will beAWAITINGand a transactionID will be returned in the response, which will be used in the consecutive step. -
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
statuschanges toACCEPTED, 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.sandbox.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
| Key | Value | Description |
|---|---|---|
| workflowId | UUID(M) | Unique ID will be shared by Bureau team. |
| string(M) | Email ID of the user | |
| name | string(M) | Name of the user |
| phoneNumber | string(M) | Phone Number of the user |
| countryCode | string(M) | IND for India |
| derivedSignals | boolean(O) | True/False, Although it is optional, we recommend to send this with the value as true for optimal results |
| enhancedCoverage | boolean(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.sandbox.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
| Key | Value | Description |
|---|---|---|
| workflowId | UUID(M) | Unique ID will be shared by Bureau team. |
| string(M) | Email ID of the user | |
| name | string(M) | Name of the user |
| phoneNumber | string(M) | Phone Number of the user |
| countryCode | string(M) | IND for India |
| transactionId | string(M) | Value from the previous API |
| derivedSignals | boolean(O) | True/False, Although it is optional, we recommend to send this with the value as true for optimal results |
| enhancedCoverage | boolean(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
| Service | Feature | Description |
|---|---|---|
| Mobile Network Intelligence Without Consent | currentNetworkName | Name of the current telecom provider. |
| currentNetworkRegion | Region where the SIM was purchased or is active from. | |
| currentNetworkcountryCodeIso2 | SIM Region Country ISO code | |
| imsi | A global unique identifier for SIM cards. | |
| isPhoneReachable | Is the phone reachable at the time of the API query? | |
| isValidPhoneNumber | Is it a valid phone number? | |
| numberBillingType | Billing Type | |
| numberHasPortingHistory | Has SIM been ported in the past? | |
| portedFromNetworkName | The network of SIM it was ported from | |
| portedFromNetworkRegion | The region of SIM it was ported from | |
| portedFromNetworkcountryCodeIso2 | Pre-porting SIM Region Country ISO code | |
| roaming | Is the SIM currently roaming? | |
| roamingNetworkName | Name of roaming network | |
| roamingNetworkRegion | Region of roaming network | |
| roamingNetworkcountryCodeIso2 | Country of roaming network | |
| Phone Name Attributes | phoneDigitalage | The digital age for the phone number in Bureau and partner network. |
| phoneNameMatchScore | The name match score for the input name and the name behind the phone number. | |
| phoneNdrScore | Measure of uniqueness of names found against Phones. More than 0.7 indicates higher identity confidence. Less than 0.3 indicates poor identity confidence. | |
| phoneFootprintStrengthOverall | The phone digital footprint strength. | |
| phoneNameDigitalAge | The digital age for the phone number in Bureau and partner network. | |
| phoneUnrScore | Ratio of number of names that were unmatched to the total no. of names found. | |
| firstNameMatch | Flag to indicate if the first name matches | |
| lastNameMatch | Flag to indicate if the last name matches | |
| unrScore | Ratio of number of names that were unmatched to the total no. of names found. | |
| Phone Social Basic | amazon | Social platform the Phone is registered. |
| flipkart | Social platform the Phone is registered. | |
| Social platform the Phone is registered. | ||
| Social platform the Phone is registered. | ||
| isWhatsappBusiness | Flag to indicate if the whatsapp account is a business account | |
| mobile | The phone number that was provided as part of the input. | |
| paytm | Social platform the Phone is registered. | |
| UPI Name | upi_name | Name associated with UPI Account. |
| upi_name_similarity | Name Similarity score between the application name and UPI Name. | |
| Email Attributes | domainCategory | Category of email's domain |
| emailFinalRecommendation | Recommendation based on email. | |
| footprint | Digital footprint of email. | |
| domainExists | Signal to indicate if the domain exists | |
| emailExists | Signal to indicate if the email is valid | |
| Email name attributes | emailDigitalage | The digital age for the email in Bureau and partner network. |
| emailDigits | The total number of digits in the email. | |
| emailFootprintStrength | The email footprint strength. | |
| emailNameDigitalAge | The digital age for the combination of the name and email number in the Bureau network. | |
| emailSpclChars | The total number of special characters in the email. | |
| multiplePhoneAttached | Flag to indicate of multiple phone numbers are attached to the email. | |
| nameEmailMatch | The name match score for the input name and the email. | |
| nameMatchScore | The name match score for the input name and the name behind the email. | |
| ndrScore | Maximum similarity score between names found against email and the name in the application. | |
| unrScore | Ratio of number of names that were unmatched to the total no. of names found. | |
| Email social signal basic | amazon | Social platforms the email is registered. |
| Social platforms the email is registered. | ||
| paytm | Social platforms the email is registered. | |
| flipkart | Social platforms the email is registered. | |
| Derived Signals | telecom risk | Measure 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 footprint | Overall digital footprint of users based on presence on social media and digital age. | |
| identity confidence | Measure 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 Score | Alternative scoring models incorporate alternative data that is essentially derived from the above raw signals. |