Querying users - Privy docs

Privy supports multiple ways to fetch and manage users in your application.

Querying users by identity token

Using identity tokens is the recommended way to query user information about authenticated users in your backend. If you need user data about unauthenticated users, you can use the getUsers method by passing in a user’s DID.

Use the getUser method to get a single user by their identity token passed from the client, to learn more about identity tokens, see identity tokens.

const user = await privy.getUser({idToken: 'your-idToken});

Other ways to query users

Privy rate limits REST API endpoints that you may call from your server. If you’re looking to get information about an authenticated user, consider using identity tokens as a more secure and efficient way to access user data.

Querying users by ID

Use the getUser method to get a single user by their Privy DID:

const user = await privy.getUserById('did:privy:XXXXXX');

Querying for all users

Use the getUsers method to get a list of all your users:

const users = await privy.getUsers();

The getUsers method automatically handles pagination and includes built-in exponential backoff to manage rate limits.

Querying for users by account data

By email address

By phone number

By wallet address

By smart wallet address

By custom auth ID

By Farcaster fid

By Twitter subject

By Twitter username

By Discord username

By Telegram User ID

By Telegram username

Querying users by identity token

Use the getUser method to get a single user by their identity token passed from the client, to learn more about identity tokens, see identity tokens.

const user = await privy.getUser({idToken: 'your-idToken});

Other ways to query users

Querying users by ID

Use the getUser method to get a single user by their Privy DID:

const user = await privy.getUserById('did:privy:XXXXXX');

Querying for all users

Use the getUsers method to get a list of all your users:

const users = await privy.getUsers();

The getUsers method automatically handles pagination and includes built-in exponential backoff to manage rate limits.

Querying for users by account data

By email address

By phone number

By wallet address

By smart wallet address

By custom auth ID

By Farcaster fid

By Twitter subject

By Twitter username

By Discord username

By Telegram User ID

By Telegram username

Querying users by identity token

Use the get_by_id_token method to get a single user by their identity token passed from the client, to learn more about identity tokens, see identity tokens.

user = privy.users.get_by_id_token(id_token="your-idToken")

Other ways to query users

Querying users by ID

Use the get method to get a single user by their Privy DID:

user = privy.users.get(user_id="did:privy:XXXXXX")

Querying for all users

Use the list method to get a list of all your users:

users = privy.users.list()

The list method automatically handles pagination.

Querying for users by account data

By email address

By wallet address

By custom auth ID

Querying users by ID

To get a user by their Privy DID, make a GET request to:

https://auth.privy.io/api/v1/users/<did>

Parameters

did

string

required

The user’s Privy DID (e.g., did:privy:XXXXXX).

Sample request

curl --request GET https://auth.privy.io/api/v1/users/<user-did> \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

Querying for all users

To get all users for your app, make a GET request to:

https://auth.privy.io/api/v1/users

Parameters

cursor

string

Cursor for pagination. Use the next_cursor from the previous response.

limit

number

Number of users to return per request. Defaults to 100.

Response

The response will include:

data: Array of user objects
next_cursor: Cursor to use for the next batch of users

Sample request

# First batch of users
curl --request GET https://auth.privy.io/api/v1/users \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

# Subsequent batches using cursor
curl --request GET https://auth.privy.io/api/v1/users?cursor=<next_cursor> \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

Querying for users by account data

By email address

To get a user by their email address, make a POST request to:

https://auth.privy.io/api/v1/users/email/address

Body

address

string

required

Email address of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/email/address" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "address": "[email protected]"
}'

By phone number

To get a user by their phone number, make a POST request to:

https://auth.privy.io/api/v1/users/phone/number

Body

number

string

required

Phone number of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/phone/number" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "number": "1234567890"
}'

By wallet address

To get a user by their wallet address, make a POST request to:

https://auth.privy.io/api/v1/users/wallet/address

Body

address

string

required

Wallet address of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/wallet/address" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "address": "0xABCDEFGHIJKL01234567895C5cAe8B9472c14328"
}'

By smart wallet address

To get a user by their smart wallet address, make a POST request to:

https://auth.privy.io/api/v1/users/smart_wallet/address

Body

address

string

required

Smart wallet address of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/smart_wallet/address" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "address": "0xABCDEFGHIJKL01234567895C5cAe8B9472c14328"
}'

By custom auth ID

To get a user by their custom auth ID, make a POST request to:

https://auth.privy.io/api/v1/users/custom_auth/id

Body

custom_user_id

string

required

Custom user ID provided by your authentication system.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/custom_auth/id" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "custom_user_id": "123"
}'

By Farcaster fid

To get a user by their Farcaster fid, make a POST request to:

https://auth.privy.io/api/v1/users/farcaster/fid

Body

fid

string

required

Farcaster ID of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/farcaster/fid" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "fid": "789"
}'

By Twitter subject

To get a user by their Twitter subject, make a POST request to:

https://auth.privy.io/api/v1/users/twitter/subject

Body

subject

string

required

Twitter subject identifier of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/twitter/subject" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "subject": "12345"
}'

Use subject instead of username to get Twitter accounts with faster queries.

By Twitter username

To get a user by their Twitter username, make a POST request to:

https://auth.privy.io/api/v1/users/twitter/username

Body

username

string

required

Twitter username of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/twitter/username" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "username": "batman"
}'

By Discord username

To get a user by their Discord username, make a POST request to:

https://auth.privy.io/api/v1/users/discord/username

Body

username

string

required

Discord username of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/discord/username" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "username": "batman"
}'

By Telegram User ID

To get a user by their Telegram User ID, make a POST request to:

https://auth.privy.io/api/v1/users/telegram/telegram_user_id

Body

telegram_user_id

string

required

Telegram User ID of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/telegram/telegram_user_id" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "telegram_user_id": "12345"
}'

Use ID instead of username to get Telegram accounts with faster queries.

By Telegram username

To get a user by their Telegram username, make a POST request to:

https://auth.privy.io/api/v1/users/telegram/username

Body

username

string

required

Telegram username of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/telegram/username" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "username": "batman"
}'

Privy supports multiple ways to fetch and manage users in your application.

Querying users by identity token

Use the getUser method to get a single user by their identity token passed from the client, to learn more about identity tokens, see identity tokens.

const user = await privy.getUser({idToken: 'your-idToken});

Other ways to query users

Querying users by ID

Use the getUser method to get a single user by their Privy DID:

const user = await privy.getUserById('did:privy:XXXXXX');

Querying for all users

Use the getUsers method to get a list of all your users:

const users = await privy.getUsers();

The getUsers method automatically handles pagination and includes built-in exponential backoff to manage rate limits.

Querying for users by account data

By email address

By phone number

By wallet address

By smart wallet address

By custom auth ID

By Farcaster fid

By Twitter subject

By Twitter username

By Discord username

By Telegram User ID

By Telegram username

Querying users by identity token

Use the getUser method to get a single user by their identity token passed from the client, to learn more about identity tokens, see identity tokens.

const user = await privy.getUser({idToken: 'your-idToken});

Other ways to query users

Querying users by ID

Use the getUser method to get a single user by their Privy DID:

const user = await privy.getUserById('did:privy:XXXXXX');

Querying for all users

Use the getUsers method to get a list of all your users:

const users = await privy.getUsers();

The getUsers method automatically handles pagination and includes built-in exponential backoff to manage rate limits.

Querying for users by account data

By email address

By phone number

By wallet address

By smart wallet address

By custom auth ID

By Farcaster fid

By Twitter subject

By Twitter username

By Discord username

By Telegram User ID

By Telegram username

Querying users by identity token

Use the get_by_id_token method to get a single user by their identity token passed from the client, to learn more about identity tokens, see identity tokens.

user = privy.users.get_by_id_token(id_token="your-idToken")

Other ways to query users

Querying users by ID

Use the get method to get a single user by their Privy DID:

user = privy.users.get(user_id="did:privy:XXXXXX")

Querying for all users

Use the list method to get a list of all your users:

users = privy.users.list()

The list method automatically handles pagination.

Querying for users by account data

By email address

By wallet address

By custom auth ID

Querying users by ID

To get a user by their Privy DID, make a GET request to:

https://auth.privy.io/api/v1/users/<did>

Parameters

did

string

required

The user’s Privy DID (e.g., did:privy:XXXXXX).

Sample request

curl --request GET https://auth.privy.io/api/v1/users/<user-did> \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

Querying for all users

To get all users for your app, make a GET request to:

https://auth.privy.io/api/v1/users

Parameters

cursor

string

Cursor for pagination. Use the next_cursor from the previous response.

limit

number

Number of users to return per request. Defaults to 100.

Response

The response will include:

data: Array of user objects
next_cursor: Cursor to use for the next batch of users

Sample request

# First batch of users
curl --request GET https://auth.privy.io/api/v1/users \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

# Subsequent batches using cursor
curl --request GET https://auth.privy.io/api/v1/users?cursor=<next_cursor> \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>"

Querying for users by account data

By email address

To get a user by their email address, make a POST request to:

https://auth.privy.io/api/v1/users/email/address

Body

address

string

required

Email address of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/email/address" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "address": "[email protected]"
}'

By phone number

To get a user by their phone number, make a POST request to:

https://auth.privy.io/api/v1/users/phone/number

Body

number

string

required

Phone number of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/phone/number" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "number": "1234567890"
}'

By wallet address

To get a user by their wallet address, make a POST request to:

https://auth.privy.io/api/v1/users/wallet/address

Body

address

string

required

Wallet address of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/wallet/address" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "address": "0xABCDEFGHIJKL01234567895C5cAe8B9472c14328"
}'

By smart wallet address

To get a user by their smart wallet address, make a POST request to:

https://auth.privy.io/api/v1/users/smart_wallet/address

Body

address

string

required

Smart wallet address of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/smart_wallet/address" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "address": "0xABCDEFGHIJKL01234567895C5cAe8B9472c14328"
}'

By custom auth ID

To get a user by their custom auth ID, make a POST request to:

https://auth.privy.io/api/v1/users/custom_auth/id

Body

custom_user_id

string

required

Custom user ID provided by your authentication system.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/custom_auth/id" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "custom_user_id": "123"
}'

By Farcaster fid

To get a user by their Farcaster fid, make a POST request to:

https://auth.privy.io/api/v1/users/farcaster/fid

Body

fid

string

required

Farcaster ID of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/farcaster/fid" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "fid": "789"
}'

By Twitter subject

To get a user by their Twitter subject, make a POST request to:

https://auth.privy.io/api/v1/users/twitter/subject

Body

subject

string

required

Twitter subject identifier of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/twitter/subject" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "subject": "12345"
}'

Use subject instead of username to get Twitter accounts with faster queries.

By Twitter username

To get a user by their Twitter username, make a POST request to:

https://auth.privy.io/api/v1/users/twitter/username

Body

username

string

required

Twitter username of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/twitter/username" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "username": "batman"
}'

By Discord username

To get a user by their Discord username, make a POST request to:

https://auth.privy.io/api/v1/users/discord/username

Body

username

string

required

Discord username of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/discord/username" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "username": "batman"
}'

By Telegram User ID

To get a user by their Telegram User ID, make a POST request to:

https://auth.privy.io/api/v1/users/telegram/telegram_user_id

Body

telegram_user_id

string

required

Telegram User ID of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/telegram/telegram_user_id" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "telegram_user_id": "12345"
}'

Use ID instead of username to get Telegram accounts with faster queries.

By Telegram username

To get a user by their Telegram username, make a POST request to:

https://auth.privy.io/api/v1/users/telegram/username

Body

username

string

required

Telegram username of the user.

Sample request

curl --request POST "https://auth.privy.io/api/v1/users/telegram/username" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "username": "batman"
}'

​Querying users by identity token

​Other ways to query users

​Querying users by ID

​Querying for all users

​Querying for users by account data

​Querying users by identity token

​Other ways to query users

​Querying users by ID

​Querying for all users

​Querying for users by account data

​Querying users by identity token

​Other ways to query users

​Querying users by ID

​Querying for all users

​Querying for users by account data

​Querying users by ID

​Parameters

​Sample request

​Querying for all users

​Parameters

​Response

​Sample request

​Querying for users by account data

API reference

Wallets

Account funding

Policies

Transactions

Key quorums

Users

​Querying users by identity token

​Other ways to query users

​Querying users by ID

​Querying for all users

​Querying for users by account data

​Querying users by identity token

​Other ways to query users

​Querying users by ID

​Querying for all users

​Querying for users by account data

​Querying users by identity token

​Other ways to query users

​Querying users by ID

​Querying for all users

​Querying for users by account data

​Querying users by ID

​Parameters

​Sample request

​Querying for all users

​Parameters

​Response

​Sample request

​Querying for users by account data

Querying users by identity token

Other ways to query users

Querying users by ID

Querying for all users

Querying for users by account data

Querying users by identity token

Other ways to query users

Querying users by ID

Querying for all users

Querying for users by account data

Querying users by identity token

Other ways to query users

Querying users by ID

Querying for all users

Querying for users by account data

Querying users by ID

Parameters

Sample request

Querying for all users

Parameters

Response

Sample request

Querying for users by account data

Querying users by identity token

Other ways to query users

Querying users by ID

Querying for all users

Querying for users by account data

Querying users by identity token

Other ways to query users

Querying users by ID

Querying for all users

Querying for users by account data

Querying users by identity token

Other ways to query users

Querying users by ID

Querying for all users

Querying for users by account data

Querying users by ID

Parameters

Sample request

Querying for all users

Parameters

Response

Sample request

Querying for users by account data