User lookup

Overview

There are two methods available for retrieving a user:

• Fetch a user by their Zealy ID.

• Retrieve a user through the IDs or handles of third-party accounts they have linked to Zealy, such as Discord, Twitter, wallet, and email.

The User object

---

id - String

Zealy ID of the user

---

name - String

Zealy username of the user

---

avatar - String

URL of the user's avatar.

---

discordHandle - String

Discord handle of the user

---

tiktokUsername - String

Tiktok username of the user

---

xp - Number

XP of the user in the community

---

level - Number

Level of the user in the community

---

rank - Number

Rank of the user in the all time leaderboard.

---

banReason - String

If the user is banned, the reason that was given by the admin for the ban

---

isBanned - Boolean

Equals `true` if the user is banned

---

Invites - Array of objects

Lists of the user invite with their respective statuses.

An invite can be in one of three states:

• Active: The invite is valid and can be used to claim a quest.

• Pending: The invite is not yet active because the invited user hasn't reached the minimum required XP for it to be valid. This minimum XP requirement is determined by the community's settings.

• Consumed: The invite has been used to claim a quest and cannot be used again.

---

connectedWallet - String

This field holds the address of the wallet the user connected to Zealy.

---

verifiedBlockchainAddresses - Object

This field contains addresses users have added using wallet connection, so we know they belong to them

---

unVerifiedBlockchainAddresses - Object

This field contains addresses users add themselves to their profiles, but we can't confirm these belong to them.

---

referrerId - String

Zealy ID of the user that invited the requested user to the community.

---

referrerUrl - String

The URL of the website the user came from when he joined the community.

---

karma - Number

Karma is a measure that reflects a community member's value. Users gain karma when their contributions are recognized with a star and lose karma if their contributions are flagged.

---

role - Enum

The role of the user in the community. The possible values are : admin, editor, reviewer, guest and banned.

---

updatedAt - String

ISO timestamp that indicates the most recent date and time when the user's information was updated.

---

createdAt - String

ISO timestamp that indicates the creation date and time of the user.

---

deletedAt - String

ISO timestamp that indicate when the user's account was deleted, if applicable

---

restoredAt - String

If the user's account was previously deleted and then restored, this field captures the date and time of the restoration.

API Reference

Get information about a user

get

Path parameters

subdomainstringRequired

userIdstring · uuidRequired

Header parameters

x-api-keystringRequired

Responses

200

200

application/json

idstringRequired

avatarstring · nullableRequired

connectedWalletstring · nullableRequired

namestring · nullableRequired

emailstring · nullableRequired

discordIdstring · nullableRequired

twitterIdstring · nullableRequired

discordHandlestring · nullableRequired

tiktokUsernamestring · nullableRequired

twitterUsernamestring · nullableRequired

xpnumberRequired

ranknumberRequired

levelnumberRequired

createdAtstring · date-timeRequired

updatedAtstring · date-timeRequired

deletedAtstring · date-time · nullableRequired

referrerUrlstring · nullableRequired

referrerIdstring · nullableRequired

banReasonstring · nullableRequired

rolestring · enum · nullableRequiredPossible values:

isBannedbooleanRequired

400

400

application/json

401

401

application/json

403

403

application/json

404

404

application/json

409

409

application/json

429

429

application/json

500

500

application/json

get

/public/communities/{subdomain}/users/{userId}

HTTPcURLJavaScriptPython

GET /public/communities/{subdomain}/users/{userId} HTTP/1.1
Host: api-v2.zealy.io
x-api-key: text
Accept: */*

{
  "id": "text",
  "avatar": "text",
  "connectedWallet": "text",
  "name": "text",
  "email": "text",
  "discordId": "text",
  "twitterId": "text",
  "discordHandle": "text",
  "tiktokUsername": "text",
  "twitterUsername": "text",
  "verifiedBlockchainAddresses": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "unVerifiedBlockchainAddresses": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "xp": 1,
  "rank": 1,
  "level": 1,
  "invites": [
    {
      "userId": "text",
      "status": "active",
      "joinedAt": "2026-03-14T03:54:56.879Z",
      "xp": 1
    }
  ],
  "createdAt": "2026-03-14T03:54:56.879Z",
  "updatedAt": "2026-03-14T03:54:56.879Z",
  "deletedAt": "2026-03-14T03:54:56.879Z",
  "referrerUrl": "text",
  "referrerId": "text",
  "banReason": "text",
  "role": "admin",
  "isBanned": true
}

Find a user by social id

get

Path parameters

subdomainstringRequired

Query parameters

discordIdstringOptional

discordHandlestringOptional

twitterUsernamestringOptional

twitterIdstringOptional

ethAddressstringOptional

emailstringOptional

blockchainNetworkstring · enumOptionalPossible values:

blockchainAddressstringOptional

Header parameters

x-api-keystringRequired

Responses

200

200

application/json

discordHandlestring · nullableRequired

tiktokUsernamestring · nullableRequired

twitterUsernamestring · nullableRequired

connectedWalletstring · nullableRequired

emailstring · nullableRequired

discordIdstring · nullableRequired

twitterIdstring · nullableRequired

idstringRequired

xpnumberRequired

namestring · nullableRequired

createdAtstring · date-timeRequired

ranknumberRequired

rolestring · enumRequiredPossible values:

levelnumberRequired

isBannedbooleanRequired

karmanumberRequired

referrerUrlstring · nullableRequired

referrerIdstring · nullableRequired

banReasonstring · nullableRequired

400

400

application/json

401

401

application/json

403

403

application/json

404

404

application/json

409

409

application/json

429

429

application/json

500

500

application/json

get

/public/communities/{subdomain}/users

HTTPcURLJavaScriptPython

GET /public/communities/{subdomain}/users HTTP/1.1
Host: api-v2.zealy.io
x-api-key: text
Accept: */*

{
  "discordHandle": "text",
  "tiktokUsername": "text",
  "twitterUsername": "text",
  "verifiedBlockchainAddresses": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "unVerifiedBlockchainAddresses": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "connectedWallet": "text",
  "email": "text",
  "discordId": "text",
  "twitterId": "text",
  "id": "text",
  "xp": 1,
  "name": "text",
  "createdAt": "2026-03-14T03:54:56.879Z",
  "rank": 1,
  "invites": [
    {
      "userId": "text",
      "status": "active",
      "joinedAt": "2026-03-14T03:54:56.879Z",
      "xp": 1
    }
  ],
  "role": "admin",
  "level": 1,
  "isBanned": true,
  "karma": 1,
  "referrerUrl": "text",
  "referrerId": "text",
  "banReason": "text"
}

List invites for a user

get

Path parameters

subdomainstringRequired

userIdstring · uuidRequired

Query parameters

statusstring · enumOptionalPossible values:

invitesQuestIdstring · uuidOptional

pageinteger · min: 1Required

page_sizeinteger · max: 100OptionalDefault: 10

Header parameters

x-api-keystringRequired

Responses

200

200

application/json

userIdstring · uuidRequired

statusstring · enumRequiredPossible values:

joinedAtstring · date-timeRequired

namestring · nullableRequired

xpnumberRequired

400

400

application/json

401

401

application/json

403

403

application/json

404

404

application/json

409

409

application/json

429

429

application/json

500

500

application/json

get

/public/communities/{subdomain}/users/{userId}/invites

HTTPcURLJavaScriptPython

GET /public/communities/{subdomain}/users/{userId}/invites?page=1 HTTP/1.1
Host: api-v2.zealy.io
x-api-key: text
Accept: */*

[
  {
    "userId": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "joinedAt": "2026-03-14T03:54:56.879Z",
    "name": "text",
    "xp": 1
  }
]

Get number of flags and stars for a user in a community

get

Path parameters

idstring · uuidRequired

subdomainstringRequired

Header parameters

x-api-keystringRequired

Responses

200

200

application/json

flagsnumberRequired

starsnumberRequired

400

400

application/json

401

401

application/json

403

403

application/json

404

404

application/json

409

409

application/json

429

429

application/json

500

500

application/json

get

/public/communities/{subdomain}/reviews/users/{id}

HTTPcURLJavaScriptPython

GET /public/communities/{subdomain}/reviews/users/{id} HTTP/1.1
Host: api-v2.zealy.io
x-api-key: text
Accept: */*

{
  "flags": 1,
  "stars": 1
}