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:

const user = await privy.getUserByEmail('user@gmail.com');

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:

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:

const user = await privy.getUserByWalletAddress('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:

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

By Farcaster fid

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

const user = await privy.getUserByFid('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:

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:

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:

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:

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:

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

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": "user@gmail.com"
}'

By phone number

Make a POST request with phone_number in the body to

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

Example

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

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

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

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

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

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

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

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

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