SOS Monitoring allows you to continuously monitor a business entity for changes to its Secretary of State (SOS) information.

After monitoring is configured, Compliancely periodically retrieves the latest SOS information based on the configured monitoring frequency, compares the latest result with the previously available data, maintains the monitoring history, and makes detected changes available through the Monitoring APIs.

Webhook notifications can also be configured so your application can be notified when monitoring checks are completed.

Currently supported states include New York, Illinois, and California.

How SOS Monitoring Works

A typical SOS Monitoring integration follows this sequence:

SOS Search → Configure Monitoring → Periodic Monitoring Attempts → Detect Changes → Versions → Review Changes / Snapshot

The APIs described below allow you to manage the complete monitoring lifecycle.

1. Initiate a New SOS Monitoring Request

Before configuring monitoring, identify the SOS record that you want Compliancely to monitor.

Create the monitoring configuration by providing the original SOS search/request reference, the SOS record to monitor, the required monitoring frequency, and optionally webhook URLs.

Supported monitoring frequencies are:

• weekly
• bi_weekly
• monthly
• quarterly

Once successfully created, Compliancely assigns a monitoring ID. Store this ID in your application because it is the primary identifier used by the subsequent monitoring APIs.

API: POST /api/v1/monitoring/sos/ - Configure SOS Monitoring

The request currently requires request_id, initial_record_id, and frequency; webhook_urls can also be supplied.

2. Check the Monitoring Configuration and Status

After creating monitoring, retrieve the monitoring record using its monitoring_id.

Use this API whenever your application needs the current details of a particular monitoring configuration.

For example, it can be used after creation or later in the lifecycle to retrieve the monitoring configuration associated with an entity.

API: GET /api/v1/monitoring/sos/{monitoring_id}/ - Get SOS Monitoring Details

This API represents the current monitoring configuration, while Timeline and Version APIs described below provide historical information about monitoring activity and SOS data changes.

3. Update the Monitoring Frequency or Webhooks

Monitoring requirements may change after the monitoring request has been created.

Use the Update SOS Monitoring API to modify the monitoring configuration without creating a new monitoring request.

You can update:

• Monitoring frequency
• Configured webhook_urls

For example, an entity currently monitored monthly can be changed to weekly.

API: PATCH /api/v1/monitoring/sos/{monitoring_id}/ - Update SOS Monitoring

Updating the configuration changes how the existing monitoring request operates; the same monitoring_id continues to identify the monitoring.

4. Understand Monitoring Attempts Using Timeline

Once monitoring is active, Compliancely performs monitoring attempts according to the configured frequency.

Use the Timeline API when you want to understand the monitoring activity associated with a monitoring request.

The timeline provides the history of monitoring attempts for the specified monitoring_id and can be used to understand when monitoring checks occurred and their associated results/statuses.

API: GET /api/v1/monitoring/sos/{monitoring_id}/timeline/ - View Monitoring Timeline

Think of the Timeline as the operational history of monitoring attempts.

It answers the question:

"What monitoring checks have occurred for this entity?"

A monitoring attempt does not necessarily mean that the SOS information changed. An attempt represents a monitoring check; versions should be used to inspect the historical SOS data/change history.

5. View Available SOS Versions

As SOS monitoring progresses, use the Versions API to retrieve the versions available for a monitoring configuration.

API: GET /api/v1/monitoring/sos/{monitoring_id}/versions/ - List SOS Monitoring Versions

Versions provide the historical view of the SOS information maintained for the monitored entity.

Use this endpoint first when you want to determine which versions are available before requesting the details or snapshot of a particular version.

Think of Versions as answering:

What historical versions of this monitored SOS entity are available?

6. Understand What Changed in a Specific Version

When you identify a version of interest, use the Version Detail API to inspect that version.

Unlike a snapshot, Version Detail is intended to describe the differences associated with that version compared with the previous version.

This is useful when your application is interested primarily in the change rather than retrieving the complete SOS record again.

API: GET /api/v1/monitoring/sos/{monitoring_id}/version/{version}/ - Get Version Detail

For example, if an entity's SOS information changes between versions, Version Detail allows the integration to determine which monitored information changed.

Think of Version Detail as answering:

What changed in this version?

7. Retrieve the Complete SOS Record for a Version

Sometimes knowing only the differences is not sufficient.

Use the Snapshot API when your application needs the complete SOS object as it existed for a particular version.

API: GET /api/v1/monitoring/sos/{monitoring_id}/version/{version}/snapshot/ - Get Version Snapshot

The distinction between Version Detail and Snapshot is important:

Version Detail - Changes/differences associated with the version.

Snapshot - Complete SOS object represented by that version.

Think of Snapshot as answering:

What did the complete SOS record look like at this version?

This allows integrations to reconstruct or inspect the full SOS information at a particular point in the monitoring history.

8 Retrieve All Monitoring Requests

When you need to retrieve monitoring requests across your account rather than one specific SOS monitoring record, use the Monitoring List API.

API: GET /api/v1/monitoring/ - Get Monitoring Requests

Use this API for scenarios such as building a monitoring dashboard, listing monitored entities, or identifying monitoring requests before retrieving their individual details.

This is a global monitoring endpoint rather than an SOS-specific detail endpoint.

9. Stop Monitoring

When an entity no longer needs to be monitored, stop the monitoring request using its monitoring_id.

API: DELETE /api/v1/monitoring/{monitoring_id}/ - Stop Monitoring

After monitoring is stopped, Compliancely should no longer perform future scheduled monitoring checks for that monitoring request.

Putting It All Together

flowchart TD

    A[Perform SOS Search]
    B[Identify SOS Record]
    C["Create Monitoring<br/>POST /api/v1/monitoring/sos/"]
    D[Store monitoring_id]
    E[Monitoring runs based on configured frequency]
    F[Perform SOS Monitoring Attempt]
    G["Timeline<br/>Monitoring attempt history"]
    H[Compare latest SOS data with previous data]
    I{Changes detected?}
    J[Create / Maintain SOS Version]
    K["Versions<br/>List available versions"]
    L["Version Detail<br/>Changes from previous version"]
    M["Snapshot<br/>Complete SOS object for the version"]
    N[No new SOS data change]

    A --> B
    B --> C
    C --> D
    C --> E

    E --> F
    F --> G
    F --> H

    H --> I

    I -->|Yes| J
    I -->|No| N

    J --> K
    J --> L
    J --> M

    N --> E
    J --> E

During the monitoring lifecycle, the monitoring configuration can also be managed independently:

flowchart LR 
    A["Monitoring Request<br/>monitoring_id"] 
    B["Get Monitoring Details<br/>GET /monitoring/sos/{monitoring_id}/"] 
    C["Update Frequency / Webhooks<br/>PATCH /monitoring/sos/{monitoring_id}/"] 
    D["View Timeline<br/>GET /monitoring/sos/{monitoring_id}/timeline/"] 
    E["View Versions<br/>GET /monitoring/sos/{monitoring_id}/versions/"] 
    F["Stop Monitoring<br/>DELETE /monitoring/{monitoring_id}/"] 
    A --> B 
    A --> C 
    A --> D 
    A --> E 
    A --> F

During the lifecycle you can also:

PATCH /monitoring/sos/{monitoring_id}/

Change frequency/webhook configuration

GET /monitoring/sos/{monitoring_id}/

Retrieve current monitoring details

GET /monitoring/

Retrieve monitoring requests

DELETE /monitoring/{monitoring_id}/

Stop monitoring

Timeline vs. Versions vs. Version Detail vs. Snapshot

These APIs serve different purposes and should not be treated as interchangeable.

Recommended Integration Flow

For most integrations:

1. Perform an SOS search and identify the record that needs to be monitored.
2. Create SOS Monitoring and persist the returned monitoring_id.
3. Configure webhook URLs if your application needs notifications about monitoring activity.
4. Use Monitoring Detail when you need the current monitoring configuration/status.
5. Use Timeline to inspect monitoring attempts.
6. Use Versions when you need to identify historical SOS versions.
7. Use Version Detail when you need to understand what changed.
8. Use Snapshot when you need the complete SOS object for a particular version.
9. Update the monitoring frequency or webhook configuration when required.
10. Stop monitoring when the entity no longer needs to be monitored.