fix(backend): Update params and documention on createUser

[dmoerner]

Add the optional emailAddressIdentificationStatus and phoneNumberIdentificationStatus parameters to CreateUserParams. The Backend API has supported these arrays on POST /v1/users since they shipped, but createUser() had no way to pass them, so every email address and phone number was necessarily created verified. Each array runs parallel to emailAddress / phoneNumber — one item per identifier, applied by position — and an item set to 'reserved' creates that identifier unverified but still usable for sign-in and locked so no other user can claim it.

The createUser() documentation is corrected accordingly: it stated unconditionally that created email addresses and phone numbers are automatically verified, which is only the default.

Description

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

[changeset-bot]

🦋 Changeset detected

Latest commit: 6754033

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@clerk/backend	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Jul 31, 2026 5:01pm
swingset	Ready	Preview	Jul 31, 2026 5:01pm

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@9305

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@9305

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@9305

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@9305

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@9305

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@9305

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@9305

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@9305

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9305

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@9305

@clerk/express

npm i https://pkg.pr.new/@clerk/express@9305

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@9305

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@9305

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@9305

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@9305

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@9305

@clerk/react

npm i https://pkg.pr.new/@clerk/react@9305

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@9305

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@9305

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@9305

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@9305

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@9305

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@9305

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@9305

commit: 6754033

[github-actions]

API Changes Report

Generated by Break Check on 2026-07-31T17:02:38.529Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on 6754033.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The backend CreateUserParams contract now supports optional positional identification status arrays for email addresses and phone numbers. Each value can be created as verified or reserved. The createUser documentation and backend changeset describe the new parameters and reserved-contact behavior. Documentation no longer states that all email addresses and phone numbers are always automatically verified.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested reviewers: alexisintech

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the backend parameter and documentation updates for createUser().
Description check	✅ Passed	The description accurately explains the new status parameters, positional behavior, reserved identifiers, and documentation correction.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

packages/backend/src/api/endpoints/UserApi.ts (1)

239-239: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Add request-body coverage for both status arrays.

The existing createUser() test path does not send either new field or inspect the request body. Add a test with mixed 'verified' and 'reserved' values. Assert that both arrays and their positional order are preserved.

Also applies to: 243-243

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/backend/src/api/endpoints/UserApi.ts` at line 239, Add request-body
coverage in the existing createUser() test path for both new status-array
fields, supplying mixed 'verified' and 'reserved' values. Capture or inspect the
outgoing request body and assert that each array is present with its values
preserved in the original positional order.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@packages/backend/src/api/endpoints/UserApi.ts`:
- Line 239: Add request-body coverage in the existing createUser() test path for
both new status-array fields, supplying mixed 'verified' and 'reserved' values.
Capture or inspect the outgoing request body and assert that each array is
present with its values preserved in the original positional order.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: da20e0b8-caec-4806-acf1-7778b2aa5fb5

📥 Commits

Reviewing files that changed from the base of the PR and between 38f347c and e3525bd.

📒 Files selected for processing (2)

• .changeset/backend-create-user-identification-status.md
• packages/backend/src/api/endpoints/UserApi.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual)
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)
• clerk/clerk-ios (auto-detected)
• clerk/clerk-android (auto-detected)
• clerk/cli (auto-detected)

[wobsoriano]

👍🏼