Requesting Recommendations

This page explains how to request recommendations when a user attempts to register for an account.

On this page:

Supported registration types

We support registration recommendations for both customer and supplier accounts.

The process for requesting recommendations is the same for both types of account.

The only differences are the data you provide in the request and the point at which you request the recommendation.

Before you request a recommendation

Before you request a recommendation, you should have already completed the following steps:

Registration form validation

Validating the form data can include checking that the email address or phone number is in the correct format and that the password is strong enough.

It should also include checking that the email address or phone number is not already registered.
Email or phone verification (if required)

If you require the user’s email or phone to be verified before an account is created, you should request a recommendation after the user has successfully verified their email address or phone number, since this is a signal that the registration is genuine.

You should include details of the completed verification checks in the recommendation request.

If you perform email or phone verification after the account is created, and not as part of registration, it is not necessary to do this before requesting a recommendation.

When to request recommendations

There are two options for when to request a recommendation.

Before you create the account
By requesting a recommendation before you create the account, you can block the account creation if we recommend that you prevent the registration. This is our recommended approach since it avoids unnecessary account creation.
After you create the account
If it is not possible to request a recommendation before creating the account, you can you request a recommendation after the account has been created. However, if we recommend that you prevent the registration you will need to be able to block access to the account.

Your Ravelin integration manager will discuss these options with you and help you decide which is the best option for your integration.

How to request recommendations

To request a recommendation send a request to our Registration endpoint using the Account Registration Checkpoint. To use the Account Registration Checkpoint add score=accountRegistration as a query parameter to the URL. This request will typically be made from your backend.

The amount of data you can provide about the registration, user, and device will affect the options available to us when making a recommendation. We recommend that you provide as much data as possible to ensure that we can make the most accurate recommendation. See our Registration Endpoint API reference for all the supported fields.

The request for a recommendation should be sent with the registration.success field omitted since this is used to indicate that either the account has been created or that the account creation was blocked. For more information on how to update us on the outcome of the registration attempt, see Sending Updates.

Customer Registration Example

A customer registration request should contain the customer object.

An example request for a customer registration is shown below:

POST https://api.ravelin.com/v2/registration?score=accountRegistration HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "registration": {
    "username": "jsmith123@example.com",
    "registrationMechanism": {
      "password": {
        "passwordHashed": "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f"
      }
    }
  },
  "customer": {
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM"
  },
  "device": {
    "deviceId": "a1b2c3d4e5f6",
    "type": "phone",
    "manufacturer": "google",
    "model": "Pixel XL",
    "os": "android",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "location": {
      "latitude": 51.503252,
      "longitude": -0.127899
    }
  }
}

Supplier Registration Example

A supplier registration request should contain the supplier object.

An example request for a supplier registration is shown below:

POST https://api.ravelin.com/v2/registration?score=accountRegistration HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "registration": {
    "username": "jsmith123@example.com",
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    },
    "registrationMechanism": {
      "password": {
        "passwordHashed": "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f"
      }
    }
  },
  "supplier": {
    "name": "John Smith",
    "groupName": "Burger Chain",
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "GBR",
    "type": "driver",
    "level": "gold",
    "employmentType": "selfEmployed",
    "transportType": "car",
    "category": "private-hire"
  },
  "device": {
    "deviceId": "a1b2c3d4e5f6",
    "type": "phone",
    "manufacturer": "google",
    "model": "Pixel XL",
    "os": "android",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "location": {
      "latitude": 51.503252,
      "longitude": -0.127899
    }
  }
}

Response Examples

An example response where we recommend allowing the user to register is shown below:

{
  "status": 200,
  "timestamp": 1512828998826,
  "data": {
    "action": "ALLOW",
    "customerId": "abc-123-xyz",
    "registrationId": "gfd-456-ert"
  }
}

An example response where we recommend preventing the user from registering is shown below:

{
  "status": 200,
  "timestamp": 1512828998826,
  "data": {
    "action": "PREVENT",
    "source": "RULE",
    "registrationId": "fgh-234-asd",
    "rules": {
      "passiveAction": "PREVENT",
      "triggered": [
        {
          "ruleId": 123,
          "ruleVersion": 1,
          "state": "active",
          "action": "PREVENT",
          "description": "Registration email is from a disposable email provider is equal to true."
        }
      ]
    }
  }
}

How to handle recommendations

The data.action field in the response contains our recommendation, you should use this to determine how you handle the registration attempt. The table below explains the actions.

Action	What it means
`ALLOW`	Allow the customer or supplier to register.
`PREVENT`	Prevent the customer or supplier from registering.

There are other fields in the response which will provide more detail as to why we have made the recommendation.

See our Registration Endpoint response API reference for all the supported fields.

Next steps

Send updates when accounts are created

Test your integration

Feedback

Was this page helpful?