insuranceUserStats API Endpoint v1 (Deprecated)

The insuranceUserStats API Endpoint v1 is deprecated. For the latest version, refer to insuranceUserStats API Endpoint v3.

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

POST https://insurance-api.zendrive.com/v1/insurance/driver_id/<driver_id>/score

This API returns the insurance scores of a user for a period of 30 days. Sample URL:

https://insurance-api.zendrive.com/v1/insurance/driver_id/user_123/score

Headers

Name	Type	Description
Authorization*	APIKEY <apikey>

Design Recommendations

Zendrive's insuranceUserStats v1 API endpoint comes with the following design recommendations:

• The insuranceUserStats v1 endpoint will provide insurance scores corresponding to each model_id and end_date combination passed as part of request payload. The score will be calculated for a 30-day period ending on the specified end_date.

• This endpoint should be called from the backend and not from WLA. Exposing this API via WLA will result in security concerns related to API key.

Request Payload

The following parameters and variables need to be present in the API request payload:

Field	Description
List of models	List of models needed to arrive at the insurance score for the user.
Start and end dates for computing the insurance score.	Date format: YYYY-MM-DD end_date: Insurance score is fetched for 30 days ending on this day. Valid values: Between '3 days before today's date' and '183 days before today's date' For example, if today's date is 2021-01-25 then the end_date should be between 2021-01-22 and 2020-07-27.
model_id	Insurance model identifier for which the customer is being scored. For example: pl_model_20, pl_model_21.

Sample Request URL

https://insurance-api.zendrive.com/v1/insurance/driver_id/user_123/score

Sample Request Schema

{
    "models": [
        {
            "model_id": "sample_model",
            "end_date": "2021-01-01"
        },
        {
            "model_id": "sample_model",
            "end_date": "2020-12-31"
        }
    ]
}

Sample Response Payload

The following table provides a sample of a possible payload retuned in response to the Request Schema sent to the insurance score API. The response payload header provides the model_id, start_date, end_date, score or error. The model_id is the same as was sent in the Request Schema, while the start_date and end_date refer to the date range for which the insurance score is calculated. If the insurance score is not found, then the response schema returns an error code.

Field	Description
driver_id	User identifier sent as part of the insuranceScore endpoint.
scores	List of score objects for requested insurance models and dates. model_id - Insurance model identifier start_date - start of score date range (end_date - 29days) end_date - end of score date range (Same as passed in request payload) score - Value of the score for user generated based on above three parameters error - When score is not available message - Error message for reasoning about absence of score value code - Error code for reasoning about absence of score value

Sample Response Schema

{
    "driver_id": "12345",
    "scores": [
        {
            "model_id": "sample_model",
            "start_date": "2020-12-03",
            "end_date": "2021-01-01",
            "score": 25
        },
        {
            "model_id": "sample_model",
            "start_date": "2020-12-02",
            "end_date": "2020-12-31",
            "error": {
                "message": "Found not enough scoring trips of driver",
                "code": "NO_SCORE_FOUND"
            }
        }
    ]
}

Response Status Codes

List of all possible response status codes in response to the request for the insurance score:

Error	Error Code	Error 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"}
OK	200	As per response schema

Response Error Codes

The list of possible error codes in response to the request schema:

Scenario	Error Codes
Invalid payload format, failed json schema	INVALID_DATA
Invalid Json, parsing error	INVALID_DATA
Invalid end date	INVALID_DATE
Application Model expired	INVALID_DATE
Invalid Application Model	INVALID_MODEL
No score found	NO_SCORE_FOUND

Sample Request and Response

curl --location --request POST 'https://insurance-api.e/driver_id/C1000537965/score' \
--header 'Authorization: APIKEY FBUp2MTtB9soC2519bHkxEeVkPDBOkTV' \
--header 'Content-Type: application/json' \
--data-raw '{
    "models": [
        {
            "model_id": "colombia_v1",
            "end_date": "2021-09-18"
        },
        {
            "model_id": "colombia_v1",
            "end_date": "2021-08-21"
        }
    ]
}'

{
    "driver_id": "C1000537965",
    "scores": [
        {
            "model_id": "colombia_v1",
            "start_date": "2021-08-20",
            "end_date": "2021-09-18",
            "score": 45.0
        },
        {
            "model_id": "colombia_v1",
            "start_date": "2021-07-23",
            "end_date": "2021-08-21",
            "error": {
                "message": "Found not enough scoring trips of driver",
                "code": "NO_SCORE_FOUND"
            }
        }
    ]
}