Enroll companies for sales signals

Developer keys need signals:read and signals:write, or the complete legacy combination of companies:read and companies:write. Signals scopes do not grant general CRM or Search access.

This reference describes the current source contract. Verify the selected server’s deployed behavior and provider readiness separately; publishing documentation does not enable monitoring.

Use a scoped developer API key or a valid user session. Developer keys require signals:read and signals:write, or both legacy Company scopes. Signals permissions do not grant general Company CRUD access. All request fields except selection are optional in the HTTP model, but each provider validates its supported configuration before selecting companies or writing subscriptions. Response counts distinguish selected, eligible, enrolled, and skipped Companies; the response example is a LinkedIn-only enrollment.

LinkedIn posts: use provider=harvest_linkedin with signalTypes=["linkedin_posts"]. The provider normalizes the effective schedule to frequency=daily, lookbackDays=1, and an empty provider window. The monitored source is posts or reposts by people associated with the company; official company-page posts are excluded.

Compatibility: existing API configurations can retain legacy LinkedIn relevance fields. They are not current monitor inputs; omit them from new requests to use the default behavior.

Companies must exist in the caller’s organization and be promoted into the Companies workspace. LinkedIn monitoring also requires a valid LinkedIn company URL or a positive numeric LinkedIn company ID saved on the Company. A domain alone is insufficient. Skipped counts distinguish not_found, not_promoted, and missing_monitoring_anchor. Resolve exact Company IDs and existing identities before enrolling.

Progress: successful enrollment or attachment saves subscriptions and reconciles their recurring due schedule; it does not mean posts have been retrieved. LinkedIn’s first and recurring checks use the same per-company subscription runtime. A LinkedIn-only request returns previewRun=null, previewRunId=null, and initialRunIds=[]; these fields do not provide a LinkedIn preview receipt. Read subscriptions for saved status, next due time, last check/result, provider deferrals, and coverage. An active subscription is not a completed scan.

Named monitor workflow: the Companies UI creates a reusable monitor definition and then attaches a Company selection. The direct bulk endpoint shown here enrolls subscriptions without creating a reusable monitor definition. To reproduce a named UI monitor, use create plus attachment and the returned monitor ID/revision.

With mixed families, a Company must meet every selected provider’s identity requirements and can receive multiple provider subscriptions. Some non-LinkedIn providers can return initial run IDs. Poll only IDs actually returned; run status does not start recurring work. An interrupted request can leave subscriptions saved. Inspect current subscription state before retrying, particularly when requesting another immediate check.

Immediate check by default: runNow defaults to true. For LinkedIn, enrollment brings checks forward through the existing subscription due queue; an already-due occurrence is reused and an existing active lease is reported without restarting it. Other providers can admit their existing initial-run path. Explicitly set runNow=false to save enrollment for its next recurring cadence instead. Neither mode waits for provider collection to finish or adds a LinkedIn preview-run receipt.

The response reports runNowRequestedCount, runNowScheduledCount, runNowAlreadyRunningCount, and runNowFailedCount. These count provider subscriptions, so mixed-provider requests can exceed the selected Company count; they are zero when runNow is false. A scheduled count includes reused due work and does not prove a worker has finished. Check failed counts and the enqueue-error field even when success=true, then inspect subscription progress.

enabled=false together with runNow=true is rejected with HTTP 422 before enrollment. To save paused subscriptions, explicitly send runNow=false with enabled=false. The example makes the default immediate-check request explicit and shows one scheduled subscription.

CLI: enabled enrollment defaults to an immediate check. Use --no-run-now to enroll for the next cadence, for example autotouch companies signals enroll --company-id <COMPANY_ID> --provider harvest_linkedin --signal-type linkedin_posts --no-run-now. --paused defaults to no immediate check. For complete --data-json or --data-file payloads, the JSON is sent unchanged: include "runNow": false to choose the next cadence, and include it with "enabled": false to save paused subscriptions. This changes initial scheduling, not the saved recurring frequency.

Delivery credits

Saving subscriptions and monitor definitions is free. Read the monitors catalog for deliveryBillingPolicy. When enabled=true, delivery costs one organization credit per unique signal delivered to that organization. Empty checks, duplicate delivery, provider retries, and additional Company associations for the same already-visible signal do not create another delivery charge.

If organization credits are insufficient, delivery is held: the new event or organization link, scoring, and webhook are not published for that delivery. While billing is enabled, the scheduler can recover held delivery after credits become available using stored evidence, without purchasing the provider result again. Enrollment success and scheduled-check counts do not confirm paid delivery.

The source billing flag defaults to false. The selected server’s returned deliveryBillingPolicy.enabled determines whether this policy is enabled there; documentation publication does not activate billing.

Criteria-discovery inputs belong to the separate discovery monitor API: keywordPhrases, providerSelection, maxCandidates and maxCreditsPerCheck are not direct Company-enrollment fields. The current bulk request and CLI already support optional runNow, full JSON payloads and provider-owned config.signal_filters.