Create a watch subscription
Watch a list of companies for confirmed change events, optionally filtered to a subset of dimensions and routed to webhook endpoints. Adding a company to a watch puts it under your coverage in the same call (watch = coverage): a company already under your coverage is attached; a company Bixel serves but you do not cover is put under your coverage — free inside your plan's allowance, otherwise the ask answers 409 coverage_confirmation_required with the per-company charge and creates nothing until re-sent with cover_beyond_allowance true; a domain Bixel has never seen is checked and added (the Request coverage path) and held as pending (subscription.pending_companies, each with a check_url) until its identity lands; anything that is not a domain answers companies_unresolved and nothing is created. Free accounts keep their watched companies without coverage. The answer's coverage block says what happened. Each plan caps the DISTINCT companies an account can watch across all subscriptions; when a create or add would exceed it the response is a 403 problem naming the cap and there is never a per-company fee. Plan allowances are listed at bixel.com/docs/webhooks. Costs 0 credits.
bx_-prefixed API key. Free keys: https://bixel.com/account/
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/v1/watch/subscriptions" \ -H "Content-Type: application/json" \ -d '{ "name": "string", "companies": [ "string" ] }'{ "data": { "subscription": { "id": "string", "name": "string", "dimensions": [ "string" ], "active": true, "companies_count": 0, "endpoint_ids": [ "string" ], "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z", "pending_companies": [ { "domain": "string", "request_id": "string", "check_url": "string", "status": "checking", "since": "2019-08-24T14:15:22Z" } ] }, "coverage": { "attached": 0, "admitted": 0, "charged": 0, "pending": [ { "domain": "string", "request_id": "string", "check_url": "string", "status": "string", "since": "2019-08-24T14:15:22Z" } ], "not_queued": [ { "domain": "string", "reason": "string" } ], "note": "string" } }, "meta": { "generated_at": "2019-08-24T14:15:22Z", "count": 0, "total": 0, "next_cursor": "string", "notice": "string", "window": { "served_from": "string", "earliest_event_at": "string", "events_beyond_window": true }, "data_version": "string", "resolved_at": "2019-08-24T14:15:22Z", "attribution": { "source": "Bixel", "url": "string", "license": "CC-BY-4.0", "notice": "from Bixel", "data_version": "string" } }}{ "type": "http://example.com", "title": "string", "status": 0, "code": "company_not_found", "detail": "string", "hint": "string", "docs_url": "http://example.com"}{ "type": "http://example.com", "title": "string", "status": 0, "code": "company_not_found", "detail": "string", "hint": "string", "docs_url": "http://example.com"}{ "type": "http://example.com", "title": "string", "status": 0, "code": "company_not_found", "detail": "string", "hint": "string", "docs_url": "http://example.com"}{ "type": "http://example.com", "title": "string", "status": 0, "code": "company_not_found", "detail": "string", "hint": "string", "docs_url": "http://example.com"}