Sisoco Oneby Sisoco Partners

Check a company, then watch your first 10 in 5 minutes

One check call, then a watchlist of ten UK companies with a signed webhook for every event on them.

Before you start

You need an API key with write access, from the account page. Keys below are placeholders: replace sisk_live_YOUR_KEY with yours. You also need:

  • WEBHOOK_URL: An https:// URL on port 443 that answers 2xx (for a first try, a request-bin service works)

cURL (bash, with jq)

export SISOCO_API_KEY="sisk_live_YOUR_KEY"
export WEBHOOK_URL="…"

Python 3 (requests)

import os
import requests

HEADERS = {"Authorization": f"Bearer {os.environ['SISOCO_API_KEY']}"}
webhook_url = os.environ["WEBHOOK_URL"]

TypeScript (Node 18+, ES module)

const headers = { Authorization: `Bearer ${process.env.SISOCO_API_KEY}` };
const webhookUrl = process.env.WEBHOOK_URL!;

Steps

1. Check a company

The front-door call: the matched company, its current signals and recent events, each with its official source. Tesco Stores Limited is a sample company: it answers even without a key, at no charge.

GET /v1/check

cURL

curl "https://api.sisoco.co.uk/v1/check?company=00519500&country=GB" \
  -H "Authorization: Bearer $SISOCO_API_KEY"

Python

answer = requests.get("https://api.sisoco.co.uk/v1/check", headers=HEADERS, params={"company": "00519500", "country": "GB"})
answer.raise_for_status()
print(answer.json())

TypeScript

const res1 = await fetch("https://api.sisoco.co.uk/v1/check" + '?' + new URLSearchParams({
  "company": "00519500",
  "country": "GB"
}), { method: 'GET', headers });
if (!res1.ok) throw new Error(`step 1: ${res1.status}`);
console.log(await res1.json());

2. Create a watchlist

A watchlist groups the companies you follow. The default profile sends every event type at its default severity.

POST /v1/watchlists

cURL

ANSWER=$(curl -X POST "https://api.sisoco.co.uk/v1/watchlists" \
  -H "Authorization: Bearer $SISOCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Quickstart"}')
WATCHLIST_ID=$(echo "$ANSWER" | jq -r '.data.id')

Python

answer = requests.post("https://api.sisoco.co.uk/v1/watchlists", headers=HEADERS, json={"name": "Quickstart"})
answer.raise_for_status()
watchlist_id = answer.json()["data"]["id"]

TypeScript

const res2 = await fetch("https://api.sisoco.co.uk/v1/watchlists", { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({
    "name": "Quickstart"
  }) });
if (!res2.ok) throw new Error(`step 2: ${res2.status}`);
const body2 = await res2.json();
const watchlistId = body2.data.id;

3. Watch ten companies

Add up to 500 companies per call by registry number. client_reference is your own id, echoed on every event.

POST /v1/watchlists/{WATCHLIST_ID}/entities

cURL

curl -X POST "https://api.sisoco.co.uk/v1/watchlists/$WATCHLIST_ID/entities" \
  -H "Authorization: Bearer $SISOCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"entities":[{"identifier":"03959649","country":"GB","client_reference":"easyJet plc"},{"identifier":"00445790","country":"GB","client_reference":"Tesco PLC"},{"identifier":"00102498","country":"GB","client_reference":"BP p.l.c."},{"identifier":"00041424","country":"GB","client_reference":"Unilever PLC"},{"identifier":"01833679","country":"GB","client_reference":"Vodafone Group plc"},{"identifier":"00617987","country":"GB","client_reference":"HSBC Holdings plc"},{"identifier":"00048839","country":"GB","client_reference":"Barclays PLC"},{"identifier":"04190816","country":"GB","client_reference":"BT Group plc"},{"identifier":"04256886","country":"GB","client_reference":"Marks and Spencer Group plc"},{"identifier":"00185647","country":"GB","client_reference":"J Sainsbury plc"}]}'

Python

answer = requests.post(f"https://api.sisoco.co.uk/v1/watchlists/{watchlist_id}/entities", headers=HEADERS, json={"entities": [
    {"identifier": "03959649", "country": "GB", "client_reference": "easyJet plc"},
    {"identifier": "00445790", "country": "GB", "client_reference": "Tesco PLC"},
    {"identifier": "00102498", "country": "GB", "client_reference": "BP p.l.c."},
    {"identifier": "00041424", "country": "GB", "client_reference": "Unilever PLC"},
    {"identifier": "01833679", "country": "GB", "client_reference": "Vodafone Group plc"},
    {"identifier": "00617987", "country": "GB", "client_reference": "HSBC Holdings plc"},
    {"identifier": "00048839", "country": "GB", "client_reference": "Barclays PLC"},
    {"identifier": "04190816", "country": "GB", "client_reference": "BT Group plc"},
    {"identifier": "04256886", "country": "GB", "client_reference": "Marks and Spencer Group plc"},
    {"identifier": "00185647", "country": "GB", "client_reference": "J Sainsbury plc"},
]})
answer.raise_for_status()
print(answer.json())

TypeScript

const res3 = await fetch(`https://api.sisoco.co.uk/v1/watchlists/${watchlistId}/entities`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({
    "entities": [
      {
        "identifier": "03959649",
        "country": "GB",
        "client_reference": "easyJet plc"
      },
      {
        "identifier": "00445790",
        "country": "GB",
        "client_reference": "Tesco PLC"
      },
      {
        "identifier": "00102498",
        "country": "GB",
        "client_reference": "BP p.l.c."
      },
      {
        "identifier": "00041424",
        "country": "GB",
        "client_reference": "Unilever PLC"
      },
      {
        "identifier": "01833679",
        "country": "GB",
        "client_reference": "Vodafone Group plc"
      },
      {
        "identifier": "00617987",
        "country": "GB",
        "client_reference": "HSBC Holdings plc"
      },
      {
        "identifier": "00048839",
        "country": "GB",
        "client_reference": "Barclays PLC"
      },
      {
        "identifier": "04190816",
        "country": "GB",
        "client_reference": "BT Group plc"
      },
      {
        "identifier": "04256886",
        "country": "GB",
        "client_reference": "Marks and Spencer Group plc"
      },
      {
        "identifier": "00185647",
        "country": "GB",
        "client_reference": "J Sainsbury plc"
      }
    ]
  }) });
if (!res3.ok) throw new Error(`step 3: ${res3.status}`);
console.log(await res3.json());

4. Register a webhook

Events on watched companies are POSTed here, signed with the secret in this answer. The secret is shown once: store it.

POST /v1/webhooks

cURL

ANSWER=$(curl -X POST "https://api.sisoco.co.uk/v1/webhooks" \
  -H "Authorization: Bearer $SISOCO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"url":"'"$WEBHOOK_URL"'","event_types":[]}')
WEBHOOK_ID=$(echo "$ANSWER" | jq -r '.data.id')

Python

answer = requests.post("https://api.sisoco.co.uk/v1/webhooks", headers=HEADERS, json={"url": f"{webhook_url}", "event_types": []})
answer.raise_for_status()
webhook_id = answer.json()["data"]["id"]

TypeScript

const res4 = await fetch("https://api.sisoco.co.uk/v1/webhooks", { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify({
    "url": `${webhookUrl}`,
    "event_types": []
  }) });
if (!res4.ok) throw new Error(`step 4: ${res4.status}`);
const body4 = await res4.json();
const webhookId = body4.data.id;

5. Send a test event

One signed sample event (header Sisoco-Test: true), to check your endpoint and your signature verification.

POST /v1/webhooks/{WEBHOOK_ID}/test

cURL

curl -X POST "https://api.sisoco.co.uk/v1/webhooks/$WEBHOOK_ID/test" \
  -H "Authorization: Bearer $SISOCO_API_KEY"

Python

answer = requests.post(f"https://api.sisoco.co.uk/v1/webhooks/{webhook_id}/test", headers=HEADERS)
answer.raise_for_status()
print(answer.json())

TypeScript

const res5 = await fetch(`https://api.sisoco.co.uk/v1/webhooks/${webhookId}/test`, { method: 'POST', headers });
if (!res5.ok) throw new Error(`step 5: ${res5.status}`);
console.log(await res5.json());

6. Read the event feed

The same events, by polling. Keep meta.next_cursor and send it as cursor next time.

GET /v1/events

cURL

curl "https://api.sisoco.co.uk/v1/events?watchlist_id=$WATCHLIST_ID" \
  -H "Authorization: Bearer $SISOCO_API_KEY"

Python

answer = requests.get("https://api.sisoco.co.uk/v1/events", headers=HEADERS, params={"watchlist_id": f"{watchlist_id}"})
answer.raise_for_status()
print(answer.json())

TypeScript

const res6 = await fetch("https://api.sisoco.co.uk/v1/events" + '?' + new URLSearchParams({
  "watchlist_id": `${watchlistId}`
}), { method: 'GET', headers });
if (!res6.ok) throw new Error(`step 6: ${res6.status}`);
console.log(await res6.json());

Next

Verify webhook signatures, see every event type, or connect an agent over MCP.