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.