---
title: Create or update user
full: true
_openapi:
  method: PUT
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Create a new user or update an existing user by external ID (upsert
          operation).


          - If the user doesn't exist, they will be created with the provided
          attributes.

          - If the user exists, their attributes will be updated (merge
          behavior).

          - `custom_fields` are deep-merged with existing values.


          **Returns:**

          - `201 Created` when a new user is created

          - `200 OK` when an existing user is updated
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Create a new user or update an existing user by external ID (upsert operation).

- If the user doesn't exist, they will be created with the provided attributes.
- If the user exists, their attributes will be updated (merge behavior).
- `custom_fields` are deep-merged with existing values.

**Returns:**
- `201 Created` when a new user is created
- `200 OK` when an existing user is updated


<APIPage document={"./openapi-admin.json"} operations={[{"path":"/users/{user_external_id}","method":"put"}]} />