Login

To request a recommendation at this endpoint use the Login checkpoint.

Account takeover recommendations need to be enabled on your account before they can be used. Please speak to your account manager about enabling account takeover recommendations.

Field Status Definitions
Required Required fields must be sent. If the data is not sent Ravelin will return an error.
Important Important fields are crucial for performance where that data is relevant for your business.
Optional Optional fields are additional data points that can be shared with Ravelin.
These fields are unlikely to impact performance but may be visible in the Ravelin dashboard.

POST api.ravelin.com/v3/login

Show all
timestamp integer required

Unix timestamp with milliseconds (nanoseconds also accepted)

login object required

The login used by the customer.

Show definition
device object optional

While Device is not a required field on the login event, it is highly recommended as it is a vital signal to account breaches. The most important Device fields are deviceId and ipAddress. deviceId can be generated using our JavaScript and mobile libraries.

Show definition
location object optional

Location is optional as we are aware you will not typically have a location at login time. If you do have location as part of your flow this can be very useful to localise ongoing or repeat attackers.

Show definition
POST https://api.ravelin.com/v3/login HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "login": {
    "username": "jsmith123@example.com",
    "success": false,
    "authenticationMechanism": {
      "password": {
        "passwordHashed": "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f",
        "emailPasswordSHA256": "1869a65c576bf844f00b2ef88aa352ffd2d5b348a383720772c0c416470fc74e",
        "passwordSHA1SHA256": "fe38f41dc87ffd6b26e432b7f9cb3475d5c1899edacb453c70ac1dcaafd73d26",
        "success": false,
        "failureReason": "BAD_PASSWORD"
      },
      "social": {
        "success": false,
        "failureReason": "TIMEOUT",
        "socialProvider": "facebook"
      },
      "oneTimeCode": {
        "success": false,
        "failureReason": "INVALID_CODE"
      },
      "u2f": {
        "success": false,
        "failureReason": "INVALID_KEY"
      },
      "rsaKey": {
        "success": false,
        "failureReason": "INVALID_KEY"
      },
      "smsCode": {
        "phoneNumber": "+447907283546",
        "success": false,
        "failureReason": "INVALID_CODE"
      },
      "magiclink": {
        "transport": "email",
        "phoneNumber": "+447907283546",
        "success": false,
        "failureReason": "INVALID_LINK"
      },
      "recaptcha": {
        "success": false,
        "failureReason": "TIMEOUT"
      },
      "bioMetric": {
        "success": false,
        "failureReason": "TIMEOUT"
      },
      "pushNotification": {
        "success": false,
        "failureReason": "INTERNAL_ERROR"
      }
    },
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    },
    "customerId": "abc-123-XYZ"
  },
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  },
  "location": {
    "country": "GBR",
    "postalCode": "E1 1AA",
    "latitude": 51.503252,
    "longitude": -0.127899,
    "addresseeName": "John Smith",
    "street1": "123 fake st.",
    "street2": "floor 4, flat 48",
    "neighbourhood": "Hackney",
    "zone": "1",
    "city": "London",
    "region": "California",
    "poBoxNumber": "1234"
  }
}

Response

Show all
status integer

The HTTP response status code.

success boolean

If the request was successful this field is true.

timestamp string

A timestamp (ISO 8601) indicating when we finished handling the request.

data object
Show definition

Contains details about whether the credentials have been found in our breached credentials database.

Show definition
customerChanges array
deprecated
Show definition
{
  "status": 200,
  "success": "true",
  "timestamp": "2021-08-27T12:19:31Z",
  "data": {
    "customerId": "39f54f7c-8ed7-41f8-5260-09881f69f675",
    "action": "ALLOW",
    "score": 20,
    "source": "RAVELIN",
    "scoreId": "4fd50782-b9f7-48be-64e1-820c7cf6dd51",
    "ato": {
      "loginId": "login-123",
      "action": "ALLOW",
      "rules": {
        "passiveAction": "REVIEW",
        "triggered": [
          {
            "ruleName": "Allow trusted customers",
            "ruleId": 123,
            "ruleVersion": 2,
            "triggered": true,
            "description": "This describes the rule.",
            "action": "ALLOW"
          }
        ]
      }
    }
  },
  "credentialStatus": {
    "passwordBreached": false,
    "usernameBreached": false
  },
  "customerChanges": [
    {
      "changeId": "9aa92ad0-ee23-4293-7fee-396dc738b195",
      "customerId": "39f54f7c-8ed7-41f8-5260-09881f69f675",
      "timestamp": "2021-08-27T12:19:31.035741497Z",
      "changeType": "DEVICE",
      "newValue": {
        "device": {
          "deviceId": "d61096b5-4ef8-4404-6666-eb9e8df1d754",
          "deviceType": "phone",
          "deviceManufacturer": "Samsung",
          "deviceModel": "SM-G960F",
          "deviceOS": "android",
          "ipAddress": "1c14:d7a:124f:3a00:400:cb7b:e4aa:af92",
          "userAgent": "Mozilla/5.0 (Linux; Android 10; SM-G960F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.152 Mobile Safari/537.36",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "ipAddr": {
          "ipAddress": "123.45.67",
          "timestamp": "2021-08-27T12:19:31.035741497Z",
          "city": "London",
          "countryISO": "GBR",
          "continentISO": "EU",
          "isp": "BT"
        },
        "email": {
          "email": "test@ravelin.com",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "password": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "telephone": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "deliveryAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.01",
          "timestamp": "2021-08-27T12:19:31Z"
        },
        "billingAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.0",
          "timestamp": "2021-08-27T12:19:31Z"
        }
      },
      "previousValue": {
        "device": {
          "deviceId": "d61096b5-4ef8-4404-6666-eb9e8df1d754",
          "deviceType": "phone",
          "deviceManufacturer": "Samsung",
          "deviceModel": "SM-G960F",
          "deviceOS": "android",
          "ipAddress": "1c14:d7a:124f:3a00:400:cb7b:e4aa:af92",
          "userAgent": "Mozilla/5.0 (Linux; Android 10; SM-G960F) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.152 Mobile Safari/537.36",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "ipAddr": {
          "ipAddress": "123.45.67",
          "timestamp": "2021-08-27T12:19:31.035741497Z",
          "city": "London",
          "countryISO": "GBR",
          "continentISO": "EU",
          "isp": "BT"
        },
        "email": {
          "email": "test@ravelin.com",
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "password": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "telephone": {
          "timestamp": "2021-08-27T12:19:31.035741497Z"
        },
        "deliveryAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.0",
          "timestamp": "2021-08-27T12:19:31Z"
        },
        "billingAddress": {
          "streetAddress1": "1 Fraud Street",
          "streetAddress2": "Ravelin House.",
          "addressCountry": "Great Britain",
          "addressCountryISO": "GBR",
          "postOfficeBoxNumber": "123",
          "postalCode": "EC1V 9GB",
          "latitude": "51.0",
          "longitude": "1.0",
          "timestamp": "2021-08-27T12:19:31Z"
        }
      },
      "verificationURL": "http://api/v2/change/verify?id=cmF2vbWVRlc3RCpzlhYTkyYWQwLRjNzM4YjN1cFsR1dHWVLWxZueELZWxpbnLTlvZ2ltNDI5My03ZmVlE5NQuLW3TCp2yM5NmZ0MjM==",
      "changeSetId": "aeb87294-a02d-4746-7d45-34770d51f308"
    }
  ]
}

Feedback