# How to turn an Excel rater into an API

> A practical guide to turning an Excel rating workbook into a pricing API: what the endpoint looks like, mapping cells to inputs, reproducing rounding, testing against the workbook, versioning and response times.

By Ptally Pricing Team, 4 November 2026. Category: Engineering.
Source: https://ptally.ai/blog/excel-rater-to-api

To turn an Excel rater into an API, you rebuild the workbook's calculation as a model that a rating engine can run, give it a defined set of named inputs, and expose it behind a single endpoint that takes those inputs as JSON and returns a price. You prove the API is right by running the workbook's own worked examples through it and matching every result to the penny. You do not wrap the spreadsheet itself in a web service. That route keeps every weakness of the workbook and adds new ones.

This article is about the mechanics of that move. If you are still deciding whether to leave Excel at all, start with [replacing a spreadsheet rater](https://ptally.ai/blog/replacing-a-spreadsheet-rater).

## What the endpoint should look like

Start from the end. A pricing API needs one call that prices one risk. On Ptally that call is `POST /quotes/:project_reference`, where the project is your product. The body is a flat set of fields that the model defines:

```bash
curl -X POST "$PTALLY_API/quotes/$PROJECT_REFERENCE" \
  -H "client_id_key: $PTALLY_CLIENT_ID" \
  -H "client_secret_key: $PTALLY_CLIENT_SECRET" \
  -H "content-type: application/json" \
  -d '{"species":"cat","breed":"persian","pet_age":3,"region":"greater_london","vet_fee_limit":4000,"excess":100,"neutered":true,"client_ref":"POL-10234"}'
```

The response carries the price, whether the quote is valid, which rules fired and which version priced it:

```json
{
  "quote_reference": "<uuid>",
  "project_reference": "<uuid>",
  "version_reference": "<uuid>",
  "version": 1,
  "result": 255.34,
  "valid": true,
  "refers": [],
  "exclusions": [],
  "output": { "result": 255.34, "valid": true, "monthly_premium": 21.28, "refer": false },
  "client_ref": "POL-10234",
  "created_at": "<timestamp>"
}
```

Agreeing this shape early helps. The team calling the API can build against it while the model is still being rebuilt. The full reference is on our [API page](https://ptally.ai/developer/api).

## Map cells to inputs

A workbook rarely has a clean input list. Inputs are scattered across an input sheet, dropdowns, hidden helper cells and sometimes values typed straight into formulas. The first job is to write them down.

For each input cell, record:

- a field name in plain words, such as `pet_age` rather than `Inputs!C7`;
- its type: number, text or true or false;
- the allowed values, taken from the dropdown list or data validation;
- what the workbook does when the cell is blank.

Keep inputs flat. An API caller should send `region`, not a nested address object. Derived values, such as an age band worked out from a date of birth, belong inside the model, not in the request. The caller sends facts about the risk. The model does the pricing.

## Rebuild the calculation as ordered steps

A Ptally model is a JSON file of ordered steps: lookups against rate tables, calculations, transforms, exclusions and referrals. Each step reads the values before it and adds new ones. Rebuilding a workbook means tracing its formula chain and writing it out in that order.

Rate tables come out of the workbook as tables, not as formulas. A `VLOOKUP` against a breed sheet becomes a lookup step against a breed table. A nested `IF` that declines pets over a certain age becomes an exclusion rule. AI can read the workbook and draft these steps and tables, which removes most of the typing. Each step still gets checked against the workbook. You can see a complete model on our [developer page](https://ptally.ai/developer).

## Reproduce rounding exactly

Rounding is where most mismatches come from. Excel rounds where the formula says to, and the displayed value often hides the unrounded figure underneath. Check each of these:

- **Where rounding happens.** Rounding the risk premium before adding tax gives a different answer from rounding only the final premium.
- **Which function is used.** `ROUND`, `ROUNDUP`, `MROUND` and cell formatting all behave differently.
- **Hidden precision.** A cell shown as 1.30 may hold 1.2999.

Write rounding into the model as explicit steps. In the Ptally pet example, the risk premium step is `round({{base_premium}} * {{pet_age_factor}} * ... , 2)`, so the rounding point is visible to anyone reading the model.

## Turn the workbook's examples into tests

The workbook is your test oracle. Every set of inputs you run through it gives you an expected result. Build a test suite from:

1. the worked examples the actuary used when setting the rates;
2. values on either side of each band boundary;
3. every decline and referral rule, plus a case just inside each;
4. a sample of real quotes priced by the workbook recently.

Each test stores the inputs and the expected `result` and `valid` values. Ptally runs the suite on every change, so a test that passes today keeps being checked. When one fails, add `?debug=true` to the quote request. The response gains a `debug` property showing every input, lookup, formula and rule the engine evaluated, which you can compare line by line with the workbook. Our article on [testing insurance pricing models](https://ptally.ai/blog/testing-insurance-pricing-models) covers test design in more depth.

## Version every change

A spreadsheet's version history is usually a folder of renamed files. An API needs better than that, because callers need to know which rates priced which quote.

On Ptally every model change creates a version that moves through draft, approval and publishing. Live quotes are priced by the published version only, so you can edit a draft without affecting traffic. Every quote response includes `version` and `version_reference`, which ties each price back to an exact model.

## Response times

A workbook recalculating on a desktop is fine for an underwriter. It is not fine for a broker platform or a price comparison website sending traffic at peak. A rating engine runs the model directly, without opening a file. The `debug` output includes a timer for each step, so you can see where time goes in your own model. Ptally has served over 50 million quotes and is live on price comparison websites at peak aggregator traffic.

## A short checklist

1. Agree the request and response shape.
2. List every input cell with a name, type and allowed values.
3. Extract rate tables and rebuild the formula chain as ordered steps.
4. Make every rounding point explicit.
5. Build tests from the workbook and run them until all pass.
6. Approve and publish the first version, then point callers at it.

## Getting started

Ptally is free to build on, with no implementation fee. Send us your workbook and its worked examples, and the model is built on the platform, tested against the spreadsheet's own results and published behind the API. Pricing experts can build it for you as part of that. Read the [developer guide](https://ptally.ai/developer), the [API reference](https://ptally.ai/developer/api), or see the plans on our [pricing section](https://ptally.ai/#pricing).