---
title: "Create a new user or return existing user"
method: POST
path: "/v1/users"
tags: ["v1 users"]
---

# Create a new user or return existing user

`POST /v1/users`

Create a new user in the UPL system or return existing user.
    
    This endpoint:
    - Validates authentication tokens
    - Creates a new user with unique email OR returns existing user if email already exists
    - Returns user details upon successful creation or retrieval
    - Uses "create or get" pattern for idempotent behavior
    
    **Authentication**: Requires valid API key or JWT token in Authorization header

## Request body

- CreateUserRequest — Request model for user creation
  - `email` string, required — User's email address
  - `name` string, required — User's full name
  - `org_user_id` string, nullable — Organization-specific user ID
  - `persona_id` string, nullable — If provided, the new user is automatically linked to this persona (cloning its knowledge graph).

## Response `200`

Successful Response

- CreateUserResponse — Response model for user creation
  - `user_id` string, required — Generated user ID
  - `email` string, required — User's email address
  - `name` string, required — User's name
  - `org_user_id` string, nullable — Organization-specific user ID
  - `created_at` string, required — User creation timestamp
  - `success` boolean — Whether the user was created successfully

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `422` — Validation Error
- `500` — Internal Server Error

---

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