insuranceUserStats API Endpoint v3

Zendrive’s insuranceUserStats v3 API retrieves the insurance score for users of the Zendrive White Label App (WLA).

The insuranceUserStats v3 API Endpoint allows the user to select a custom date range based on start_date and end_date, along with model_id (model_id could be Score, Pricing or Risk).

GET https://insurance-api.zendrive.com/v3/insurance/driver_id/<driver_id>/score

Headers

Name	Type	Description
Authorization*	String	APIKEY

200: OK (Response as per Response Schema)

400: Bad Request Invalid Request

{"error":<error_message_string>,
"error_code": <error_code_string>,
"success": false}

401: Unauthorized

{"error": "Invalid ApiKey"}

403: Forbidden Access denied

{"error": "Access Denied"}

500: Internal Server Error

  {"error": "Internal Server Error"}

503: Service Unavailable

Sample Request

https://insurance-api.zendrive.com/v3/insurance/driver_id/00000/score?start_date=2023-05-01&end_date=2023-07-18&model_id=pl_model_20&fields=info,driving_behaviour

Primary Request Parameters

Parameter	Type	Description
start_date	String	Format: YYYY-MM-DD. The start date of the time period, from current date to any date within the last 6 months.
end_date	String	Format: YYYY-MM-DD. The end_date of the time period, including the current date.
model_id	String	Format: [model_name] The ID of the Scoring Model to be used for generating the score. Multiple models can be used. Supported models: v1, ‘v2, pl_model_20, pl_model_rsa_21,
Fields (info, driving_behavior)	String

Request Parameter: Fields

Field names can be a comma-separated list. If user does not specify a field, no field data will be returned.

Parameter	Type	Description
info	String	Returns driver-related information that is not part of the insurance scoring model, such as total miles driven, trip count, total drive hours, and nighttime driving hours.
driving_behavior	String	Returns grades and scores for driving events such as hard brake, hard turn, rapid acceleration, phone use, and over-speeding.

Request Parameter: Score Details

Please make sure to include the required parameters and headers in your API requests.

Parameter	Type	Description
event_scores	String	Event scores can range in value from 0.0 to 100.0, with 0.0 being the lowest, and 100.0 being the highest.
event_grade	String	Returns an integer value between 1 and 5, with 1 being the lowest, and 5 being the highest.
insurance_grade	String	Transforms the insurance score to a value between 0 - 100, with 0 being the lowest, and 100 being the highest.

Sample Result

{
    "success": true,
    "driver_id": "00000",
    "scores": [
        {
            "model_id": "pl_model_20",
            "start_date": "2023-05-01",
            "end_date": "2023-07-18",
            "score": 0.06146224470030697,
            "driving_behaviour": {
                "event_grades": {
                    "hard_brake": 3,
                    "hard_turn": 5,
                    "over_speeding": 5,
                    "phone_use": 5,
                    "rapid_acceleration": 5
                },
                "event_scores": {
                    "hard_brake": 43.0,
                    "hard_turn": 0.0,
                    "over_speeding": 0.0,
                    "phone_use": 2.0,
                    "rapid_acceleration": 0.0
                },
                "insurance_grade": 94
            },
            "info": {
                "nighttime_driving_hours": 0.0,
                "total_driving_hours": 1.7133575000000003,
                "total_trips": 17,
                "total_miles": 22.685119848620335
            }
        }
    ]
}

Response Status Codes

The following is a list of all possible response status codes to the insurance score request:

Response Status	Response Status Code	Description
Internal Server Error	500	{"error": "Internal Server Error"}
Service unavailable	503
Invalid request	400	{"error":<error_message_string>, "error_code": <error_code_string>, "success": false}
Unauthorized	401	{"error": "Invalid ApiKey"}
Access denied	403	{"error": "Access Denied"}
Invalid resource	404
Success - Ok	200	As per response schema

Error Codes

Here's the list of error codes that can be returned in response to the request schema.

Scenario	Error Codes
Invalid Date	INVALID START_DATE OR END_DATE
Invalid Date Format	INVALID DATE FORMAT
Application Format Expired	INVALID_MODEL
Invalid JSON	INVALID DATE
Application Model Expired	INVALID_DATE
Invalid Application Model	INVALID MODEL VERSION
Invalid User Id	INVALID USER ID