Cancellation API

Before getting started, Scrive has to be in place:

Scrive API key has to be sent to us and added to your account configuration
Cancellation PDF template with correct parameterization has to be sent to us

The Cancellation API along with insurance collection module makes it possible to collect power of attorney for insurance cancellations.

Order of operation

Insurance collection has already been performed - please see separate documentation

Create cancellations - POST /cancellations - Power of attorney documents for the insurance cancellations are sent to the insurance holder for digital signature by Scrive - either by e-mail or SMS. - Document IDs are returned

Get current status of document signature - GET /cancellations/{documentId} - Status is CLOSED when signed

When cancellation has been signed, PDF of signed cancellation can be retrieved and archvied - GET /cancellations/{documentId}/pdf

Authentication

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

Header	Header Value
Authorization-token	Your API key
Insurely-Version	The API version you integrate against, for example `2026-04-01`

If your organisation uses the Insurely 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@insurely.com and we'll provide one.

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

Environments

Environment	Base URL
Production	`https://api.insurely.com`
Test	`https://api.test.insurely.com`

Use the API key issued for the environment you call.

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@insurely.com for each environment. 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 Insurely-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.

Header	Header Value
Insurely-Version	The version of the API, as `YYYY-MM-DD`

Mutual TLS (mTLS)

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

Create two private keys and two Certificate Signing Requests (CSR), one for test and one for production, and send them to support@insurely.com. We will sign and send the certificates back.

genrsa -out my_test_client.key 2048
openssl req -new -key my_test_client.key -out my_test_client.csr
openssl genrsa -out my_prod_client.key 2048
openssl req -new -key my_prod_client.key -out my_prod_client.csr

Verify your received certificates

curl --key my_test_client.key --cert my_test_client.pem  'https://mtls.api.test.insurely.com/health'
curl --key my_prod_client.key --cert my_prod_client.pem  'https://mtls.api.insurely.com/health'

You should get the same response for both requests:

{ "status": "healthy" }

To enforce mTLS - prefix all urls with the mtls subdomain as shown in verification examples above.