Read watched events

Your organization's watched items, every list of the path's country together, oldest first in the order they were matched — not by occurred_on. type says which of two kinds an item is, and so which of event and segment_change it holds; switch on it before reading anything else.

• event: the timeline's event, and trigger (recorded, or retyped when a legal notice first recorded without its values became readable: the same event.id again, to store over the first).
• segment.entered and segment.left: a company that entered or left a segment one of your lists follows. segment_change holds its own id (the key to deduplicate on), change (entered or left), segment (id, and name, null once the segment is deleted), company with the fields of a segment's sample and their sources, index_at and previous_index_at (the two daily updates of the segment index the change was read between, index_at being the one that showed it), and prospecting: notice, the RNE caveat to repeat wherever you show the company, and acknowledgement, the sole-trader acknowledgement the segment was saved with, or null. trigger is always recorded.

Every item carries watchlist_ids (every one of your lists it matched) and its own cursor. Every item has a type, one of those three; the contract below types it as a plain string, and event as optional because a segment item has segment_change instead.

Paginated by cursor, not by page. Without cursor, the feed starts at its beginning. Pass pagination.next_cursor back unchanged as cursor; has_more says whether a next page is already waiting. next_cursor is null only while the feed holds nothing; when nothing new has arrived it is the cursor you sent, so keep it and poll with it. per_page is 20 by default, between 1 and 100, clamped. watchlist_id limits the feed to one list, and a list that is not your organization's is 404 not_found. A cursor this API did not issue is 400 invalid_request. The contract below declares cursor alone; per_page and watchlist_id are accepted all the same.

A value of a company or establishment that is partially disclosed at the time of the read is withheld from an event item: payload is {} for a legal entity, legal_entity_number alone for an establishment, and a gazette event's source_ref is null. A segment item is judged when it is read. One whose company may not be listed now — partially disclosed, the company or its head office; a sole trader the segment was not saved to list; or no longer in the registry — is skipped whole, and the cursor moves past it: it is never delivered. One whose company could not be read in full is not judged yet: the page ends before it, with has_more: true, and next_cursor stays before it, so the next read asks again — for 24 hours at most, after which an item still unreadable is skipped like a withheld one. A page can therefore hold fewer items than per_page, or none, while has_more is true; when next_cursor comes back equal to the cursor you sent, wait before the next read rather than reading again at once. Segment items are kept 90 days: older ones are no longer in the feed.

Counted as one call, unlike the other watch operations. The loop that reads it, and how it relates to webhooks, is in watch companies.