---
title: "Create or Update User Profile"
method: POST
path: "/users"
tags: ["Users"]
---

# Create or Update User Profile

`POST /users`

Keep track of who's talking to your AI by creating user profiles with contact information and custom properties.

Provide an `externalUserId` to identify the user—your ID from your own system. Don't worry about whether they already exist; we'll create them if they're new or update their profile if they already exist. This makes syncing user data effortless.

You can then reference this user in other API calls using the same `externalUserId`.

Optionally associate users with an organization by providing an `externalOrganizationId`. If the organization doesn't exist yet, we'll create it automatically.

## Request body

- CreateUserRequest — Request payload for creating a new user profile.
  - `externalUserId` string, required — Your unique identifier for the user. Use this same ID in other API calls to reference this user.
  - `organizationId` string, uuid — The Greenflash organization ID that the user belongs to.
  - `externalOrganizationId` string — Your unique identifier for the organization this user belongs to. If provided, the user will be associated with this organization.
  - `name` string — The user's full name.
  - `email` string, email — The user's email address.
  - `phone` string — The user's phone number.
  - `anonymized` boolean — Whether to anonymize the user's personal information. Defaults to false.
  - `properties` object — Additional data about the user (e.g., plan type, preferences).

## Response `200`

User profile created or updated successfully

- CreateUserResponse — Success response for user creation.
  - `success` boolean, required — Whether the API call was successful.
  - `participant` Participant, required — The user profile.
    - `id` string, required — The Greenflash participant ID.
    - `externalId` string, required — Your external user ID (matches the externalUserId from the request).
    - `organizationId` string, uuid, nullable, required — The internal organization ID that the user belongs to.
    - `externalOrganizationId` string, nullable, required — Your external identifier for the user's organization.
    - `name` string — The participant's full name.
    - `email` string — The participant's email address.
    - `phone` string — The participant's phone number.
    - `anonymized` boolean, required — Whether the participant's personal information is anonymized.
    - `properties` object, required — Additional data about the participant.
    - `createdAt` string, date-time — When the participant was first created.
    - `updatedAt` string, date-time — When the participant was last updated.

## Other responses

- `400` — Bad request - invalid input data
- `500` — Server error

## Changes

- **2025-11-24** `c1998d918478` — 2 breaking, 1 warning, 6 info
  - removed the required property `participant/metadata` from the response with the `200` status
  - removed the required property `participant/tenantId` from the response with the `200` status
  - removed the request property `metadata`
  - api tag `Users` added
  - …5 more
- **2025-10-09** `48adb6bfe01d` — 2 breaking
  - the `participant/createdAt` response's property type/format changed from `string`/`date` to `string`/`date-time` for status `200`
  - the `participant/updatedAt` response's property type/format changed from `string`/`date` to `string`/`date-time` for status `200`
- **2025-10-09** `e2ce5771d0c3` — 2 breaking
  - the response property `participant/createdAt` became optional for the status `200`
  - the response property `participant/updatedAt` became optional for the status `200`
- **2025-10-06** `8ac2a6f673ac` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/changes/users/post.md)

---

[API](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference.md) · [All operations](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenflash-ai/greenflash-api-reference/revisions/c566e560677d/schema)