Skip to main content
GET
/
:projectId
/
api
/
v7
/
users
/
by-foreign-id
Fetch User by Foreign ID
curl --request GET \
  --url https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id
{
  "id": "<string>",
  "foreignId": {},
  "projectId": "<string>",
  "name": {},
  "username": {},
  "avatar": {},
  "bio": {},
  "metadata": {},
  "reputation": 123,
  "avatarFile": {},
  "bannerFile": {},
  "createdAt": "<string>"
}
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).

​
Query Parameters

​
foreignId
string
required
The external identifier from your system.
​
include
string
Comma-separated list of associations to include. Pass "files" to include the processed avatarFile and bannerFile objects.
​
createIfNotFound
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.
​
name
string
Display name to set when creating the user (createIfNotFound only).
​
username
string
Username to assign when creating the user (createIfNotFound only).
​
avatar
string
Avatar URL to set when creating the user (createIfNotFound only).
​
bio
string
Bio text to set when creating the user (createIfNotFound only).
​
metadata
string
JSON-encoded public metadata to set when creating the user (createIfNotFound only).
​
secureMetadata
string
JSON-encoded private metadata to set when creating the user (createIfNotFound only).

​
Space-scoped reputation

This endpoint has no space in context, so spaceReputationId accepts 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.
​
spaceReputationId
string
Adds spaceReputation to each returned user. Either a space <uuid> (that space’s bucket) or none (the project-general bucket). context, the empty string, and the legacy general / null aliases are rejected (400). Missing buckets read as 0.
​
spaceReputationDescendants
boolean
Only honored with an explicit space <uuid>. When true, spaceReputation is the subtree sum — the space plus all of its descendants. Ignored for none.

​
Response

Returns HTTP 200 (found) or 201 (created) with the user object:
​
id
string
Unique user ID (UUID).
​
foreignId
string | null
The foreign ID you provided.
​
projectId
string
Project this user belongs to.
​
name
string | null
Display name.
​
username
string | null
Unique username within the project.
​
avatar
string | null
Avatar image URL.
​
bio
string | null
Short bio text.
​
metadata
object | null
Public custom key-value data.
​
reputation
number
Reputation score.
​
avatarFile
object | null
Processed avatar image with variants. Only present when include=files is requested.
​
bannerFile
object | null
Processed banner image with variants. Only present when include=files is requested.
​
createdAt
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

{
  "error": "User not found",
  "code": "user/not-found"
}

{
  "error": "...",
  "code": "user/invalid-query"
}

​
See Also