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

# Bulk update user data

`POST /api/users/bulkUpdate`

Bulk updates user data. This endpoint adds and overwrites user profile fields as needed. It does not modify top-level fields omitted from the request body. <br/><br/>If you'd like to merge (rather than overwrite) a user profile's top-level objects with the values provided for them in the request body, set <code>mergeNestedObjects</code> to <code>true</code>.<br/><br/>When updating an existing field, you cannot change its data type (the new value must have the same data type as the old value).<br/><br/>When adding a new field, remember that each project has a soft limit of 1,000 unique user profile fields (across all its users, with a field's uniqueness determined by its name and position on the user profile). <br/><br/>Iterable handles requests to this endpoint separately from requests to single-user endpoints (<code>update</code>, <code>updateEmail</code>, <code>updateSubscriptions</code>, etc.). For a given user, in a short period of time, only use single-user calls or bulk update calls. Otherwise, results may be inconsistent.<br/><br/>When updating the <code>emailListIds</code> field, this endpoint does not generate subscribe or unsubscribe events. The same is true for updates to <code>unsubscribedChannelIds</code> and <code>unsubscribedMessageTypeIds</code> (but these can only be updated by this endpoint in projects where the opt-in message types feature is not enabled).<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>Max size of request body</b>: 4MB<br/><b>Rate limit</b>: 5 requests/second, per project

## Request body

- BulkUpdateUsersRequest
  - `createNewFields` boolean — Whether new fields should be ingested and added to the schema. Defaults to project's setting to allow or drop unrecognized fields. Added fields will be included in the response's <code>createdFields</code>. Dropped fields will be included in <code>filteredOutFields</code> and not added to user profiles.
  - `users` OptionalApiUser[], required
    - `dataFields` object
    - `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
- `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)