NAV
shell python javascript

Introduction

This document describes the usage of the Tint API version 2.

Tint APIs enable any company to embed insurance into their own product. AI-powered risk scoring, quotes, decisions, policy bindings, claims can all be managed on Tint app. All of your product configuration is customizable on Tint App.

You need an API key to interact with our API. If you need more information, please get in touch with us at support@tint.ai or via your dedicated Slack channel.

Environments

Production Environment

Tint API only allows https calls.

It is currently in its v2 version, for which the base URL is https://api.tint.ai/v2.

Sandbox Environment

Sandbox environment is the recommended way to test your integration with the Tint API, either on your development or staging environment (but not in production).

Our sandbox environment is available on https://api-sandbox.tint.ai/v2 endpoint.

API is the same than in production. If external data providers have a sandbox environment, all your external data calls would be redirected to it.

Your sandbox API key would be provided by the Tint team. It is different from your production one.

Authentication

curl \
    -X POST \
    -H "x-api-key: SECRET_API_KEY" \
    "https://api.tint.ai/v2/policy"
import requests

requests.post(
    "https://api.tint.ai/v2/policy",
    headers={
      "x-api-key": "SECRET_API_KEY"
    }
)
fetch('https://api.tint.ai/v2/policy', {
    method: 'POST',
    headers: {
        'x-api-key': 'SECRET_API_KEY',
    },
});

All endpoints of the Tint API require clients to provide their API key in the X-API-Key header.

Warning: You should never share your API key. This is a sensitive piece of information. Please contact us immediately at support@tint.ai if you believe your API key has been leaked. We'll update it and send you the new one to prevent some malicious use of the lost key.

Error Handling

Error Structure

{
    "error": {
        "code": "INVALID_REQUEST",
        "message": "Invalid request",
        "requestId": "c4e5fcb8-5e44-4dd6-9ac0-d71429cdd44c",
        "details": {
            "age": ["min value is 0"]
        }
    }
}

Every erred response contains an error object as described below:

All endpoints would use the same error structure for the body, whatever the response code.

Error Codes

Error Code HTTP Status Description
INVALID_REQUEST 400 The list of provided parameters was invalid.
ACCESS_DENIED 403 Missing or invalid token (should be in the x-api-key header)
NOT_FOUND 404 The endpoint, or one of your entity, has not been found.
METHOD_NOT_ALLOWED 405 The method used to request and endpoint is not supported (eg. POST instead of GET)
UNSUPPORTED_MEDIA_TYPE 415 The request header Content-Type was not found or invalid (the Tint API only supports application/json)
INTERNAL_ERROR 500 Something wrong happened on our side. We have been alerted, no need to contact us.
PREDICTION_ERROR 500 An error occured while calculating one of your prediction. There are probably some unhandled edge cases in your model configuration.

Entities

Tint API always returns the same entities, depending on the endpoint. All entity details are described in this section.

Policy

{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "session_identifier": {
        "user_id": "unique-user-id"
    },
    "insurance_product_version": {
        "id": "38855d0d-4305-468c-bde7-5246f82667bd",
        "name": "+10 margin (Jan. 2021)"
    },
    "policy_details": {
        "custom_id": "P-7600BN1",
        "start_date": "2019-10-30T12:00:00.00Z",
        "end_date": "2019-11-02T12:00:00.00Z",
        "asset": {
            "custom_id": "T-09918",
            "type": "car",
            "vehicle_make": "Toyota",
            "vehicle_model": "Camry",
            "vehicle_year": 2018
        },
        "renter": {
            "custom_id": "U-73610",
            "email_address": "john.doe@example.com"
        }
    },
    "created_at": "2019-08-11T12:42:51.00Z",
    "updated_at": "2019-08-11T12:42:51.00Z",
    "effective_date": "2019-09-17T00:00:00.00Z",
    "term_end_date": "2019-09-21T23:59:59.00Z",
    "cancelled_at": null,
    "confirmed_at": null,
    "issued_at": null
}

Policy is the fundamental basis of all other Tint endpoints. It represents a potential contract between an insurer and an insured. It can have one or several coverages.

The list of possible Policy attributes defined under policy_details is fully customizable. It can be retrieved with the Insurance Products endpoint. Please contact us if you need to update it.

Depending on the use case you are tackling with Tint, several entities can be attached to a Policy:

A Policy is represented by the following JSON object:

Insurance Product Version

{
    "id": "4dcd3825-51fd-4f1e-89ad-21dba836e74a",
    "name": "+10% margin (Jan. 2021)"
}

When you create a new policy, this policy is automatically assigned to one of your live product versions.

Versions are provided mainly for analytics purpose, hence are read-only. Login on the Tint app if you need to manage your version.

Claim

{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "type": "broken window",
    "custom_id": "9481BC",
    "gross_value": 4000,
    "net_value": 2500,
    "created_at": "2019-05-28T18:24:45.988336",
    "updated_at": "2019-05-28T18:24:45.988336"
}

Each Claim is attached to a Policy and has the following properties:

All fields but type are optional.

Score

{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "value": 43,
    "status": "DONE",
    "prediction_type": "PHYSICAL_DAMAGE",
    "reject_threshold": 75,
    "reject": false,
    "created_at": "2019-08-11T12:42:51.00Z",
    "updated_at": "2019-08-11T12:42:51.00Z"
}

Score is the result of combining multiple signals from your internal data and external data vendors to quantify the risk of a given policy. It has the following properties:

Insurance Product

{
    "id": "46b051e4-4ccd-4d70-afc9-8e3025be0523",
    "name": "Tint.ai's Insurance Product",
    "slug": "tint-ai-insurance-product",
    "validation_schema": {
        "type": "object",
        "properties": {
            "asset": {
                "type": "object",
                "properties": {
                    "value": {
                        "type": "number",
                        "min": 0
                    }
                },
                "required": ["value"],
                "additionalProperties": false
            },
            "renter": {
                "type": "object",
                "properties": {
                    "age": {
                        "type": "number",
                        "min": 0
                    },
                    "email": {
                        "type": "string"
                    }
                },
                "required": ["value"],
                "additionalProperties": false
            }
        },
        "required": ["value"],
        "additionalProperties": false
    }
}

InsuranceProduct is represented by a JSON object with the following attributes:

InsurancePlan

{
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "name": "Peace of Mind"
}

InsurancePlan represents a set of coverages. It is represented by a JSON object with the following attributes:

Coverage

{
    "name": "Property Damage Protection",
    "description": "Property Damage Protection: Up to $15K",
    "premium": 320,
    "deductible": 2000,
    "limit": 15000,
    "security_deposit": 450,
    "custom_attributes": {
        "order": 2
    }
}

Coverage are returned in every Quote. You can use it to display the coverages provided with a specific InsurancePlan.

Quote

{
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "calculated_premium": 470,
    "insurance_plan": {
        "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
        "name": "Peace of Mind"
    },
    "coverages": {
        "property-damage-protection": {
            "name": "Property Damage Protection",
            "description": "Damage Protection",
            "premium": 470,
            "deductible": 1500,
            "limit": 500000,
            "security_deposit": 450,
            "custom_attributes": {}
        }
    }
}

Quote contains all the information to be displayed on your UI, in order to let your customer purchase a policy. It is represented by a JSON object with the following attributes:

Read the Rating Engine section to know how to retrieve Quotes for a given Policy.

Decision

{
    "type": "PREQUAL",
    "decision": "APPROVED"
}

Read the Decision Engine section to know how to retrieve decisions for a given Policy.

Policy Module

Get Insurance Products

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request GET \
    https://api.tint.ai/v2/insurance-products
import requests

requests.get(
    "https://api.tint.ai/v2/insurance-products",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/insurance-products`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
    }
);
/* Response */
[
    {
        "id": "46b051e4-4ccd-4d70-afc9-8e3025be0523",
        "name": "Tint.ai's Insurance Product",
        "slug": "tint-ai-insurance-product",
        "validation_schema": {
            "type": "object",
            "properties": {
                "asset": {
                    "type": "object",
                    "properties": {
                        "value": {
                            "type": "number",
                            "min": 0
                        }
                    },
                    "required": ["value"],
                    "additionalProperties": false
                },
                "renter": {
                    "type": "object",
                    "properties": {
                        "age": {
                            "type": "number",
                            "min": 0
                        },
                        "email": {
                            "type": "string"
                        }
                    },
                    "required": ["value"],
                    "additionalProperties": false
                }
            },
            "required": ["value"],
            "additionalProperties": false
        }
    }
]

The GET /insurance-products endpoint displays all your available Insurance Products details, including the JSON schema used to validate the attributes you can provide to your policies.

It is especially useful to retrieve the product slugs you need to create policies.

Create a Policy

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request POST https://api.tint.ai/v2/policy \
    --data @- <<EOL
{
    "insurance_product_slug": "my-awesome-product",
    "session_identifier": {
        "user_id": "unique-user-id"
    },
    "policy_details": {
        "id": "B-667091",
        "start_date": "2019-05-15T09:00:00.000000",
        "end_date": "2019-05-18T09:00:00.000000",
        "asset": {
            "id": "T-09918",
            "asset_type": "car",
            "vehicle_make": "Toyota",
            "vehicle_model": "Camry",
            "vehicle_year": 2018
        },
        "renter\": {
            "id": "user1",
            "email_address": "john.doe@gmail.com"
        }
    }
}
EOL
import requests

requests.post(
    "https://api.tint.ai/v2/policy",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        "insurance_product_slug": "my-awesome-product",
        "session_identifier": {
            "user_id": "unique-user-id"
        },
        "policy_details": {
            "custom_id": "B-667091",
            "start_date": "2019-05-15T09:00:00.000000",
            "end_date": "2019-05-18T09:00:00.000000",
            "asset": {
                "custom_id": "T-09918",
                "asset_type": "car",
                "vehicle_make": "Toyota",
                "vehicle_model": "Camry",
                "vehicle_year": 2018
            },
            "renter": {
                "custom_id": "user1",
                "email_address": "john.doe@gmail.com"
            }
        }
    }
)
fetch(
    `https://api.tint.ai/v2/policy`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
        body: JSON.stringify({
            insurance_product_slug: "my-awesome-product",
            session_identifier: {
                user_id: "unique-user-id"
            },
            policy_details: {
                id: "B-667091",
                start_date: "2019-05-15T09:00:00.000000",
                end_date: "2019-05-18T09:00:00.000000",
                asset: {
                    id: "T-09918",
                    asset_type: "car",
                    vehicle_make: "Toyota",
                    vehicle_model: "Camry",
                    vehicle_year: 2018
                },
                renter: {
                    id: "user1",
                    email_address: "john.doe@gmail.com",
                },
            }
        }),
    }
);
/* Response */
{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "session_identifier": {
        "user_id": "unique-user-id"
    },
    "insurance_product_version": {
        "id": "38855d0d-4305-468c-bde7-5246f82667bd",
        "name": "+10 margin (Jan. 2021)"
    },
    "policy_details": {
        "custom_id": "P-7600BN1",
        "start_date": "2019-10-30T12:00:00.00Z",
        "end_date": "2019-11-02T12:00:00.00Z",
        "asset": {
            "custom_id": "T-09918",
            "type": "car",
            "vehicle_make": "Toyota",
            "vehicle_model": "Camry",
            "vehicle_year": 2018
        },
        "renter": {
            "custom_id": "U-73610",
            "email_address": "john.doe@example.com"
        }
    },
    "created_at": "2019-09-17T00:00:00.00Z",
    "updated_at": "2019-09-17T00:00:00.00Z",
    "confirmed_at": null,
    "issued_at": null,
    "effective_date": null,
    "term_end_date": null,
    "cancelled_at": null
}

To create a new Policy, you have to call the POST /v2/policy endpoint, passing the related insurance product (via the insurance_product_slug property), the policy_details, and eventually a unique identifier in session_identifier in the request body.

The insurance_product_slug can be retrieved using the insurance products list endpoint.

The policy_details is a set of attributes, giving more details about the ongoing policy: personal insured informations, asset value, etc. The schema of this object is fully customizable. Contact us if you need to update it.

Even if some fields of the policy_details are optional, the more fields you send to the API, the more control you will have from the app to manage and customize the insurance product without requiring additional engineering efforts.

When rolling out new versions of your insurance product using Tint, you'll want to keep a consistent experience for a given customer. For Tint to identify a given customer and ensure a consistent experience, you can set a session_identifier property, containing any identifying data your have, i.e. a session ID, user ID, account ID, IP address, browser ID, etc. Essentially, it would be any internal database key you're using to track what "customer" means to you.

If you need to support multiple traffic types or if you have any question about what to key to use for your particular use case, feel free to reach out to us.

Extra GET Parameters

This endpoint also accepts two extra GET parameters to calculate scores and/or quotes at the policy creation level. This is especially useful if you need to call the API only once in your whole workflow.

Adding a withScores=true parameter in the URL would return the list of Scores calculated for the created policy within the scores property.

Same for quotes: adding a withQuotes=true would add an extra quotes key, containing a list of Quotes.

Those parameters are not mutually exclusive, for example the following request is valid:

POST /v2/policy?withScores=true&withQuotes=true

When should I call this endpoint?

Policies are the basis of all other Tint API entities and must be created before you can interact with our API. All other endpoints would require a created policy as an input.

Update a Policy

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request PUT https://api.tint.ai/v2/policy/080949ea-0de3-4690-8cb4-6f558118d7e5 \
    --data @- <<EOL
{
    "policy_details": {
        "payment": {
            "id": "P-VS84990",
            "bank": "Bank of America",
            "name_on_card": "John Doe",
            "card_brand": "VISA",
            "card_type": "credit",
            "success": true,
            "cvc_check_success": true,
            "zip_check_success": true
        }
    }
}
EOL
import requests

requests.put(
    "https://api.tint.ai/v2/policy/080949ea-0de3-4690-8cb4-6f558118d7e5",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        "policy_details": {
            "payment": {
                "custom_id": "P-VS84990",
                "bank": "Bank of America",
                "name_on_card": "John Doe",
                "card_brand": "VISA",
                "card_type": "credit",
                "success": true,
                "cvc_check_success": true,
                "zip_check_success": true,
                "extra": {}
            }
        }
    }
)
fetch(
    `https://api.tint.ai/v2/policy/080949ea-0de3-4690-8cb4-6f558118d7e5`, {
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
        body: JSON.stringify({
            policy_details: {
                payment: {
                    id: "P-VS84990",
                    bank: "Bank of America",
                    name_on_card: "John Doe",
                    card_brand: "VISA",
                    card_type: "credit",
                    success: true,
                    cvc_check_success: true,
                    zip_check_success: true,
                    extra: {}
                }
            }
        }),
    }
);
/* Response */
{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "session_identifier": {
        "user_id": "unique-user-id"
    },
    "insurance_product_version": {
        "id": "38855d0d-4305-468c-bde7-5246f82667bd",
        "name": "+10 margin (Jan. 2021)"
    },
    "policy_details": {
        "custom_id": "P-7600BN1",
        "start_date": "2019-10-30T12:00:00.00Z",
        "end_date": "2019-11-02T12:00:00.00Z",
        "asset": {
            "custom_id": "T-09918",
            "type": "car",
            "vehicle_make": "Toyota",
            "vehicle_model": "Camry",
            "vehicle_year": 2018
        },
        "renter": {
            "custom_id": "U-73610",
            "email_address": "john.doe@example.com"
        },
        "payment": {
            "id": "P-VS84990",
            "bank": "Bank of America",
            "name_on_card": "John Doe",
            "card_brand": "VISA",
            "card_type": "credit",
            "success": true,
            "cvc_check_success": true,
            "zip_check_success": true,
            "extra": {}
        }
    },
    "created_at": "2019-09-17T00:00:00.00Z",
    "updated_at": "2019-09-18T00:00:00.00Z",
    "confirmed_at": null,
    "issued_at": null,
    "effective_date": null,
    "term_end_date": null,
    "cancelled_at": null
}

To update an existing Policy, you have to call the PUT /v2/policy/{policyId} endpoint, passing the updated details in the request body, via the policy_details property

The policyId was returned by the API response when you created the policy.

API returns the updated details of the Policy object, including the PolicyDetails.

Note that you can't change insurance product of an existing policy.

Extra GET Parameters

As for the policy creation, this endpoint also accepts two extra GET parameters to calculate scores and/or quotes at the policy update level:

Those parameters are not mutually exclusive, for example the following request is valid:

PUT /v2/policy?withScores=true&withQuotes=true

When should I call this endpoint?

When new information is generated for a policy.

For example, you first created the policy to get the quotes for the different plans of your insurance product. Now your customer has subscribed to the policy and paid for it. You can add the payment information to the policy, this way, if you score the policy or make a decision whether to accept or reject this policy, all the information available for the policy, including the payment information, is taken into account. Usually, the type of card used for payment (debit, credit) helps building a more robust risk profile and is used by the underlying AI models.

If you have any doubts, feel free to ping us on the best implementation based on your use case on support@tint.ai or via your dedicated Slack channel.

Issue a Policy

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request POST https://api.tint.ai/v2/policy/{policyId}/issue \
    --data @- <<EOL
{
    "subscribed_quote_id": "ae6ab42f-3ffb-4006-954c-769d281787bb",
    "subscribed_coverages": {
        "third-party-liability": {
            "charged_premium": 15
        },
        "physical-damage": {
            "charged_premium": 39
        },
        "road-side-assistance": {
            "charged_premium": 10
        }
    },
    "effective_date": "2020-05-01T12:00:00Z",
    "term_end_date": "2020-05-09T12:00:00Z"
}
EOL
import requests

requests.post(
    "https://api.tint.ai/v2/policy/{policyId}/issue",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        "subscribed_quote_id": "ae6ab42f-3ffb-4006-954c-769d281787bb",
        "subscribed_coverages": {
            "third-party-liability": {
                "charged_premium": 15
            },
            "physical-damage": {
                "charged_premium": 39,
            },
            "road-side-assistance": {
                "charged_premium": 10
            }
        },
        "effective_date": "2020-05-01T12:00:00Z",
        "term_end_date": "2020-05-09T12:00:00Z"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/issue`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }, {
        subscribed_quote_id: "ae6ab42f-3ffb-4006-954c-769d281787bb",
        subscribed_coverages: {
            "third-party-liability": {
                "charged_premium": 15
            },
            "physical-damage": {
                "charged_premium": 39,
            },
            "road-side-assistance": {
                "charged_premium": 10
            }
        },
        effective_date: "2020-05-01T12:00:00Z",
        term_end_date: "2020-05-09T12:00:00Z"
    }
);
// Response
{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "session_identifier": {
        "user_id": "unique-user-id"
    },
    "insurance_product_version": {
        "id": "38855d0d-4305-468c-bde7-5246f82667bd",
        "name": "+10 margin (Jan. 2021)"
    },
    "policy_details": {
        "custom_id": "P-7600BN1",
        "start_date": "2019-10-30T12:00:00.00Z",
        "end_date": "2019-11-02T12:00:00.00Z",
        "asset": {
            "custom_id": "T-09918",
            "type": "car",
            "vehicle_make": "Toyota",
            "vehicle_model": "Camry",
            "vehicle_year": 2018
        },
        "renter": {
            "custom_id": "U-73610",
            "email_address": "john.doe@example.com"
        },
        "payment": {
            "id": "P-VS84990",
            "bank": "Bank of America",
            "name_on_card": "John Doe",
            "card_brand": "VISA",
            "card_type": "credit",
            "success": true,
            "cvc_check_success": true,
            "zip_check_success": true,
            "extra": {}
        }
    },
    "created_at": "2019-09-17T00:00:00.00Z",
    "updated_at": "2019-09-18T00:00:00.00Z",
    "confirmed_at": "2020-12-01T09:44:23.924Z",
    "issued_at": "2020-12-01T09:44:23.924Z",
    "effective_date": "2020-05-01T12:00:00.000Z",
    "term_end_date": "2020-05-09T12:00:00.000Z",
    "cancelled_at": null
}

Issuing a policy permanently commits the changes applied to the policy, including the insured asset, the subscribed coverages, etc. The only way to edit an issued policy is to send an endorsement request, via the UPDATE endpoint. The policy would then need to be re-issued.

To issue a policy, you'll need to call the POST /policy/{policyId}/issue endpoint, passing it all the following parameters:

This endpoint would return the ISSUED policy.

Cancel a Policy

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request POST \
    https://api.tint.ai/v2/policy/{policyId}/cancel
import requests

requests.post(
    "https://api.tint.ai/v2/policy/{policyId}/cancel",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/cancel`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
// Response
{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "session_identifier": {
        "user_id": "unique-user-id"
    },
    "insurance_product_version": {
        "id": "38855d0d-4305-468c-bde7-5246f82667bd",
        "name": "+10 margin (Jan. 2021)"
    },
    "policy_details": {
        "custom_id": "P-7600BN1",
        "start_date": "2019-10-30T12:00:00.00Z",
        "end_date": "2019-11-02T12:00:00.00Z",
        "asset": {
            "custom_id": "T-09918",
            "type": "car",
            "vehicle_make": "Toyota",
            "vehicle_model": "Camry",
            "vehicle_year": 2018
        },
        "renter": {
            "custom_id": "U-73610",
            "email_address": "john.doe@example.com"
        },
        "payment": {
            "id": "P-VS84990",
            "bank": "Bank of America",
            "name_on_card": "John Doe",
            "card_brand": "VISA",
            "card_type": "credit",
            "success": true,
            "cvc_check_success": true,
            "zip_check_success": true,
            "extra": {}
        }
    },
    "created_at": "2019-09-17T00:00:00.00Z",
    "updated_at": "2019-09-18T00:00:00.00Z",
    "confirmed_at": "2020-12-01T09:44:23.924Z",
    "issued_at": "2020-12-01T09:44:23.924Z",
    "effective_date": "2020-05-01T12:00:00.000Z",
    "term_end_date": "2020-05-09T12:00:00.000Z",
    "cancelled_at": "2020-12-01T10:46:41.829Z"
}

To cancel a policy subscription, call the POST /policy/{policyId}/cancel endpoint. That would return the cancelled Policy:

You can use either the policyId or your own custom_id in the URL.

When a policy is cancelled, it can not be re-enabled. Instead, you should create a new policy.

When should I call this endpoint?

If a user cancels their policy, do not forget to notify us via this endpoint.

Claim Module

Create a Claim

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request POST https://api.tint.ai/v2/policy/{policyId}/claim \
    --data @- << EOL
{
    "custom_id": "9481BC",
    "gross_value": 4000,
    "net_value": 2500,
    "type": "theft"
}
EOL
import requests

requests.post(
    "https://api.tint.ai/v2/policy/{policyId}/claim",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        "custom_id": "9481BC",
        "gross_value": 4000,
        "net_value": 2500,
        "type": "theft"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/claim`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
        body: JSON.stringify({
            "custom_id": "9481BC",
            "gross_value": 4000,
            "net_value": 2500,
            "type": "theft"
        })
    }
);
// Response
{
    "id": "077d6d5f-e2c6-4e6d-a2e1-8fad0716de86",
    "type": "theft",
    "custom_id": "9481BC",
    "gross_value": 4000,
    "net_value": 2500,
    "created_at": "2020-12-01T09:30:44.691Z",
    "updated_at": "2020-12-01T09:30:44.691Z"
}

To report a claim, you should call the POST /v2/policy/{policyId}/claim endpoint. It takes the claim details as a parameter, including:

You can use either the policyId or your own custom_id in the URL.

Response would be the freshly created Claim object.

When should I call this endpoint?

Whenever one of your customers reports you a claim, you should call this endpoint. It allows us to track the policies for which you incurred a loss in order to improve the risk prediction models.

Update a Claim

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request PUT \
    --data "{\"net_value\": 2840}" \
    https://api.tint.ai/v2/policy/{policyId}/claim/{claimId}
import requests

requests.put(
    "https://api.tint.ai/v2/policy/{policyId}/claim/{claimId}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        "net_value": 2840
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/claim/{claimId}`, {
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
        body: JSON.stringify({
            "net_value": 2840
        })
    }
);
// Response
{
    "id": "077d6d5f-e2c6-4e6d-a2e1-8fad0716de86",
    "type": "theft",
    "custom_id": "9481BC",
    "gross_value": 4000,
    "net_value": 2840,
    "created_at": "2020-12-01T09:30:44.691Z",
    "updated_at": "2020-12-01T09:31:44.691Z"
}

If one of your claims changes over time, you can update it using the PUT /v2/policy/{policyId}/claim/{claimId} endpoint. It takes one or several of the claim editable attributes:

You can use either the policyId or your own custom_id in the URL.

This endpoint returns the final Claim object, including your latest changes.

When should I call this endpoint?

You need to call this endpoint whenever a claim information changes, either to fix erred data, or if you have more details about this claim. For instance, you can send us an estimated gross_value for a claim, and refine it later when you have the exact amount.

Get a List of Policy Claims

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request GET \
    https://api.tint.ai/v2/policy/{policyId}/claims
import requests

requests.get(
    "https://api.tint.ai/v2/policy/{policyId}/claims",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/claims`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
// Response
[
    {
        "id": "077d6d5f-e2c6-4e6d-a2e1-8fad0716de86",
        "type": "theft",
        "custom_id": "9481BC",
        "gross_value": 4000,
        "net_value": 2840,
        "created_at": "2020-12-01T09:30:44.691Z",
        "updated_at": "2020-12-01T09:31:44.691Z"
    }
]

To get the list of claims attached to a policy, just call the the GET /v2/policy/{policyId}/claims endpoint. It would return an array of Claim attached to the given policy.

You can use either the policyId or your own custom_id in the URL.

When should I call this endpoint?

This endpoint may be useful to retrieve claims in case you lost track of it in your own internal system.

You should generally not call this endpoint directly. Instead, we recommend either passing us a claim customId at claim creation, and using it as a claimId parameter in other claims endpoint, or to store in your own system the Tint claim ID.

Get Claim Details

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request GET \
    https://api.tint.ai/v2/policy/{policyId}/claim/{claimId}
import requests

requests.get(
    "https://api.tint.ai/v2/policy/{policyId}/claim/{claimId}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/claim/{claimId}`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
// Response
{
    "id": "077d6d5f-e2c6-4e6d-a2e1-8fad0716de86",
    "type": "theft",
    "custom_id": "9481BC",
    "gross_value": 4000,
    "net_value": 2840,
    "created_at": "2020-12-01T09:30:44.691Z",
    "updated_at": "2020-12-01T09:31:44.691Z"
}

If you need to retrieve the specific details of a claim, just call the GET /v2/policy/{policyId}/claim/{claimId} endpoint. It would return a single Claim object.

You can use either the policyId or your own custom_id in the URL.

When should I call this endpoint?

You can call this endpoint in case you want to check some details about a given claim, in an admin for instance (even if we encourage you using the Tint platform instead to browse all the claim details).

Score Module

Compute Policy Scores

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request GET \
    https://api.tint.ai/v2/policy/{policyId}/scores
import requests

requests.get(
    "https://api.tint.ai/v2/policy/{policyId}/scores",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/scores`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
/* Response */
[
    {
        "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
        "value": 43,
        "status": "DONE",
        "prediction_type": "PHYSICAL_DAMAGE",
        "reject_threshold": 75,
        "reject": false,
        "created_at": "2019-08-11T12:42:51.00Z",
        "updated_at": "2019-08-11T12:42:51.00Z"
    },
    {
        "id": "b0af7561-c140-4892-9185-96d4d6cdb51f",
        "value": 1,
        "status": "DONE",
        "prediction_type": "THEFT",
        "reject_threshold": 50,
        "reject": false,
        "created_at": "2019-08-11T12:42:51.00Z",
        "updated_at": "2019-08-11T12:42:51.00Z"
    }
]

To compute Scores attached to a Policy, you have to call the GET /v2/policy/{policyId}/scores endpoint. Response would be an array of Scores.

You can use either the policyId or your own custom_id in the URL.

When should I call this endpoint?

When you want to score a policy to evaluate the different risks associated to it. You will need to have created or retrieved the policyId of the Policy you are trying to score.

Get Policy Score Details

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request GET \
    https://api.tint.ai/v2/policy/{policyId}/score/{scoreId}
import requests

requests.get(
    "https://api.tint.ai/v2/policy/{policyId}/score/{scoreId}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/score/{scoreId}`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
/* Response */
{
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "value": 43,
    "status": "DONE",
    "prediction_type": "PHYSICAL_DAMAGE",
    "reject_threshold": 75,
    "reject": false,
    "created_at": "2019-08-11T12:42:51.00Z",
    "updated_at": "2019-08-11T12:42:51.00Z"
}

If you need to retrieve details of a given score, you can use the GET /policy/{policyId}/score/{scoreId} endpoint. It returns a Score entity.

You can use either the policyId or your own custom_id in the URL for the policy.

When should I call this endpoint?

If you need to get more details about an already computed score. It may be the case if you want to display it in an admin on your side, even if we strongly encourage you to use the Tint App instead.

Rating Engine

Get Policy Quotes

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request GET \
    https://api.tint.ai/v2/policy/{policyId}/quotes
import requests

requests.get(
    "https://api.tint.ai/v2/policy/{policyId}/quotes",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/quotes`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
    }
);
/* Response */
[
    {
        "id": "eb3faaac-f7a7-476d-a6c8-18e071426efb",
        "calculated_premium": 125.13,
        "insurance_plan": {
            "id": "f2b16261-1659-4f28-bd7f-0a4f56f70417",
            "name": "Platinum"
        },
        "coverages": {
            "physical-damage": {
                "name": "Physical Damage",
                "description": null,
                "premium": 120.13,
                "deductible": 500,
                "limit": 89000,
                "security_deposit": 0,
                "custom_attributes": {}
            },
            "third-party-liability": {
                "name": "Third-party liability",
                "description": null,
                "premium": 0,
                "deductible": 0,
                "limit": 1000000,
                "security_deposit": 0,
                "custom_attributes": {}
            },
            "roadside-assistance": {
                "name": "Roadside assistance",
                "description": null,
                "premium": 5,
                "deductible": 0,
                "limit": 200,
                "security_deposit": 0,
                "custom_attributes": {}
            }
        }
    }
]

To retrieve the quotes based on your own insurance plans, you have to call the GET /policy/{policyId}/quotes endpoint. It returns the quotes (including the calculated premium) you should display to the end user.

You can use either the policyId or your own custom_id in the URL.

When should I call this endpoint?

You should call this endpoint whenever you need to display the insurance options (generally when the user is logged and has chosen an asset to rent). Through this call, you would be able to retrieve the recommended price and the plan details your UI needs.

Decision Engine

The Decision Engine allows to retrieve and enforce decisions applied to Policies based on business rules configured in the Tint App.

Get Policy Decision

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request GET \
    https://api.tint.ai/v2/policy/{policyId}/decisions/{decisionType}
import requests

requests.get(
    "https://api.tint.ai/v2/policy/{policyId}/decisions/{decisionType}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://api.tint.ai/v2/policy/{policyId}/decisions/{decisionType}`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
    }
);
/* Response */
{
    "type": "PREQUAL",
    "decision": "APPROVED"
}

To retrieve the business decisions for your policies, call the GET /policy/{policyId}/decisions/{decisionType} endpoint.

It returns the Decision of the given type, for the given policy.