Getting started

Authentication

Every request needs an API key, sent either as a header:

X-API-Key: YOUR_API_KEY

or as a query parameter:

?api_key=YOUR_API_KEY

There are two kinds of key:

• A read-only key works against the search endpoints (/v1/notices, /v1/notices/{id}, /v1/companies/{acn_or_abn}, /v1/filters, /v1/stats).
• An account key (it looks like ask_...) works against those and also unlocks the watch and webhook routes. Your account key is issued when you subscribe, and is shown to you once, so store it somewhere safe.

A request with no key, or a key that doesn’t match anything, gets:

{
  "error": {
    "code": "unauthorised",
    "message": "Missing or invalid API key"
  }
}

with HTTP status 401.

Your first request

curl "https://api.insolvencyalerts.com.au/v1/notices?q=drifta" \
  -H "X-API-Key: YOUR_API_KEY"

See Notices for the full parameter reference and response shape.

From zero to a verified webhook

The whole integration is four calls. Everything below needs an account key.

1. Check the identifiers you hold

Before storing anything, screen your book to see what you are dealing with. POST /v1/match takes up to 50,000 ACNs or ABNs, stores nothing, and tells you which ones have notices and which it could not resolve.

curl -X POST "https://api.insolvencyalerts.com.au/v1/match" \
  -H "X-API-Key: YOUR_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"identifiers": ["163753428", "32613554233"]}'

Anything in unresolved is an identifier ASIC’s register does not know. It is worth fixing those now rather than discovering later that a company you thought you were watching was never on the list.

2. Create a watch

curl -X POST "https://api.insolvencyalerts.com.au/v1/watches" \
  -H "X-API-Key: YOUR_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "debtor book", "identifiers": ["163753428", "32613554233"]}'

Keep the id from the response. It looks like wch_... and every route below hangs off it.

3. Backfill what is already there

A new watch matches history, not just the future. Pull it once so your system starts from a correct picture rather than assuming everything is healthy until the first webhook arrives.

curl "https://api.insolvencyalerts.com.au/v1/watches/wch_.../matches" \
  -H "X-API-Key: YOUR_ACCOUNT_KEY"

Keep meta.next_since from the response if you also intend to poll.

4. Attach a webhook

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

The response carries secret, shown once. Store it before you close the terminal. Webhooks has working verification code for Node and Python, and you should have that endpoint verifying signatures before you rely on it.

Polling instead

If you would rather poll than receive, skip step 4 and call /v1/watches/{id}/matches with ?since= set to the last meta.next_since you saw. See cursor polling for why since beats a date filter: it does not miss a notice ASIC publishes late.

Rate and quota behaviour

Search endpoints aren’t metered per request. What’s limited is how many companies your account can watch at once, and how many watch lists you can create, both set by your plan:

Plan	Companies watched	Watch lists
Starter	250	3
Pro	2,500	25
Business	25,000	Unlimited

Creating a watch, or adding identifiers to one, that would put your account over either limit is rejected with HTTP 402 before anything is written:

{
  "error": {
    "code": "quota_exceeded",
    "message": "Your plan allows 250 companies. You have 240 and tried to add 50."
  }
}

Because the check runs first, a rejected request leaves your account exactly as it was.

Subscription errors

If your account’s subscription has lapsed, every /v1/ route answers 402 instead of serving the request:

{
  "error": {
    "code": "subscription_inactive",
    "message": "This subscription is not active. Reactivate it to resume API access."
  }
}

Reactivating your subscription resumes access immediately, no new key required.

Errors lists every code the API returns and which ones are worth retrying.