Heap user-property updates flag reserved id keys.

Heap reserves id, ID, Id and iD for internal variables. Advice identifies each immediate properties key in single and bulk user updates, with a target pointing to the submitted row.

Custom property names and account-property IDs keep their separate contracts. The source permits differently cased Email keys as custom properties, so those names are left open. Account state and receiver acceptance require external evidence.

What this pack matches

Hosts: heapanalytics.com, c.eu.heap-api.com
Paths: /api/add_user_properties
Vendor docs: developers.heap.io/reference/add-user-properties

Rules

Codes are stable. A finding in CI, MCP, or the playground lands on the same id.

Field	Required	What it checks	Rule ids	Source
`app_id`	required	It is the Heap environment ID. Heap documents it as required. Native JSON type: string. Fix: Set app_id to the environment ID from Heap Projects.	`vendor.heap-user-properties.body.app_id.missing` `vendor.heap-user-properties.body.app_id.empty` `vendor.heap-user-properties.body.app_id.invalid`	docs
`users`	optional	Native JSON type: array. Maximum array items: 1000.	`vendor.heap-user-properties.body.users.invalid`	docs
`users[]`	optional	Native JSON type: object.	`vendor.heap-user-properties.body.users[].invalid`	docs
`root`	optional	Native JSON type: object.	`vendor.heap-user-properties.body.root.invalid`	docs
`identity`	required	It is the known identity. Heap documents it as required. The server API cannot attach properties to an anonymous Heap user_id. Body scope: ["users[]",""]. Native JSON type: string. Maximum decoded characters: 255. Fix: Send the same identity you use in Heap Identify.	`vendor.heap-user-properties.body.identity.missing` `vendor.heap-user-properties.body.identity.empty` `vendor.heap-user-properties.body.identity.invalid`	docs
`properties`	recommended	It is the trait object. Heap documents keys and values as strings or numbers, fewer than 1024 characters. The builtin Email property is the lowercase key email. Body scope: ["users[]",""]. Native JSON type: object. Fix: Send a properties object. Use the key email, lowercase, for Heap's builtin Email property.	`vendor.heap-user-properties.body.properties.missing` `vendor.heap-user-properties.body.properties.invalid`	docs
`property_value…`	optional	The vendor documents `property_value` in the request contract. Body scope: ["users[]",""]. Native JSON type: number or string. Maximum decoded characters: 1023.	`vendor.heap-user-properties.body.property_value.invalid`	docs
`root`	optional	The vendor documents `` in the request contract. Body scope: ["users[]",""]. Native JSON type: object.	`vendor.heap-user-properties.body.root.invalid`	docs
`overlong_property_names…`	forbidden	Property keys must have fewer than1024characters, counted afterJSONdecoding. Body scope: ["users[]",""]. Presence diagnostic severity: error.	`vendor.heap-user-properties.body.overlong_property_names.forbidden`	docs
`reserved_id_property…`	forbidden	The official Add User Properties guide reserves all casings of id for internal variables. This advice applies to immediate property keys in single and bulk updates, not substrings, nested keys or account properties. Body scope: ["users[]",""]. Presence diagnostic severity: warning. Fix: Rename this custom property. Keep the user identity in the top-level identity field.	`vendor.heap-user-properties.body.reserved_id_property.forbidden`	docs
`method`	required	This published ingestion operation uses HTTP POST. Complete HTTP capture contract. Native JSON type: string.	`vendor.heap-user-properties.http.method.missing` `vendor.heap-user-properties.http.method.empty` `vendor.heap-user-properties.http.method.invalid`	docs
`content_type`	recommended	Use a published request media type. Complete HTTP capture contract. Presence diagnostic severity: warning. Value diagnostic severity: warning. Native JSON type: string.	`vendor.heap-user-properties.http.content_type.missing` `vendor.heap-user-properties.http.content_type.empty` `vendor.heap-user-properties.http.content_type.invalid`	docs
`body`	required	The request body is a JSON object. Complete HTTP capture contract. Native JSON type: object.	`vendor.heap-user-properties.http.body.missing` `vendor.heap-user-properties.http.body.invalid`	docs

Validate a payload

pixellint validate json @payload.json --rulepack vendor/heap-user-properties

Try this failing payload in the playground. A Heap user update with a reserved ID property.

{
  "app_id": "123",
  "identity": "synthetic",
  "properties": {
    "ID": "synthetic"
  }
}

cargo install pixellint · npm install pixellint