Appearance
Searching users
Privy allows you to search for your users by their email address, phone number, wallet address, or Farcaster fid from your server. You can also pass a partial email, phone number, or wallet address for your user as a search term that will be partially matched.
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
By email
Use the PrivyClient
's getUserbyEmail
method to get a single user by their email address. As a parameter, pass the user's DID as a string
:
typescript
const user = await privy.getUserByEmail('[email protected]');
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.
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');
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.
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');
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.
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
:
typescript
const user = await privy.getUserByFid('1402');
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.
By search term
Use the PrivyClient
's getUsers
method to search all of your users, passing your search term as a string
in the searchTerm
parameter:
typescript
const user = await privy.getUsers('0x123');
If users are found with an account that partially matches the search term, the method will return the matched users in an array of User
object. If no matching users are found, the method will return an empty array ([]
).
Using the REST API
Make a POST request to:
sh
https://auth.privy.io/api/v1/users/search
In the request body, specify the following fields:.
emails
(optional): An array of email addresses of users to retrieve.phoneNumbers
(optional): An array of phone numbers of users to retrieve.walletAddresses
(optional): An array of wallet addresses of users to retrieve.searchTerm
(optional): Filter users by email's, phone number's, and wallet address's that contain the term.cursor
(optional)- When you request a batch of users from Privy, the API will return a cursor for the next batch of users in the
next_cursor
field of the response. This will be a Privy DID (e.g. 'did:privy:123456'). - If you are requesting the first batch of users for your app, do not include a
cursor
in your request body. - If you have already requested a batch of users and want to request the next batch, set the
cursor
in your request body to be thenext_cursor
returned by the API in your previous query. If the providedcursor
is not a valid Privy DID, the API will return an error.
- When you request a batch of users from Privy, the API will return a cursor for the next batch of users in the
limit
(optional): The number of users you would like the API to return. Defaults to and may not exceed 100.
TIP
Searches can be made on emails
, phoneNumbers
, and walletAddresses
OR searchTerm
. If emails
, phoneNumbers
, or walletAddresses
AND searchTerm
are specified the API will respond with an error.
This is a paginated query, and the API will return up to 100 users for a single request. As an example, to get the first 100 users for your app with a gmail email address:
bash
curl --request POST https://auth.privy.io/api/v1/users/search \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-d '{"searchTerm":"@gmail.com"}'
Then, to get the next 100 users for your app with a gmail email address, you should pass the next_cursor
field of the last response as the cursor
in your request body:
bash
# Replace 'did:privy:123456' below with the `next_cursor` returned by the last query
curl --request POST https://auth.privy.io/api/v1/users/search \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-d '{
"searchTerm":"@gmail.com",
"cursor": "did:privy:123456"
}'
By email
bash
curl --request POST "https://auth.privy.io/api/v1/users/search" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-d '{
"emails": ["[email protected]", "[email protected]"]
}'
By phone number
bash
curl --request POST "https://auth.privy.io/api/v1/users/search" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-d '{"phoneNumbers": ["555 555 5555"]}'
By wallet address
bash
curl --request POST "https://auth.privy.io/api/v1/users/search" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-d '{"walletAddresses": ["0xABCDEFGHIJKL01234567895C5cAe8B9472c14328"]}'
By search term
bash
curl --request POST "https://auth.privy.io/api/v1/users/search" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-d '{"searchTerm":"@gmail.com"}'
Response format
A successful response will include:
data
: the user objects for your users as an arraynext_cursor
: the cursor to be used in your next request to this API
Below is an example:
json
{
"data": [
{
"id": "did:privy:cfbsvtqo2c22202mo08847jdux2z",
"created_at": 1667165891,
"linked_accounts": [
{
"type": "wallet",
"address": "0xABCDEFGHIJKL01234567895C5cAe8B9472c14328",
"chain_type": "ethereum",
"verified_at": 1667165891
},
{
"type": "email",
"address": "[email protected]",
"verified_at": 1667350653
}
]
}
],
"next_cursor": "did:privy:123456789"
}