Every request and response field, generated from the endpoints themselves so it cannot drift.
OPEN THE REFERENCE →Send us a list of URLs; get back the emails, phone numbers and social profiles found on them. Everything the console does, your own systems can do — which is how a scrape reaches your CRM without anyone exporting a spreadsheet.
REST over HTTPS, JSON in and out. Every URL spends credit from the same balance the console spends, at your plan's published rate.
Base URL https://api.cyclosa.co/api/public Auth Authorization: Bearer cyc_live_… Versioning /v1 is in the path, so a URL says which contract it was written against
New optional fields can appear inside v1, so parse defensively and ignore what you do not recognise. Anything that would break a working integration opens a v2 served alongside it.
Create a key in the console under Developers, and send it on every request:
Authorization: Bearer cyc_live_xxxxxxxxxxxxxxxxxxxx
A key is shown once, when you create it. We store only a hash, so we cannot show it again and neither can anyone who reaches our database — a lost key is replaced, not recovered.
Send it as a header and never in a query string, which is written to the logs of every proxy between you and us.
An account has one key at a time. Creating a key retires the previous one the moment it is issued, so a token you have stopped trusting is dead as soon as its replacement exists — there is no second credential left open for someone to find later.
That also means replacing a key is a change you deploy: every system sending the old one starts getting 401 at once. Work already queued is unaffected — a key authorises the submission, not the batch, so scrapes in flight finish normally and their contacts stay readable with the new key.
Three calls, or two if you use a webhook: send the URLs, wait for the batch to finish, then read the contacts off it.
export CYCLOSA_KEY=cyc_live_…
# 1. Send the URLs
BATCH=$(curl -sS -X POST https://api.cyclosa.co/api/public/v1/scrapes \
-H "Authorization: Bearer $CYCLOSA_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://acme.example/contact"]}' | jq -r .batch_id)
# 2. Wait for it
until [ "$(curl -sS https://api.cyclosa.co/api/public/v1/scrapes/$BATCH \
-H "Authorization: Bearer $CYCLOSA_KEY" | jq -r .status)" = finished ]; do
sleep 3
done
# 3. Take the contacts
curl -sS https://api.cyclosa.co/api/public/v1/scrapes/$BATCH/contacts \
-H "Authorization: Bearer $CYCLOSA_KEY"There is no SDK to install: these are the standard HTTP client and JSON parser your language already ships, which is one fewer dependency to keep current.
POST /v1/scrapes answers 202, not 200 — the work is accepted, not done. A browser render takes seconds and a challenged page tens of them, so the contacts arrive later.
curl -X POST https://api.cyclosa.co/api/public/v1/scrapes \
-H "Authorization: Bearer $CYCLOSA_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://acme.example/contact", "https://globex.example"],
"name": "Tuesday prospects",
"render": false,
"llm": false
}'{
"batch_id": "6f1c2d…",
"accepted": 2,
"queued": [{"url": "https://acme.example/contact", "job_id": "…", "state": "queued"}],
"cached": [{"url": "https://globex.example", "job_id": "…", "state": "cached"}],
"render": false,
"llm": false
}A URL someone scraped recently comes back under cached and is already complete — it cost no credit and will not be fetched. Set refresh: true to fetch it anyway.
A submission you cannot afford is refused whole, with a 402. Nothing is queued and no batch is created, so there is never a half-started list to clean up.
GET /v1/scrapes/{batch_id} is cheap enough to poll every few seconds.
{"batch_id": "6f1c2d…", "status": "running", "total_urls": 2,
"done": 1, "failed": 0, "running": 1, "queued": 0, "contacts_found": 3}finished means nothing more is coming, which includes the URLs that could not be read. Check failed rather than waiting for done to reach total_urls — that will not happen if one site timed out, and some always do.
GET /v1/scrapes/{batch_id}/contacts answers while the batch is still running as well as after it finishes, so a long list can be drained as it completes.
{
"batch_id": "6f1c2d…",
"status": "finished",
"total_urls": 2,
"results": [
{
"url": "https://acme.example/contact",
"final_url": "https://acme.example/contact",
"status": "done",
"http_status": 200,
"title": "Contact us — Acme",
"contacts": {
"emails": ["sales@acme.example"],
"phones": ["+63 2 8123 4567"],
"social": ["https://linkedin.com/company/acme"]
},
"cached": false,
"error": null
}
]
}GET /v1/account says what you have left. Worth asking before a long list, because a submission beyond your credit is refused rather than trimmed.
{"plan": "pro", "scans_left": 14300, "included_scans": 15000,
"concurrency": 5, "in_flight": 1}concurrency is how many URLs your plan fetches at once. Submitting while every slot is busy answers 429 — wait for one to finish, or move to a plan with more. Jobs from paid plans are handed out ahead of Free ones. There is no separate request-rate limit: credit and concurrency are what bound the work.
Register a URL and we post each finished batch to it, contacts included. Nothing on your side has to run a timer, and a CRM sync becomes a handler rather than a cron job.
curl -X PUT https://api.cyclosa.co/api/public/v1/webhook \
-H "Authorization: Bearer $CYCLOSA_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://your-crm.example/hooks/cyclosa"}'
{"url": "https://your-crm.example/hooks/cyclosa", "secret": "shown once"}The secret comes back here and from POST /v1/webhook/rotate, and nowhere else. Setting the same URL again keeps it, so correcting a typo does not break a receiver that was verifying properly.
Each delivery arrives as:
POST https://your-crm.example/hooks/cyclosa
X-Cyclosa-Event: batch.finished
X-Cyclosa-Delivery: 1841
X-Cyclosa-Signature: sha256=…
{
"event": "batch.finished",
"batch": {"id": "6f1c2d…", "name": "Tuesday prospects", "total_urls": 2,
"created_at": "2026-09-22T20:31:02+00:00"},
"results": [ … the same shape as /contacts … ]
}The contacts are in the payload rather than behind a link, so the thing receiving it does not need an API key of its own.
Anyone who learns your URL can post to it. The signature is what says we sent it, so check it before you trust the body.
import hmac, hashlib
def is_ours(raw_body: bytes, header: str, secret: str) -> bool:
expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(header, f"sha256={expected}")Compute it over the exact bytes you received, not over a re-encoded copy of the parsed JSON. Two encoders disagree about spacing and key order, and a signature over a different rendering of the same data fails for no reason you can see. Most frameworks need telling to keep the raw body.
Answer 2xx, and answer quickly — queue the work on your side rather than doing it while we wait. We give up on a response after 10 seconds.
Anything else is retried after 1 minute, then 5, 30, 120, 480 and 1440. After the sixth attempt we stop; the batch is still there to fetch over the API, and GET /v1/webhook/deliveries shows what happened, with the status code and error we saw.
Delivery is at-least-once. A receiver that times out after acting on a payload will be sent it again, so key on batch.id and a repeat costs you nothing.
Every error is JSON with a detail naming what went wrong in words you can show someone.
Request and response fields for each are on the generated reference, where you can also try them with your own key.