---
title: "Create or replace an identified user"
method: PUT
path: "/users/{userId}"
tags: ["Users"]
---

# Create or replace an identified user

`PUT /users/{userId}`

## Request

- Base URL: `https://api.produktly.com/api/v1`
- URL: `https://api.produktly.com/api/v1/users/{userId}`
- Auth: HTTP bearer

Server-side equivalent of identifyUser() with replace semantics: creates the user if it doesn't exist (201), otherwise replaces its entire metadata object (200). Prefer PATCH for scheduled syncs so you don't clobber attributes set client-side.

## Path parameters

- `userId` string, required: The user's external ID — the same value you pass to window.Produktly.identifyUser(). URL-encode it.

## Request body

- object
  - `metadata` object, required: User attributes as a JSON object (nested values allowed, max 32 KB serialized). Replaces the entire stored metadata object.

## Response `200`

Replaced

- User
  - `userId` string, required
  - `metadata` object, nullable, required
  - `createdAt` string, date-time, required
  - `updatedAt` string, date-time, required

## Other responses

- `201`: Created
- `400`: Validation error
- `401`: Unauthorized
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/produktly/apis/produktly-api.md) · [All operations](https://skmtc.dev/produktly/apis/produktly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/produktly/apis/produktly-api/revisions/fd942a97a7d1?raw)