Fetch User by Foreign ID
User Endpoints
Fetch User by Foreign ID
Look up a user by your own system’s external user ID
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-inspaceReputation 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 HTTP200 (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
User Not Found — 404
User Not Found — 404
Invalid Query — 400
Invalid Query — 400

