Skip to content

POST /v3/search/subscriptions

Create a search subscription.

API key: required. See Authentication.

Group: Webhooks (API: callbacks)

Parameters

This route takes no parameters.

Request body

A SearchSubscriptionCreate object, as JSON.

FieldTypeRequiredDescription
endpoint_idstringyesOne of the organization's endpoints; it must list filing.new (filing, firehose) or search.match (search).
include_correctionsbooleanno
min_interval_sinteger | nullno
namestringyes1 to 800 bytes.
queryobjectyesThe query and filter parameters of /v3/search (q, syntax, match, forms, form_types, form_families, doctypes, ciks, tickers, sics, states, inc_states, primary_only, entityName, locationCode, ...) as JSON members (a list as a comma string or an array), plus items (8-K item codes). A filing-date window (filed_from, filed_to, startdt, enddt, or a dateRange preset) is a 400 naming it, and so is status (a subscription receives new filings); an acceptance window is not stored. An unknown ticker is a 400 naming tickers (q for a ticker: term in q).

Responses

StatusBodyDescription
201SearchSubscriptionCreated (application/json)Created
400Problem (application/problem+json)Invalid or unknown parameter, or a body that is not one JSON document (code invalid_body).
401Problem (application/problem+json)Missing, invalid or inactive API key (code unauthorized), or a refused access token (code invalid_token: malformed, unknown key, bad signature, expired, wrong issuer or audience, revoked grant). WWW-Authenticate names the protected-resource metadata (RFC 9728).
403Problem (application/problem+json)The credential's scope does not cover this route (code forbidden).
409Problem (application/problem+json)Conflict with the current state.
415Problem (application/problem+json)The body is not sent as Content-Type: application/json (code unsupported_media_type).
503Problem (application/problem+json)Full-text search cannot answer now: search_unavailable (sb_search unreachable or not configured), search_busy (its queue is full), search_timeout (the query hit its time budget), ticker_resolution_unavailable; or the database is unavailable. Retry after the Retry-After delay when one is given.
defaultProblem (application/problem+json)Any other error (405, 500, 504).

Response body

A 201 carries a SearchSubscriptionCreated object.

FieldTypeRequiredDescription
activebooleanyes
created_atdate-time (RFC 3339, UTC)yes
endpoint_idstringyescbe_ and 24 hex digits.
idstringyessub_ and 24 hex digits.
include_correctionsbooleanyes
kindstringyesFrom the query: search when q is not empty, or doctypes, primary_only=true or entityName is given; else filing when a filing-level filter is given (forms, form_types, form_families and their exclusions, ciks, tickers, sics, states, inc_states, locationCode, items); else firehose. filing and firehose deliver filing.new, search delivers search.match. A filing subscription counts against limits.filter. Text subscriptions (kind search) are not offered: a create or PATCH whose query has q, doctypes, primary_only=true or entityName is a 400 invalid_parameter naming that parameter. One of: filing, firehose, search.
min_interval_sinteger | nullyesDigest interval; null: every event is delivered alone.
namestringyes
queryobjectyesAs stored: q, syntax, match and the structured filters as /v3/search/parse normalises them, tickers resolved into ciks at save time (no tickers member), items as given, accepted_from and accepted_to always null.
query.filtersobjectyes
query.matchstringyesOne of: exact, stem.
query.qstringyes
query.syntaxstringyesOne of: sb, edgar.
updated_atdate-time (RFC 3339, UTC)yes
resolvedobjectyesThe tickers of the query and the CIKs they were resolved to at save time; in the answers of POST and of a PATCH with a query.
resolved.tickersobjectno

Example request

Shell
curl -sS -X POST -H "Authorization: Bearer $SECBLAST_API_KEY" \
  -H "Content-Type: application/json" -d @body.json \
  'https://api.secblast.com/v3/search/subscriptions'

More in Webhooks (API: callbacks)

Previous: GET /v3/search/subscriptions · Next: GET /v3/search/subscriptions/{id}

Markdown version: /docs/reference/post-search-subscriptions.md