Choose the company.
Keep following it.

1. Find the company

   Use the company name, registration or VAT number and its two-letter country code. Present ambiguous matches for selection.

   curl 'https://companydelta.com/api/v1/companies/search' \
     -H "Authorization: Bearer $COMPANYDELTA_API_KEY" \
     -H 'Content-Type: application/json' \
     -d '{"query":"YOUR REGISTRATION NUMBER","country":"GB","search_by":"registration_number"}'

   Keep the chosen result’s selection_token. Search tokens expire after 24 hours. Do not substitute an unverified company name or an upstream ID.

2. Choose the list and signals

   Read GET /api/v1/lists and GET /api/v1/watch-fields. Create a list with POST /api/v1/lists and {"name":"Strategic Suppliers"} if needed. Read GET /api/v1/notification-options for available recipients and destinations.

3. Start monitoring

   curl 'https://companydelta.com/api/v1/monitoring' \
     -H "Authorization: Bearer $COMPANYDELTA_API_KEY" \
     -H 'Content-Type: application/json' \
     -d '{
       "selection_token":"SELECTED_SEARCH_TOKEN",
       "list_id":"YOUR_LIST_ID",
       "fields":["company.status","officer.appointment"],
       "alerts":{"email_recipients":null,"webhook_ids":[]}
     }'

   This example uses the workspace email default and disables webhooks for this company. Dashboard updates stay enabled. Use an existing company_id instead of selection_token to resume a saved company.

4. Check activation and receive changes

   Inspect company_id, list, fields, alerts and monitoring_state. Read the saved company again with GET /api/v1/monitoring/{company_id}; its monitoring object contains the latest state. Retrieve events using GET /api/v1/events?company_id=YOUR_COMPANY_ID, or receive signed webhook deliveries.

Existing GET /api/v1/companies, /events and /cases routes remain available. List responses contain data and next_cursor; pass the cursor back and use up to 100 records per request.

Retry behaviour: a company is unique by workspace, country and registration number. Repeating a start request reuses the company and preserves existing signals. PATCH replaces fields when supplied. Omitted settings are preserved. With several lists, choose list_id explicitly for a new company.

Creating a webhook requires a separate permission, granted by a workspace owner or admin. Send {"name":"ERP","url":"https://your-domain.com/company-events"} to POST /api/v1/webhooks. Save the returned signing secret securely. A repeated request for the same enabled URL returns the existing destination without revealing its secret again. No test message is sent automatically.

Queued deliveries are checked against current preferences before sending. Email and webhook delivery depend on configured services and receiver availability. Read the signature and delivery guidance →

Successful searches and live previews each consume one search credit. Failed searches restore that credit. New saved companies consume a company slot; adding signals to an existing company does not create a second slot. HTTP 401 indicates a missing, expired or revoked credential; 403 indicates insufficient scope or plan access; 409 indicates an unresolved selection or capacity issue.

Permission changes and revocation restrict subsequent calls. The assistant must report activation failures accurately. Connecting an assistant does not keep a chat running or push future messages into the conversation: CompanyDelta’s monitoring continues independently, and the assistant retrieves changes when asked.

In Agent workflows, choose Create workflow to open five editable templates: company status, ownership, director, financial information and company details changes. Select saved companies or a list, choose the reviewer and priority, then review the exact monitoring signals before activation.

Activation adds missing signals, resumes the paused companies shown in the confirmation, and preserves existing monitoring signals and alert recipients. The workflow remains paused until monitoring is confirmed for every company. If setup is interrupted or a company fails, edit the saved workflow to retry. Companies added to a list later must also have the required signals enabled. A coverage banner and “Review monitoring setup” button show gaps and let you preview and confirm the missing setup.

Saving a paused workflow leaves monitoring unchanged. Workflows act on future matching events; earlier changes are not replayed. The same templates and saved workflows are available through the dashboard, API and MCP. Use the workflow endpoints below to configure and activate a rule from your application or assistant.

1. Choose a template, scope and reviewer

   If the company is not saved, use search_companies, explicitly select its legal entity, then call save_company with selection_token and list_id. This requires read and workflows:write, consumes a saved-company slot and starts no monitoring. Existing monitoring settings are preserved. Search separately requires search and uses one search credit on success. The dashboard has “Find and add company” inside the workflow builder.

   Read templates, GET /api/v1/lists and GET /api/v1/notification-options. Template IDs are status, ownership, directors, financials and details. The assignee must be a current owner, admin or analyst’s email; read-only viewers cannot be assigned reviews; omit it or use an empty string to leave the review unassigned.

   Use scope_type: "portfolio" with one list ID, "companies" with selected saved company IDs, or "all" with no scope IDs. Custom rules omit template_id and provide name and types from the watch-field catalogue.

2. Create a paused workflow

   curl 'https://companydelta.com/api/v1/workflows' \
     -H "Authorization: Bearer $COMPANYDELTA_API_KEY" \
     -H 'Content-Type: application/json' \
     -d '{
       "request_id":"supplier-ownership-rule-1",
       "template_id":"ownership",
       "scope_type":"portfolio",
       "scope_ids":["YOUR_LIST_ID"],
       "assignee":"MEMBER_EMAIL",
       "priority":"high"
     }'

   Store workflow_id. Retrying the same request with the same request_id reuses the rule. Reusing that ID with different settings returns a conflict. The workflow is initially paused. You can override a template’s name, types, priority and optional condition.

3. Preview the exact setup

   POST an empty JSON object to /api/v1/workflows/{workflow_id}/preview. Inspect monitoring_setup.companies, required_fields, readiness, overlaps and the assigned reviewer. Keep monitoring_setup.confirmation for activation. A changed rule or company scope requires a fresh preview.

   Conditions support any, equals, not_equals, contains, gt and lt. Set condition_value for every operator except any. Text comparisons ignore case; numeric comparisons require numeric new values.

4. Confirm and activate

   POST /api/v1/workflows/{workflow_id}/activate
   {
     "monitoring_confirmation":"CONFIRMATION_FROM_PREVIEW"
   }

   Each request checks up to three companies within a bounded time window. If activation_status is pending, repeat the same endpoint with the returned activation_token and next_cursor as cursor, keeping the original confirmation:

   {
     "monitoring_confirmation":"CONFIRMATION_FROM_PREVIEW",
     "activation_token":"TOKEN_FROM_PENDING_RESPONSE",
     "cursor":3
   }

   Only enabled: true with activation_status: "active" confirms completion. needs_attention leaves the workflow paused and reports company failures in monitoring_setup. Review the failures, preview again and retry without an activation token. Completed monitoring is preserved. If a continuation session ended, read the workflow before starting a new attempt.

5. Inspect reviews and maintain the rule

   Read the workflow’s /runs for recent matches and GET /api/v1/cases for review tasks. PATCH settings to save an edited rule paused, then preview and activate it again. POST an empty JSON object to /pause to stop future tasks from that rule without changing company monitoring.

Read GET /api/v1/cases/{review_id} first. Submit its current review.revision when updating. All review operations require read; updates additionally require reviews:write. Existing keys and OAuth connections need this permission explicitly added. MCP updates also require confirmed: true.

PATCH /api/v1/cases/REVIEW_ID
{
  "revision": 0,
  "status": "resolved",
  "note": "Reviewed the source filing and recorded the supplier decision."
}

Supported statuses are open, in_review and resolved. Resolution requires a written decision. You can also update assignee (an eligible member email or empty string), priority, and due (YYYY-MM-DD or null). Omitted fields are preserved. A stale revision returns HTTP 409 without changing the review or queuing notifications; read the latest state and confirm your intended change again. Each successful revision records its actor and before/after values.

Removing a reviewer or changing their role to viewer clears their workflow assignments and moves their unresolved reviews to the unassigned queue. Existing resolved decisions and run-history snapshots are retained. Queued task emails recheck the current reviewer’s access and assignment before sending.

Task notifications and review webhooks

Workflows support notify_assignee (default true). Assigned reviewers receive a transactional email with a direct task link. This is separate from company-change email recipients. Disable it in the workflow’s Review action step or through the API. Reassignment can notify the new reviewer; unassigned or resolved reviews do not generate assignment emails.

Webhook destinations opt into event_types: company.changed, review.created and review.resolved. Existing destinations retain company changes only. Select review events under Notifications → Event subscriptions, or supply the array to create_webhook. Per-company webhook destination preferences still apply. Review payloads include the review ID, status, assignee, priority, revision, decision, task URL and source event ID. Delivery uses the same signature headers, durable queue and retries as company events. Deduplicate by delivery ID; do not depend on delivery order.

Coverage, archive and history

get_company includes monitoring.workflow_coverage; save/monitoring responses include workflow_coverage directly. A new list member can be in scope while missing required signals. Inspect get_workflow, preview its updated company scope and confirm activation to repair coverage. No additional subscriptions are started merely because a company joins a list.

Archive keeps company monitoring, existing reviews and all run history. Restore with {"archived": false}; the rule stays paused until you preview and activate it. Workflow listings hide archived rules by default; use include_archived=true to include them. Run history supports limit (1–100) and an opaque cursor. Pass next_cursor unchanged until it is null, including for archived workflows.