Retrieve the business timeline

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:

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 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 to the Business.

How to retrieve the timeline

1
{
2
  "object": "list",
3
  "data": [
4
    {
5
      "object": "event",
6
      "id": "e0000004-0000-4000-8000-000000000004",
7
      "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234",
8
      "type": "registration.updated",
9
      "data": {
10
        "object": {
11
          "object": "registration",
12
          "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
13
          "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678",
14
          "status": "inactive",
15
          "jurisdiction": "DOMESTIC",
16
          "file_number": "C1234567",
17
          "registration_date": "2019-01-15",
18
          "state": "CA"
19
        },
20
        "previous_attributes": {
21
          "status": "active"
22
        }
23
      },
24
      "occurred_at": "2021-03-02T00:00:00.000Z",
25
      "created_at": "2026-01-07T12:00:00.000Z"
26
    },
27
    {
28
      "object": "event",
29
      "id": "e0000005-0000-4000-8000-000000000005",
30
      "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234",
31
      "type": "address.created",
32
      "data": {
33
        "object": {
34
          "object": "address",
35
          "full_address": "123 MAIN ST, SAN FRANCISCO, CA 94105",
36
          "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678",
37
          "created_at": "2020-06-15T00:00:00Z",
38
          "updated_at": "2020-06-15T00:00:00Z",
39
          "sources": [
40
            {
41
              "id": "d4e5f6a7-b8c9-0123-def0-123456789012",
42
              "type": "registration",
43
              "metadata": {
44
                "state": "CA",
45
                "file_number": "C1234567",
46
                "jurisdiction": "DOMESTIC"
47
              }
48
            }
49
          ]
50
        }
51
      },
52
      "occurred_at": "2020-06-15T00:00:00.000Z",
53
      "created_at": "2026-01-07T12:00:00.000Z"
54
    }
55
  ],
56
  "url": "/v1/businesses/a0b1c2d3-e4f5-6789-0abc-def012345678/timeline",
57
  "has_more": false,
58
  "total_count": 2
59
}

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

$
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 object.
• name.* events use the Name object.
• person.* events use the Person object.
• registration.* events use the 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 and re-run the relevant review task.