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.{module_name}.ALL
(or)
scope=ZohoCRM.{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, field_history.field_label, field_history.enable_colour_code, field_history.pick_list_values, done_by.type__s, done_by.profile.
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
Use this parameter to filter the response based on certain fields. You can filter based on the API name of the record's module, ID of the user that updated the record, audited time of the record, and the source of the update.
The allowed "group_operator" is "AND", the allowed "comparators" are "equal", "between", "in", and the allowed fields in "api_name" are "record.module.api_name", "done_by.id", "audited_time".The following are the comparators for each field type with their allowed values.
record.module.api_name - equal, in - The allowed values are Notes, Attachments, Tasks, Calls, Events, Emails.
done_by.id - equal, in - The allowed values are user IDs.
audited_time - between - Timestamp in ISO format.
source - equal, in - The allowed values are 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.
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?include_inner_details=field_history.data_type%2C%20field_history.field_label%2C%20field_history.enable_colour_code%2C%20field_history.pick_list_values%2C%20done_by.type__s%2C%20done_by.profile&sort_by=audited_time&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_by
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_record
The name and ID of the parent record which the task, call, or meeting belongs to.
- automation_details
Represents that the record was modified through an automation action such as a workflow.
- record
The name and ID of the task, call, or meeting that was created for the parent record.
- audited_time
The date and time at which the update on the record happened.
- action
The action that happened on the record. Some of the possible values are "added", "updated", "owner_assigned", "TaskAssigned", "RelListAssociation added".
- id
The unique ID of the action on the timeline.
- source
Represents from where the record was updated. The possible values are "crm_ui", "migration", "massupdate", "massaddtionviaui", "crm_api", "workflow".
- field_history
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
Reasons:
You have used disallowed comparators in the "filters" parameter.
You have not encoded the value of the filters parameter.
the ID of the record is invalid in the request URL.
Resolution:
Refer to the "filters" parameter in the "Parameters" section for the list of allowed comparators and the fields.
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
}
}