Worked example: pet insurance - Agentic Insurance Protocol

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 and checks them against the schema 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.

spec/examples/insurance-01-get_distributor.result.json

{
  "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.

spec/examples/insurance-02-list_products.params.json

{
  "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.

spec/examples/insurance-03-list_products.result.json

{
  "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.

spec/examples/insurance-04-quote.params.first.json

{
  "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.

spec/examples/insurance-05-quote.result.needs_input.json

{
  "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.

spec/examples/insurance-06-quote.params.complete.json

{
  "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.

spec/examples/insurance-07-quote.result.offers.json

{
  "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.

spec/examples/insurance-08-quote.result.no_offer.json

{
  "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.

spec/examples/insurance-09-quote.result.outside_scope.json

{
  "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.

spec/examples/insurance-10-submit_application.params.json

{
  "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.

spec/examples/insurance-11-submit_application.result.json

{
  "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.

spec/examples/insurance-12-get_operation.params.json

{
  "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.

spec/examples/insurance-13-get_operation.result.approved.json

{
  "application_id": "app-3310",
  "state": "approved"
}

​1. Find the distributor

​2. Look for a product

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

​4. Quote with the answers from the chat

​5. Get the questions that are still open

​6. Quote with every answer

​7. Compare the offers

​8. Get a reason when there is no offer

​9. Refuse a risk outside the scope

​10. Apply

​11. Get the page to approve

​12. Approve on the seller’s page

​13. Learn the outcome