Searching users

Privy allows you to search for your users by their email address, phone number, wallet address, custom user ID, Farcaster fid, Twitter subject and Twitter username from your server.

This endpoint may be useful in situations where you have a user's linked accounts, but not their DID. If you have their DID, use the get user by DID endpoint instead for faster lookup.

WARNING

Privy rate limits REST API endpoints that you may call from your server. If you suspect your team will require an increased rate limit, please reach out to support!

Using `@privy-io/server-auth`

Use Privy's built in helper functions to easily get a user.

If a matching user is found, the method will return the corresponding User object. If no matching user is found, the method will throw an error.

TIP

Ensure your @privy-io/server-auth package is updated to the latest version to take advantage of substantial performance improvements in searching for users by an account identifier.

By email

Use the PrivyClient's getUserbyEmail method to get a single user by their email address. As a parameter, pass the user's email address as a string:

typescript

const user = await privy.getUserByEmail('[email protected]');

By phone number

Use the PrivyClient's getUserbyPhoneNumber method to get a single user by their phone number. As a parameter, pass the user's phone number as a string:

typescript

const user = await privy.getUserByPhoneNumber('+1 555 555 5555');

By wallet address

Use the PrivyClient's getUserByWalletAddress method to get a single user by their wallet address. As a parameter, pass the user's wallet address as a string:

typescript

const user = await privy.getUserByWalletAddress('0xABCDEFGHIJKL01234567895C5cAe8B9472c14328');

By smart wallet address

Use the PrivyClient's getUserBySmartWalletAddress method to get a single user by their smart wallet address. As a parameter, pass the user's smart wallet address as a string:

typescript

const user = await privy.getUserBySmartWalletAddress('0xABCDEFGHIJKL01234567895C5cAe8B9472c14328');

By custom user ID

Use the PrivyClient's getUserByCustomAuthId method to get a single user by their custom auth ID. As a parameter, pass the user's id, as provided by your custom auth provider:

typescript

const user = await privy.getUserByCustomAuthId('123');

By Farcaster `fid`

Use the PrivyClient's getUserByFarcasterId method to get a single user by their Farcaster fid. As a parameter, pass the user's fid as a number:

typescript

const user = await privy.getUserByFarcasterId(1402);

By Twitter subject

Use the PrivyClient's getUserByTwitterSubject method to get a single user by their Twitter subject. As a parameter, pass the user's Twitter subject as a string:

typescript

const user = await privy.getUserByTwitterSubject('456');

By Twitter username

Use the PrivyClient's getUserByTwitterUsername method to get a single user by their Twitter username. As a parameter, pass the user's Twitter username as a string:

typescript

const user = await privy.getUserByTwitterUsername('batman');

By Discord username

Use the PrivyClient's getUserByDiscordUsername method to get a single user by their Discord username. As a parameter, pass the user's Discord username as a string:

typescript

const user = await privy.getUserByDiscordUsername('batman');

By Telegram ID

Use the PrivyClient's getUserByTelegramUserId method to get a single user by their Telegram ID. As a parameter, pass the user's Telegram ID as a string:

typescript

const user = await privy.getUserByTelegramUserId('456');

By Telegram username

Use the PrivyClient's getUserByTelegramUsername method to get a single user by their Telegram username. As a parameter, pass the user's Telegram username as a string:

typescript

const user = await privy.getUserByTelegramUsername('batman');

Using the REST API

Use the REST API to easily get a user. For each request, include your Privy app ID and Privy app secret.

If a matching user is found, the response will contain the corresponding User object. If no matching user is found, the response will contain an error.

By email

Make a POST request with address in the body to

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

Example

bash

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

Make a POST request with phone_number in the body to

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

Example

bash

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

Make a POST request with address in the body to

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

Example

bash

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

Make a POST request with address in the body to

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

Example

bash

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

Make a POST request with custom_user_id in the body to

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

Example

bash

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

Make a POST request with fid in the body to

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

Example

bash

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

Make a POST request with subject in the body to

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

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

Example

bash

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"
}'

By Twitter username

Make a POST request with username in the body to

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

Example

bash

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

Make a POST request with username in the body to

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

Example

bash

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

Make a POST request with telegram_user_id in the body to

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

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

Example

bash

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"
}'

By Telegram username

Make a POST request with username in the body to

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

Example

bash

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"
}'

Setup

Frameworks

UI issues

Searching users

Using `@privy-io/server-auth`

By email

By phone number

By wallet address

By smart wallet address

By custom user ID

By Farcaster `fid`

By Twitter subject

By Twitter username

By Discord username

By Telegram ID

By Telegram username

Using the REST API

By email

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

Searching users ​

Using @privy-io/server-auth ​

By email ​

By phone number ​

By wallet address ​

By smart wallet address ​

By custom user ID ​

By Farcaster fid ​

By Twitter subject ​

By Twitter username ​

By Discord username ​

By Telegram ID ​

By Telegram username ​

Using the REST API ​

By email ​

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 ​

Searching users

Using `@privy-io/server-auth`

By email

By phone number

By wallet address

By smart wallet address

By custom user ID

By Farcaster `fid`

By Twitter subject

By Twitter username

By Discord username

By Telegram ID

By Telegram username

Using the REST API

By email

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