Connect API Reference

Ravelin Connect allows you to create a connected graph of your customers using common attributes such as emails, phone numbers, deviceIds 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. The results are available immediately in the Connect dashboard.

Connecting

Events are sent to Ravelin as JSON objects to a POST endpoint over HTTPS. Ravelin Connect’s API lives at https://api.ravelin.com/v2/connect.

Ravelin uses API keys to allow access to the API. You can register a new Ravelin API key by contacting your account manager. Ravelin expects the API key to be included in the authorization header for all API requests i.e.

## Using curl, pass the authentication header with each request
curl "https://api.ravelin.com/v2/auth/checktoken" \
  -H "Authorization: token sk_live_XXXXXXXX"

When submitting a JSON request, make sure to include the JSON mime-type in the Content-Type HTTP header.

Content-Type: application/json; charset=utf-8

Your secret API keys can be reached from https://dashboard.ravelin.com/#/developer/api/keys.

Connecting Customers

To add a customer to Ravelin Connect you will need to send Ravelin the customer’s details to the API. If you add another customer with matching attributes they will be linked together on the Connect graph view.

Customers can be connected or linked together via a number of different common attributes

  • email address
  • telephone number
  • device identifer
  • payment instrument

Examples follow.

Connect by Email

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

POST /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 /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 /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 /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 /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 /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 /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 /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
}

Adding Chargebacks

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

Customer with Chargeback

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

POST /v2/connect HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
    "customerId": "cust_1111111",
    "chargeback": {
        "amount": 373,
        "chargebackId": "ch_8_5a8d1bea-6d38-11e7-8f2c-9801a79b5e51",
        "currency": "gbp",
        "gateway": "pay1",
        "gatewayReference": "zzpza",
        "reason": "insufficient funds",
        "status": "lost"
    },
    "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 customer support 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 /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 /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
}

Graph Features

You can retrieve features of the graph centred around a target customer with the following request. The features relate to:

  • The number of hops to a chargeback or reviewed fraudster (-1 is used when there is no chargeback or reviewed fraudster within depth)
  • The number of each node type.
  • The Min, Max and Mean degree (count of connections) of each node type.

Each feature is calculated within depth hops of the target node. Counting stops when a chargeback or reviewed fraudster is reached.

GET /v2/connect/customers/61283761287361?depth=10 HTTP/1.1
Authorization: token ...

HTTP/1.1 200 OK
Content-Type: application/json
{
    "timestamp": 1532439836,
    "customerID": "61283761287361",
    "count" : 60,
    "customerCount": 5,
    "cardCount": 4,
    "chargebackCount": 1,
    "reviewedFraudsterCount": 1,
    "reviewedGenuineCount": 0,
    "emailCount": 4,
    "phoneCount": 3,
    "deviceCount": 4,
    "hopsToFraud": 3,
    "customerDegreeMin": 2,
    "customerDegreeMean": 3.5,
    "customerDegreeMax": 4,
    "cardDegreeMin": 1,
    "cardDegreeMean": 1.2,
    "cardDegreeMax": 2,
    "emailDegreeMin": 1,
    "emailDegreeMean": 1.3,
    "emailDegreeMax": 3,
    "phoneDegreeMin": 1,
    "phoneDegreeMean": 1.1,
    "phoneDegreeMax": 2,
    "deviceDegreeMin": 1,
    "deviceDegreeMean": 1.472,
    "deviceDegreeMax": 3
}

Batch Upload

The same API is available under the path /v2/backfill/connect to be used for batch upload. This API has a higher, separate rate limit to /v2/connect so that you do not interrupt your production system’s use of Ravelin Connect. The additions are processed asynchronously to the request.

POST /v2/connect

The full JSON Schema by which this endpoint is validated is available at https://api.ravelin.com/v2/connect/schema.json. Additionally, authenticated POST requests can be made to https://api.ravelin.com/v2/connect/validate which will return a 400 if the request does not validate, with explanations.

Name Type Description Example
timestamp
required
link integer

The time at which this data playload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A unix timestamp as an integer count of milliseconds, or nanoseconds since 1970-01-01T00:00 UTC.

1479231064920
customerId
optional
link string

The ID of the customer you want to link to in the graph. Mutually exclusive with customer.

customer
optional
link object

The customer you want to link to in the graph. Mutually exclusive with customerId. (See customers.)

Show definition keyboard_arrow_down
paymentMethods
optional
link array

Payment methods you want to associate the customer with. (See payment methods.)

Show definition keyboard_arrow_down
deviceId
optional
link string

The ID of the device to which you want to link the customer. Mutually exclusive with device.

device
optional
link object

The device to which you want to link the customer. Mutually exclusive with deviceId.

Show definition keyboard_arrow_down
chargeback
optional
link object

The chargeback to which you want to link the customer. (See chargebacks.)

Show definition keyboard_arrow_down
review
optional
link object

The manual review you would like to apply to the customer, stating whether your analyst believes them to be fraudulent or genuine.

Show definition keyboard_arrow_down

Example

POST /v2/connect HTTP/1.1
Content-Type: application/json

{
  "timestamp": 1479231064920,
  "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": "GB",
    "country": "GB",
    "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": "GB",
        "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": "GB",
          "poBoxNumber": "1234",
          "postalCode": "E1 1AA",
          "custom": {
            "foo": "bar",
            "biz": "baz",
            "one": 1
          }
        },
        "billingFamilyName": "Smith",
        "billingGivenName": "John"
      }
    }
  ],
  "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": "TODO",
    "gatewayReference": "abc-123-XYZ",
    "reason": "TODO",
    "status": "TODO",
    "amount": 15212,
    "currency": "GBP",
    "disputeTime": 1479302798,
    "custom": {
      "foo": "bar",
      "biz": "baz",
      "one": 1
    }
  },
  "review": {
    "label": "FRAUDSTER",
    "comment": "Definitely a fraudster.",
    "reviewer": {
      "name": "tom@mycompany.com",
      "email": "Tom"
    }
  }
}