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 by a number of different common attributes:

Email address
Telephone number
Device ID
Card payment method
Form of national identification
Vehicle
Custom nodes

Connect by email address

The following request shows how to connect an email address to a customer:

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

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

The following request shows how to connect the same email address to a second customer:

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

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

Connect by telephone number

The following request shows how to connect a telephone number to a customer:

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

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

The following request shows how to connect the same telephone number to a second customer:

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

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

Connect by device ID

The following request shows how to connect a device ID to a customer:

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

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

The following request shows how to connect the same device ID to a second customer:

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

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

Connect by card payment method

The following request shows how to connect a card payment method to a customer:

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

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

The following request shows how to connect the same card payment method to a second customer:

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

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

Connect by form of national identification

Forms of national identification are identified in the network by a combination of the type of identification, the document ID number, the country in which the document was issued, and, where applicable, the state in which it was issued.

Supported forms of national identification are:

The following request shows how to connect a driving license to a customer:

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

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

The following request shows how to connect the same driving license to a second customer:

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

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

Connect by Vehicle

Vehicles are identified in the network in two ways.

Firstly, by a combination of the vehicle’s registration number, the country in which the vehicle is registered, and, where applicable, the state where it is registered. For example, a vehicle with the registration number ABC123, registered in California, USA would be identified as "USA-CA-ABC123".
Secondly, vehicles can be identified by a vehicle identification number (VIN).

These identifiers produce two different types of vehicle node in the graph.

The following request shows how to connect a vehicle to a customer:

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

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

The following request shows how to connect the same vehicle to a second customer:

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

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

Connect by Custom Nodes

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

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

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

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

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

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

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

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

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.

An example request is shown below:

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

The example response below shows that the customer (cust_1111111) does not have the tag (vip), but is in a network with other customers who do have the tag:

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

Graph Feature Limits

Searching ends when fraud is found

If fraud is found while searching the network (identified either as an unforgiven dispute or a reviewed fraudster), the search will not continue any deeper into the network. The remaining nodes at the current depth will be examined and then the results will be returned.

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), the search will stop and the maxDepthReached field will be set 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?