如何通过Marketo REST API为线索记录自定义活动数据？

嘿，刚好我对Marketo的自定义活动API很熟，这就给你一步步讲清楚怎么操作，结合你已经创建好的TEST_ACTIVITY（ID:100001）来举例：

前提确认 #

首先确保你已经满足这些条件：

• 已经在Marketo门户成功创建了目标自定义活动（就是你给出的TEST_ACTIVITY，ID=100001）
• 你的API应用拥有activity_write权限（在Marketo门户的API角色里配置）
• 能获取到要关联的线索ID（可以通过创建线索API或查询线索API拿到）

核心API调用：创建自定义活动 #

你需要调用Marketo的Create Custom Activity端点，具体信息如下：

• 请求方法：POST
• 端点URL：/rest/v1/activities/custom.json（要加上你的Marketo实例域名前缀，比如https://xxx-xxx.mktorest.com/rest/v1/activities/custom.json）
• 认证方式：和创建线索的API一致，请求头携带Authorization: Bearer {你的Access Token}

请求体格式（适配你的自定义活动） #

根据你给出的自定义活动结构，请求体需要严格匹配属性定义，下面是完整的示例：

{
  "input": [
    {
      "leadId": 123456, // 替换为你要关联的真实线索ID
      "activityDate": "2024-05-20T14:30:00Z", // 活动发生时间，必须是ISO 8601带时区格式
      "activityTypeId": 100001, // 你的自定义活动ID，就是100001
      "primaryAttributeValue": "EVT-20240520-001", // 对应primaryAttribute的event_id值
      "attributes": [
        {
          "name": "email", // 建议用自定义活动里的apiName，避免名称变更影响
          "value": "customer@example.com"
        },
        {
          "name": "event_data",
          "value": "{\"event_type\":\"webinar\",\"attended\":true}" // 如果是复杂数据，转成JSON字符串
        }
      ]
    }
  ]
}

字段说明 #

• leadId: 必填，关联的线索唯一ID
• activityDate: 必填，活动发生的时间，格式必须是YYYY-MM-DDTHH:mm:ssZ（比如UTC时间）
• activityTypeId: 必填，你自定义活动的ID（100001）
• primaryAttributeValue: 必填，对应自定义活动中primaryAttribute（event_id）的取值
• attributes: 可选，对应自定义活动中的其他属性，每个子对象的name要和活动定义里的apiName完全一致，value要匹配对应的数据类型（比如email类型传合法邮箱字符串）

批量处理支持 #

如果要给多个线索记录相同或不同的自定义活动，只需要在input数组中添加多个活动对象即可，比如：

{
  "input": [
    {
      "leadId": 123456,
      "activityDate": "2024-05-20T14:30:00Z",
      "activityTypeId": 100001,
      "primaryAttributeValue": "EVT-20240520-001",
      "attributes": [{"name":"email","value":"customer1@example.com"}]
    },
    {
      "leadId": 789012,
      "activityDate": "2024-05-20T15:00:00Z",
      "activityTypeId": 100001,
      "primaryAttributeValue": "EVT-20240520-002",
      "attributes": [{"name":"email","value":"customer2@example.com"}]
    }
  ]
}

成功响应示例 #

调用成功后，你会收到类似这样的响应：

{
  "requestId": "7a6b8c9d-1234-5678-90ab-cdef12345678",
  "result": [
    {
      "id": 987654, // 生成的自定义活动记录ID
      "status": "success"
    }
  ],
  "success": true
}

常见注意事项 #

• 权限问题：如果返回403 Forbidden，检查API角色是否添加了activity_write权限
• 字段匹配：activityTypeId和属性的name（apiName）必须和门户里的定义完全一致，大小写敏感
• 数据类型：属性值要匹配定义的dataType，比如email类型不能传非邮箱字符串，否则会报错
• 时间格式：activityDate必须是合法的ISO 8601格式，否则会返回验证错误

内容的提问来源于stack exchange，提问作者Amber More