Timeline of a Record
Purpose
To get the timeline of a record. The response gives you the history of the record including all the updates that were made to any of its fields and related records.
Request Details
Request URL
{api-domain}/crm/{version}/{module_API_name}/{record_ID}/__timeline
Supported Modules
Leads, Contacts, Accounts, Deals, Tasks, Meetings, Calls, Products, Services, Appointments, Purchase Orders, Sales Orders, Quotes, Invoices, Notes, Custom
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
scope=ZohoCRM.modules.{module_name}.ALL
(or)
scope=ZohoCRM.modules.{module_name}.READ
Parameters
- per_pageinteger, optional
The number of records you want to fetch per page. You can use this parameter for the first page only. For the subsequent pages, you must use the "page_token" parameter.
- page_tokenstring, mandatory
Specify the "next_page_token" or the "previous_page_token" after you have paginated and retrieved 200 records. Note that you cannot give "per_page" parameter if you give "page_token" in the request.
- include_timeline_typestring, optional
To include extra types in the "timeline" object. You can get "signals" data through this to get signals-related timeline entries.
- includestring, mandatory when you specify "include_timeline_type" parameter
Use this parameter if you want to view the details of updates to the record through signals or any other means. The possible values are extension and type. For example, if the record was updated through a signal, then the response will have details of the extension as email insights, while the type of update will be signals.
- include_inner_detailsstring, optional
Use this parameter if you want to get extra details of the updates made to the record in the "field_history" object of the response.
The possible values are:
- field_history.data_type - Gives the details of the data type of the field that was updated.
- field_history.field_label - Gives the details of the field labels that were updated.
- field_history.pick_list_values - Represents the list of values that are available for a picklist.
- field_history.enable_colour_code - Represents whether color coding is enabled for that picklist value.
- done_by.profile - Gives the details of the user's profile who updated the record.
- done_by.type__s - Gives the details of the type of user such as portal user or a regular user that modified the record.
- filtersJSON object (encoded), optional
The filters parameter is used for filtering the response from the timeline API based on specific conditions based on certain response JSON keys. This parameter has three components, namely field, comparator and value, that form the conditions for filtering timeline data.
For example, {"field":{"api_name":"record.module.api_name"},"comparator":"equal","value":"Notes"}.
The field component comprises of a key-value pair. For field, possible value of key is api_name and possible values for value are:
record.module.api_name: In the response, this field represents the details of the parent module or related module in which a particular change occurs. You can filter the timeline details of a few modules out of the different modules listed here.
The modules that allow filtering (i.e. possible values for value ) are Notes, Attachments, Tasks, Calls, Events, Emails.The allowed comparators are equal and in.
For example,for filtering Notes :
{"field":{"api_name":"record.module.api_name"},"comparator":"equal","value":"Notes"}
For filtering Notes and Tasks :
{"field":{"api_name":"record.module.api_name"},"comparator":"in","value":["Notes","Tasks"]}
done_by.id: In the response, this field represents the details of the user who did the changes. You can filter the timeline details done by a particular user.
The allowed comparators are equal and in. The allowed values are user IDs. You can get user ID from Get Users API.
For example, to filter timeline details done by a particular user ID :
{"field":{"api_name":"done_by.id"},"comparator":"in","value":["5843104000000424001"]}
audited_time: In the response, this field represents the data and time at which the record update happened. You can filter timeline data based on its audited time.
The allowed comparator is between. The allowed value is time in ISO 8601 format..
For example to filter time line details between two dates :
{"field":{"api_name":"audited_time"},"comparator":"between","value":["2023-10-25T00:00:00+12:00","2023-10-30T23:59:59+12:00"]}
source: In the response, this field represents the source of record updation. You can filter time line data based on its source.
The allowed comparators are equal and in. The allowed values include crm_api, mass_delete_via_crm_api, bulkapi, approval_process, assignment_rules, blueprint, mass_update_via_blueprint, orchestration, convert, massconvert, custom_function, macro, crm_ui, mass_update, mass_update_via_scheduler, mass_delete_via_clean_up, bulk_action, change_owner, mass_change_owner_via_scheduler, review_process, scoringrule, wizard, workflow.
For example to filter timeline details based on source:
{"field":{"api_name":"source"},"comparator":"equal","value":"crm_ui"} {"field":{"api_name":"source"},"comparator":"in","value":["crm_api",crm_ui"]}
You can combine multiple conditions using group_operator and group.
{"group_operator":"AND","group":[{"field":{"api_name":"record.module.api_name"},"comparator":"in","value":["Notes"]},{"field":{"api_name":"source"},"comparator":"in","value":["crm_ui","crm_api"]}]}
You can also refer to the sample request for the structure. Note that you must encode the value of this parameter.
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v5/Leads/554023000001122039/__timeline?sort_by=audited_time&include_inner_details=field_history.data_type, field_history.field_label, field_history.enable_colour_code, field_history.pick_list_values, done_by.type__s, done_by.profile&filters=%7B%22comparator%22%3A%22between%22%2C%22field%22%3A%7B%22api_name%22%3A%22audited_time%22%7D%2C%22value%22%3A%5B%222023-06-07T00%3A00%3A00%2B05%3A30%22%2C%222023-06-07T12%3A59%3A59%2B05%3A30%22%5D%7D"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"Response JSON
- done_byJSON Object
The details of the user who modified the record such as the name, ID, name and ID of that user's profile, and the user type.
- related_recordJSON Object
The name and ID of the parent record which the task, call, or meeting belongs to.
- automation_detailsJSON Object
Represents that the record was modified through an automation action such as a workflow.
- recordJSON Object
The name and ID of the task, call, or meeting that was created for the parent record.
- audited_timestring
The date and time at which the update on the record happened.
- actionstring
The action that happened on the record. Some of the possible values are "added", "updated", "owner_assigned", "task_assigned", "relatedrecords_added".
- idlong
The unique ID of the action on the timeline.
- sourcestring
Represents from where the record was updated. The possible values include crm_api, mass_delete_via_crm_api, bulkapi, approval_process, assignment_rules, blueprint, mass_update_via_blueprint, orchestration, convert, massconvert, custom_function, macro, crm_ui, mass_update, mass_update_via_scheduler, mass_delete_via_clean_up, bulk_action, change_owner, mass_change_owner_via_scheduler, review_process, scoringrule, wizard, workflow.
- field_historyJSON Array
Contains the following details:
- api_name - The API name of the field that was modified. This will be available by default in the response.
- _value - The old and new values of the field. This will be available by default in the response.
- The following values are available in the response when you specify the include_inner_details parameter.
- enable_colour_code - Represents whether color coding is enabled for the picklist field.
- data_type - The data type of the field that was modified.
- pick_list_values - The details of the various values of the picklist.
Possible Errors
- NO_CONTENTHTTP 204
Data unavailability or there is no timeline for the applied filter.
Resolution: Modify the filter values and try again.
- INVALID_DATAHTTP 400
You have used comparators that are not allowed in the "filters" parameter.
Resolution: Refer to the "filters" parameter in the "Parameters" section for the list of allowed comparators and the fields.
- INVALID_DATAHTTP 400
You have not encoded the value of the filters parameter.
Resolution: Encode the fields parameter.
- INVALID_DATAHTTP 400
The ID of the record is invalid in the request URL.
Resolution: Specify a valid record ID. Refer to Get Records API to get the record ID.
- AMBIGUITY_DURING_PROCESSINGHTTP 400
You have specified both "per_page" and "page_token" parameters.
Resolution: You can only use the "page_token" parameter for navigation.
- OAUTH_SCOPE_MISMATCHHTTP 401
You do not have the right scope to access this API.
Resolution: Create a new token with the scopes mentioned in the "Scopes" section, and try this API.
- INTERNAL_SERVER_ERRORHTTP 500
Unhandled and unexpected exception in server.
Resolution: Contact support@zohocrm.com for assistance.
Sample Response
Copied{
"__timeline": [
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": null,
"automation_details": null,
"record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": "Patricia Boyle",
"id": "554023000001122039"
},
"audited_time": "2023-06-07T19:32:21-11:00",
"action": "tag_added",
"id": "554023000003097009",
"source": "mass_update",
"field_history": [
{
"api_name": "Tag",
"field_label": "Tag",
"enable_colour_code": false,
"data_type": "text",
"_value": {
"new": "Prime",
"old": "blank"
},
"id": "554023000000138025",
"pick_list_values": []
}
]
},
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": null,
"automation_details": null,
"record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": "Patricia Boyle",
"id": "554023000001122039"
},
"audited_time": "2023-06-07T18:58:36-11:00",
"action": "updated",
"id": "554023000003097006",
"source": "crm_ui",
"field_history": [
{
"api_name": "Phone",
"field_label": "Phone",
"enable_colour_code": false,
"data_type": "phone",
"_value": {
"new": "1234567",
"old": null
},
"id": "554023000000000565",
"pick_list_values": []
}
]
},
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": null,
"automation_details": null,
"record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": "Patricia Boyle",
"id": "554023000001122039"
},
"audited_time": "2023-06-07T18:17:54-11:00",
"action": "updated",
"id": "554023000003095054",
"source": "crm_ui",
"field_history": [
{
"api_name": "Last_Name",
"field_label": "Last Name",
"enable_colour_code": false,
"data_type": "text",
"_value": {
"new": "Boyle",
"old": "Smith"
},
"id": "554023000000000559",
"pick_list_values": []
},
{
"api_name": "First_Name",
"field_label": "First Name",
"enable_colour_code": false,
"data_type": "text",
"_value": {
"new": "Patricia",
"old": null
},
"id": "554023000000000557",
"pick_list_values": []
},
{
"api_name": "Full_Name",
"field_label": "Full Name",
"enable_colour_code": false,
"data_type": "text",
"_value": {
"new": "Patricia Boyle",
"old": "Smith"
},
"id": "554023000000000597",
"pick_list_values": []
}
]
},
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": null,
"automation_details": null,
"record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": " Smith",
"id": "554023000001122039"
},
"audited_time": "2023-06-07T18:17:19-11:00",
"action": "updated",
"id": "554023000003095048",
"source": "crm_ui",
"field_history": [
{
"api_name": "Company",
"field_label": "Company",
"enable_colour_code": false,
"data_type": "text",
"_value": {
"new": "ABC",
"old": "Zylker"
},
"id": "554023000000000555",
"pick_list_values": []
}
]
},
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": null,
"automation_details": null,
"record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": " Smith",
"id": "554023000001122039"
},
"audited_time": "2023-06-07T18:12:11-11:00",
"action": "updated",
"id": "554023000003095038",
"source": "crm_api",
"field_history": [
{
"api_name": "Lead_Source",
"field_label": "Lead Source",
"enable_colour_code": false,
"data_type": "picklist",
"_value": {
"new": "Cold Call",
"old": "Employee Referral"
},
"id": "554023000000000573",
"pick_list_values": [
{
"display_value": "-None-",
"sequence_number": 1,
"colour_code": null,
"actual_value": "-None-",
"id": "554023000000002313",
"type": "used"
},
{
"display_value": "Advertisement",
"sequence_number": 2,
"colour_code": null,
"actual_value": "Advertisement",
"id": "554023000000002315",
"type": "used"
},
{
"display_value": "Chat",
"sequence_number": 28,
"colour_code": null,
"actual_value": "Chat",
"id": "554023000000040001",
"type": "used"
},
{
"display_value": "Cold Call",
"sequence_number": 6,
"colour_code": null,
"actual_value": "Cold Call",
"id": "554023000000002317",
"type": "used"
},
{
"display_value": "Employee Referral",
"sequence_number": 8,
"colour_code": null,
"actual_value": "Employee Referral",
"id": "554023000000002319",
"type": "used"
},
{
"display_value": "External Referral",
"sequence_number": 9,
"colour_code": null,
"actual_value": "External Referral",
"id": "554023000000002321",
"type": "used"
},
{
"display_value": "Facebook",
"sequence_number": 15,
"colour_code": null,
"actual_value": "Facebook",
"id": "554023000001157033",
"type": "used"
},
{
"display_value": "Internal Seminar",
"sequence_number": 22,
"colour_code": null,
"actual_value": "Seminar-Internal",
"id": "554023000000172093",
"type": "used"
},
{
"display_value": "Online Store",
"sequence_number": 14,
"colour_code": null,
"actual_value": "OnlineStore",
"id": "554023000000172095",
"type": "used"
},
{
"display_value": "Partner",
"sequence_number": 18,
"colour_code": null,
"actual_value": "Partner",
"id": "554023000000002323",
"type": "used"
},
{
"display_value": "Public Relations",
"sequence_number": 19,
"colour_code": null,
"actual_value": "Public Relations",
"id": "554023000000002325",
"type": "used"
},
{
"display_value": "Sales Email Alias",
"sequence_number": 20,
"colour_code": null,
"actual_value": "Sales Mail Alias",
"id": "554023000000172089",
"type": "used"
},
{
"display_value": "Seminar Partner",
"sequence_number": 21,
"colour_code": null,
"actual_value": "Seminar Partner",
"id": "554023000000172091",
"type": "used"
},
{
"display_value": "Trade Show",
"sequence_number": 25,
"colour_code": null,
"actual_value": "Trade Show",
"id": "554023000000002327",
"type": "used"
},
{
"display_value": "Twitter",
"sequence_number": 16,
"colour_code": null,
"actual_value": "Twitter",
"id": "554023000001157037",
"type": "used"
},
{
"display_value": "Web Download",
"sequence_number": 26,
"colour_code": null,
"actual_value": "Web Download",
"id": "554023000000172085",
"type": "used"
},
{
"display_value": "Web Research",
"sequence_number": 27,
"colour_code": null,
"actual_value": "Web Research",
"id": "554023000000172087",
"type": "used"
}
]
}
]
},
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": "Smith",
"id": "554023000001122039"
},
"automation_details": null,
"record": {
"module": {
"api_name": "Tasks",
"id": "554023000000000143"
},
"name": "test task",
"id": "554023000003095019"
},
"audited_time": "2023-06-07T18:10:47-11:00",
"action": "added",
"id": "554023000003095029",
"source": "crm_ui",
"field_history": null
},
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": "Smith",
"id": "554023000001122039"
},
"automation_details": null,
"record": {
"module": {
"api_name": "Notes",
"id": "554023000000000147"
},
"name": "This is a test note",
"id": "554023000003096003"
},
"audited_time": "2023-06-07T18:10:29-11:00",
"action": "added",
"id": "554023000003096001",
"source": "crm_ui",
"field_history": null
},
{
"done_by": {
"profile": {
"name": "Administrator",
"id": "554023000000015972"
},
"name": "Patricia Boyle",
"id": "554023000000235011",
"type__s": "regular user"
},
"related_record": null,
"automation_details": null,
"record": {
"module": {
"api_name": "Leads",
"id": "554023000000000125"
},
"name": " Smith",
"id": "554023000001122039"
},
"audited_time": "2023-06-07T18:09:49-11:00",
"action": "updated",
"id": "554023000003095017",
"source": "crm_ui",
"field_history": [
{
"api_name": "Lead_Source",
"field_label": "Lead Source",
"enable_colour_code": false,
"data_type": "picklist",
"_value": {
"new": "Employee Referral",
"old": null
},
"id": "554023000000000573",
"pick_list_values": [
{
"display_value": "-None-",
"sequence_number": 1,
"colour_code": null,
"actual_value": "-None-",
"id": "554023000000002313",
"type": "used"
},
{
"display_value": "Advertisement",
"sequence_number": 2,
"colour_code": null,
"actual_value": "Advertisement",
"id": "554023000000002315",
"type": "used"
},
{
"display_value": "Chat",
"sequence_number": 28,
"colour_code": null,
"actual_value": "Chat",
"id": "554023000000040001",
"type": "used"
},
{
"display_value": "Cold Call",
"sequence_number": 6,
"colour_code": null,
"actual_value": "Cold Call",
"id": "554023000000002317",
"type": "used"
},
{
"display_value": "Employee Referral",
"sequence_number": 8,
"colour_code": null,
"actual_value": "Employee Referral",
"id": "554023000000002319",
"type": "used"
},
{
"display_value": "External Referral",
"sequence_number": 9,
"colour_code": null,
"actual_value": "External Referral",
"id": "554023000000002321",
"type": "used"
},
{
"display_value": "Facebook",
"sequence_number": 15,
"colour_code": null,
"actual_value": "Facebook",
"id": "554023000001157033",
"type": "used"
},
{
"display_value": "Internal Seminar",
"sequence_number": 22,
"colour_code": null,
"actual_value": "Seminar-Internal",
"id": "554023000000172093",
"type": "used"
},
{
"display_value": "Online Store",
"sequence_number": 14,
"colour_code": null,
"actual_value": "OnlineStore",
"id": "554023000000172095",
"type": "used"
},
{
"display_value": "Partner",
"sequence_number": 18,
"colour_code": null,
"actual_value": "Partner",
"id": "554023000000002323",
"type": "used"
},
{
"display_value": "Public Relations",
"sequence_number": 19,
"colour_code": null,
"actual_value": "Public Relations",
"id": "554023000000002325",
"type": "used"
},
{
"display_value": "Sales Email Alias",
"sequence_number": 20,
"colour_code": null,
"actual_value": "Sales Mail Alias",
"id": "554023000000172089",
"type": "used"
},
{
"display_value": "Seminar Partner",
"sequence_number": 21,
"colour_code": null,
"actual_value": "Seminar Partner",
"id": "554023000000172091",
"type": "used"
},
{
"display_value": "Trade Show",
"sequence_number": 25,
"colour_code": null,
"actual_value": "Trade Show",
"id": "554023000000002327",
"type": "used"
},
{
"display_value": "Twitter",
"sequence_number": 16,
"colour_code": null,
"actual_value": "Twitter",
"id": "554023000001157037",
"type": "used"
},
{
"display_value": "Web Download",
"sequence_number": 26,
"colour_code": null,
"actual_value": "Web Download",
"id": "554023000000172085",
"type": "used"
},
{
"display_value": "Web Research",
"sequence_number": 27,
"colour_code": null,
"actual_value": "Web Research",
"id": "554023000000172087",
"type": "used"
}
]
}
]
}
],
"info": {
"per_page": 200,
"next_page_token": null,
"count": 10,
"page": 1,
"previous_page_token": null,
"more_records": false
}
}