Skip to content
firmus.shdocs

Every page's text, headings and title. Code samples are not indexed.

firmus.sh

Add watches

Watch up to 1 000 SIRENs or SIRETs, or the companies a file job identified, all or nothing against the allowance.

Send numbers, an array or one comma-separated string of up to 1 000 SIRENs (9 digits) or SIRETs (14 digits), spaces ignored; or job_id, the id of a finished file job of your organization, whose matched rows (or, on an enrich job, enriched rows) give the numbers, up to 100 000. Not both.

The answer is 200 with results, one status per number in the order sent: added, already_watched (already in this list), not_found (neither the registry nor the event log knows it: not watched) or invalid (not 9 or 14 digits). counts tallies them, and a status no number answered is absent from it rather than 0. watched is the list's new total and allowance the organization's.

All or nothing. A request whose new numbers would take the organization past its allowance (5 on Free, 1 000 on Pro, 10 000 on Scale, counted as distinct numbers across every list) adds none of them and is refused with 402 quota_exceeded, with no Retry-After: remove watches or change plan, then send it again. Refused with 400 invalid_request for no number, more than 1 000 (100 000 from a job), both numbers and job_id, or a job that is not finished or not your organization's. Not counted as a call.

POST/v1/{country_code}/watchlists/{watchlist_id}/watchesScope read

Parameters

ParameterInTypeRequiredExample
country_codepathstringYesfr
watchlist_idpathintegerYes2

Request

bash
curl -X POST -H "Authorization: Bearer $FIRMUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"numbers":["552032534"]}' \
  "https://api.firmus.sh/v1/fr/watchlists/2/watches"

Fields

  • resultsobject[]
    • []objectoptional
      • numberstring
      • statusstring
  • countsobject
    • already_watchedintegeroptional
    • addedinteger
  • watchedinteger
  • allowanceobject
    • includedinteger
    • usedinteger

Responses

Adds up to 1 000 numbers (SIRENs or SIRETs) to a list, from `numbers` or a finished CSV job's matched rows (`job_id`). All or nothing against the plan's watched entities: a request that would cross the allowance adds nothing and is a 402. A number neither the registry nor the event log knows is `not_found` and is not watched.