PARTNERING INSURTECH LIMITED Aggregator: Merchant API

Public: this route is mounted before authentication.

Public. servers[0].url is rewritten from the request host so the document points back at the deployment that served it.

Public. An HTML page that renders /api/v1/openapi.json with ReDoc.

The classes, categories and product types products are filed under. Only active nodes are served, grouped by level and sorted by parent then sort order.

Only products available to this business in this key's environment are listed; availability cannot be relaxed from the query string.

Paging is by opaque cursor. Send no cursor for the first page, then send back the nextCursor the previous page returned, unchanged, until nextCursor is null. A page may be shorter than limit and still carry a nextCursor: a short page is not the end of the list, only a null nextCursor is. A cursor this API did not issue is refused with 400.

Text search (q) is single-page: it answers the best matches for the query and always returns nextCursor: null, so pair q with limit rather than paging it.

A product this business may not sell, one hidden by its status, and one that does not exist are the same 404. The configuration is best-effort: when the insurer cannot be reached for it the product is still served, with config: null and configStatus: "unavailable".

The share of each available product's price this business receives, resolved from the platform's commercial configuration. The platform's own share is never included. Scoped to the key's environment, exactly as GET /products is.

Paging is by opaque cursor, exactly as GET /products pages: send no cursor for the first page, then send back the nextCursor the previous page returned, unchanged, until nextCursor is null. A page may be shorter than limit and still carry a nextCursor; only a null nextCursor means the list is exhausted. A cursor this API did not issue is refused with 400.

Returns the insurer's form document for one context. The form is validated against the OIIS form schema before it is served: a form that fails validation is 422, with the validator's findings in fieldErrors. Keep formId and formVersion, because quoting requires them. The renewal and endorsement contexts can be fetched but have no submit route in this version, so build no flow on them yet.

For fields whose options come from the insurer rather than the form document. The field's declared options URL is interpolated from values, so send the answers it names; a placeholder with no answer, a non-scalar answer, or an answer that would escape the insurer's namespace is 400 and names the offending path. A field that loads no options remotely (and a form version this business never fetched) is 404. Searchable fields refuse a query shorter than the field's minimum.

Reserves a slot with the insurer for one file and hands back the URL to PUT the bytes to. Upload the file yourself, then quote the fileId in a claim's attachments[] or in an attach-document request. An insurer that caps out on the size answers 413 UPLOAD_TOO_LARGE.

One row per product this business may sell of the given product type, over the same coverage dictionary rows and the same comparison attributes, so the rows line up column by column. A product this business may not sell is simply absent: the response never names it, never says why, and no field relaxes that.

Every premium is read from what the insurer already published. Set quotes to true to additionally ask for an indicative quote wherever one can be asked for; inputs and a UUIDv4 Idempotency-Key are then required, at most 10 insurers are asked, and any beyond that carry premiumUnavailable.reason: "QUOTE_LIMIT_REACHED". The Idempotency-Key header is read only when quotes is true, and a product whose insurer publishes an exact price is never re-quoted.

Nothing here ranks, recommends or re-prices: the only ordering is the sort asked for, and every amount is an integer in minor units carrying its own currency.

The quotes this business has requested, newest first.

Prices a product with the answers collected on its quote form. formId and formVersion must be the ones /products/{providerId}/{productId}/form served. The stored quote is validated against the OIIS quote schema: an insurer response that fails it is 422 and no retry of the same request will help. Fetch the form from GET /products/{providerId}/{productId}/form before quoting: a formId@formVersion this API has not fetched from that insurer is 422 VALIDATION_FAILED, not 404.

A quote another business owns is the same 404 as one that does not exist.

The purchases this business has made, newest first.

Turns a usable quote into a policy. Collect the premium yourself and describe the settled payment in payment; amountMinor must match the quote's total, or the request is 409 AMOUNT_MISMATCH. A quote that has expired or has already been bought is 409.

A purchase another business owns is the same 404 as one that does not exist.

The policies this business has sold, newest first. Each row carries the last policy document read from the insurer; read the policy itself for a live view.

Reads the policy from the insurer, not from the stored row, so the state is current. A policy another business owns is a 404 and the insurer is never called.

Lists the documents the insurer holds for this policy, so a documentId can be discovered rather than guessed. Read the bytes of one with GET /policies/{providerId}/{policyId}/documents/{documentId}. A policy another business owns is a 404 and the insurer is never called.

Answers the decoded bytes, not JSON. Content-Type is the insurer's media type when it is a well-formed type and application/octet-stream otherwise; Content-Disposition is always attachment with a sanitised filename, falling back to the document id. A document larger than the ceiling this API will hold in memory is refused with 502 rather than streamed: DOCUMENT_TOO_LARGE when the insurer inlines the bytes, DOCUMENT_REDIRECT_REFUSED when a signed-redirect download overruns the ceiling or its URL fails the redirect policy.

Answers 200 whether the insurer cancelled outright or took the request under review: read outcome to tell them apart. A policy the insurer will not cancel is 409 POLICY_NOT_CANCELLABLE.

The claims this business has filed, newest first. Each row carries the last claim document read from the insurer; read the claim itself for a live view.

Files a claim against a policy this business sold. Attach evidence by reserving slots at /uploads, uploading the bytes, and quoting the fileIds here. A claim against a policy another business owns is a 404. When you send formId and formVersion, fetch that form from GET /products/{providerId}/{productId}/form first: a form this API has not fetched from that insurer is 422 VALIDATION_FAILED, not 404.

Reads the claim from the insurer, not from the stored row. A claim another business owns is a 404 and the insurer is never called.

Quotes a fileId from /uploads against an open claim. Answers 200 with the updated claim, replayed or not.

A claim gets one appeal. A claim in a state that cannot be appealed, and one that has already used its appeal, are both 409 APPEAL_NOT_ALLOWED.

Every event this API has sent, or is still trying to send, to the webhook endpoint of this business in this environment, newest first. Deliveries of another business are never listed, and neither the signing secret nor the endpoint of anyone else is ever part of a row.

The same row the list serves, plus the exact event body that was signed and the endpoint it was sent to. A delivery this business does not own is a 404, indistinguishable from one that never existed.

Queues the delivery again from a clean slate: the status goes back to PENDING, the attempt counter to zero, the last failure is cleared and the next sweep sends it. PENDING, FAILED and DEAD deliveries can be retried; one that already succeeded is 409 INVALID_STATE_TRANSITION. No attempt is made while your request is open, so a 200 means queued, not delivered. The retry is recorded against your Idempotency-Key, so repeating that key replays the stored result with Idempotency-Replayed: true; the delivery is queued once, and a key repeated after the delivery has since succeeded still replays that stored result rather than answering 409.

The endpoints of this business in the environment of the key, oldest first. A business holds at most 10 endpoints per environment, so the list is not paged. Signing secrets are never part of a row.

Registers an endpoint in the environment of the key and mints its signing secret. The secret is returned in this response only: store it now. Events are sent to the endpoint only when their name is in events; ["*"] subscribes to every event, including ones added later. The URL must be https and reach a public host. Repeating the Idempotency-Key replays the stored endpoint with 200, Idempotency-Replayed: true and without secret, since the plaintext secret is never stored; recover it by rotating the secret with POST /webhook-endpoints/{endpointId}/rotate-secret, which returns a new secret once. More than 10 endpoints per environment, an unknown event name or a URL the policy refuses is 422 VALIDATION_FAILED.

One endpoint of this business in the environment of the key. An endpoint of another business or of the other environment is 404.

Removes the endpoint. Nothing more is sent to its URL: deliveries still pending for it stop with FAILED.

Changes the fields sent and leaves the others as they are. A null description clears it. Disabling an endpoint stops new deliveries to it, and deliveries still pending for it stop with FAILED. Fields other than url, events, description and enabled are ignored.

Mints a new signing secret and returns it in this response only. The previous secret keeps signing alongside the new one for 24 hours, so your receiver can switch over without dropping events: during that window every event carries a signature for each secret.

Sends a signed webhook.test event to the endpoint now, whatever events it subscribes to, and answers what your endpoint replied. The event is not queued, retried or written to the delivery log. A 2xx answer from an endpoint of the test environment completes the webhook step of the production activation checklist, exactly as a real delivery does. A disabled endpoint, or one whose signing secret was revoked, is sent nothing.

Every event name an endpoint can subscribe to, and the wildcard that subscribes to all of them.