Integration Steps Overview Detection API Update API Postback API Connectivity API dEdge API Integrations DataVisor API References DataVisor Integration Guide for Device Intelligence DataVisor Integration Guide for Comprehensive Fraud Solution Overview DataVisor’s comprehensive fraud solution provides rapid and flexible integration with your current data architecture, existing detection systems, and third-party vendors. We provide options for both real-time and batch integration. For real-time integration, choose the APIs based on the specific DataVisor solution modules that you subscribe to. Depending on how you plan to utilize our solution, one or more of the APIs will be used in the integration. The default integration mechanism for all APIs supports real-time, synchronous HTTPS-based RESTful calls (secured with TLS v1.2). Please consult your technical account manager (TAM) for a customized integration plan if you prefer implementing queue-based asynchronous real-time integration. API References Detection API API Details: Method: POST. URL: The url is provided by DataVisor Request Body: HTTP Standard Type: String Requirement: It must be a valid String converted from JSONObject . DataVisor uses org.json.simple.JSONValue#parse() to do the conversion. Data schema in the request body: The data fields and data values to be processed by the Detection API should be included in the request body as key-value pairs in the JSON object. The three request fields described in the table below are mandatory: Key Mandatory Value Exception if null event_type Yes For example: transaction, registration, login, order, money_transfer, … No (DataVisor will use default value) event_time Yes We support a number of standard formats, including millisec and ISO-compliant String formats. The default format is: YYYY-MM-DD HH:MM:SS – for other formats please consult your TAM. Yes user_id Yes The identifier for the primary entity that you want the detection to be performed on. it can be “user_id”, “event_id”, “transaction_id”, “customer_id” etc. Yes Other attributes No Please consult the Use Case-Specific Data Sheet for your specific fraud use case. No The data fields and data values to be processed by the Detection API should be included in the request body as key-value pairs in the JSON object. Please work with your Technical Account Manager to determine what other data fields (e.g. ip_address, email, order_amount) are needed by the DataVisor fraud detection modules you subscribe to. Please work with your Technical Account Manager if the required fields are not available. DataVisor can help map these fields. Responses: Normal Response: HTTP status code 200. The response format is a JSON line that will include key metadata about the detection results and decision action. The actual key-value pairs in the response depend on the DataVisor detection modules that you subscribe to, and the configurations your Technical Account Manager makes for you. In order for the nested JSON response above to be valid JSON, nested quotes will be escaped with a backslash (“\”). In order to properly parse our response, DataVisor recommends that a JSON parsing library is used, e.g json (Python) or JSONObject (Java), as these libraries can appropriately handle complex JSON structures. Error Response: All errors resulting from misconfigurations or missing mandatory values (for example, missing one of the mandatory fields in the request body) return HTTP status 400 Bad Request Data Dictionary of the Detection API Response: Element in Response Examples Dictionary User ID “user_id”:”12345″ This identifies the unique entity upon which any action is taken. It could be a user, a transaction, an application, or something else. Feature Values “count_lastName_from_SSN”:”2″ sum_amount_from_user”:”100″ ip_risk_level”:”high” If you are using DataVisor’s Feature Platform to compute advanced features or to fetch enriched signals from DataVisor’s data partners, you can choose to return these features in your detection response. Such features could be used in rules or models downstream of the feature computation layer. Final Decision “1”:{“action”:”REJECT”} If you are using DataVisor Rules Engine to implement your decision logic of what action to take given all intermediate detection results available in DataVisor platform (DataVisor models, DataVisor rules, your own detections, …), your Technical Account Manager (TAM) will guide you to create a decision rule which returns the decision action in this part. In the example on the left, “1” is the rule ID of the decision rule. It will not necessarily be 1 in your case, but should be a fixed number after the rule is created. “action” is the name of the decision feature that your TAM will create for you. “REJECT” is the ‘winning action’ from the action list that you predefined in the DataVisor Rules Engine. UML Response “2”:{“uml_response”:”{\”responseType\”:\”success\”, \”score\”:0.6, \”campaignName\”:\”12BDX123D\”, \”user_id\”:\”12345\”, \”correlatedUsers\”:\”23456,34567,45678\”} If you are using a DataVisor Unsupervised Machine Learning (UML) model, you will receive the UML model results in this part. “2” is the rule ID of the rule calling for UML model results. It will not necessarily be 2 in your case, but should be a fixed number after the rule is created. “responseType” specifies that the HTTPS response was successful. “score” is the UML model score, ranging from 0 (undetected) to 1 (very high risk). “user_id” specifies the primary identifier for the entity being detected, the value itself could be a user ID, an account ID, etc. “campaignName” specifies the cluster ring ID for this user “correlatedUsers” provides other entities from the same fraud ring SML Response “3”:{“sml_score”:”0.75″} If you are using a DataVisor Supervised Machine Learning (SML) model, you will receive the SML model score in this part. “3” is the rule ID of the rule calling for SML model results. It will not necessarily be 3 in your case, but should be a fixed number after the rule is created. Rule Results “5”:{“TAG USER”:”Suspicious IP”} “8”:{“REVIEW QUEUE”:”AML Queue”,”ACCEPT”:”Good History”} This part will show what rules were triggered by the event, and what metadata those rules get returned via API. The general format in this part is: “Rule ID”:{“Rule Action”:”Action Metadata”} In the second example, “8” is the rule ID of the triggered rule, “REVIEW QUEUE” is the action that the rule author specified, “AML Queue” is the action metadata that the rule author specified. Examples of API Detection: Response: { “user_id”:”12345″, “feature1″:”feature1value”, “feature2″:”feature2value”, “1”:{“action”:”REJECT”}, “2”:{“uml_response”:”{\”responseType\”:\”success\”,\”score\”:0.6,\”campaignName\”:\”12BDX123D\”, \”userID\”:\”12345\”,\”correlatedUsers\”:\”23456,34567,45678\”}”}, “3”:{“sml_score”:”0.75″}, “5”:{“Rule 5 action”:”Action metadata”}, “8”:{“Rule 8 action”:”Action metadata”}, “11”:{“Rule 11 Action”: “Action metadata”} } Error: { “codeId”: 1034, “codeKey”: “FP_API_ERROR_CLIENT_EVENT_INVALID_EXCEPTION”, “msg”: “Can’t get eventTime from raw input String: eventTime:null”, “exInfo”: “com.datavisor.exception.ClientEventInvalidException: …” } Update API This is the API that you call to provide additional data to be processed by DataVisor systems when no detection result is needed or when detection result does not need to be returned synchronously . A few examples of such data to be sent with this API are: Labels to update the DataVisor system on whether an entity (user, account, payment, transaction, …) is fraud or not. Status update or action update to inform DataVisor systems what status change or action has been taken in your other systems, e.g. blocking an account, declining a transaction, deleting a product review. Data sources update (e.g. IP blacklist, email domain whitelist, currency exchange rate table) that you want DataVisor systems to remain in sync with. Additional user attributes that you want to be processed by DataVisor systems so that they are shown in DataVisor Knowledge Graph. API Details: Method: POST. URL: to be provided by DataVisor. Request Body: HTTP Standard Type: String Requirement: It must be a valid String converted from JSONObject. DataVisor uses org.json.simple.JSONValue#parse() to for conversion. Data schema in the request body: The data fields and data values to be processed by Update API should be included in the request body as key-value pairs in the JSON object. Please discuss with your Technical Account Manager about the data fields needed for your usage of the Update API. For example, if you want to use the Update API to send DataVisor your fraud labels, you will need to include certain relevant fields such as “transaction_id”, “fraud_label”, “chargeback_label”, “label_time”, “reported by”. There is no mandatory field for this API. You can post an update about any entity without providing a user_id or an event_time. It is strongly recommended that you include the “event_type” field to specify what type of updates you are providing, e.g. “fraud_label”, “blacklist_update”, to inform DataVisor Feature Platform how to process the update. Response: A response with HTTP status code 200 is returned to your system to acknowledge the receiving of the information. Postback API This is the API that DataVisor uses to send you the review decisions or data source updates that your team members make in DataVisor Case Management System or DataVisor Knowledge Graph. API Details: Method: POST. URL: to be provided by the client. Request Body: HTTP Standard Type: String Requirement: It must be a valid String converted from JSONObject. DataVisor uses org.json.simple.JSONValue#parse() for the conversion. Data schema in the request body: Element in the Message Example Definition Origin “origin”:”datavisor” Source of the review. Not configurable. Reviewer “reviewer”:”michael.jordan@nba.com” Reviewer name / account. Not configurable. Timestamp “reviewTimestamp”:”2020-11-25T08:46:37.078Z” Time of the review decision. Not configurable. Response Type “responseType”:”review” Type of post-back action. Not configurable. Action “action”:”accept” The action that the reviewer selected from the action list. Data field name is not configurable, but the action list is configurable. Comments “comment”:”Suspicious IP and high event velocity” The comment that the reviewer made on the Case Management portal. Data field name is not configurable. Entity ID “transactionId”:”123456″ “userId”:”abcdef” The entity upon which the case is being reviewed. Depending on how you set up the Case Management portal, the entity could be a user, an account, or a transaction. Data field name is configurable in DataVisor Feature Platform. Feature Value “country”:”US” “account_age”:”2″ You can tag certain features in the DataVisor Feature Platform to have them returned in the postback. Configurable in DataVisor Feature Platform. Request example for manual review decision: { “origin”:”datavisor”, “reviewer”:”first.last@email.com”, “reviewTimestamp”:”2020-11-25T08:46:37.078Z”, “responseType”:”review”, “action”:”accept”, “comment”:”Suspicious IP and high event velocity”, “entityId”:”XXXXX”, “feature_1″:”value_1”, “feature_2″:”value_2” } Response: You may configure your URL endpoint to respond with HTTP status code 200 upon receiving the request from the DataVisor Postback API. Connectivity API This is the API that you call to establish connectivity with the DataVisor system and ensure that your server IPs have been successfully whitelisted. This API can also be used for system health checks in a production environment. Because the goal is to establish connectivity, the data sent to this API is not stored by the DataVisor system You may send any data via this API, even a request not in JSON format, because there will be no parsing of the request by DataVisor In a production environment, our recommended approach is to send a “ping” to the Connectivity API on a predefined time interval (e.g. every 1 minute) to ensure that there are no system connectivity issues API Details: Method: GET. URL: An endpoint provided by DataVisor at the time of onboarding, typically in the following format: https://[clientname].dv-api.com/[clientname]/ack Data schema in the request body: There are no requirements for the data schema for the Connectivity API, since DataVisor does not parse the raw request Response: A response with HTTP status code 200 is returned for successful requests, with a response body of simply “ack”. Unsuccessful requests would return non-200 response codes, and would indicate timeouts or other issues caused by non-valid source IPs. dEdge API If dEdge is part of your DataVisor subscription and you plan to use the device ID and device risk signals in your in-house business rules, detection models, or other existing systems, your system can use this API to directly query dEdge for such signals. API Details: Method: POST. Request body: a custom domain name that is provided by DataVisor the DV_token value of the device that you want to query for value of your access_key provided by DataVisor value of your access_secret provided by DataVisor Please refer to our dEdge API Integration Guide for more details.