---
updatedAt: 2026-01-09T21:03:28.000Z
agentTools:
  projectIndex: https://developers.heap.io/llms.txt
---

# Add User Properties

This API allows you to attach custom properties to any identified users from your servers, such as Sign Up Date (in [ISO8601 format](https://help.heap.io/heap-administration/administration-faqs/what-format-do-i-use-to-send-time-as-a-data-type-into-heap/)), Total # Transactions Completed, or Total Dollars Spent.<br><br>Note that Heap will create a new property if it doesn’t already exist, and will overwrite the previous property if one already exists with the same name. If the identity does not exist in Heap, Heap will create it as a user but with no events. Once events come to the user with the same Identity, the two will be merged under one user profile.<br><br>Currently, `heap.AddUserProperties` calls cannot be named all casings of id (ID,Id,iD,id) as it clashes with internal variables.<br><br>Our Looker Actions integration allows you to quickly import property data into Heap. See the  [Looker Actions Integration guide](https://help.heap.io/integrations/other/looker-actions-integration/) to learn more.  

> 🚧 If your Heap data is in an EU datacenter, the correct endpoint is:
>
> <https://c.eu.heap-api.com/api/add_user_properties> (**NOT** heapanalytics.com)

> 👍 Important
>
> If you want to write your user's email into the builtin Email property, you must send the key lowercase as per the example above.
>
> Sending an email value with a non-lowercase key will create a new property to store this data.

> 📘 FYI
>
> Requests are limited to 30 requests per 30 seconds per identity per app\_id

> ❗️ Limitations
>
> Please note: `fetch`, `jQuery`, and `XMLHttpRequest` options are not currently supported.

<HTMLBlock>{`
<div id="heapCustom">
  <strong>Did you find what you were looking for?</strong>
  <br>
  <a href="https://survey.nicereply.com/heap.api/docs/Add-User-Properties?s=10">
  <img alt="Thumb up" src="https://survey.nicereply.com/trackmaili/thumb_10.png">
  </a>
  <a href="https://survey.nicereply.com/heap.api/docs/Add-User-Properties?s=1">
    <img alt="Thumb down" src="https://survey.nicereply.com/trackmaili/thumb_1.png">
  </a>
</div>
`}</HTMLBlock>

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "server-side-api",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://heapanalytics.com/"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/api/add_user_properties": {
      "post": {
        "summary": "Add User Properties",
        "description": "This API allows you to attach custom properties to any identified users from your servers, such as Sign Up Date (in [ISO8601 format](https://help.heap.io/heap-administration/administration-faqs/what-format-do-i-use-to-send-time-as-a-data-type-into-heap/)), Total # Transactions Completed, or Total Dollars Spent. Note that Heap will create a new property if it doesn’t already exist, and will overwrite the previous property if one already exists with the same name.\n\nCurrently, `heap.AddUserProperties` calls cannot be named all casings of id (ID,Id,iD,id) as it clashes with internal variables.\n\nOur Looker Actions integration allows you to quickly import property data into Heap. See the  [Looker Actions Integration guide](https://help.heap.io/integrations/other/looker-actions-integration/) to learn more.",
        "operationId": "add-user-properties",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "app_id",
                  "identity"
                ],
                "properties": {
                  "app_id": {
                    "type": "string",
                    "description": "The environment ID of your Main Production project."
                  },
                  "identity": {
                    "type": "string",
                    "description": "An identity, typically corresponding to an existing user. If no such identity exists, then a new user will be created with that identity. Case-sensitive string, limited to 255 characters."
                  },
                  "properties": {
                    "type": "string",
                    "description": "An object with key-value properties you want associated with the user. Each key and property must either be a number or string with fewer than 1024 characters.",
                    "format": "json"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {}
                }
              }
            }
          }
        },
        "deprecated": false,
        "security": [],
        "x-readme": {
          "code-samples": [
            {
              "language": "curl",
              "code": "curl \\\n  -X POST \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"app_id\": \"11\",\n    \"identity\": \"bob@example.com\",\n    \"properties\": {\n      \"age\": \"25\",\n      \"language\": \"English\",\n      \"profession\": \"Scientist\",\n      \"email\": \"bob2@example2.com\"\n    }\n  }' \\\n  https://heapanalytics.com/api/add_user_properties"
            }
          ],
          "samples-languages": [
            "curl"
          ]
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```