记录时间轴
目的
要获取记录的时间轴。响应会提供记录的历史,包括对其任何字段和相关记录所做的所有更新。
端点
- GET /{module_API_name}/{record_ID}/__timeline
请求详情
请求URL
{api-domain}/crm/{version}/{module_API_name}/{record_ID}/__timeline
支持的模块
潜在客户、联系人、账户、交易、任务、会议、电话、产品、服务、预约、采购订单、销售订单、报价、发票、备注、自定义
标题
授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
scope=ZohoCRM.modules.{module_name}.ALL
(或)
scope=ZohoCRM.modules.{module_name}.READ
参数
- per_page 整数,可选
您想要每页获取的记录数。此参数仅可用于首页。对于后续页面,必须使用 “page_token” 参数。
- page_token 字符串,必填
在进行分页并检索了 200 条记录后,指定 "next_page_token" 或 "previous_page_token"。请注意,如果请求中提供了 "page_token",则不能再提供 "per_page" 参数。
- include_timeline_type 字符串,可选
用于在 "timeline" 对象中包含额外类型。通过此参数,可以获取与信号相关的 "signals" 数据,从而获得与信号有关的时间线条目。
- 包含字符串,在指定 "include_timeline_type" 参数时为必填项
如果您希望通过信号或其他方式查看记录更新的详细信息,请使用此参数。可能的取值有 extension 和 type。例如,如果记录是通过信号进行更新的,则响应中会包含扩展部分的详细信息,如电子邮件分析(email insights),而更新类型为信号(signals)。
- include_inner_details 字符串, 可选
如果您希望在响应的 "field_history" 对象中获取记录更新的额外详细信息,请使用此参数。可用值有 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 - 提供已更新字段的数据类型的详细信息。
- field_history.field_label - 提供已更新字段标签的详细信息。
- field_history.pick_list_values - 表示选项列表可用的值。
- field_history.enable_colour_code - 表示该选项值是否启用了颜色编码。
- done_by.profile - 提供更新该记录的用户资料的详细信息。
- done_by.type__s - 提供修改该记录的用户类型信息,如门户用户或普通用户。
- 过滤器 JSON 对象 (已编码),可选
filters 参数用于根据特定条件过滤来自时间线 API 的响应。该参数包含三个组成部分,分别是 field(字段)、comparator(比较符)和 value(值),它们共同构成过滤时间线数据的条件。
该字段的 api_name 键可能的取值为 - record.module.api_name、source、audited_time 和 done_by.id。
record.module.api_name:您可以使用此参数筛选记录的备注、附件、任务、电话、活动和邮件的时间轴详情。
允许的比较符有 equal、in。允许的取值有 Notes(备注)、Attachments(附件)、Tasks(任务)、Calls(电话)、Events(活动)、Emails(邮件)。
例如:
筛选备注:
{"field":{"api_name":"record.module.api_name"},"comparator":"equal","value":"Notes"}
筛选备注和任务:
{"field":{"api_name":"record.module.api_name"},"comparator":"in","value":["Notes","Tasks"]}
done_by.id:您可以按特定用户筛选时间线详情。支持的比较符有equal(等于)、in(属于)。允许的取值为用户ID。
例如,按某个用户ID筛选时间线详情:
{"field":{"api_name":"done_by.id"},"comparator":"in","value":["5843104000000424001"]}
- audited_time:您可以根据审核时间筛选时间线数据。允许的比较符是 between(介于)。允许的取值为 ISO 8601 格式的时间。例如,要筛选两个日期之间的时间线详情:{"field":{"api_name":"audited_time"},"comparator":"between","value":["2023-10-25T00:00:00+12:00","2023-10-30T23:59:59+12:00"]}
source:您可以根据来源筛选时间线数据。允许的比较符有 equal,in。允许的取值包括: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":{"api_name":"source"},"comparator":"equal","value":"crm_ui"}
{"field":{"api_name":"source"},"comparator":"in","value":["crm_api","crm_ui"]}
您可以使用group_operator和group来组合多个条件。
{"group_operator":"AND","group":[{"field":{"api_name":"record.module.api_name"},"comparator":"in","value":["备注"]},{"field":{"api_name":"source"},"comparator":"in","value":["crm界面","crm接口"]}]}
您还可以参考示例请求以了解结构。请注意,您必须对该参数的值进行编码。
在示例请求中,filters={"comparator":"between","field":{"api_name":"audited_time"},"value":["2023-06-07T00:00:00+05:30","2023-06-07T12:59:59+05:30"]} 被编码为 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
您可以在我们的URL 编码/解码工具中使用“编码 URL/解码 URL”选项对该值进行编码。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/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"响应 JSON
- done_by
修改该记录的用户的详细信息,例如姓名、ID、该用户所属角色的名称和ID,以及用户类型。
- related_record
任务、电话或会议所属的父记录名称和ID。
- automation_details
表示该记录是通过自动化操作(如工作流)修改的。
- 记录
为父级记录创建的任务、呼叫或会议的名称和 ID。
- audited_time
记录被更新的日期和时间。
- 操作
在记录上发生的操作。一些可能的取值包括“已添加”、“已更新”、“所有者已分配”、“任务已分配”、“关联列表已添加”等。
- id
时间轴上该操作的唯一ID。
- 来源
表示记录是从哪里被更新的。可能的取值包括 "crm_ui"、"migration"、"mass_update"、"mass_addition_via_ui"、"crm_api"、"workflow" 等。
- field_history
包含以下详细信息。
- api_name - 被修改字段的 API 名称。该字段默认会出现在响应中。
- _value - 该字段的旧值和新值。该字段默认会出现在响应中。
- 当你指定 include_inner_details 参数时,响应中会包含以下值:
- enable_colour_code - 表示是否为选项列表字段启用了颜色编码。
- data_type - 被修改字段的数据类型。
- pick_list_values - 选项列表中各值的详细信息。
可能的错误
- NO_CONTENTHTTP 204
数据不可用或所应用的筛选条件下没有时间线。
解决方法:请修改筛选条件后重试。 - INVALID_DATAHTTP 400
原因:
- 您在“filters”参数中使用了不允许的比较符。
- 您未对filters参数的值进行编码。
- 请求URL中的记录ID无效。
解决方法:
- 请参考“参数”部分中的“filters”参数,查找允许的比较符和字段。
- 请指定有效的记录ID。参考获取记录 API获取记录ID。
- AMBIGUITY_DURING_PROCESSINGHTTP 400
您同时指定了“per_page”和“page_token”参数。
解决方法:导航时只能使用“page_token”参数。 - OAUTH_SCOPE_MISMATCH HTTP 401
您没有权限访问此API所需的Scope。
解决方法:请根据“Scopes”部分提到的Scope新建Token并重试此API。 - INTERNAL_SERVER_ERROR HTTP 500
服务器出现未处理或意外异常。
解决方法:请联系support@zohocrm.com寻求帮助。
示例响应
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
}
}