> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenticinsuranceprotocol.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Worked example: pet insurance

> A pet insurance flow from discovery to evidence, as the JSON that each tool sends and returns.

A broker, Example Pets, sells the pet insurance of an insurer, Example Mutual, in France. An agent finds the product, quotes a cat called Miso for Alice, and applies for the first offer. Alice approves the application once, on Example Pets' page, where she also signs and pays. All companies, people and prices are fictional. The repository writes these files with [`scripts/examples.ts`](https://github.com/Agentic-Insurance-Foundation/agentic-insurance-protocol/blob/main/scripts/examples.ts) and checks them against the [schema](https://docs.agenticinsuranceprotocol.org/0.1/reference.md) and the rules on every push.

## 1. Find the distributor

*get\_distributor, result*

The agent asks who sells and under which licence. Example Pets is a broker in the ORIAS register, and it declares level 3 for pet insurance in France.

```json spec/examples/insurance-01-get_distributor.result.json theme={null}
{
  "legal_name": "Example Pets SAS",
  "trading_name": "Example Pets",
  "domain": "pets.example.com",
  "roles": [
    "broker"
  ],
  "licences": [
    {
      "country": "FR",
      "regulator": "ACPR",
      "register": "ORIAS",
      "identifier_type": "orias_number",
      "identifier": "00000000",
      "role": "broker",
      "categories": [
        "COA"
      ],
      "verification_url": "https://www.orias.fr/"
    }
  ],
  "countries": [
    "FR"
  ],
  "complaints_url": "https://pets.example.com/complaints",
  "aip": {
    "version": "0.1",
    "conformance_level": 3,
    "lines": [
      "pet"
    ],
    "countries": [
      "FR"
    ]
  }
}
```

## 2. Look for a product

*list\_products, params*

Alice lives in France and wants to insure her cat. The agent asks for the products that cover a cat in France. With the country, the family and the kind, the filters cover the whole structured part of the scope.

```json spec/examples/insurance-02-list_products.params.json theme={null}
{
  "country": "FR",
  "insured_family": "pet",
  "insured_kind": "cat",
  "language": "fr"
}
```

## 3. Read the scope, the tiers and the documents

*list\_products, result*

The product publishes its scope before any question: France only, cats and dogs, and four conditions in plain words. The agent checks the conditions against what Alice said, and asks her when it is not sure. The product names its insurer, Example Mutual, and the agent checks it in the registry before it asks any question. It has two tiers, Essentiel 70 and Essentiel 90, each with its cover and no price. The product also lists its documents. The IPID and the general conditions must reach the customer before they commit.

```json spec/examples/insurance-03-list_products.result.json theme={null}
{
  "products": [
    {
      "product_id": "pet-fr-essentiel",
      "name": "Essentiel",
      "line": "pet",
      "provider": {
        "name": "Example Mutual",
        "legal_name": "Example Mutual Assurances SA",
        "role": "insurer",
        "domain": "mutual.example.com",
        "lei": "EXAMPLEMUTUAL0000042",
        "licences": [
          {
            "country": "FR",
            "regulator": "ACPR",
            "register": "REGAFI",
            "identifier_type": "lei",
            "identifier": "EXAMPLEMUTUAL0000042",
            "role": "insurer",
            "verification_url": "https://www.regafi.fr/"
          }
        ]
      },
      "underwriting_scope": {
        "geography": {
          "countries": [
            "FR"
          ]
        },
        "insured": [
          {
            "family": "pet",
            "kinds": [
              "cat",
              "dog"
            ]
          }
        ],
        "conditions": [
          "The pet lives with the subscriber, in France.",
          "The pet is identified by a microchip or a tattoo.",
          "Not for a dog of category 1 or 2 under French law (attack, guard and defence dogs).",
          "Not for a pet kept for breeding or for professional use."
        ]
      },
      "summary": "Pays back the vet costs of a cat or a dog after an accident or an illness, at 70% or 90%.",
      "tiers": [
        {
          "key": "essentiel-70",
          "name": "Essentiel 70",
          "summary": "70% of the vet costs, up to 1,500 EUR a year.",
          "cover": {
            "included": [
              "Accident",
              "Illness",
              "Surgery"
            ],
            "limits": [
              {
                "key": "vet_costs_per_year",
                "label": "Vet costs per year",
                "limit": {
                  "amount": "1500.00",
                  "currency": "EUR"
                },
                "reimbursement_rate": 0.7
              }
            ],
            "excess": {
              "amount": "0.00",
              "currency": "EUR"
            },
            "main_exclusions": [
              "Pre-existing conditions"
            ],
            "waiting_periods": [
              {
                "applies_to": "Accident",
                "days": 0
              },
              {
                "applies_to": "Illness",
                "days": 45
              },
              {
                "applies_to": "Surgery",
                "days": 45
              }
            ]
          }
        },
        {
          "key": "essentiel-90",
          "name": "Essentiel 90",
          "summary": "90% of the vet costs, up to 2,500 EUR a year.",
          "cover": {
            "included": [
              "Accident",
              "Illness",
              "Surgery"
            ],
            "limits": [
              {
                "key": "vet_costs_per_year",
                "label": "Vet costs per year",
                "limit": {
                  "amount": "2500.00",
                  "currency": "EUR"
                },
                "reimbursement_rate": 0.9
              }
            ],
            "excess": {
              "amount": "0.00",
              "currency": "EUR"
            },
            "main_exclusions": [
              "Pre-existing conditions"
            ],
            "waiting_periods": [
              {
                "applies_to": "Accident",
                "days": 0
              },
              {
                "applies_to": "Illness",
                "days": 45
              },
              {
                "applies_to": "Surgery",
                "days": 45
              }
            ]
          }
        }
      ],
      "options": [
        {
          "key": "prevention",
          "label": "Forfait prévention",
          "price": {
            "amount": {
              "amount": "3.00",
              "currency": "EUR"
            },
            "period": "month",
            "taxes_included": true
          }
        }
      ],
      "documents": [
        {
          "type": "ipid",
          "title": "IPID Example Pets Essentiel",
          "url": "https://pets.example.com/docs/ipid-essentiel-2026-09.pdf",
          "required_before_commitment": true
        },
        {
          "type": "general_conditions",
          "title": "Conditions générales",
          "url": "https://pets.example.com/docs/cg-2026-09.pdf",
          "required_before_commitment": true
        }
      ]
    }
  ]
}
```

## 4. Quote with the answers from the chat

*quote, params*

The agent quotes with the five answers it already has. Each answer has a source. Alice gave four of them, and the agent read the breed from her photo.

```json spec/examples/insurance-04-quote.params.first.json theme={null}
{
  "product_id": "pet-fr-essentiel",
  "answers": {
    "country": "FR",
    "postal_code": "69003",
    "species": "cat",
    "pet_name": "Miso",
    "breed": "European shorthair"
  },
  "answer_sources": {
    "country": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "postal_code": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "species": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "pet_name": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "breed": {
      "origin": "agent",
      "validated_by_customer": false
    }
  },
  "language": "fr"
}
```

## 5. Get the questions that are still open

*quote, result*

The server returns the questions of the product as a JSON Schema, and lists the required answers that are missing. The agent asks Alice only those, and her vet clinic's record gives the date of birth. No question asks for a bank account or an identity number: Example Pets asks for them on its own page.

```json spec/examples/insurance-05-quote.result.needs_input.json theme={null}
{
  "status": "needs_input",
  "answers_schema": {
    "type": "object",
    "properties": {
      "country": {
        "type": "string",
        "pattern": "^[A-Z]{2}$",
        "description": "Country where the pet lives."
      },
      "postal_code": {
        "type": "string",
        "description": "Postal code where the pet lives."
      },
      "species": {
        "type": "string",
        "enum": [
          "dog",
          "cat"
        ],
        "description": "Is the pet a cat or a dog?"
      },
      "pet_name": {
        "type": "string",
        "description": "Name of the pet."
      },
      "breed": {
        "type": "string",
        "description": "Breed of the pet."
      },
      "sex": {
        "type": "string",
        "enum": [
          "female",
          "male"
        ],
        "description": "Sex of the pet."
      },
      "is_neutered": {
        "type": "boolean",
        "description": "Is the pet neutered or spayed?"
      },
      "date_of_birth": {
        "type": "string",
        "format": "date",
        "description": "Date of birth of the pet. An approximate date is fine."
      },
      "lifestyle": {
        "type": "string",
        "enum": [
          "indoor",
          "outdoor"
        ],
        "description": "Does the pet go outside?"
      },
      "currently_insured": {
        "type": "boolean",
        "description": "Is the pet insured with another company today?"
      }
    },
    "required": [
      "country",
      "postal_code",
      "species",
      "pet_name",
      "breed",
      "sex",
      "is_neutered",
      "date_of_birth",
      "currently_insured"
    ]
  },
  "missing_fields": [
    {
      "field": "sex",
      "issue": "missing"
    },
    {
      "field": "is_neutered",
      "issue": "missing"
    },
    {
      "field": "date_of_birth",
      "issue": "missing",
      "message": "An approximate date is fine."
    },
    {
      "field": "currently_insured",
      "issue": "missing"
    }
  ]
}
```

## 6. Quote with every answer

*quote, params*

The agent sends all the answers and their sources again. The date of birth comes from a third party, named in `source_name`.

```json spec/examples/insurance-06-quote.params.complete.json theme={null}
{
  "product_id": "pet-fr-essentiel",
  "answers": {
    "country": "FR",
    "postal_code": "69003",
    "species": "cat",
    "pet_name": "Miso",
    "breed": "European shorthair",
    "sex": "female",
    "is_neutered": true,
    "date_of_birth": "2023-04-01",
    "lifestyle": "indoor",
    "currently_insured": false
  },
  "answer_sources": {
    "country": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "postal_code": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "species": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "pet_name": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "breed": {
      "origin": "agent",
      "validated_by_customer": false
    },
    "sex": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "is_neutered": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "date_of_birth": {
      "origin": "third_party",
      "validated_by_customer": false,
      "source_name": "veterinary clinic record (FR)"
    },
    "lifestyle": {
      "origin": "customer",
      "validated_by_customer": true
    },
    "currently_insured": {
      "origin": "customer",
      "validated_by_customer": true
    }
  },
  "language": "fr"
}
```

## 7. Compare the offers

*quote, result*

Two offers, one for each tier of the product, in the same shape, each with its excess, its limits, its fees and its documents. Their price can change after the insurer's checks, and the approval page shows the firm price.

```json spec/examples/insurance-07-quote.result.offers.json theme={null}
{
  "status": "complete",
  "offers": [
    {
      "offer_id": "of-3c81",
      "product_id": "pet-fr-essentiel",
      "tier": "essentiel-70",
      "provider": {
        "name": "Example Mutual",
        "legal_name": "Example Mutual Assurances SA",
        "role": "insurer",
        "domain": "mutual.example.com",
        "lei": "EXAMPLEMUTUAL0000042",
        "licences": [
          {
            "country": "FR",
            "regulator": "ACPR",
            "register": "REGAFI",
            "identifier_type": "lei",
            "identifier": "EXAMPLEMUTUAL0000042",
            "role": "insurer",
            "verification_url": "https://www.regafi.fr/"
          }
        ]
      },
      "pricing": {
        "premium": {
          "amount": {
            "amount": "14.90",
            "currency": "EUR"
          },
          "period": "month",
          "taxes_included": true
        },
        "fees": [],
        "cover": {
          "included": [
            "Accident",
            "Illness",
            "Surgery"
          ],
          "limits": [
            {
              "key": "vet_costs_per_year",
              "label": "Vet costs per year",
              "limit": {
                "amount": "1500.00",
                "currency": "EUR"
              },
              "reimbursement_rate": 0.7
            }
          ],
          "excess": {
            "amount": "0.00",
            "currency": "EUR"
          },
          "main_exclusions": [
            "Pre-existing conditions"
          ],
          "waiting_periods": [
            {
              "applies_to": "Accident",
              "days": 0
            },
            {
              "applies_to": "Illness",
              "days": 45
            },
            {
              "applies_to": "Surgery",
              "days": 45
            }
          ]
        }
      },
      "valid_until": "2026-11-19T23:59:59+01:00",
      "handoff_url": "https://pets.example.com/q/of-3c81",
      "documents": [
        {
          "type": "ipid",
          "title": "IPID Example Pets Essentiel",
          "url": "https://pets.example.com/docs/ipid-essentiel-2026-09.pdf",
          "required_before_commitment": true
        },
        {
          "type": "general_conditions",
          "title": "Conditions générales",
          "url": "https://pets.example.com/docs/cg-2026-09.pdf",
          "required_before_commitment": true
        }
      ]
    },
    {
      "offer_id": "of-3c82",
      "product_id": "pet-fr-essentiel",
      "tier": "essentiel-90",
      "provider": {
        "name": "Example Mutual",
        "legal_name": "Example Mutual Assurances SA",
        "role": "insurer",
        "domain": "mutual.example.com",
        "lei": "EXAMPLEMUTUAL0000042",
        "licences": [
          {
            "country": "FR",
            "regulator": "ACPR",
            "register": "REGAFI",
            "identifier_type": "lei",
            "identifier": "EXAMPLEMUTUAL0000042",
            "role": "insurer",
            "verification_url": "https://www.regafi.fr/"
          }
        ]
      },
      "pricing": {
        "premium": {
          "amount": {
            "amount": "21.40",
            "currency": "EUR"
          },
          "period": "month",
          "taxes_included": true
        },
        "fees": [],
        "cover": {
          "included": [
            "Accident",
            "Illness",
            "Surgery"
          ],
          "limits": [
            {
              "key": "vet_costs_per_year",
              "label": "Vet costs per year",
              "limit": {
                "amount": "2500.00",
                "currency": "EUR"
              },
              "reimbursement_rate": 0.9
            }
          ],
          "excess": {
            "amount": "0.00",
            "currency": "EUR"
          },
          "main_exclusions": [
            "Pre-existing conditions"
          ],
          "waiting_periods": [
            {
              "applies_to": "Accident",
              "days": 0
            },
            {
              "applies_to": "Illness",
              "days": 45
            },
            {
              "applies_to": "Surgery",
              "days": 45
            }
          ]
        }
      },
      "valid_until": "2026-11-19T23:59:59+01:00",
      "handoff_url": "https://pets.example.com/q/of-3c82",
      "documents": [
        {
          "type": "ipid",
          "title": "IPID Example Pets Essentiel",
          "url": "https://pets.example.com/docs/ipid-essentiel-2026-09.pdf",
          "required_before_commitment": true
        },
        {
          "type": "general_conditions",
          "title": "Conditions générales",
          "url": "https://pets.example.com/docs/cg-2026-09.pdf",
          "required_before_commitment": true
        }
      ]
    }
  ]
}
```

## 8. Get a reason when there is no offer

*quote, result*

For a dog born in 2015, the insurer makes no offer and gives a stable reason code.

```json spec/examples/insurance-08-quote.result.no_offer.json theme={null}
{
  "status": "complete",
  "offers": [],
  "no_offer": {
    "reason_code": "age_not_accepted",
    "message": "Example Mutual does not start cover for a dog older than 9 years."
  }
}
```

## 9. Refuse a risk outside the scope

*quote, result*

A cat that lives in the United Kingdom is outside the geography of the scope. An agent that follows the rules does not send this quote. The server refuses it anyway, with the reason `outside_underwriting_scope`.

```json spec/examples/insurance-09-quote.result.outside_scope.json theme={null}
{
  "status": "complete",
  "offers": [],
  "no_offer": {
    "reason_code": "outside_underwriting_scope",
    "message": "Essentiel covers pets that live in France. Pixel lives in the United Kingdom."
  }
}
```

## 10. Apply

*submit\_application, params*

Alice chooses Essentiel 70. The agent sends the offer and the parties. It does not send the answers again: the server takes them, with their sources, from the offer.

```json spec/examples/insurance-10-submit_application.params.json theme={null}
{
  "offer_id": "of-3c81",
  "parties": [
    {
      "party_ref": "p1",
      "kind": "person",
      "roles": [
        "subscriber",
        "insured",
        "payer"
      ],
      "display_name": "Alice",
      "country_of_residence": "FR"
    }
  ],
  "language": "en"
}
```

## 11. Get the page to approve

*submit\_application, result*

Nothing is committed yet. The summary gives the price and each answer with its source, and asks Alice to approve only if each answer is true and complete. The agent gives Alice the `url`, which holds a token of its own, and keeps the `application_key` to itself.

```json spec/examples/insurance-11-submit_application.result.json theme={null}
{
  "application_id": "app-3310",
  "application_key": "k9VdQ2xLm7Rt4Wb1Zp8NcY3s",
  "summary": "Apply for Essentiel 70 cat insurance for Miso with Example Mutual: 14.90 EUR a month, 70% of vet costs up to 1,500 EUR a year, no excess, no fees. Check Miso's answers. You said: lives in France, postal code 69003, a female cat named Miso, spayed, stays indoors, not insured today. Your assistant read the breed from your photo, and you have not checked it yet: European shorthair. Your vet clinic's record gives the date of birth, and you have not checked it yet: 1 April 2023. If an answer is false, Example Mutual can refuse to pay a claim or cancel the cover. Approve only if each answer is true and complete. Then you sign and pay on the same page.",
  "url": "https://pets.example.com/approve/Hq2xK9mVb3RtL0wPz4N8aJ",
  "expires_at": "2026-10-20T11:00:00+02:00"
}
```

## 12. Approve on the seller's page

*get\_operation, params*

On Example Pets' page, Alice reads the documents, checks the answers and the firm price, and approves. Then she signs and pays on the same page. The agent reads the application with its ID and its key.

```json spec/examples/insurance-12-get_operation.params.json theme={null}
{
  "application_id": "app-3310",
  "application_key": "k9VdQ2xLm7Rt4Wb1Zp8NcY3s"
}
```

## 13. Learn the outcome

*get\_operation, result*

Alice approved. Example Pets keeps what she approved, with the answers and their sources, for the period that the law requires.

```json spec/examples/insurance-13-get_operation.result.approved.json theme={null}
{
  "application_id": "app-3310",
  "state": "approved"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.