Policy Module

get
Get Insurance Products
https://api.tint.ai/v2/insurance-products
This endpoint returns all the available insurance products, including the JSON schema used to validate the attributes you can provide to your policies.
Request
Response
Request
​
Response
200: OK
List of available insurance products
[
    {
        "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": ["email"],
                    "additionalProperties": false
                }
            },
            "required": ["asset", "renter"],
            "additionalProperties": false
        }
    }
​
post
Create a Policy
https://api.tint.ai/v2/policy
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.
Request
Response
Request
Query Parameters
withScores
optional
boolean
Should the query calculate and return scores while creating the policy? Default to false.
withQuotes
optional
boolean
Should the query calculate and return quotes while creating the policy? Default to false.
Body Parameters
insurance_product_slug
required
string
Product slug you want to assign the policy. They can be retrieved using the insurance product list endpoint.
session_identifier
optional
object
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. slug you want to assign the policy. They can be retrieved using the insurance product list endpoint.

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.
policy_details
required
object
A set of attributes, giving more details about the ongoing policy: personal insured information, 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.
Response
200: OK
Returns the created 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)",
        "traffic_rate": 0.75
    },
    "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": "[email protected]"
        }
    },
    "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 further interact with the API, you need to store the policy id returned by Tint.
get
Get a Policy
https://api.tint.ai/v2/policy/:id
Request
Response
Request
Path Parameters
id
required
string
ID of the policy to retrieve
Response
200: OK
The Policy entity corresponding to the provided ID.
{
    "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)",
        "traffic_rate": 0.75
    },
    "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": "[email protected]"
        },
        "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
}
put
Update a Policy
https://api.tint.ai/v2/policy/:id
Update an existing policy using newly generated information.
Request
Response
Request
Path Parameters
id
required
string
ID of the policy to update
Query Parameters
withScores
optional
boolean
Should the query calculate and return the updated scores while updating the policy? Default to false.
withQuotes
optional
boolean
Should the query calculate and return the updated quotes while updating the policy? Default to false.
Body Parameters
policy_details
required
object
A set of attributes to update the policy with. It should also matches the validation schema configured by Tint.
Response
200: OK
The updated 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)",
        "traffic_rate": 0.75
    },
    "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": "[email protected]"
        },
        "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
}
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 [email protected] or via your dedicated Slack channel.
You can't change the insurance product of an existing policy.
post
Issue a Policy
https://api.tint..ai/v2/policy/:id/issue
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 policy update endpoint. The policy would then need to be re-issued.
Request
Response
Request
Path Parameters
id
required
string
Policy ID to issue
Body Parameters
subscribed_quote_id
required
string
ID of the quote the end user subscribed to. You can retrieve it using the Tint rating engine module.
subscribed_coverages
required
object
Object whose keys are the subscribed coverage slugs, and whose values are an object containing the charged_premium for this specific coverage.
effective_date
required
string
ISO 8601 date at which the policy takes effect.
term_end_date
required
string
ISO 8601 date at which the policy ends effect.
Response
200: OK
Returns the issued 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)",
        "traffic_rate": 0.75
    },
    "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": "[email protected]"
        },
        "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
}
All these fields are mandatory. If you get some trouble configuring your product to retrieve a quote ID, feel free to contact us at [email protected] or on Slack.
post
Report a Policy Usage
https://api.tint.ai/v2/policy/:id/report-usage
When a policy is completed, you may need to track final information about the effective transaction. That's especially useful to track your insurance usage (for instance, number of miles or rental days).
Request
Response
Request
Path Parameters
id
required
string
Policy ID to report the usage to.
Response
200: OK
A policy including its report usage in the policy_details attribute.
{
    "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)",
        "traffic_rate": 0.75
    },
    "policy_details": {
        "custom_id": "P-7600BN1",
        "mileage": 25678,
        "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": "[email protected]"
        },
        "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
}
You can also report usage without any existing policy, calling the /v2/policy/report-usage endpoint (without any policy ID). It is especially useful if you don't need any quotes or decisions.
post
Cancel a Policy
https://api.tint.ai/v2/policy/:id/cancel
Request
Response
Request
Path Parameters
id
required
string
Policy ID to cancel
Response
200: OK
Returns the cancelled 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)",
        "traffic_rate": 0.75
    },
    "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": "[email protected]"
        },
        "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"
}
When a policy is cancelled, it can not be re-enabled. Instead, you should create a new policy.