Zoho crm Logo

获取记录

记录是一个实体，它存储了从各种来源获取的特定联系人或公司的所有综合信息。这些信息可能来自网页表单、社交媒体服务、广告等。记录API允许用户获取、创建、更新、删除或搜索记录。

目的

获取模块中可用记录的列表，或者通过其唯一记录ID获取特定记录的详细信息。

端点

  • GET /{module_api_name}
  • GET /{module_api_name}/{record_id}
  • {module_api_name} : API name of the module whose records you want to retrieve
  • {record_id} : 您想要获取的记录的唯一ID。

请求详情

Request URL

{api-domain}/crm/{version}/{module_api_name}

获取特定记录：
{api-domain}/crm/{version}/{module_api_name}/{record_id}

支持的模块

潜在客户，账户，联系人，交易，活动，任务，案例，事件，电话，解决方案，产品，供应商，价格书，报价，销售订单，采购订单，发票，自定义，预约，预约重新安排历史，服务和活动

自定义模块

对于自定义模块，请在请求URL中使用各自的API名称。您可以从设置 -> 开发者中心 -> APIs & SDKs -> API名称中获取API名称。您也可以从模块API的响应中的api_name键获取模块API名称。

头部

授权：Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

If-Modified-Since: 2019-07-25T15:26:49+05:30

范围

scope=ZohoCRM.modules.ALL
(或者)
scope=ZohoCRM.modules.{module_name}.{operation_type}

可能的模块名称

线索，账户，联系人，交易，活动，任务，案例，事件，电话，解决方案，产品，供应商，价格表，报价，销售订单，采购订单，发票，自定义，预约，预约重新安排历史，服务。

可能的操作类型

ALL - 对记录的完全访问
READ - 从模块获取记录

参数
  • fields字符串，获取所有记录时必填

    指定在获取记录时要检索的字段的API名称。请注意，此参数中最多可以包含50个字段API名称。使用GET - 字段元数据API 来检索模块中可用字段的列表。
    可能的值：多个字段API名称，以逗号分隔的格式。例如：Last_Name, Email。 

    注意：full_name字段包含First Name和Last Name字段的连接值。 
    这是一个只读字段，仅在Leads，Contacts和Users模块中可用。

  • cvidlong

    指定自定义视图ID以根据自定义视图获取记录列表。请注意，您不能将此参数与"sort_by"参数一起使用。您可以从自定义视图元API的响应中获取自定义视图id。
    可能的值：{custom_view_id}。

  • ids字符串，可选

    根据其唯一ID检索特定记录。
    可能的值： 记录的有效唯一ID。例如：4150868000001944196

  • per_page整数

    指定每页返回的记录数。默认值和可能的最大值是200。
    可能的值：仅正整数。

  • 页面整数

    获取相应页面的记录列表。默认值为1。请注意，您不能将此参数与"page_token"参数一起使用。
    可能的值：仅限正整数值。

  • page_token字符串，必须用于获取超过2000条记录的分页

    您可以使用"page"参数获取最多2000条记录，无需使用"page_token"。要获取超过2000条记录，您必须在请求中包含"page_token"参数。此参数从第一次获取记录调用的响应中的"next_page_token"键获取值。请注意，此令牌值是用户特定的。如果您使用其他用户的令牌，系统将抛出错误。
    请注意，您不能将此参数与"page"参数一起使用。

  • sort_order字符串

    根据"sort_by"参数的值，以升序或降序对可用的记录列表进行排序。
    可能的值： 

    • desc - 以降序显示记录。这是默认值。
    • asc - 以升序显示记录。
  • sort_by字符串

    根据字段id，Created_Time和Modified_Time对记录进行排序。默认值为'id'。请注意，您不能将此参数与"cvid"参数一起使用。

  • convertedstring

    获取已转换记录的列表。默认值为false。
    可能的值： 

    • false - 只获取未转换的记录。
    • true - 只获取已转换的记录。
    • both - 获取所有记录。
  • territory_idlong

    指定领土ID以获取属于特定领土的记录列表。您可以使用获取领土API来获取领土ID。
    可能的值：{territory_id}。

  • include_child布尔值

    包含子领域的记录。默认值是false。
    可能的值： 

    • false - 不包含子领域的记录。
    • true - 包含子领域的记录。

Note

  • "sort_order"适用于给定的"sort_by"字段。如果未提供"sort_by"参数，则它适用于系统定义的字段。
  • 如果您的需求是获取少于2000条记录，请使用"page"和"per_page"参数（page=1至10，per_page=200）。
  • 分页
    • 如果你想要为超过2000条记录进行分页，使用你在第一次响应中收到的"page_token"参数。你需要将从响应中收到的页面令牌与参数page=10一起传递，以获取从2001到2200的记录。如果还有更多的记录，API的响应中将会有"next_page_token"和"previous_page_token"，以便于分页。
      使用连续请求中的页面令牌，你可以导航并获取多达100,000条记录。
    • 键"page_token_expiry"包含next_page_token和previous_page_token过期的时间。
    • 请注意，在上述两种情况中，每个请求的最大记录数只会是200。
  • 在fields参数中使用键$approval_state来检索记录的审批状态。
  • 键Converted__s和Converted_Date_Time分别代表记录是否被转换，以及转换的日期和时间。
  • 字段Enrich_Status__s和Last_Enriched_Time__s已添加到数据丰富模块中。
  • 只有在获取特定记录时，您才能在响应中获取子表单记录、多选查找字段和多用户查找字段的值。
  • 响应中的$has_more JSON对象渲染模块中的子表单、多选查找字段和多用户查找字段的API名称，并使用布尔值来指示这些字段在模块中是否有更多的记录。只有在获取特定记录时，此键才会在响应中呈现。
  • 只有在从库存模块之一获取特定记录时，响应将包含以下子表单：
    • Quoted_Items（用于报价）
    • Invoiced_Items（用于发票）
    • Ordered_Items（用于销售订单）
    • Purchased_Items（用于采购订单）
  • 使用fields参数中的$event_cancelled键来获取会议的取消状态。响应中的$event_cancelled键代表会议的取消状态。
  • 要获取您的组织启用的领土列表，请参考领土API。领土仅支持交易，联系人和账户模块。
  • 只有管理员用户可以从Notes模块获取记录。当非管理员用户尝试从Notes模块获取记录时，系统会抛出错误。
  • 只有在合规设置中禁用了通过API限制数据访问选项时，才会检索到包含敏感健康数据的字段的值。如果启用了该选项，值将为null。有关更多详细信息，请参阅HIPAA合规性。
  • 在 Get Records API 的响应中，富文本字段被截断，仅显示前500个字符。使用富文本字段 API来检索富文本字段的完整内容。

样本请求：第一个API调用

对第一个API调用的响应

可能的错误

  • INVALID_MODULEHTTP 400

    给出的模块名称无效。
    解决方案：指定一个有效的模块API名称。请参考上面的可能模块部分。

  • INVALID_MODULEHTTP 400

    给定的模块在API中不受支持。
    解决方案：当前API不支持诸如文档和项目等模块。（一旦这些模块得到支持，此错误将不会显示）。请指定一个有效的模块API名称。请参考上述可能的模块部分。

  • INVALID_MODULEHTTP 400

    给定模块不支持区域。
    解决方案：给定模块不支持区域。区域只支持Deals，Contacts和Accounts模块。

  • TOKEN_BOUND_DATA_MISMATCHHTTP 400

    给出的page_token似乎无效，或者输入参数被添加、修改或删除。
    解决方案： page_token与请求中使用的参数绑定。不要更改参数，并使用旧的page_token。

  • INVALID_DATAHTTP 400

    您在"cvid"参数中使用了不支持的字段。
    解决方案：响应中的"details"键提供了您可以在cvid参数中使用的支持字段。只通过这些字段进行筛选。

  • REQUIRED_PARAM_MISSINGHTTP 400

    缺少预期的参数之一。
    解决方案：响应中的 "details" 键提供了请求中缺少的参数。确保在 "Parameters" 部分中包含标记为 "mandatory" 的参数。

  • LIMIT_EXCEEDEDHTTP 400

    字段限制超出。
    解决方案：在"fields"参数中，你只能包含最多50个字段API名称。

  • INVALID_DATAHTTP 400

    给出的令牌似乎无效。您使用了无效的page_token或者由其他用户生成的page_token。
    解决方案： page_token是用户特定的。只使用为您生成的。

  • EXPIRED_VALUEHTTP 400

    给定的令牌已过期。
    解决方案： page_token仅在生成后的24小时内有效。

  • DISCRETE_PAGINATION_LIMIT_EXCEEDEDHTTP 400

    你只能在不使用page_token参数的情况下获取前2000条记录。
    解决方案：如果你想获取超过2000条记录，你必须使用"page_token"参数。

  • AMBIGUITY_DURING_PROCESSINGHTTP 400

    您不能同时使用cvid和sort_by，以及page和page_token
    解决方案：您不能在自定义视图中对记录进行排序。在请求中使用“cvid”或“sort_by”参数。同样，在请求中使用“page”或“page_token”。

  • PAGINATION_LIMIT_EXCEEDEDHTTP 400

    您只能使用page_token参数获取最多100000条记录。
    解决方案：您可以在获取记录API中使用page_token参数获取最多100,000条记录。

  • NO_PERMISSIONHTTP 403

    拒绝读取记录的权限
    解决方案：用户没有读取记录的权限。请联系您的系统管理员。

  • NOT_SUPPORTEDHTTP 403

    此API仅支持管理员用户。
    解决方案：只有管理员用户可以从Notes模块获取记录。

样本请求：使用 "page_token" 进行第二次 API 调用

对第二个API调用的响应

获取特定记录的示例响应