Nuon.AI Price Prediction API Specification (1.0.0)

Download OpenAPI specification:Download

Nuon.AI Ltd: hi@nuon.ai

This API to provides access to NUON.AI's price recommendation service for inbound insurance quotes.

It is designed to be as simple as possible to integrate with. Just two endpoints are involved:-
  • /model/predict - typically called during the process of preparing a quote for a customer. Given details about the rating factors, it returns a price adjustment that should be applied to the premium.
  • /mode/outcome - called when you know whether the quote was purchased. This gives the AI the feedback it needs in order to learn.

This version of the API includes two optional and experimental endpoints which give access to Nuon's Real Time Pricing service:-

  • /rtp/approval - normally called before rating is performed to determine whether the quote should be referred or declined immediately before actual rating is performed, and before any (potentially costly) 3rd party services are used.
  • /rtp/rating - called during the preparation of a quote (after /rtp/approval, if used). Given details about the rating factors, it applies a set of rules applying specific loadings and/or discounts, before handling the quote to the AI for price adjustment. The service returns a price adjustment that should be applied to the premium.

The API is based on REST principles and requires an authorisation key to access the endpoints.

Errors

Each API call returns an HTTP status code that reflects the nature of the response. We have done our best to follow the HTTP status code conventions:-

  • Any request that did not succeed will return a 4xx or 5xx error.
  • The 4xx range means there was a problem with the request, like a missing parameter or a quoteId which could not be found.
  • The 5xx range means that something went wrong on our end.

For example:-

  • 400 Bad Request - Invalid request parameters.
  • 401 Unauthorized - Incorrect or missing API key.
  • 403 Forbidden - You do not have permission to view a resource or perform an action.
  • 404 Not Found - The specified resource could not be found.
  • 500, 502, 503, 504 Internal Server Error - There was a problem on our end!

Request Timeout

Normal response times from this API are well below 1s (a mean of 100-200ms is a reasonable expectation). However, the internet is a complex place, and slow response which are completely outside of our or your control are possible. For that reason it is strongly recommended that client code includes some kind of request timeout mechanism to protect against any impact on your processes.

Occasional request timeouts can be safely ignored, there is no need to retry the request. However, if you are seeing a high rate of timeouts, please contact us.


Predict

Get pricing predictions

Predict

Run the AI model to generate a price adjustment prediction that should be applied to the premium based on the policy features supplied.

query Parameters
key
required
string
Example: key=AshsgdnAVJ

Key parameter taking the required api key value in the request query to allow access to the resource.

Request Body schema: application/json
customerId
required
string

Unique customer identifier. The customerId is mandatory. It needs to be unique and consistent for each customer, but it does not need to be a system id or uuid. It is used as reference more than an ID.
Integrators may build it by concatenating information that they do have. For example, generate a string of car registration + postcode.

quoteId
required
string

Unique quote id. In most scenarios this is a required property, however, in order to cater for all premium calculation pipelines (which may include requoting for example), the AI can be configured to allow for the quoteId to be either undefined, or a duplicate from a previous call to this endpoint.

tenant
string

Tenant or scheme name to identify product or group of products. When multiple tenants are configured, this value must be provided and in combination with quoteId must be unique.

quoteExpiry
string <date>

Date that the quote is considered to have expired.

price
required
number

The price your rating system has calculated for the quote. This is the total price that you would have presented to the customer. Strictly speaking, this property is optional. However, the AI will be considerably less effective without it.

adjustmentLimit
number

Set or override lower and upper allowable price adjustment as a decimal. This value must not be included if the lowerAdjustmentLimit and upperAdjustmentLimit has been provided.

lowerAdjustmentLimit
number

Set or override the lower allowable price adjustment as a decimal. This value must not be included if the adjustmentLimit has been provided.

upperAdjustmentLimit
number

Set or override the upper allowable price adjustment as a decimal. This value must not be included if the adjustmentLimit has been provided.

competativeNeighbourDelta
number

Difference in price to the cheapest or most expensive neighbour

transactionType
string
Default: "NEW_BUSINESS"
Enum: "NEW_BUSINESS" "MTA" "RENEWAL" "REBROKE"

The transaction type for the input pricing quote

required
Array of objects (Feature)

A list of features describing the rating factors for this quote. The set of features is flexible to allow for all kinds of products. We will help you define the ideal set to match your product and your aims.

Responses

Request samples

Content type
application/json
{
  • "customerId": "LX839",
  • "quoteId": "Q_08281",
  • "quoteExpiry": "2022-07-31",
  • "price": 298.79,
  • "adjustmentLimit": 1.3,
  • "transactionType": "NEW_BUSINESS",
  • "feature": [
    ]
}

Response samples

Content type
application/json
{
  • "premiumPrediction": 298.45,
  • "premiumAdjustment": 1
}

Outcome

Record that a policy which had previously been sent to the /model/predict API call has been purchased or not.

The /model/outcome API would usually be called with the mandatory quoteId and result of PURCHASED, when a policy had been purchased by the customer.

The /model/outcome API can also be called with the mandatory quoteId and result of NTU, if the policy will not be purchased. This call is not required and the unpurchased quotes will be managed by NUON AI automatically.

query Parameters
key
required
string
Example: key=AshsgdnAVJ

Key parameter taking the required api key value in the request query to allow access to the resource.

Request Body schema: application/json
quoteId
required
string

Unique quote id.

result
required
string
Enum: "UNKNOWN" "PURCHASED" "NTU" "INVALID"

The type of outcome being recorded.

tenant
string

Tenant or scheme name to identify product or group of products.

soldPrice
number

Price the the policy sold for. If supplied, this is checked against the predicted price and a warning is raised if the difference is greater than the configured threshold.

Responses

Request samples

Content type
application/json
{
  • "quoteId": "Q_08281",
  • "result": "PURCHASED",
  • "tenant": "MotorPlus"
}

Response samples

Content type
application/json
{
  • "code": 404,
  • "message": "Record x not found",
  • "errors": {
    }
}

RTP

Access Nuon's Real Time Pricing endpoints. These service are in beta and may change without notice.

Approval (beta)

Run the AI model to generate a price adjustment prediction that should be applied to the premium based on the policy features supplied.

query Parameters
key
required
string
Example: key=AshsgdnAVJ

Key parameter taking the required api key value in the request query to allow access to the resource.

Request Body schema: application/json
any

The approval service doesn't define a specific object format. You can pass data into the service in whatever format is most convenient to you, the service's process is tailored to extract the data it needs from your object format.

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "lines": [
    ],
  • "status": "DECLINED"
}

Rating (beta)

Run the AI model to generate a price adjustment prediction that should be applied to the premium based on the policy features supplied.

query Parameters
key
required
string
Example: key=AshsgdnAVJ

Key parameter taking the required api key value in the request query to allow access to the resource.

Request Body schema: application/json
any

The rating service doesn't define a specific object format. You can pass data into the service in whatever format is most convenient to you, the service's process is tailored to extract the data it needs from your object format.

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "lines": [
    ],
  • "status": "PRICED"
}