Skip to content
firmus.shdocs

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

firmus.sh

Follow a segment

Be told which companies enter a saved segment, and optionally which leave it, through the list's webhooks, digest and feed.

The list follows one of your organization's saved segments. After each daily update of the segment index, every company that entered the segment reaches the list's webhook endpoints, digest and pull feed as a segment.entered item; with include_leavers: true, every company that left it arrives too, as segment.left.

read -rs FIRMUS_KEY && export FIRMUS_KEY
curl -s -X PUT -H "Authorization: Bearer $FIRMUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_leavers": true}' \
  https://api.firmus.sh/v1/fr/watchlists/3/segments/2

The body is optional: an empty body, or none, follows without leavers. The first PUT answers 201 Created; the same PUT again answers 200 and changes include_leavers only when the body sends it, so it is safe to repeat. Both carry segment_watch (the segment's id, name, include_sole_traders and watch, watchlist_id, include_leavers, followed_at) and the organization's allowance. Turning include_leavers on later delivers the companies that leave from then on: leavers are recorded only while at least one list following the segment asks for them, so earlier ones are not kept to be sent.

Following again resumes a paused segment. A segment whose daily update failed three times in a row is paused for every list that follows it (segment.watch.paused_at, see list followed segments). A PUT from any of those lists resumes it, from a new baseline for each of them: what changed while it was paused is never delivered.

There is no backlog. Each follow gets its own baseline, taken from the segment's membership as it stands just after the follow, and the list receives only changes read after it: the first items are the companies that enter at the next daily update of the index. Nothing read before the follow reaches the list, not even changes that piled up while the segment's updates were failing for other lists. To have the companies already in the segment, export it. A company enters by being newly registered into the filters, by a change of its activity, address, workforce or legal form that brings it into them, by newly meeting a window filter such as head_office_moved_within_days, or by ceasing to be partially disclosed. It leaves by the converse, by ceasing, or when a window slides past it.

What is never delivered: a company partially disclosed at the moment of delivery, a sole trader unless the segment was saved with the sole-trader acknowledgement, and a company no longer in the registry. Such an item is withheld whole, its registry number included; it is not sent later. A company that could not be read in full at delivery is not withheld: it is asked again, by each channel (see watch companies). Segment items are kept 90 days.

The allowance is a number of segments followed, not of calls: 1 on Free, 10 on Pro, 100 on Scale, counted as distinct segments across every list of the organization. Following one more is refused with 402 quota_exceeded, without Retry-After, and follows nothing: stop following a segment or change plan, then send it again. Following again a segment the organization already follows from another list takes no new unit.

400 invalid_request for a body field other than include_leavers, or a value other than true, false, 1 or 0. 404 not_found for a list or a segment that is not your organization's, or a segment saved for another country. A publishable fk_pub key is refused with 403 public_key_forbidden. Not counted as a call.

PUT/v1/{country_code}/watchlists/{watchlist_id}/segments/{segment_id}Scope read

Parameters

ParameterInTypeRequiredExample
country_codepathstringYesfr
segment_idpathintegerYes2
watchlist_idpathintegerYes3

Request

bash
curl -X PUT -H "Authorization: Bearer $FIRMUS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"include_leavers":true}' \
  "https://api.firmus.sh/v1/fr/watchlists/3/segments/2"

Fields

  • segment_watchobject
    • segmentobject
      • idinteger
      • namestring
      • include_sole_tradersboolean
      • watchobjectoptional
        • paused_atunspecifiednullable
        • failuresinteger
        • last_failed_atunspecifiednullable
    • watchlist_idinteger
    • include_leaversboolean
    • followed_atstring
  • allowanceobject
    • includedinteger
    • usedinteger

Responses

The list follows the segment: from the next daily update of the segment index on, every company that enters it — and, with `include_leavers`, every one that leaves it — is delivered through the list's webhook endpoints, digest and the pull feed, as `segment.entered` and `segment.left` items. Nothing is sent for the companies already in it. Partially disclosed companies are never delivered, and sole traders only for a segment saved with the acknowledgement. Following again changes `include_leavers` and answers 200. Counts against the plan's watched segments; not counted as a call.