> 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 timeline for a business GET https://api.middesk.com/v1/businesses/{business_id}/timeline Returns a paginated list of timeline events for a business, providing a chronological record of changes observed on the business's Secretary of State registrations. Events are ordered by `occurred_at`, newest first. For accounts with the timeline feature enabled, a business's timeline is constructed once from historical SOS filings when the business's first Verify or Identity order is placed. From then on, new events are appended as Middesk observes registration changes for businesses with an active registration [monitor](https://docs.middesk.com/reference/monitor). Reference: https://docs.middesk.com/api-reference/business-verification/timeline/get-business-timeline ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `business_id` (string, required) — Business ID ### Query parameters - `page` (integer, optional) — Page number (default: 1) - `per_page` (integer, optional) — Number of events per page (default: 100, max: 100) - `start_date` (string, optional) — Filter events occurring on or after this date (YYYY-MM-DD format) - `end_date` (string, optional) — Filter events occurring on or before this date (YYYY-MM-DD format) - `event_types` (string, optional) — Comma-separated list of event types to filter by. Valid values: `registration.created`, `registration.updated`, `address.created`, `address.deleted`, `person.created`, `person.deleted`, `name.created`, `name.deleted` ## Response ### 200 timeline events list - `object` (string, required) - `has_more` (boolean, required) - `data` (list of TimelineEvent, optional) - `total_count` (integer, optional) ## Errors ### 404 Get Business Timeline Request Not Found Error business not found - `errors` (list of ErrorResponseErrorsItem, required) ## Types ### TimelineEvent A single change observed on a business's Secretary of State record. Events are sourced both from historical SOS filings and from ongoing SOS monitoring. - `object` (enum, required) - Allowed values: `event` - `id` (string, required) - `account_id` (string, required) - `type` (enum, required) — The kind of change observed. A name change is represented as a `name.deleted` event for the old name paired with a `name.created` event for the new name. - Allowed values: `registration.created`, `registration.updated`, `address.created`, `address.deleted`, `person.created`, `person.deleted`, `name.created`, `name.deleted` - `data` (TimelineEventData, required) - `occurred_at` (datetime, required) — When the change occurred in the real world, falling back to when Middesk recorded the event if the source did not report a timestamp. - `created_at` (datetime, required) — When Middesk recorded the event. ### ErrorResponseErrorsItem - `message` (string, required) - `parameter` (string, optional) — Request parameter associated with the error, when applicable ### TimelineEventData - `object` (map from string to any, required) — The resource the change was observed on, matching the event `type`: an [Address](https://docs.middesk.com/reference/address), [Person](https://docs.middesk.com/reference/person), [Name](https://docs.middesk.com/reference/names), or [Registration](https://docs.middesk.com/reference/registration) as described in the Business Verification Object Reference. Events constructed from historical Secretary of State filings carry null values for any fields the filing did not supply. In particular, addresses, names, and people on historical events have a null `id` — they describe past observations, not retrievable records — and registrations on historical events carry null values for `name`, `entity_type`, and (on `registration.created`) `status`. - `previous_attributes` (map from string to any, optional) — The prior values of the registration fields that changed. Present only on `registration.updated` events. A null value means the field previously had no value. ## Examples **Response** ```json { "object": "list", "has_more": false, "data": [ { "object": "event", "id": "e0000001-0000-4000-8000-000000000001", "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234", "type": "person.created", "data": { "object": { "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678", "name": "ROGER SMITH", "object": "person", "sources": [ { "id": "d4e5f6a7-b8c9-0123-def0-123456789012", "metadata": { "file_number": "C1234567", "jurisdiction": "DOMESTIC", "state": "CA", "status": "active" }, "type": "registration" } ], "submitted": false } }, "occurred_at": "2026-05-20T08:30:00Z", "created_at": "2026-05-20T08:30:00Z" }, { "object": "event", "id": "e0000002-0000-4000-8000-000000000002", "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234", "type": "name.deleted", "data": { "object": { "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678", "name": "ACME HOLDINGS LLC", "object": "name", "sources": [ { "id": "d4e5f6a7-b8c9-0123-def0-123456789012", "metadata": { "file_number": "C1234567", "jurisdiction": "DOMESTIC", "state": "CA" }, "type": "registration" } ], "submitted": false } }, "occurred_at": "2023-08-10T00:00:00Z", "created_at": "2026-01-07T12:00:00Z" }, { "object": "event", "id": "e0000003-0000-4000-8000-000000000003", "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234", "type": "person.created", "data": { "object": { "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678", "name": "JANE DOE", "object": "person", "sources": [ { "id": "d4e5f6a7-b8c9-0123-def0-123456789012", "metadata": { "file_number": "C1234567", "jurisdiction": "DOMESTIC", "state": "CA" }, "type": "registration" } ], "submitted": false, "titles": [ { "object": "person_title", "title": "PRESIDENT" } ] } }, "occurred_at": "2022-04-01T00:00:00Z", "created_at": "2026-01-07T12:00:00Z" }, { "object": "event", "id": "e0000004-0000-4000-8000-000000000004", "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234", "type": "registration.updated", "data": { "object": { "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678", "file_number": "C1234567", "id": "d4e5f6a7-b8c9-0123-def0-123456789012", "jurisdiction": "DOMESTIC", "object": "registration", "registration_date": "2019-01-15", "state": "CA", "status": "inactive" }, "previous_attributes": { "status": "active" } }, "occurred_at": "2021-03-02T00:00:00Z", "created_at": "2026-01-07T12:00:00Z" }, { "object": "event", "id": "e0000005-0000-4000-8000-000000000005", "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234", "type": "address.created", "data": { "object": { "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678", "cmra": false, "created_at": "2020-06-15T00:00:00Z", "full_address": "123 MAIN ST, SAN FRANCISCO, CA 94105", "is_registered_agent": false, "object": "address", "rating": { "risk_rating": "not_available" }, "sources": [ { "id": "d4e5f6a7-b8c9-0123-def0-123456789012", "metadata": { "file_number": "C1234567", "jurisdiction": "DOMESTIC", "state": "CA" }, "type": "registration" } ], "submitted": false, "updated_at": "2020-06-15T00:00:00Z" } }, "occurred_at": "2020-06-15T00:00:00Z", "created_at": "2026-01-07T12:00:00Z" }, { "object": "event", "id": "e0000006-0000-4000-8000-000000000006", "account_id": "f2a3b4c5-d6e7-8901-5678-9abcdef01234", "type": "registration.created", "data": { "object": { "business_id": "a0b1c2d3-e4f5-6789-0abc-def012345678", "file_number": "C1234567", "id": "d4e5f6a7-b8c9-0123-def0-123456789012", "jurisdiction": "DOMESTIC", "object": "registration", "registration_date": "2019-01-15", "state": "CA" } }, "occurred_at": "2019-01-15T00:00:00Z", "created_at": "2026-01-07T12:00:00Z" } ], "total_count": 6 } ``` **SDK Code** ```python Timeline events import requests url = "https://api.middesk.com/v1/businesses/business_id/timeline" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript Timeline events const url = 'https://api.middesk.com/v1/businesses/business_id/timeline'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Timeline events package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.middesk.com/v1/businesses/business_id/timeline" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Timeline events require 'uri' require 'net/http' url = URI("https://api.middesk.com/v1/businesses/business_id/timeline") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Timeline events import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.middesk.com/v1/businesses/business_id/timeline") .header("Authorization", "Bearer ") .asString(); ``` ```php Timeline events request('GET', 'https://api.middesk.com/v1/businesses/business_id/timeline', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Timeline events using RestSharp; var client = new RestClient("https://api.middesk.com/v1/businesses/business_id/timeline"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Timeline events import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.middesk.com/v1/businesses/business_id/timeline")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```