Merchants > Guides > Connect

Connect

Connect allows you to create a connected graph of your customers using common attributes such as emails, phone numbers, device IDs or payment methods to link them together. The graph can be enhanced to show additional information about customers such as receipt of chargebacks or manual reviews. Customers can be ’tagged’ (for example, as a VIP), and the presence of this tag can be searched for. The results are available immediately in the Connect dashboard for analysis, and can be consumed as features through the API for use within your own systems.

Connecting Customers

To add a customer to Connect you will need to send the customer’s details to the Connect Endpoint.

If you add another customer that shares some attributes with the original customer, Connect will link them together.

Link types

Customers can be connected or linked together by sharing a number of different common attributes:

Email address
Telephone number
Device identifier
Payment method identifier
Form of identification
Vehicle
Any other consistent node

Connect by Email

To add the first customer with an email address, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_1111111",
        "email": "john.smith@gmail.com"
    },
    "timestamp": 1486387634000
}

To add the second customer with the same email address, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_2222222",
        "email": "john.smith@gmail.com"
    },
    "timestamp": 1486387634000
}

Connect by Telephone

To add the first customer with a telephone number, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_1111111",
        "telephone": "+441234567890",
        "telephoneCountry": "GB"
    },
    "timestamp": 1486387634000
}

To add the second customer with the same telephone number, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_2222222",
        "telephone": "+441234567890",
        "telephoneCountry": "GB"
    },
    "timestamp": 1486387634000
}

Connect by Device ID

To add the first customer with a device ID, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_1111111"
    },
    "device": {
        "deviceId": "dv_1234567890"
    },
    "timestamp": 1486387634000
}

To add the second customer with the same device ID, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_2222222"
    },
    "device": {
        "deviceId": "dv_1234567890"
    },
    "timestamp": 1486387634000
}

Connect by Payment Method

To add the first customer with a payment method, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_1111111"
    },
    "paymentMethods": [
        {
            "card": {
                "cardLastFour": "1234",
                "cardType": "visa",
                "expiryMonth": 4,
                "expiryYear": 2020,
                "instrumentId": "in_1234567890"
            }
        }
    ],
    "timestamp": 1486387634000
}

To add the second customer with the same payment method, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_2222222"
    },
    "paymentMethods": [
        {
            "card": {
                "cardLastFour": "1234",
                "cardType": "visa",
                "expiryMonth": 4,
                "expiryYear": 2020,
                "instrumentId": "in_1234567890"
            }
        }
    ],
    "timestamp": 1486387634000
}

Connect by Form of Identification

To add the first customer with a national form of identification, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_1111111"
    },
"nationalIdentifications": [
    {
      "driversLicense": {
        "idNumber": "10261985",
        "jurisdictionCountry": "USA",
        "jurisdictionState": "CA",
        "name": "Marty McFly"
      }
    }
  ],
    "timestamp": 1486387634000
}

To add the second customer with the same ID, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_2222222"
    },
"nationalIdentifications": [
    {
      "driversLicense": {
        "idNumber": "10261985",
        "jurisdictionCountry": "USA",
        "jurisdictionState": "CA",
        "name": "Marty McFly"
      }
    }
  ],
    "timestamp": 1486387634000
}

Connect by Vehicle

To add the first customer with a vehicle, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_1111111"
    },
  "vehicles": [
    {
      "plate": "OUTATIME",
      "jurisdictionCountry": "USA",
      "jurisdictionState": "CA",
      "make": "DeLorean Motor Company",
      "model": "DeLorean",
      "year": 1983,
      "vin": "2GTEK13M081122443"
    }
  ],
    "timestamp": 1486387634000
}

To add the second customer with the same vehicle, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_2222222"
    },
  "vehicles": [
    {
      "plate": "OUTATIME",
      "jurisdictionCountry": "USA",
      "jurisdictionState": "CA",
      "make": "DeLorean Motor Company",
      "model": "DeLorean",
      "year": 1983,
      "vin": "2GTEK13M081122443"
    }
  ],
    "timestamp": 1486387634000
}

Connect by Custom Node

You can link customers in the graph using custom nodes. These nodes should represent consistent entities which do not change and which are not normally shared by many customers. Please contact us if you want to use custom nodes for your organisation.

Adding Disputes

You are also able to submit dispute information for customers. If customers within the same network have disputed payments, this is often an indicator of an organised ring of fraudsters. By adding disputes to a customer, they can be associated with other customers via the graph links.

See the Sending Disputes guide to learn more.

Customer with a Dispute

To add a dispute for a new or existing customer, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customerId": "cust_1111111",
    "dispute": {
        "amount": 373,
        "currency": "GBP",
        "disputeId": "ch_8_5a8d1bea-6d38-11e7-8f2c-9801a79b5e51",
        "reason": "fraud",
        "stage": "CHARGEBACK"
    },
    "timestamp": 1486387634000
}

Reviewing Customers

You are also able review customers to specify your personal impression on their trustworthiness. This may be as a result of manual investigation or additional information (such as being your staff). You can review customers to be one of 3 different statuses.

UNREVIEWED
GENUINE
FRAUDSTER

Fraudulent Customer

To review a customer as a fraudster, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customerId": "cust_1111111",
    "review": {
        "comment": "Excessive chargebacks received",
        "label": "FRAUDSTER",
        "reviewer": {
            "email": "terry.support@mycompany.com",
            "name": "Terry Support"
        }
    },
    "timestamp": 1486387634000
}

Genuine Customer

To review a customer as genuine, the request looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customerId": "cust_2222222",
    "review": {
        "comment": "Corporate staff account",
        "label": "GENUINE",
        "reviewer": {
            "email": "terry.support@mycompany.com",
            "name": "Terry Support"
        }
    },
    "timestamp": 1486387634000
}

Tagging Customers

Customers can be tagged with strings such as vip, or politically-exposed-person. You can then query for the presence of this tag in the network, and the depth away from the target customer.

Setting/Unsetting a Tag

To tag a customer, specify the tag ID followed by true or alternatively false to unset it. Different tags can set be set/unset in the same request which looks like this:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customer": {
        "customerId": "cust_2222222",
        "tags": {
          "ex-staff": true,
          "staff": false
        }
    },
    "timestamp": 1486387634000
}

Querying a Graph for Tags

You can query for the presence of a particular tag in a network. The response will contain any customers that contain that tag, and their distance from the target customer. If the target customer also has the queried tag, they will be returned in the response with “depth”: 0. The request and response look like this for a customer that does not have the tag but is in a network with other customers who have the tag:

GET https://api.ravelin.com/v2/connect/tag?customerId=cust_1111111&depth=10&tagId=vip HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "matches": [
        {
            "customerId": "cust_2222222",
            "depth": 2
        },
        {
            "customerId": "cust_3333333",
            "depth": 6
        }
    ]
}

Graph Feature Limits

Fraud found

If Connect finds fraud (a chargeback or a reviewed fraudster) it will not continue searching any deeper into the network. It will complete looking at nodes at the current depth, then return the results.

Maximum number of visited nodes

Connect will visit at most 5000 nodes searching for fraud. If this limit is reached all the xxxCount fields (customerCount, cardCount…) are set to 5000 in the response to indicate the limit has been hit. Note that count is the sum of the xxxCount fields, so in this case will be set to a multiple of 5000.

Maximum depth

If fraud is not found before the requested maximum depth is reached (specified by the depth parameter in the request), Connect will stop searching and will set the maxDepthReached field to true in the response.

Maximum degree

Connect will not search through nodes connected to over 5000 other nodes. The search will continue, but will ignore this node and its connections. Connect will set the maxDegreeHit field to true in the response to indicate this has happened.

Phone numbers

Connect will not search through phone numbers with more than 500 connections. In this case the autoExcludeHit field will be set to true in the response. In our experience phone numbers with a very large number of connections occur when customers enter invalid but easily guessed phone numbers, such as 123456789.

Genuine reviews

Connect will not search through customers that are marked genuine, except if the customer is the target starting customer.

Sandbox

The graph databases powering Connect will not restore historical data for Sandbox accounts. This may result in some data disappearing from the graph, and inconsistent results when refreshing.

Example Request

An example request for the Connect Endpoint with all entities populated is shown below:

POST https://api.ravelin.com/v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1479302798,
    "familyName": "Smith",
    "givenName": "John",
    "name": "John Smith",
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1479302798,
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1479302798,
    "telephoneCountry": "GBR",
    "tags": {
      "foo": true,
      "bar": false
    },
    "country": "GBR",
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "paymentMethods": [
    {
      "card": {
        "paymentMethodId": "123-abc-XYZ",
        "nickName": "joescard",
        "lastVerified": 1480340580,
        "banned": false,
        "active": true,
        "registrationTime": 1480340580,
        "custom": {
          "foo": "bar",
          "biz": "baz",
          "one": 1
        },
        "instrumentId": "123-abc-XYZ",
        "cardBin": "123456",
        "cardLastFour": "1234",
        "cardType": "visa",
        "expiryMonth": 4,
        "expiryYear": 2020,
        "nameOnCard": "John Smith",
        "successfulRegistration": true,
        "issuer": "barclaycard",
        "countryIssued": "GBR",
        "prepaidCard": false,
        "billingAddress": {
          "latitude": 51.503252,
          "longitude": -0.127899,
          "geohash": "gcpuvp",
          "street1": "123 fake st.",
          "street2": "floor 4, flat 48",
          "neighbourhood": "Hackney",
          "zone": "1",
          "city": "London",
          "region": "California",
          "country": "GBR",
          "poBoxNumber": "1234",
          "postalCode": "E1 1AA",
          "custom": {
            "foo": "bar",
            "biz": "baz",
            "one": 1
          }
        },
        "billingFamilyName": "Smith",
        "billingGivenName": "John",
        "corporateCard": true,
        "virtualCard": true
      }
    }
  ],
  "nationalIdentifications": [
    {
      "driversLicense": {
        "idNumber": "10261985",
        "jurisdictionCountry": "USA",
        "jurisdictionState": "CA",
        "name": "Marty McFly"
      }
    }
  ],
  "vehicles": [
    {
      "plate": "OUTATIME",
      "jurisdictionCountry": "USA",
      "jurisdictionState": "CA",
      "make": "DeLorean Motor Company",
      "model": "DeLorean",
      "year": 1983,
      "vin": "2GTEK13M081122443"
    }
  ],
  "device": {
    "deviceId": "abc-123-ZYZ",
    "type": "phone",
    "manufacturer": "google",
    "model": "Pixel XL",
    "os": "android",
    "browser": "Chrome 42",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/54.0.2840.98 Safari/537.36"
  },
  "chargeback": {
    "chargebackId": "abc-123-XYZ",
    "gateway": "Stripe",
    "gatewayReference": "abc-123-XYZ",
    "reason": "FRAUD",
    "status": "LOST",
    "amount": 15212,
    "currency": "GBP",
    "disputeTime": 1479302798,
    "liabilityShifted": true,
    "nonFraud": false,
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "review": {
    "label": "FRAUDSTER",
    "comment": "Definitely a fraudster.",
    "reviewer": {
      "name": "tom@mycompany.com",
      "email": "Tom"
    }
  },
  "customNode": {
    "nodeType": "group",
    "nodeId": "group-abc-123-ZYZ",
    "nodeName": "Group abc-123-ZYZ"
  },
  "customNodes": [
    {
      "nodeType": "group",
      "nodeId": "group-abc-123-ZYZ",
      "nodeName": "Group abc-123-ZYZ"
    }
  ]
}

Feedback

Was this page helpful?