Class ApolloRESTClient

Create a label. Master key required.

modality is not optional to Apollo despite reading like it should be: posting without it returns HTTP 422 "Please enter a non-empty modality!". It defaults to 'contacts' here because a people list is the common case.

The create response shape is not pinned in Apollo's docs, so a bare label object, a { label: {...} } envelope and a { labels: [...] } envelope are all accepted — mirroring how listLabels tolerates two read shapes. A shape none of those match throws rather than returning a label with an empty id, which would then be written into a membership array.

Resolve a label by exact name, case-insensitive; null when nothing matches. This is how a human-supplied list name becomes the id a search filter needs.

Every label, account lists and contact lists alike. Master key required. Apollo returns either a bare array or a { labels: [...] } envelope depending on the account; both are accepted.

Move accounts between lists. The supplied accounts must carry current labelNames from a fresh searchAccounts read — this method writes whatever it is given as the intended set, so stale labels here mean real memberships silently disappear.

With verify, the destination list is re-read after each remove to flag silent-fail records. Never deletes, never auto-retries.

Move contacts between lists. Same two-step and verify semantics as accounts.

One page of saved accounts. Paging defaults to page 1 — when draining a list, never advance (quirk #3).

One page of saved contacts. Same drain-page-1 default as searchAccounts.

One page of prospecting people — net-new, not your saved contacts. Apollo does not return emails or phones here by design.

Unlike the two searches above, this one does not need the label maps: the prospecting response carries no memberships, so fetching them would be a wasted master-key call on a read a scoped key can otherwise serve.