---
title: "Update user data"
method: POST
path: "/api/users/update"
tags: ["users"]
---

# Update user data

`POST /api/users/update`

Updates user data or adds a user if none exists. Data is merged - missing fields are not deleted. Please note there is a soft limit (default: 1,000) on the number of unique fields users can have. Types of data fields must match the types sent in previous requests, across all data fields in the project.<br/>Processing time varies based on the current load for Iterable's back-end services. To avoid race conditions, provide a buffer of at least 60 seconds between this request and subsequent dependent requests, such as <code>POST /api/email/target.</code><br/><br/>Learn about <a href="https://support.iterable.com/hc/articles/29156459027348">identifying users by <code>userId</code> and <code>email</code></a>.<br/><br/><b>Rate limit</b>: 500 requests/second, per project.

## Request body

- ApiUserUpdateRequest
  - `createNewFields` boolean — Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields.
  - `dataFields` object — Data to store on the user profile identified by <code>userId</code> or <code>email</code>.
  - `email` string — An email address that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.
  - `mergeNestedObjects` boolean — Merge top-level objects instead of overwriting them. Defaults to <code>false</code>. For example, if a user profile has data <code>{"mySettings":{"mobile":true}}</code> and the request has data <code>{"mySettings":{"email":true}}</code>, merging results in <code>{"mySettings":{"mobile":true,"email":true}}</code>.
  - `preferUserId` boolean — Whether or not a new user should be created if the request includes a <code>userId</code> that doesn't yet exist in the Iterable project. Defaults to <code>false</code>. Only respected in API calls for <a href="https://support.iterable.com/hc/articles/29156459027348">email-based projects</a>.
  - `userId` string — A user ID that identifies a user profile in Iterable. Provide an <code>email</code> or a <code>userId</code> (but not both), depending on <a href="https://support.iterable.com/hc/articles/29156459027348">how your project identifies users</a>.

## Response `200`

successful operation

## Other responses

- `400` — Invalid parameters
- `401` — Invalid API key
- `409` — Contact is GDPR forgotten<br/>Email/userId conflict
- `429` — Rate limit exceeded. Response includes <code>params</code> with:<br/><code>rateLimitLimit</code> — maximum token capacity (burst allowance)<br/><code>rateLimitRemaining</code> — tokens remaining after this request<br/><code>rateLimitReset</code> — seconds until enough tokens refill to retry

---

[API](https://skmtc.net/iterable/apis/iterable-api.md) · [All operations](https://skmtc.net/iterable/apis/iterable-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/iterable/iterable-api/revisions/afaab604b58c/schema)