Collect customer and link visitor / 采集客户信息并关联访客

Purpose and authorization

Create/update a customer from verified identity/profile data, then link its website visitor. Call from the website's trusted backend after verifying the submitted identities and ownership of the submitted visitor context. Use OAuth2 Authorization: Bearer <access_token> and JSON. Never place OAuth credentials in browser code. Both permissions are required: link el cdp behavior identity AND restful post el_cdp_api_customer_resource. Domain registration gates browser collection, not this authenticated server API.

Request contract

A non-empty object with exactly source=web, visitor_id, identifications, body; total body at most 8192 bytes. Identities: list of 1–20 non-empty string key/value pairs using configured identity definitions. body must be a non-empty object using configured customer-property IDs. Unknown profile properties are filtered by the shared Customer API; known invalid identity/property values return 400. session_id, request customer_id/customer_uuid, singular identification, and content_tag_ids are unsupported top-level fields. No public auto_merge/allow_empty switches: the service fixes automatic merging and empty-value overwrites to false. Profile values do not become verified identities merely by appearing in body.

Matching, conflict, and persistence

The existing Customer API matching rules decide create versus update; this is not a bind-existing-ID-only endpoint. A visitor already linked to a customer must provide verified identities that match that customer before any write. Missing match, unavailable customer, or a match to another customer returns 409; no automatic rebinding occurs. In particular, do not pass an unverified email/mobile merely to update the previously linked profile.
The visitor is locked for concurrent writes (bounded wait 10 seconds). SQL customer writes and final binding share a transaction; final binding failure rolls them back. This does not promise atomic rollback of external customer lifecycle integrations. The binding key (source,visitor_id) is durable across domains and raw-event cleanup; one customer can have multiple visitor links. Backend UUID checks prevent an old numeric customer ID from silently attaching to a different customer after an ID reset. Customer merging follows the normal merge-target resolution.

Event and profile lifecycle

A successful response confirms profile save and binding, not immediate event conversion. Prior raw events within retention, and later events with the same visitor, are converted asynchronously by Cron. Raw events are kept 30 days from receipt; bindings do not expire with them. Even linked-visitor events first enter the raw table. Anonymous event properties do not update customer profiles; subsequent verified calls to this endpoint do. Stored content-tag snapshots move to customer events; conversion does not trigger marketing automation.

Response and errors

HTTP 200 uses the standard {code:200,data:{...}} envelope: encoded customer_id, linked=true, plus the shared Customer API save result (is_new, new/conflicting identifications, merged_customer_ids). Errors use {code,message} and optional structured errors. 400 invalid input/profile; 401 missing/invalid authentication; 403 insufficient permission; 409 visitor association conflict/unavailable target; 413 more than 8 KiB; 429 configured global versioned-API concurrency protection; 500 unexpected failure, including a visitor-lock timeout. Framework-level media-type/JSON routing errors may be returned before the resource runs.

中文说明

用途与权限

由网站可信后端提交已验证的客户身份和资料，创建或更新客户并关联浏览器访客。必须验证身份及本次提交的访客上下文，使用 OAuth2 Bearer 与 JSON，不能在浏览器中放 OAuth 凭据。账号必须同时拥有 link el cdp behavior identity 和 restful post el_cdp_api_customer_resource 两项权限。网站域名登记用于浏览器采集入口，不作为此后端 API 的认证条件。

参数与匹配

顶层只接受 source=web、visitor_id、identifications、body，请求最多 8192 字节。身份列表 1–20 项，每项 key/value 为非空字符串并使用已配置的身份定义；body 是非空客户属性对象。未知客户属性由现有客户 API 过滤，已知身份/属性值无效返回 400。body 中的手机号、邮箱不会仅因提交而自动成为已验证身份。不支持 session_id、请求客户 ID/UUID、单数 identification、内容标签字段，也没有自动合并/空值覆盖选项；两项行为均固定关闭。
按现有客户 API 规则决定创建或更新。已绑定访客必须提交能匹配原客户的已验证身份；不能匹配、原客户不可用或匹配其他客户时，在写客户资料前返回 409，不自动换绑。访客并发写入使用锁，等待上限 10 秒；SQL 客户写入及最终关联在同一事务中，关联失败回滚 SQL，但不保证外部集成副作用跨系统回滚。

生命周期与返回

(source,visitor_id) 关联长期保留，可跨已登记网站；同一客户可有多个访客关联。服务内部保存客户 UUID 防止 ID 重用误关联，正常合并时解析当前目标客户。返回 200 只确认资料写入及关联成功，不代表历史事件已经转化。
历史保留期内的原始事件及后续同访客事件由 Cron 异步转成客户事件；原始事件按接收时间保留 30 天，关联不随其过期。已绑定访客的事件也先写原始表。匿名属性不自动写客户资料，后续资料更新仍须通过此可信 API。标签快照随事件转化，不触发营销自动流。
成功返回 code/data，包括编码 customer_id、linked=true 及现有客户保存结果。错误为 code/message，可含 errors。400 参数/资料无效；401 未认证；403 无权限；409 关联冲突/客户不可用；413 超过 8 KiB；429 系统配置的版本化 API 并发保护；500 未知错误或访客锁等待超时。媒体类型、JSON 解码等框架错误可能在资源入口前返回。

application/json

Bodyapplication/json

示例

{
  "code": 200,
  "data": {
    "customer_id": "example-encoded-customer-id",
    "linked": true,
    "is_new": true,
    "new_identifications": [
      {
        "key": "el_email",
        "value": "verified@example.invalid"
      }
    ],
    "conflict_identifications": [],
    "merged_customer_ids": []
  }
}

Collect customer and link visitor / 采集客户信息并关联访客

Purpose and authorization

Request contract

Matching, conflict, and persistence

Event and profile lifecycle

Response and errors

中文说明

用途与权限

参数与匹配

生命周期与返回

请求参数

请求示例代码

返回响应

Collect customer and link visitor / 采集客户信息并关联访客

Purpose and authorization#

Request contract#

Matching, conflict, and persistence#

Event and profile lifecycle#

Response and errors#

中文说明#

用途与权限#

参数与匹配#

生命周期与返回#

请求参数

请求示例代码

返回响应

Purpose and authorization

Request contract

Matching, conflict, and persistence

Event and profile lifecycle

Response and errors

中文说明

用途与权限

参数与匹配

生命周期与返回