Zoho crm Logo

使用外部 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"
        }
    ]
}