NAV Navbar
shell python javascript

Introduction

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

Using Tint API allows computing various AI-powered risk scores, selecting risk segments within your population, and returning AI-based pricing for an insurance policy.

Tint.ai empowers organizations of all sizes to design and distribute profitable insurance products using machine learning. Tint.ai helps businesses to make accurate, real-time decisions that both improve user experience and increase profitability. You can use Tint.ai whether you’re building a brand new insurance product or looking to augment an existing legacy system.

Tint.ai makes risk predictions in real-time using your own data and 100s of additional external variables from a curated list of compliant vendors in Tint.ai’s global network. Our machine learning systems identify patterns of behavior across hundreds of your insurance policy signals. These are often patterns that only a machine learning system can spot. Using Tint.ai, businesses have generated millions of dollars in ROI.

Because you are unique, you need a unique configuration for your Insurance Products. That's why we provide you the Tint App. From there, you have control and transparency on what Tint.ai is doing for you. Whether you want to change the deductible of a particular coverage or adjust the margin for your premium calculations, there is a dedicated section in the Tint App.

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

Environments

Production Environment

The Tint API version 2 only allows https calls.

It is currently in its v2 version, for which the base URL is https://score-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://score-apisandbox.tint.ai/v2 endpoint.

API is the same than the one provided in the production environment, except:

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

Authentication

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

requests.post(
    "https://score-api.tint.ai/v2/policy",
    headers={
      "x-api-key": "SECRET_API_KEY"
    }
)
fetch("https://score-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 most likely invalid.
ACCESS_DENIED 403 Missing or invalid token (should be in the x-api-key header)
NOT_FOUND 404 The endpoint or model was not found.
INTERNAL_ERROR 500 Something wrong happened on our side. Please contact us at support@tint.ai

Models

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

Policy

{
  "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
  "session_identifier": {
    "user_id": "unique-user-id"
  },
  "policy_details": {
    "custom_id": "P-7600BN1",
    "start_date": "2019-10-30T12:00:00.000000Z",
    "end_date": "2019-11-02T12:00:00.000000Z",
    "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"
    }
  },
  "confirmed_at": null,
  "effective_date": "2019-09-17T00:00:00.000000Z",
  "term_end_date": "2019-09-21T23:59:59.000000Z",
  "created_at": "2019-08-11T12:42:51.000000Z",
  "updated_at": "2019-08-11T12:42:51.000000Z"
}

Policy is the fundamental basis of all other Tint endpoints. It represents a potential contract between an insurer and an insured, for example a renter, in order to provide protection for the different coverages inside a plan of an insurance product.

In order to determine the risk associated with a Policy, you will need to provide the Policy Details, such as the insured asset, the insured, etc.

Depending on the use case you are tackling with Tint, a Policy would also be attached to:

A Policy is represented by the following JSON object:

Policy Details

Policy Details contains all the details required to compute the risk related to the policy, such as the insured and the details of the asset or the risk that is covered. It is represented by a JSON object that will be provided by the Tint.

This JSON object relies on the structure provided in the GET /insurance-products endpoint, via the validation_schema property. It depends of the model needs and of your use case.

{
  "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
  "custom_id": "T-456998",
  "booking_date": "2019-10-11T14:57:21.000000Z",
  "start_date": "2019-10-30T12:00:00.000000Z",
  "end_date": "2019-11-02T12:00:00.000000Z",
  "amount": 420
}

Claim

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

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

All fields but type are optional.

Score

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:

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

InsuranceProduct

InsuranceProduct represents one of your insurance product. It is characterized by a list of InsurancePlans.

InsurancePlan is represented by the following JSON object:

{
  "id": "46b051e4-4ccd-4d70-afc9-8e3025be0523",
  "name": "Tint.ai's Insurance Product",
  "slug": "tint-ai-insurance-product",
  "plans": [
    {
      "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
      "name": "Peace of Mind",
      "coverages": [
        {
          "id": "85f81290-25c5-4fb8-9a39-52bf02472624",
          "name": "$1M Liability Coverage",
          "description": "Liability insurance provides the insured party with protection against claims resulting from injuries and damage to people and/or property. Liability insurance policies cover both legal costs and any payouts for which the insured party would be responsible if found legally liable"
        },
        {
          "id": "0d64e40c-e0b1-414e-b56b-fd1c53005f3e",
          "name": "Property Damage Protection",
          "description": "Damage Protection"
        }
      ]
    }
  ],
  "validation_schema": {
    "custom_id": {
      "type": "string"
    },
    "renter": {
      "type": "dict",
      "schema": {
        "first_name": {
          "type": "string"
        },
        "last_name": {
          "type": "string"
        },
        "address": {
          "type": "dict",
          "schema": {
            "street": {
              "type": "string"
            },
            "city": {
              "type": "string"
            },
            "state": {
              "type": "string"
            },
            "country": {
              "type": "string"
            }
          }
        }
      }
    }
  }
}

InsurancePlan

InsurancePlan represents a particular plan associated to your insurance product. InsurancePlans are characterized by a list of coverages.

InsurancePlan is represented by the following JSON object:

{
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "name": "Peace of Mind",
    "coverages": [{
        "id": "85f81290-25c5-4fb8-9a39-52bf02472624",
        "name": "$1M Liability Coverage",
        "description": "Liability insurance provides the insured party with protection against claims resulting from injuries and damage to people and/or property. Liability insurance policies cover both legal costs and any payouts for which the insured party would be responsible if found legally liable"
    }, {
        "id": "0d64e40c-e0b1-414e-b56b-fd1c53005f3e",
        "name": "Property Damage Protection",
        "description": "Damage Protection"
    }]
    "extra":{}
}

Coverage

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

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

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
    }
  }
}

Quote contains the information related to the quote for a given Policy and InsurancePlan.

Quote is represented by the following JSON object:

Subscription

{
  "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
  "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
      }
    }
  },
  "subscribed_coverages": ["property-damage-protection"],
  "charged_premium": 470,
  "cancelled_at": null,
  "created_at": "2019-05-28T18:24:45.988336",
  "updated_at": "2019-05-28T18:24:45.988336"
}

Subscription contains the information related to a given Quote that was confirmed and generated a valid policy. It is represented by the following JSON object:

When a subscription is cancelled, it can not be re-enabled. Instead, you should create a new subscription using the /subscribe endpoint.

Core Module

Get Insurance Products

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

requests.get(
    "https://score-api.tint.ai/v2/insurance-products",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-api.tint.ai/v2/insurance-products`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
    }
);

The GET /insurance-products endpoint displays all your Insurance Product details, including the attached Insurance Plans. You can especially retrieve the product slugs you would need to create policies.

/* Response */
[
  {
    "id": "46b051e4-4ccd-4d70-afc9-8e3025be0523",
    "name": "Tint.ai's Insurance Product",
    "slug": "tint-ai-insurance-product",
    "plans": [
      {
        "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
        "name": "Peace of Mind"
      }
    ]
  }
]

Create a Policy

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request POST \
    --data "{ \
        \"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\" \
            } \
        } \
    }" \
    https://score-api.tint.ai/v2/policy
import requests

requests.post(
    "https://score-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://score-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",
                },
            }
        }),
    }
);

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 (as a 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.

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.

Some policy details fields are optional (check the GET /insurance-products endpoint for more details). Yet, the more fields you send to the API, the more accurate the Score or Quote will be.

/* Response */
{
  "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
  "session_identifier": {
    "user_id": "unique-user-id"
  },
  "policy_details": {
    "custom_id": "P-7600BN1",
    "start_date": "2019-10-30T12:00:00.000000Z",
    "end_date": "2019-11-02T12:00:00.000000Z",
    "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"
    }
  },
  "effective_date": "2019-09-17T00:00:00.000000Z",
  "term_end_date": "2019-09-21T23:59:59.000000Z",
  "created_at": "2019-08-11T12:42:51.000000Z",
  "updated_at": "2019-08-11T12:42:51.000000Z"
}

API returns the newly created Policy object, including the PolicyDetails.

Extra GET Parameters

This endpoint also exposes two extra GET parameters to calculate scores and/or quotes at the policy creation level. This is especially useful if you need to call us 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.

When should I call this endpoint?

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




This example response is voluntarily truncated to save you some long scrolling. You would get the full Policy Details when calling the API.

Update a Policy

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request PUT \
    --data "{ \
        \"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 \
            }
        } \
    }" \
    https://score-api.tint.ai/v2/policy/080949ea-0de3-4690-8cb4-6f558118d7e5
import requests

requests.put(
    "https://score-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://score-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: {}
                }
            }
        }),
    }
);

To update an existing Policy, you have to call the PUT /v2/policy/{policyId} endpoint, passing the updated details of the policy_details (Policy Details) in the request body. The policyId was returned in 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.

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.

/* Response */
{
  "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
  "policy_details": {
    "custom_id": "P-7600BN1",
    "start_date": "2019-10-30T12:00:00.000000Z",
    "end_date": "2019-11-02T12:00:00.000000Z",
    "asset": {
      "type": "car",
      "custom_id": "T-09918",
      "vehicle_make": "Toyota",
      "vehicle_model": "Camry",
      "vehicle_year": 2018
    },
    "renter": {
      "custom_id": "U-73610",
      "email_address": "john.doe@example.com"
    },
    "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": {}
    }
  },
  "effective_date": "2019-09-17T00:00:00.000000Z",
  "term_end_date": "2019-09-21T23:59:59.000000Z",
  "created_at": "2019-08-11T12:42:51.000000Z",
  "updated_at": "2019-08-11T12:42:51.000000Z"
}

Create a Claim

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

requests.post(
    "https://score-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://score-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": "080949ea-0de3-4690-8cb4-6f558118d7e5",
  "custom_id": "9481BC",
  "gross_value": 4000,
  "net_value": 2500,
  "type": "theft",
  "created_at": "2020-01-28T10:01:53.076945",
  "updated_at": "2020-01-28T10:01:53.076949"
}

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://score-api.tint.ai/v2/policy/{policyId}/claim/{claimId}
import requests

requests.put(
    "https://score-api.tint.ai/v2/policy/{policyId}/claim/{claimId}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        "net_value": 2840
    }
)
fetch(
    `https://score-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": "080949ea-0de3-4690-8cb4-6f558118d7e5",
  "custom_id": "9481BC",
  "gross_value": 4000,
  "net_value": 2840,
  "type": "theft",
  "created_at": "2020-01-28T10:01:53.076945",
  "updated_at": "2020-01-28T10:01:53.076949"
}

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://score-api.tint.ai/v2/policy/{policyId}/claims
import requests

requests.get(
    "https://score-api.tint.ai/v2/policy/{policyId}/claims",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-api.tint.ai/v2/policy/{policyId}/claims`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
// Response
[
  {
    "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
    "custom_id": "9481BC",
    "gross_value": 4000,
    "net_value": 2840,
    "type": "theft",
    "created_at": "2020-01-28T10:01:53.076945",
    "updated_at": "2020-01-28T10:01:53.076949"
  }
]

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://score-api.tint.ai/v2/policy/{policyId}/claim/{claimId}
import requests

requests.get(
    "https://score-api.tint.ai/v2/policy/{policyId}/claim/{claimId}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-api.tint.ai/v2/policy/{policyId}/claim/{claimId}`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
// Response
{
  "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
  "custom_id": "9481BC",
  "gross_value": 4000,
  "net_value": 2840,
  "type": "theft",
  "created_at": "2020-01-28T10:01:53.076945",
  "updated_at": "2020-01-28T10:01:53.076949"
}

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://score-api.tint.ai/v2/policy/{policyId}/scores
import requests

requests.get(
    "https://score-api.tint.ai/v2/policy/{policyId}/scores",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-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",
    "status": "DONE",
    "value": 43,
    "prediction_type": "PHYSICAL_DAMAGE",
    "reject_threshold": 75,
    "reject": false,
    "created_at": "2019-08-11T12:42:51.000000Z",
    "updated_at": "2019-08-11T12:42:51.000000Z"
  },
  {
    "id": "b0af7561-c140-4892-9185-96d4d6cdb51f",
    "status": "DONE",
    "value": 1,
    "prediction_type": "THEFT",
    "reject_threshold": 50,
    "reject": false,
    "created_at": "2019-08-11T12:42:51.000000Z",
    "updated_at": "2019-08-11T12:42:51.000000Z"
  }
]

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 and make an informed decision based on the score. 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://score-api.tint.ai/v2/policy/{policyId}/score/{scoreId}
import requests

requests.get(
    "https://score-api.tint.ai/v2/policy/{policyId}/score/{scoreId}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-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",
  "status": "DONE",
  "value": 43,
  "prediction_type": "PHYSICAL_DAMAGE",
  "reject_threshold": 75,
  "reject": false,
  "created_at": "2019-08-11T12:42:51.000000Z",
  "updated_at": "2019-08-11T12:42:51.000000Z"
}

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.

Confirm a Policy

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

requests.post(
    "https://score-api.tint.ai/v2/policy/{policyId}/confirm-transaction",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-api.tint.ai/v2/policy/{policyId}/confirm-transaction`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
// Response
{
  "id": "080949ea-0de3-4690-8cb4-6f558118d7e5",
  "custom_id": "P-7600BN1",
  "transaction": {
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "start_date": "2019-10-30T12:00:00.000000Z",
    "end_date": "2019-11-02T12:00:00.000000Z",
    "asset": {
      "id": "30d215d5-f63e-45e4-b247-0ebe45c3a097",
      "type": "car",
      "custom_id": "T-09918",
      "vehicle_make": "Toyota",
      "vehicle_model": "Camry",
      "vehicle_year": 2018
    },
    "renter": {
      "id": "96b39586-e4e6-4a4d-a415-ab818e2890d6",
      "custom_id": "U-73610",
      "email_address": "john.doe@example.com"
    }
  },
  "confirmed_at": "2019-05-30T11:12:41.221774",
  "effective_date": "2019-09-17T00:00:00.000000Z",
  "term_end_date": "2019-09-21T23:59:59.000000Z",
  "created_at": "2019-08-11T12:42:51.000000Z",
  "updated_at": "2019-08-11T12:42:51.000000Z"
}

We need to know when a transaction effectively occured. That's the purpose of the POST /policy/{policyId}/confirm-transaction endpoint. Just call it, and we'll return you an updated Policy object:

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

When should I call this endpoint?

If you don't use the Premium Engine, we have to exclude the policies that are not underwritten after they were scored (they are either cancelled or rejected) from our continuous machine learning processes. Hence, we need a confirmation from your side that the policy has been confirmed, which is the aim of this endpoint. We recommend you send us a call as soon as the policy is subscribed.

Premium Engine Endpoints

Get Policy Quotes

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

requests.get(
    "https://score-api.tint.ai/v2/policy/{policyId}/quotes",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-api.tint.ai/v2/policy/{policyId}/quotes`, {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
    }
);
/* Response */
[
  {
    "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
      }
    }
  },
  {
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "calculated_premium": 75,
    "insurance_plan": {
      "id": "a9c3235e-b144-4f27-b0bf-5ee7709ec19c",
      "name": "Risk Taker"
    },
    "coverages": {
      "property-damage-protection": {
        "name": "Property Damage Protection",
        "description": "Damage Protection",
        "premium": 75,
        "deductible": 3500,
        "limit": 100000,
        "security_deposit": 450
      }
    }
  }
]

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.

Subscribe to a Quote

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request POST \
    --data '{ \
        "subscribed_coverages": [ \
            "property-damage-protection" \
        ], \
        "charged_premium": 400 \
    }' \
    https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/subscribe
import requests

requests.post(
    "https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/subscribe",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        'subscribed_coverages': [
            'property-damage-protection'
        ],
        'charged_premium': 400
    }
)
fetch(
    `https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/subscribe`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
        body: JSON.stringify({
            subscribed_coverages: [
                'property-damage-protection'
            ],
            charged_premium: 400
        })
    }
);
// Response
{
  "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
  "quote": {
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "calculated_premium": 470,
    "insurance_plan": {
      "id": "a9c3235e-b144-4f27-b0bf-5ee7709ec19c",
      "name": "Risk Taker"
    },
    "coverages": {
      "property-damage-protection": {
        "name": "Property Damage Protection",
        "description": "Damage Protection",
        "premium": 75,
        "deductible": 3500,
        "limit": 100000,
        "security_deposit": 450
      }
    }
  },
  "subscribed_coverages": ["property-damage-protection"],
  "charged_premium": 400,
  "cancelled_at": null,
  "created_at": "2019-05-28T18:24:45.988336",
  "updated_at": "2019-05-28T18:24:45.988336"
}

To confirm the subscription of a policy by your end user, you should use the POST /policy/{policyId}/quote/{quoteId}/subscribe endpoint.

Two fields are required to confirm the subscriptions:

These informations allow to improve your convertion model.

That would return a Subscription object.

When should I call this endpoint?

When the end-user opted for a specific insurance plan, you should call us with the selected quote ID. This way, we would be able to add this policy to both the conversion and risk prediction models.

Update a Policy Subscription

curl -H "Content-Type: application/json" \
    -H "X-Api-Key: SECRET_API_KEY" \
    --request PUT \
    --data '{ \
        "subscribed_coverages": [ \
            "property-damage-protection" \
        ], \
        "charged_premium": 150 \
    }' \
    https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/subscription/{subscriptionId}
import requests

requests.put(
    "https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/subscription/{subscriptionId}",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    },
    json={
        'subscribed_coverages': [
            'property-damage-protection'
        ],
        'charged_premium': 150
    }
)
fetch(
    `https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/subscription/{subscriptionId}`, {
        method: 'PUT',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        },
        body: JSON.stringify({
            subscribed_coverages: [
                'property-damage-protection'
            ],
            charged_premium: 150
        })
    }
);
// Response
{
  "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
  "quote": {
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "calculated_premium": 470,
    "insurance_plan": {
      "id": "a9c3235e-b144-4f27-b0bf-5ee7709ec19c",
      "name": "Risk Taker"
    },
    "coverages": {
      "property-damage-protection": {
        "name": "Property Damage Protection",
        "description": "Damage Protection",
        "premium": 75,
        "deductible": 3500,
        "limit": 100000,
        "security_deposit": 450
      }
    }
  },
  "subscribed_coverages": ["property-damage-protection"],
  "charged_premium": 150,
  "cancelled_at": null,
  "created_at": "2019-05-28T18:24:45.988336",
  "updated_at": "2019-05-28T18:24:45.988336"
}

To edit an existing policy subscription, you should use the PUT /v2/policy/{policyId}/quote/{quoteId}/subscription/{subscriptionId} endpoint.

The parameters of this endpoint are similar to the quote subscription endpoint.

That would return the edited Subscription object.

When should I call this endpoint?

Whenever the insurance plan terms are changed, due to an end-user request or on your own initiative. That would help refining our conversion models, keeping informations up-to-date for this specific user.

If a user cancelled its subscription, please refer to Cancel a Policy Subscription.

Cancel a Policy Subscription

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

requests.post(
    "https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/cancel",
    headers={
        "X-Api-Key": "SECRET_API_KEY"
    }
)
fetch(
    `https://score-api.tint.ai/v2/policy/{policyId}/quote/{quoteId}/cancel`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
            'X-Api-Key': "SECRET_API_KEY",
        }
    }
);
// Response
{
  "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
  "quote": {
    "id": "3d762b4c-0e1e-4631-896f-06ebf31f0ef9",
    "calculated_premium": 470,
    "insurance_plan": {
      "id": "a9c3235e-b144-4f27-b0bf-5ee7709ec19c",
      "name": "Risk Taker"
    },
    "coverages": {
      "property-damage-protection": {
        "name": "Property Damage Protection",
        "description": "Damage Protection",
        "premium": 75,
        "deductible": 3500,
        "limit": 100000,
        "security_deposit": 450
      }
    }
  },
  "subscribed_coverages": {
    "property-damage-protection": {
      "name": "Property Damage Protection",
      "description": "Damage Protection",
      "premium": 75,
      "deductible": 3500,
      "limit": 100000,
      "security_deposit": 450
    }
  },
  "charged_premium": 123,
  "cancelled_at": "2019-05-30T11:12:41.221774",
  "created_at": "2019-05-28T18:24:45.988336",
  "updated_at": "2019-07-30T13:48:21.440749"
}

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

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

When a subscription is cancelled, it can not be re-enabled. Instead, you should create a new subscription using this same endpoint.

When should I call this endpoint?

If a user cancels their policy, do not forget to warn us via this endpoint. That would help refining our conversion models, telling us that this specific user didn't convert.