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.