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.
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
POST /v1/matchwith every ACN or ABN you have, and get back the ones with insolvency notices.POST /v1/watcheswith the same list, to keep watching it.- 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 osimport 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:
unresolvedlists 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_deregistrationisfalseby default, sonotice_countcounts 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.
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:
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 hashlibimport hmacimport 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 "", 200Things 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
- The watches docs cover filters, quotas and polling with
since. - The webhooks docs cover retries and the full payload.
- What a match means for money you’re owed: what happens when a customer goes into administration.
- Not a developer? The dashboard does all of this with a CSV upload and an email address.
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.