Skip to main content
Fetch User by Foreign ID
Finds a user within the project by their foreignId — the external identifier you provided when creating or syncing the user. Optionally creates the user if not found (requires service or master token).
If the profile owner has blocked the signed-in caller, this returns 404 — the same response as a user who does not exist. The reverse is not true: a user you have blocked stays visible, so you keep a way to find and unblock them. Requires the moderation bundle.

Query Parameters

string
required
The external identifier from your system.
string
Comma-separated list of associations to include. Pass "files" to include the processed avatarFile and bannerFile objects.
string
Set to "true" to create the user if they do not exist. Requires a service or master token. Returns 201 on creation, 200 on an existing user.
string
Display name to set when creating the user (createIfNotFound only).
string
Username to assign when creating the user (createIfNotFound only).
string
Avatar URL to set when creating the user (createIfNotFound only).
string
Bio text to set when creating the user (createIfNotFound only).
string
JSON-encoded public metadata to set when creating the user (createIfNotFound only).
string
JSON-encoded private metadata to set when creating the user (createIfNotFound only).

Space-scoped reputation

This endpoint has no space in context, so the opt-in spaceReputation object accepts a spaceId of a space <uuid> or none only — context is rejected (400). It adds a spaceReputation field to each returned user, alongside the always-present reputation total. Requires the reputation bundle. See the Reputation data model.

Response

Returns HTTP 200 (found) or 201 (created) with the user object:
string
Unique user ID (UUID).
string | null
The foreign ID you provided.
string
Project this user belongs to.
string | null
Display name.
string | null
Unique username within the project.
string | null
Avatar image URL.
string | null
Short bio text.
object | null
Public custom key-value data.
number
Reputation score.
object | null
Processed avatar image with variants. Only present when include=files is requested.
object | null
Processed banner image with variants. Only present when include=files is requested.
string
ISO timestamp of account creation.
createIfNotFound=true is only permitted with a service or master token. Client tokens receive a 404 if the user does not exist.

Error Responses

See Also