Cancellation API

The Cancellation API, together with insurance collection, creates a power of attorney (PoA) for cancelling the insurances a consumer has collected. The PoA is filled in with the collected insurance data.

There are two ways to get the PoA signed, chosen with documentType when creating the cancellation:

  • SCRIVE (default): we send the PoA to the insurance holder for signing through your Scrive account, by e-mail or SMS, and track the signing status.
  • MANUAL: we only create the PoA. You fetch the unsigned PDF, get it signed in your own signing solution (for example with BankID), send it to the insurer, and report the outcome back.

Before getting started

  • A cancellation PDF template with the correct parameterization has to be sent to us (both types).
  • For Scrive cancellations only: your Scrive API key has to be sent to us and added to your account configuration.

Order of operation: Scrive

  1. Insurance collection has already been performed - please see separate documentation
  1. Create cancellations with POST /cancellations, with documentType: SCRIVE (or no documentType), a deliveryMethod and an authenticationMethod. The PoA is sent to the insurance holder for digital signature by Scrive, by e-mail or SMS. Document IDs are returned
  1. Get the current status of the signature with GET /cancellations/{documentId}. The status is CLOSED when signed
  1. When the cancellation has been signed, retrieve and archive the signed PDF with GET /cancellations/{documentId}/pdf

Order of operation: Manual

  1. Insurance collection has already been performed - please see separate documentation
  1. Create cancellations with POST /cancellations and documentType: MANUAL. The PoA is created but not sent anywhere. Document IDs are returned and the status is CREATED
  1. Fetch the unsigned PoA with GET /cancellations/{documentId}/pdf, have the insurance holder sign it in your own signing solution, and send it to the insurer
  1. Report the outcome with POST /cancellations/{documentId}/status (PENDING, CLOSED, REJECTED or CANCELED), so the cancellation shows the right status

GET /cancellations/{documentId}/delivery-status and POST /cancellations/{documentId}/cancel only work for Scrive cancellations; for a manual one they return 409.

Authentication

Calls from your server authenticate with an API key, sent in the Authorization-token header. Send Api-Version on every request too (see API versioning).

HeaderHeader Value
Authorization-tokenYour API key
Api-VersionThe API version you integrate against, for example 2026-04-01

Getting an API key

If your organisation uses the Anessa Hub, a customer admin can create and delete API keys there: open your client's settings and go to the API & Credentials tab. You can have several keys at once, so to rotate a key, create a new one, deploy it, then delete the old one. Without Hub access, email support@anessa.co and we'll provide one.

Keep API keys on your server. Never put them in a web page or mobile app.

Base URL

All requests go to https://api.anessa.co.

IP allowlist

Requests authenticated with an API key are only accepted from the IP addresses registered for your client. Send your servers' outbound IP addresses to support@anessa.co. A request from an address that isn't registered gets 401 with the message Authentication failed, the same response as an invalid key, so check both when you see it.

API Versioning

Every request should send the Api-Version header with the date of the version you integrate against, such as 2026-04-01. The version these pages describe is shown in the API picker at the top of the sidebar.

If the header is missing, or names a version older than your client's minimum version, the API uses your client's minimum version instead. That is usually an older version than the one you are reading about, with different endpoints and fields, so always send the header.

HeaderHeader Value
Api-VersionThe version of the API, as YYYY-MM-DD

Moving from Insurely-Version

Api-Version replaces the Insurely-Version header. Both take the same value, and the rename changes nothing else about a request or its response.

  • Insurely-Version keeps working for API versions up to and including 2026-04-01.
  • Versions after 2026-04-01 accept only Api-Version. A request that sends Insurely-Version with a later version returns 400.
  • Send only one of the two headers. A request that sends both returns 400.

To migrate, rename the header in your requests. You can do that today, on the version you already use.

Mutual TLS (mTLS)

Our APIs have support for mTLS. These are the steps needed to enable mTLS for your client.

Create a private key and a Certificate Signing Request (CSR) and send the CSR to support@anessa.co. We will sign it and send the certificate back.

openssl genrsa -out my_client.key 2048
openssl req -new -key my_client.key -out my_client.csr

Verify your received certificate

curl --key my_client.key --cert my_client.pem  'https://mtls.api.insurely.com/health'

You should get this response:

{ "status": "healthy" }

To enforce mTLS, prefix all URLs with the mtls subdomain as shown in the verification example above.