Fetch User by Foreign ID

curl --request GET \
  --url https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id

const options = {method: 'GET'};

fetch('https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "id": "<string>",
  "foreignId": {},
  "projectId": "<string>",
  "name": {},
  "username": {},
  "avatar": {},
  "bio": {},
  "metadata": {},
  "reputation": 123,
  "avatarFile": {},
  "bannerFile": {},
  "createdAt": "<string>"
}

GET

:projectId

api

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

const options = {method: 'GET'};

fetch('https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.sublay.io/api/v6/:projectId/api/v7/users/by-foreign-id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

{
  "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

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 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.

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.

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:

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

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

Invalid Query — 400

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

Overview

Auth Endpoints

OAuth Endpoints

User Endpoints

User Follow Operations

User Connection Operations

Follow Endpoints

Connection Endpoints

Entity Endpoints

Comment Endpoints

Chat — Conversations

Chat — Members

Chat — Messages

Collection Endpoints

App Notification Endpoints

Push Notification Endpoints

Report Endpoints

Search Endpoints

Space Endpoints

Space — Membership

Space — Rules

Space — Moderation

Space — Chat

Event Endpoints

Storage Endpoints

Utils

Crypto

Fetch User by Foreign ID

Query Parameters

Space-scoped reputation

Response

Error Responses

See Also

​Query Parameters

​Space-scoped reputation

​Response

​Error Responses

​See Also

Query Parameters

Space-scoped reputation

Response

Error Responses

See Also