1. Sign up and verify your email

Enter your email on the sign-up page. You'll get a link by email — click it, and you'll be shown an API key straight away. This is the only time it's shown, so copy it somewhere safe before you navigate away.

2. Add a company to your watchlist

Add a company by its Companies House number:

curl -X POST https://api.company-watch.co.uk/v1/watchlist \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "companyNumber": "01234567" }'

Endpoint path shown is illustrative — check /scalar/v1 for the exact, current path and response shape.

3. Choose which types of change you want

By default you receive every type. If there's a category of change you don't care about, exclude it — either for your account as a whole, or for one company specifically. See the API reference for the exact exclusion endpoints.

4. Register a webhook, or just poll

Pick whichever fits your integration — you don't have to choose only one.

// Register a webhook
curl -X POST https://api.company-watch.co.uk/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com/hooks/company-watch" }'

// ...or poll on your own schedule
curl https://api.company-watch.co.uk/v1/updates \
  -H "Authorization: Bearer YOUR_API_KEY"

See Webhooks vs polling for how each one behaves.

5. Fire a test event

Prove the whole path works — request handling, matching, and delivery — without waiting for a real filing:

curl -X POST https://api.company-watch.co.uk/v1/test-events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "companyNumber": "01234567" }'

You'll see it arrive at your registered webhook (or show up on your next poll) within a few seconds. That's the whole integration proven end to end.

---

Next: Webhooks vs polling →