PreQual Coverage Quickstart Guide

PreQual Coverage creates a driving score based on a user and their Motor Vehicle Record (MVR) data. This documentation includes everything needed to successfully get a PreQual Coverage score. If you have any additional questions around using PreQual APIs please contact your Customer Success team.

All requests to Arity require authentication and all applications must be registered with us.


  1. Client ID and Client Secret
    Get your Client ID and Client Secret. These have already been created and approved by Arity, and have been sent to you. Contact us if you need help locating them.
  2. Access token
    Every call for a PreQual Coverage score requires authorization through an access token.
    Use generateToken to generate a b2b-scope access token by sending your Client ID and Client Secret. This access token expires every hour and must be passed in the header of all subsequent API calls.
  3. User
    We require a user to generate a coverage score. In PreQual user refers to the driver being scored. A dateOfBirth, in the format of YYYY-MM-DD, and homeZip, in the format of ##### or #####-####, are not required to create a user, however they are required to get a PreQual Coverage Score.
    New user - Use the createUser method to create a new user. You can specify the userId or leave it blank and let Arity generate it for you. To create a user with an auto-generated id leave the userId field NULL or remove the key-value pair entirely.
    Update user - Use the updateUser method to add data to a user that has already been created. You will need to provide the userId to be updated.

    *Note: when you createUser they will be assigned pending for their enrollmentStatus in Step 6.

  4. User MVR
    In addition to userId data, we require Motor Vehicle Record (MVR) data for that user in order to generate a coverage score. Depending on your organization, you may have Checkr or Samba as your MVR data source. You must provide the full MVR record from your source that includes all violations and accident data. We cannot accept the “light” version MVR that gives a simple pass/fail. You can download a sample of both MVR file sources from the Postman Documentation.

    You will never update an MVR record; you will only create new ones with this endpoint. PreQual Coverage creates a score on the latest MVR created for a user.
    Use createCheckrMVR or createSambaMVR to provide Checkr or Samba MVR data for a userId

    *Note: all MVR data fields are passed in directly from the MVR provider (Checkr or Samba).

  5. Retrieve user score
    Once we have the user and MVR data we can retrieve a coverage score. A PreQual Coverage Score is created based on the most recent MVR provided for a user.

    PreQual Coverage Score breakdown: Riskiest drivers = 0-300, Median score = 500, Safest drivers = 600-900
    Use getPrequalCoverageScore to retrieve the coverage score for the userId. 
  6. Set/change user status
    Now that you have a score, you may want to change your user’s status to indicate whether or not they have been approved to use your platform. A user’s status can be changed at any time to any of the options. Enrollment has no impact on the user's score. This allows you to keep track of the user's status in your program. User status is not case sensitive.

    Status options are: accepted, pending, rejected.
    Use enrollUser to change the enrollmentStatus of the userId. 

    *Note: the user is given a default status of pending when you createUser in Step 3.

  7. Retrieve user details
    At any time following successful creation of a userId, you may retrieve user information with the getUser endpoint
    Use getUser to retrieve details for the userId.

Troubleshooting

If you receive an error message from getPrequalCoverageScore, add the missing user data using updateUser then try to getPrequalCoverageScore again.

If required data is missing, you will receive a response saying what data is needed to complete the score. You will need to update the userId with any required data to successfully retrieve a PreQual Coverage score.


authorization-controller

Method
Description

POST

generateToken

https://api.arity.com/platform/oauth/v1/token

Generate an access token to use for authorization on subsequent API calls. Token expires every hour and must be passed in the header of all subsequent API calls. Required fields: Client ID and Client Secret

user-controller

Method
Description

POST

createUser

https://api.arity.com/shared-mobility-insights/v2/users

Create a new user (the driver you want scored). User will receive a default enrollment status of pending. Required fields: userID (use NULL to have one assigned), dateOfBirth, homeZip (required to get a PreQual score)

GET

getUser

https://api.arity.com/shared-mobility-insights/v2/users/{userId}

Retrieve all of the user data we have on a userID including the enrollmentStatus. Does not retrieve MVR for user. Required fields: userID

PUT

updateUser

https://api.arity.com/shared-mobility-insights/v2/users/{userId}

Update and replace a user's data entirely but not their MVR. You cannot update a userID. Required fields: userID

PUT

enrollUser

https://api.arity.com/shared-mobility-insights/v2/users/{userId}/enrollment

Update a user’s enrollment status. This does not impact user’s PreQual score. Status can be changed at any time. Status can be: accepted, pending, rejected. Required fields: userID, enrollmentStatus

PATCH

patchUser

https://api.arity.com/shared-mobility-insights/v2/users/{userId}

Update and replace a user's data partially but not their MVR. You cannot update a userID. Required fields: userID

mvr-controller

Method
Description

POST

createCheckrMvr

https://api.arity.com/shared-mobility-insights/v2/users/{userId}/checkr-mvr

Create a Checkr formatted MVR for a userID. You must provide the full MVR record including all violations and accident data. User’s score will reflect the most recent MVR provided. Required fields: userID, Complete CheckrMVR

POST

createSambaMvr

https://api.arity.com/shared-mobility-insights/v2/users/{userId}/samba-mvr

Create a Samba formatted MVR for a userID. You must provide the full MVR record including all violations and accident data. User’s score will reflect the most recent MVR provided. Required fields: userID, Complete SambaMVR

prequal-controller

Method
Description

GET

getPrequalCoverageScore

https://api.arity.com/shared-mobility-insights/v2/users/{userId}/prequal-coverage-score

Get the user’s PreQual Coverage Score. PreQual scores are based on most recent MVR. Be sure all user data is the most recent before calling a score. Required fields: userID

© 2019 Arity, LLC. All rights reserved.  | Privacy Policy | Terms of Use | Legacy APIs