使用外部 ID 插入或更新记录
目的
通过外部字段更新模块中的现有记录或插入新记录。
请求详情
请求 URL
https://www.zohoapis.com/crm/{version}/{module_api_name}/upsert
支持的模块
潜在客户、Account、联系人、交易、活动、案件、解决方案、产品、Vendors、价目表、报价单、SalesOrders、采购Orders、Invoices、预约、服务和自定义。
可能的操作类型
标题
授权:Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
范围
scope=ZohoCRM.modules.all
(或)
scope=ZohoCRM.modules.{module_name}.{operation_type}
可能的模块名称
线索,账户,联系人,交易,活动,案例,解决方案,产品,供应商,价格表,报价,销售订单,采购订单,发票,自定义,约会,服务和备注
可能的操作类型
ALL - 完全访问该记录
WRITE - Edit该模块中的记录
CREATE - 在该模块中创建记录
当外部值唯一时插入或更新记录
让我们以联系人模块中的插入或更新(upsert)请求为例。当外部字段的值是唯一的,并且其他重复字段已被检查时,系统会插入该联系人。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/upsert"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Last_Name": "Boyle",
"External_Contact_ID": "Boyle1"
}
]
}通过外部值进行记录更新或插入
当您在请求中传递外部值时,如果该外部值在模块的记录中已存在,系统会用输入中的其他详情更新该记录。否则,系统将在该模块中插入一条新的记录。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/upsert"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Last_Name": "Boyle P",
"External_Contact_ID": "Boyle1",
"Email": "p.boyle@abc.com"
}
]
}示例回复
Copied{
"data": [
{
"code": "SUCCESS",
"duplicate_field": "External_Contact_ID",
"action": "update",
"details": {
"Modified_Time": "2019-12-23T16:39:18+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-23T16:39:18+05:30",
"id": "111111000000157039",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}使用系统定义的重复检查字段进行外部字段的插入或更新(Upsert)
在此示例中,一个新的外部值被传递给联系人模块中的外部字段External_Contact_ID。此时,系统会检查系统定义的重复检查字段“Email”。如果该EmailID已存在于某个联系人中,系统会使用外部字段的新值来更新该联系人。
基于组织的外部ID字段的重复检查
假设在联系人模块中有一个外部字段“External_Campaign_ID”,存储来自第三方应用的活动值。用户1在联系人模块中创建一条记录,并将该外部字段的值设置为“Camp_MailChimp_1”。此时,当用户2尝试用相同的外部字段值创建记录时,系统会抛出DUPLICATE_DATA(重复数据)错误。
基于用户的外部ID字段的重复检查
假设联系人模块中有一个外部字段“External_Contact_ID”。用户1创建一条记录,其该字段的值为“Contact1”。当同一用户以此外部字段进行upsert操作时,系统会检查是否有用户1创建的记录包含外部字段值“Contact1”。如果有匹配的记录,系统则更新该记录;如果没有匹配记录,系统就会用给定数据创建一条新记录。
- 在使用upsert API时,无需提供X-EXTERNAL头信息,因为系统会将外部字段视为唯一字段,并据此执行重复检查。
示例请求
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/upsert"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@sample.json"示例输入
Copied{
"data": [
{
"Last_Name": "Boyle P",
"External_Contact_ID": "Boyle123",
"Email": "p.boyle@abc.com"
}
]
}示例回复
Copied{
"data": [
{
"code": "SUCCESS",
"duplicate_field": "Email",
"action": "update",
"details": {
"Modified_Time": "2019-12-23T16:39:18+05:30",
"Modified_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
},
"Created_Time": "2019-12-23T16:39:18+05:30",
"id": "111111000000157040",
"Created_By": {
"name": "Patricia Boyle",
"id": "111111000000044700"
}
},
"message": "record updated",
"status": "success"
}
]
}