--- title: "Create a user" method: POST path: "/user" tags: ["Users"] --- # Create a user `POST /user` Creates a user. ## Headers - `Accept` 'application/vnd.Creative Force.v2.3+json' | 'application/vnd.Creative Force.v2.3+xml', required ## Request body - union - object - `first_name` string, required — User's first name. - `last_name` string, required — User's last name. - `password` string, required — Password for the new user. The minimum length and complexity requirements are configured per account, so a value accepted on one account may be rejected on another. - `email` string, email, required — User's email address. Required if `mobile` is not set. - `mobile` string — User's mobile number in E.164 international format, such as `+14155552671`. Required if `email` is not set. - `roles` string[] — Role slugs to assign to the user. If omitted or empty, the default role for the account is assigned instead, so the user is never left without a role. - `preferences` object — User notification preferences. - `broadcast_emails` boolean — Specifies whether the user receives broadcast emails. - `notification_emails` boolean — Specifies whether the user receives notification emails. - `notification_sms` boolean — Specifies whether the user receives notification text messages. - `user_fields` object — User field values, keyed by field slug. For example, `{ "fJkIjGmB": "Test value" }`. Single-value fields take a string; multi-value fields, such as checkbox or multi-select, take an array of strings. - object - `first_name` string, required — User's first name. - `last_name` string, required — User's last name. - `password` string, required — Password for the new user. The minimum length and complexity requirements are configured per account, so a value accepted on one account may be rejected on another. - `email` string, email — User's email address. Required if `mobile` is not set. - `mobile` string, required — User's mobile number in E.164 international format, such as `+14155552671`. Required if `email` is not set. - `roles` string[] — Role slugs to assign to the user. If omitted or empty, the default role for the account is assigned instead, so the user is never left without a role. - `preferences` object — User notification preferences. - `broadcast_emails` boolean — Specifies whether the user receives broadcast emails. - `notification_emails` boolean — Specifies whether the user receives notification emails. - `notification_sms` boolean — Specifies whether the user receives notification text messages. - `user_fields` object — User field values, keyed by field slug. For example, `{ "fJkIjGmB": "Test value" }`. Single-value fields take a string; multi-value fields, such as checkbox or multi-select, take an array of strings. ## Response `201` User created, or an existing user added to the account. Two outcomes share this status code: - **New user** — a new user record is created. The body is the full user resource and the `Location` header links to it. - **Existing user** — the email or mobile already belongs to a user on another account, so that user is added to the current account instead. The body is a confirmation message and no `Location` header is returned. - union - User — Detailed user fields returned only for a single user. - `analytics_cookies` boolean — Specifies whether the user accepted analytics cookies. - `broadcast_emails` boolean — Specifies whether the user accepted broadcast emails. - `comments` string — Administrative notes recorded against the user, formatted for export. - `confirmation` string — Account confirmation status of the user, such as `Confirmed` or `Invited`. - `confirmed_at` string, date-time, nullable — Date and time when the user confirmed the account. Value is `null` for an invited user who has not yet confirmed. - `created_at` string, date-time — Date and time when the user account was created. - `created_by` string — Method by which the user account was created, such as `manual` or `registration`. - `email` string, email, nullable — Email address of the user. Value is `null` when no email address is recorded. - `first_name` string — First name of the user. - `language` object — Preferred language of the user. - `code` string — Locale code of the language, such as `en_GB`. - `language` string — Display name of the language, such as `English (United Kingdom)`. - `last_name` string — Last name of the user. - `marketing_cookies` boolean — Specifies whether the user accepted marketing cookies. - `mobile` string — Mobile phone number of the user. - `name` string — Full name of the user. - `necessary_cookies` boolean — Specifies whether the user accepted necessary cookies. - `notification_emails` boolean — Specifies whether the user accepted notification emails. - `notification_sms` boolean — Specifies whether the user accepted notification text messages. - `roles` object[] — Roles assigned to the user within the account. - `slug` string — URL-safe identifier of the role. - `link` string, uri — URL of the role resource. - `name` object — Name of the role. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. - `slug` string — URL-safe identifier of the user. - `updated` string, date-time — Date and time when the user account was last updated. - `preferences` object — Notification preferences selected by the user. - `broadcast_emails` boolean — Specifies whether the user receives broadcast emails. - `notification_emails` boolean — Specifies whether the user receives notification emails. - `notification_sms` boolean — Specifies whether the user receives notification text messages. - `social_sharing` boolean — Specifies whether the user opted in to social sharing. - `user_fields` object[] — Custom field responses captured on the user profile. - `slug` string — URL-safe identifier of the field. - `link` string, uri — URL of the field resource. - `label` object — Label of the field. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. - `title` object — Plain-text title of the field. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. - `value` string — Value submitted for the field. - `token` string — File token for the uploaded file, present on file fields. - `translated` object — Translated value of the field. Map keyed by locale code (for example, `en_GB` or `fr_FR`). Keys are drawn from the languages enabled on the account. Values are the translated string. - object — Confirmation returned when an existing user is added to the account. - `message` string — Confirmation that an existing user was added to the account. ## Other responses - `400` — Request was rejected before the endpoint could process it. Common causes: invalid `Accept` header, unsupported `x-api-language` code, empty request body on `POST` / `PUT`, invalid JSON in the request body, or an invalid slug format in a path parameter. - `401` — Missing `x-api-key` header. - `403` — Authenticated request denied. Common causes: invalid or unknown API key, suspended account, or `api` feature not enabled for the account. - `422` — Request was syntactically valid but could not be processed. Returned in two scenarios: - **Field-level validation failure** — one or more request fields violated the endpoint's validation rules. The body includes an `errors` map keyed by field name with one or more validation messages each. - **Resource-state precondition failure** — the request fields were all valid, but the target resource was in a state that does not permit the requested operation. The body carries only `message` and `status_code`; no `errors` map. - `429` — Rate limit of 60 requests per minute exceeded. - `503` — Service is temporarily unavailable due to regional maintenance. ## Changes - **2026-07-07** (v2) `9b9103538ceb` — 2 info - api tag `Users` added - api tag `User` removed - **2026-07-01** (v2) `e96a96d4507e` — 7 info - added the media type `application/xml` for the response with the status `201` - added the media type `application/xml` for the response with the status `400` - added the media type `application/xml` for the response with the status `401` - added the media type `application/xml` for the response with the status `403` - …3 more - **2026-06-29** (v2) `afd0f985b088` — 1 breaking, 8 info - added `#/components/schemas/User, subschema #2` to the response body `oneOf` list for the response status `201` - request property `user_fields/additionalProperties/` list-of-types was widened by adding types `array` to media type `application/json` - removed `#/components/schemas/UserSummary, #/components/schemas/UserDetail` from the response body `allOf` list for the response status `201` - added the non-success response with the status `400` - …5 more [Change history](https://skmtc.dev/tectonic/apis/award-force-api/changes/user/post.md) --- [API](https://skmtc.dev/tectonic/apis/award-force-api.md) · [All operations](https://skmtc.dev/tectonic/apis/award-force-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tectonic/award-force-api/revisions/e2511e46f9f2/schema)