35 exact fields in five groups
New monitoring settings use the exact upstream field identifier. Existing records that use the five older category values remain compatible. Availability still varies by jurisdiction and source, so confirm collection and comparison behaviour for your portfolio.
| Group | Exact supported field identifiers |
|---|---|
| Company | company.name, company.status, company.registration_number, company.vat, company.address_street, company.email, company.phone, company.fax, company.website, company.bank, company.employees_number, company.trading_activity_export, company.trading_activity_import, company.group_structure, company.financial |
| Locations | office.identity, office.email, office.fax, office.phone, office.website, address.street |
| Shareholders | shareholder.holding, shareholder.holding_historical, shareholder.exit_precise, shareholder.exit_approximate, shareholder.share_type, shareholder.share_price |
| Employees | employee.appointment, employee.phone, employee.email, employee.resignation_date |
| Officers | officer.appointment, officer.phone, officer.email, officer.resignation_date |
Review guidance by group
ownershipShareholders and recorded holdings
Example: a recorded shareholder's holding changes from 40% to 65%, or the available record identifies a different corporate shareholder.
Useful review: inspect the source, the shareholder identity and available group relationships. A holding change alone does not establish the final beneficial owner or every route of control.
Ownership investigations →directorsDirectors and company officers
Example: an available record identifies an appointment or resignation, or the recorded director count changes.
Useful review: check the role, dates and identity information. A change in a count does not identify a particular person. Similar person names across companies require additional evidence before linking them.
Company verification →statusRecorded legal status
Example: the source changes its company-status value from active to a different recorded state.
Useful review: inspect the original status and its jurisdiction-specific meaning. Check whether the event describes a filing, a pending process or an effective legal change before deciding what action is appropriate.
Supplier intelligence →financialsFinancial filings and reported figures
Example: new financial statements become available, or an available reported figure differs between saved records.
Useful review: establish the reporting period, currency and whether the accounts cover the company or the group. A new value can reflect a new period, a restatement or a source correction. This category does not provide a partner credit rating.
Financial filing monitoring →detailsRegistered company information
Example: a registered address, legal name or other supported company-detail field changes in the source record.
Useful review: confirm the same entity is being compared and identify the exact field. A registered-office change should not automatically overwrite a delivery address or another operational field in your system.
Company data management →Read the event as a record of a difference
The events API returns saved event rows. The fields below are the core information a receiving application should understand. Preserve unknown values rather than substituting invented dates or evidence.
| Field | Meaning | Handling |
|---|---|---|
id | CompanyDelta event identifier. | Use to join records and deduplicate downstream actions. |
company | Saved CompanyDelta company identifier. | Map to the company record; do not confuse it with a registration number. |
external_id | Source pipeline's event reference. | Unique for ingestion within a workspace. |
type / title | Category and a description of the recorded change. | Use type for routing and title for human context. |
previous / current | Stored before-and-after values. | Read with the event title and source; do not assume every value is numeric. |
source / source_url | Source description and any saved link. | An empty link remains a gap; it is not proof of a verified document. |
filed / effective / detected | Available filing, effective and detection dates. | Keep the dates distinct and preserve null values. |
sample | Numeric sample indicator, inherited from the company. | Exclude illustrative events from production reporting and actions. |
evidence | Serialized evidence references when collected by the source-check process. | Parse when needed; an empty list means no references are attached. |
Keep source dates separate from detection time
A change may take effect before a filing appears, and a source may publish that filing before your next collection. The event's detection timestamp records when CompanyDelta saved the event. It is not automatically the date on which the business changed.
For a sample ownership event, the effective date might be 4 September, the filing date 9 September and the detection date 12 September. A review should be able to see all three. If the source does not provide a date, retain the gap and explain it.
A comparison between two saved snapshots shows what differed between those observations. It may not expose every intermediate change. Source corrections and changes in coverage can also affect the available record. Read the sources and evidence guide when designing a defensible review.
Use the right format for the direction
The ingestion request, saved-event response and outbound webhook are related but distinct contracts:
| Direction | Company and value fields | Dates |
|---|---|---|
| Ingest with POST events | company_id, previous_value, current_value | Optional filed_at and effective_at. Detection is assigned by CompanyDelta. |
| Read with GET events | company, previous, current | filed, effective and detected. |
| Receive a webhook | company.id, company.name, and change.field, change.old_value, change.new_value. | occurred_at records the detected time. |
The outbound envelope uses type: "company.changed"; the exact Watch API field is at change.field. In a saved API event row, that identifier is directly in type. Use the ingestion example and webhook payload as the corresponding references.
A recorded event is the start of a workflow
An accepted event can create a case when the company is eligible and a matching enabled workflow exists. The current ingestion logic uses the first matching enabled workflow for the exact field or its review group. It does not promise that every possible rule will run.
Each accepted monitored update creates an in-workspace alert and queues an email for every workspace member. It also queues the same update for every enabled API webhook destination. Email and webhook attempts use durable delivery records and bounded retries; a configured destination is required for outbound API delivery.
Before relying on a quiet feed, confirm the Watch API subscription or last source check succeeded and the field is available. “No event recorded” and “no company change occurred” are different statements. For a pilot, validate a known event, a source gap and a delivery failure as well as the normal path.
Review company and corporate linkage coverage before selecting fields for your portfolio. Country record counts do not establish that every company has every event type.