> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.middesk.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.middesk.com/_mcp/server.

# Retrieve the business timeline

> Retrieve a chronological record of changes to a business's Secretary of State registration data

The business timeline is a chronological record of changes to a business's Secretary of State (SOS) registration data. Use it to review how a business has changed over time, like when it changed status, moved its address, or added and removed officers. Because these changes often carry risk signals, the timeline is useful when investigating a business, reviewing it before a decision, or building an audit trail of its registration history.

## How the timeline works

Each entry in the timeline is an event describing a single change to the business's registration data. Each event has one of the following types:

| Event                  | Description                                            |
| ---------------------- | ------------------------------------------------------ |
| `registration.created` | A registration was added to the business.              |
| `registration.updated` | A field on a registration changed, such as its status. |
| `address.created`      | An address was added to a registration.                |
| `address.deleted`      | An address was removed from a registration.            |
| `name.created`         | A business or DBA name was added to a registration.    |
| `name.deleted`         | A name was removed from a registration.                |
| `person.created`       | A person was added to a registration.                  |
| `person.deleted`       | A person was removed from a registration.              |

A change to an existing value is represented as a pair of events. For example, a name change arrives as a `name.deleted` event for the old name alongside a `name.created` event for the new one.

Every event carries two timestamps. `occurred_at` is when the change happened in the real world, falling back to when Middesk recorded the event if the source did not report a timestamp. `created_at` is when Middesk recorded the event. The timeline is ordered by `occurred_at`, newest first.

## How the timeline is updated

The timeline always includes the full history of changes to the business's registration data. How recent that history is depends on whether the business is enrolled in monitoring:

* **With [monitoring](../monitor-activity/how-monitoring-works) enabled.** Middesk detects and appends new changes as they happen, so the timeline stays current automatically and always reflects every change recorded on the business.
* **Without monitoring.** The timeline is current as of the most recent Verify order placed on the Business. To pick up changes that occurred since then, [add a new Verify order](/create-orders) to the Business.

## How to retrieve the timeline

#### Request the timeline

Call the timeline endpoint with the business ID. The response is a paginated list of events ordered newest first.

**`Example JSON response`**

```json title="Example JSON response"
{
  "object": "list",
  "data": [
    {
      "object": "event",
      "id": "e0000004-0000-4000-8000-000000000004",
      "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234",
      "type": "registration.updated",
      "data": {
        "object": {
          "object": "registration",
          "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
          "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678",
          "status": "inactive",
          "jurisdiction": "DOMESTIC",
          "file_number": "C1234567",
          "registration_date": "2019-01-15",
          "state": "CA"
        },
        "previous_attributes": {
          "status": "active"
        }
      },
      "occurred_at": "2021-03-02T00:00:00.000Z",
      "created_at": "2026-01-07T12:00:00.000Z"
    },
    {
      "object": "event",
      "id": "e0000005-0000-4000-8000-000000000005",
      "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234",
      "type": "address.created",
      "data": {
        "object": {
          "object": "address",
          "full_address": "123 MAIN ST, SAN FRANCISCO, CA 94105",
          "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678",
          "created_at": "2020-06-15T00:00:00Z",
          "updated_at": "2020-06-15T00:00:00Z",
          "sources": [
            {
              "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
              "type": "registration",
              "metadata": {
                "state": "CA",
                "file_number": "C1234567",
                "jurisdiction": "DOMESTIC"
              }
            }
          ]
        }
      },
      "occurred_at": "2020-06-15T00:00:00.000Z",
      "created_at": "2026-01-07T12:00:00.000Z"
    }
  ],
  "url": "/v1/businesses/a0b1c2d3-e4f5-6789-0abc-def012345678/timeline",
  "has_more": false,
  "total_count": 2
}
```

#### Page through results

The endpoint returns up to 100 events per page. Use `page` and `per_page` to move through the feed, and increment `page` until `has_more` is `false` to retrieve every event. `total_count` reports the total number of events across all pages.

```bash
curl -X GET "https://api.middesk.com/v1/businesses/{business_id}/timeline?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Filter the feed

Narrow the feed to the events you care about with these query parameters:

* `start_date` and `end_date` restrict the feed to events whose `occurred_at` falls on or between the two dates, formatted as `YYYY-MM-DD`.
* `event_types` restricts the feed to a comma-separated list of event types.

```bash
curl -X GET "https://api.middesk.com/v1/businesses/{business_id}/timeline?start_date=2024-01-01&event_types=registration.updated,name.created" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Understanding the event payloads

Each event's `data.object` is the resource the change was observed on, matching the event `type`. The payload follows the canonical shape of the corresponding object:

* `address.*` events use the [Address](/reference/address) object.
* `name.*` events use the [Name](/reference/names) object.
* `person.*` events use the [Person](/reference/person) object.
* `registration.*` events use the [Registration](/reference/registration) object.

A payload carries only the fields relevant to the change; fields the source did not supply return `null` or an empty default. Address and name payloads can have a `null` `id` when the event describes a past change rather than a currently retrievable record. `registration.updated` events also include a `previous_attributes` object holding the prior values of the fields that changed.

Once you have the events, store them for an audit or history view, read `previous_attributes` on a `registration.updated` event to see a field's prior value, or treat a change as a trigger to [retrieve the full business](/api-reference/business-verification/businesses/retrieve-a-business) and re-run the relevant [review task](/reference/business-review-tasks).

> **Get a demo**
>
> Contact your account manager or [contact sales](https://www.middesk.com/contact-sales) to inquire about access.