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:

• Examples of API Detection:

Response:

Error:

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:

Request example for manual review decision:

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.