Start free trial

Screen your whole debtor book against ASIC notices in one API call

A worked example for developers using the ASIC insolvency notices API: check thousands of customers with POST /v1/match, then watch them and receive signed webhooks, in Node and Python.

Insolvency Alerts6 min read

Your debtor book is a list of companies you are owed money by. ASIC publishes a notice whenever one of them enters liquidation, administration or restructuring. This post joins the two with the Insolvency Alerts ASIC notices API: one call to check the whole book today, and a watch that tells you about tomorrow’s notices.

The short version

  1. POST /v1/match with every ACN or ABN you have, and get back the ones with insolvency notices.
  2. POST /v1/watches with the same list, to keep watching it.
  3. Add a webhook, and verify each delivery’s HMAC-SHA256 signature before trusting it.

You need an account key (ask_...), which you get when you subscribe, and a CSV export of your customers with an ACN or ABN column.

Step 1: Screen the book once

POST /v1/match takes up to 50,000 identifiers and returns only the ones with notices. It stores nothing, so it is safe to run as often as you like.

Node

import { readFile } from "node:fs/promises";
const API = "https://api.insolvencyalerts.com.au";
const KEY = process.env.INSOLVENCY_ALERTS_KEY; // ask_...
// One ACN or ABN per line; a real export would parse the CSV properly.
const identifiers = (await readFile("customers.txt", "utf8"))
.split(/\r?\n/)
.map((line) => line.replace(/\s/g, ""))
.filter(Boolean);
const res = await fetch(`${API}/v1/match`, {
method: "POST",
headers: { "X-API-Key": KEY, "Content-Type": "application/json" },
body: JSON.stringify({ identifiers }),
});
if (!res.ok) throw new Error(`match failed: ${res.status} ${await res.text()}`);
const { data } = await res.json();
console.log(`Checked ${data.checked}, ${data.matched} with insolvency notices`);
for (const m of data.matches) console.log(m.acn, m.notice_count);
if (data.unresolved.length) console.warn("Could not resolve:", data.unresolved);

Python

import os
import requests
API = "https://api.insolvencyalerts.com.au"
KEY = os.environ["INSOLVENCY_ALERTS_KEY"] # ask_...
with open("customers.txt") as f:
identifiers = ["".join(line.split()) for line in f if line.strip()]
res = requests.post(
f"{API}/v1/match",
headers={"X-API-Key": KEY},
json={"identifiers": identifiers},
timeout=60,
)
res.raise_for_status()
data = res.json()["data"]
print(f"Checked {data['checked']}, {data['matched']} with insolvency notices")
for m in data["matches"]:
print(m["acn"], m["notice_count"])
if data["unresolved"]:
print("Could not resolve:", data["unresolved"])

The response looks like this:

{
"data": {
"checked": 2,
"matched": 1,
"matches": [{ "acn": "163753428", "notice_count": 3 }],
"unresolved": [],
"include_deregistration": false
}
}

Two things to check in it:

  • unresolved lists any ABN that ASIC’s register couldn’t turn into an ACN, often a sole trader or trust, which can’t appear in company notices anyway. Nothing is dropped silently.
  • include_deregistration is false by default, so notice_count counts only insolvency notices. About nine in ten ASIC notices are deregistrations, and counting them would flag nearly every company.

For each match, GET /v1/companies/{acn} returns the notices themselves, each with a source_url back to ASIC. Our guide to reading an ASIC insolvency notice explains every field.

Step 2: Keep watching it

A match tells you about the past. A watch tells you about new notices as ASIC publishes them.

Terminal window
curl -X POST https://api.insolvencyalerts.com.au/v1/watches \
-H "X-API-Key: $INSOLVENCY_ALERTS_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"debtor book","identifiers":["163753428","32613554233"]}'
{ "id": "wch_...", "name": "debtor book", "acn_count": 2, "unresolved": [] }

A watch’s matches include its full history, so a company that was already in liquidation when you added it shows up straight away. Keep the list current as customers come and go with POST and DELETE on /v1/watches/{id}/acns.

Two options when you create the watch:

  • Narrow it with filters. Add "appointment_type": ["Court Liquidation", "Creditors' Voluntary Liquidation"] to hear about only those.
  • Email as well. PATCH /v1/watches/{id} with {"alert_email": ["credit@yourco.example"]} sends each match to up to 10 addresses.

Step 3: Receive matches as webhooks

Register an https endpoint on the watch:

Terminal window
curl -X POST https://api.insolvencyalerts.com.au/v1/watches/wch_.../webhook \
-H "X-API-Key: $INSOLVENCY_ALERTS_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://your-app.example/asic"}'

The response includes a secret (whsec_...), shown once. Store it: it is how you prove a delivery came from us.

Each delivery is a POST with the notice as JSON and two headers:

  • X-ASIC-Signature: sha256= followed by an HMAC-SHA256 of the raw body, keyed with your secret.
  • X-ASIC-Delivery: an id that stays the same across retries, so you can ignore a repeat.

Verify in Node (Express)

import crypto from "node:crypto";
import express from "express";
const app = express();
// express.raw, not express.json: the signature covers the exact bytes sent.
app.post("/asic", express.raw({ type: "application/json" }), (req, res) => {
const want = Buffer.from(
"sha256=" + crypto.createHmac("sha256", process.env.ASIC_WEBHOOK_SECRET)
.update(req.body).digest("hex"),
);
const sent = Buffer.from(req.get("X-ASIC-Signature") ?? "");
if (sent.length !== want.length || !crypto.timingSafeEqual(sent, want)) {
return res.sendStatus(401);
}
const { watch_id, notice } = JSON.parse(req.body.toString("utf8"));
queue.add({ delivery: req.get("X-ASIC-Delivery"), watch_id, notice });
res.sendStatus(200); // acknowledge fast, work later
});

Verify in Python (Flask)

import hashlib
import hmac
import os
from flask import Flask, abort, request
app = Flask(__name__)
@app.post("/asic")
def asic():
raw = request.get_data() # the raw bytes, before any parsing
expected = "sha256=" + hmac.new(
os.environ["ASIC_WEBHOOK_SECRET"].encode(), raw, hashlib.sha256
).hexdigest()
if not hmac.compare_digest(expected, request.headers.get("X-ASIC-Signature", "")):
abort(401)
payload = request.get_json()
queue.put((request.headers["X-ASIC-Delivery"], payload["watch_id"], payload["notice"]))
return "", 200

Things that trip people up

Symptom Cause Fix
Every signature fails The framework parsed and re-serialised the JSON before you hashed it Hash the raw body bytes
The same notice arrives twice A retry after your endpoint timed out Store X-ASIC-Delivery and skip repeats
Deliveries stop The endpoint failed 10 times in a row, so the watch paused Fix the endpoint, then PATCH the watch with {"active": true}
A redirect “works” but nothing arrives Redirects are not followed Give the final https URL
Slow endpoint times out Deliveries are abandoned after 10 seconds Acknowledge with 200 first, then process

Where to go from here

Questions

How many companies can I check in one call?

POST /v1/match and the watch routes accept up to 50,000 identifiers per request. How many you can keep watched depends on your plan.

Can I send ABNs instead of ACNs?

Yes. Send 9-digit ACNs, 11-digit ABNs or a mix. ABNs are resolved to ACNs through ASIC's company register, and any that can't be resolved come back in unresolved rather than being dropped.

Why doesn't a customer with a deregistration notice show as a match?

Deregistrations are hidden by default, because about nine in ten notices are deregistrations and counting them would flag almost everyone. Send include_deregistration: true to count them.

Do I need to poll, or will you tell me?

Either. A watch can post each new match to your endpoint as a signed webhook, email it, or both, and GET /v1/watches/{id}/matches lets you poll with a since cursor.