Documentation

Users

users

Methods

Gets Users -> Cursor<
User
>
get/v1/users

Get all users in your app.

Create User ->
User
post/v1/users

Create a new user with linked accounts. Optionally pre-generate embedded wallets for the user.

Get User ->
User
get/v1/users/{user_id}

Get a user by user ID.

path Parameters
user_id: string

User ID

Response fields
User
Request example
200Example
Lookup User By Discord Username ->
User
post/v1/users/discord/username

Looks up a user by their Discord username.

Lookup User By Email Address ->
User
post/v1/users/email/address

Looks up a user by their email address.

Lookup User By Farcaster ID ->
User
post/v1/users/farcaster/fid

Looks up a user by their Farcaster ID.

Response fields
User
Request example
200Example
Lookup User By GitHub Username ->
User
post/v1/users/github/username

Looks up a user by their Github username.

Lookup User By Phone Number ->
User
post/v1/users/phone/number

Looks up a user by their phone number.

Lookup User By Smart Wallet Address ->
User
post/v1/users/smart_wallet/address

Looks up a user by their smart wallet address.

Lookup User By Telegram User ID ->
User
post/v1/users/telegram/telegram_user_id

Looks up a user by their Telegram user ID.

Lookup User By Telegram Username ->
User
post/v1/users/telegram/username

Looks up a user by their Telegram username.

Lookup User By Twitter Subject ->
User
post/v1/users/twitter/subject

Looks up a user by their Twitter subject.

Lookup User By Twitter Username ->
User
post/v1/users/twitter/username

Looks up a user by their Twitter username.

Lookup User By Wallet Address ->
User
post/v1/users/wallet/address

Looks up a user by their wallet address.

Lookup User By Custom Auth ID ->
User
post/v1/users/custom_auth/id

Looks up a user by their custom auth ID.

Delete User ->
delete/v1/users/{user_id}

Delete a user by user ID.

Create Custom Metadata ->
User
post/v1/users/{user_id}/custom_metadata

Adds custom metadata to a user by user ID.

Unlink A User Linked Account ->
User
post/v1/users/{user_id}/accounts/unlink

Unlinks a user linked account.

Create Embedded Wallet ->
User
post/v1/users/{user_id}/wallets

Creates an embedded wallet for an existing user.

Search Users By Search Term ->
User
post/v1/users/search

Search users by search term, emails, phone numbers, or wallet addresses.

Domain types

AuthenticatedUser = { token, privy_access_token, refresh_token, 5 more... }

The authenticated user.

CrossAppEmbeddedWallet = { address }

An embedded wallet associated with a cross-app account.

CrossAppSmartWallet = { address }

A smart wallet associated with a cross-app account.

CustomMetadata = Record<string, string | number | boolean>

Custom metadata associated with the user.

EmbeddedWalletRecoveryMethod = "privy" | "user-passcode" | "google-drive" | 3 more...

The method used to recover an embedded wallet account.

LinkedAccount =
LinkedAccountEmail
|
LinkedAccountPhone
|
LinkedAccountEthereum
| 25 more...

A linked account for the user.

LinkedAccountAppleInput = { subject, type, email }

The payload for importing an Apple account.

LinkedAccountAppleOAuth = { email, first_verified_at, latest_verified_at, 3 more... }

An Apple OAuth account linked to the user.

LinkedAccountAuthorizationKey = { first_verified_at, latest_verified_at, public_key, 2 more... }

An authorization key linked to the user.

LinkedAccountBaseWallet = { address, chain_type, type }

Base schema for wallet accounts linked to the user.

LinkedAccountBitcoinSegwitEmbeddedWallet = { id, address, chain_id, 13 more... }

A Bitcoin SegWit embedded wallet account linked to the user.

LinkedAccountBitcoinTaprootEmbeddedWallet = { id, address, chain_id, 13 more... }

A Bitcoin Taproot embedded wallet account linked to the user.

LinkedAccountCrossApp = { embedded_wallets, first_verified_at, latest_verified_at, 5 more... }

A cross-app account linked to the user.

LinkedAccountCurveSigningEmbeddedWallet = { id, address, chain_id, 13 more... }

A curve signing embedded wallet account linked to the user.

LinkedAccountCustomJwt = { custom_user_id, first_verified_at, latest_verified_at, 2 more... }

A custom JWT account linked to the user.

LinkedAccountCustomJwtInput = { custom_user_id, type }

The payload for importing a Custom JWT account.

LinkedAccountCustomOAuth = { first_verified_at, latest_verified_at, subject, 6 more... }

A custom OAuth account linked to the user.

LinkedAccountDiscordInput = { subject, type, username, 1 more... }

The payload for importing a Discord account.

LinkedAccountDiscordOAuth = { email, first_verified_at, latest_verified_at, 4 more... }

A Discord OAuth account linked to the user.

LinkedAccountEmail = { address, first_verified_at, latest_verified_at, 2 more... }

An email account linked to the user.

LinkedAccountEmailInput = { address, type }

The payload for importing an email account.

LinkedAccountEmbeddedWallet =
LinkedAccountEthereumEmbeddedWallet
|
LinkedAccountSolanaEmbeddedWallet
|
LinkedAccountBitcoinSegwitEmbeddedWallet
| 2 more...
LinkedAccountEmbeddedWalletWithID =
LinkedAccountEthereumEmbeddedWallet
|
LinkedAccountSolanaEmbeddedWallet
|
LinkedAccountBitcoinSegwitEmbeddedWallet
| 2 more...

An embedded wallet account with an ID.

LinkedAccountEthereum = { address, chain_type, first_verified_at, 7 more... }

An Ethereum wallet account linked to the user.

LinkedAccountEthereumEmbeddedWallet = { id, address, chain_id, 12 more... }

An Ethereum embedded wallet account linked to the user.

LinkedAccountFarcaster = { fid, first_verified_at, latest_verified_at, 10 more... }

A Farcaster account linked to the user.

LinkedAccountFarcasterInput = { fid, owner_address, type, 5 more... }

The payload for importing a Farcaster account.

LinkedAccountGitHubInput = { subject, type, username, 2 more... }

The payload for importing a Github account.

LinkedAccountGitHubOAuth = { email, first_verified_at, latest_verified_at, 5 more... }

A GitHub OAuth account linked to the user.

LinkedAccountGoogleInput = { email, name, subject, 1 more... }

The payload for importing a Google account.

LinkedAccountGoogleOAuth = { email, first_verified_at, latest_verified_at, 4 more... }

A Google OAuth account linked to the user.

LinkedAccountInput =
LinkedAccountWalletInput
|
LinkedAccountEmailInput
|
LinkedAccountPhoneInput
| 15 more...

The input for adding a linked account to a user.

LinkedAccountInstagramInput = { subject, type, username }

The payload for importing an Instagram account.

LinkedAccountInstagramOAuth = { first_verified_at, latest_verified_at, subject, 3 more... }

An Instagram OAuth account linked to the user.

LinkedAccountLineInput = { subject, type, email, 2 more... }

The payload for importing a LINE account.

LinkedAccountLineOAuth = { email, first_verified_at, latest_verified_at, 5 more... }

A LINE OAuth account linked to the user.

LinkedAccountLinkedInInput = { subject, type, email, 2 more... }

The payload for importing a LinkedIn account.

LinkedAccountLinkedInOAuth = { email, first_verified_at, latest_verified_at, 5 more... }

A LinkedIn OAuth account linked to the user.

LinkedAccountPasskey = { credential_id, enrolled_in_mfa, first_verified_at, 8 more... }

A passkey account linked to the user.

LinkedAccountPasskeyInput = { credential_device_type, credential_id, credential_public_key, 2 more... }

The payload for importing a passkey account.

LinkedAccountPhone = { first_verified_at, latest_verified_at, phoneNumber, 3 more... }

A phone number account linked to the user.

LinkedAccountPhoneInput = { number, type }

The payload for importing a phone account.

LinkedAccountSmartWallet = { address, first_verified_at, latest_verified_at, 4 more... }

A smart wallet account linked to the user.

LinkedAccountSolana = { address, chain_type, first_verified_at, 6 more... }

A Solana wallet account linked to the user.

LinkedAccountSolanaEmbeddedWallet = { id, address, chain_id, 13 more... }

A Solana embedded wallet account linked to the user.

LinkedAccountSpotifyInput = { subject, type, email, 1 more... }

The payload for importing a Spotify account.

LinkedAccountSpotifyOAuth = { email, first_verified_at, latest_verified_at, 4 more... }

A Spotify OAuth account linked to the user.

LinkedAccountTelegram = { first_verified_at, latest_verified_at, telegram_user_id, 6 more... }

A Telegram account linked to the user.

LinkedAccountTelegramInput = { telegram_user_id, type, first_name, 3 more... }

The payload for importing a Telegram account.

LinkedAccountTiktokInput = { name, subject, type, 1 more... }

The payload for importing a Tiktok account.

LinkedAccountTiktokOAuth = { first_verified_at, latest_verified_at, name, 4 more... }

A TikTok OAuth account linked to the user.

LinkedAccountTwitchInput = { subject, type, username }

The payload for importing a Twitch account.

LinkedAccountTwitchOAuth = { first_verified_at, latest_verified_at, subject, 3 more... }

A Twitch OAuth account linked to the user.

LinkedAccountTwitterInput = { name, subject, type, 2 more... }

The payload for importing a Twitter account.

LinkedAccountTwitterOAuth = { first_verified_at, latest_verified_at, name, 5 more... }

A Twitter OAuth account linked to the user.

LinkedAccountType = "email" | "phone" | "wallet" | 18 more... |
CustomOAuthProviderID

The possible types of linked accounts.

LinkedAccountWalletInput = { address, chain_type, type }

The payload for importing a wallet account.

LinkedMfaMethod =
SMSMfaMethod
|
TotpMfaMethod
|
PasskeyMfaMethod

A multi-factor authentication method linked to the user.

OAuthTokens = { access_token, provider, access_token_expires_in_seconds, 3 more... }

OAuth tokens associated with the user.

PasskeyMfaMethod = { type, verified_at }

A Passkey MFA method.

SmartWalletType = "safe" | "kernel" | "light_account" | 3 more...

The provider for a smart wallet.

SMSMfaMethod = { type, verified_at }

A SMS MFA method.

TotpMfaMethod = { type, verified_at }

A TOTP MFA method.

User = { id, created_at, has_accepted_terms, 4 more... }

A Privy user object.

UserBatchCreateInput = { users }

The payload for batch creating users.

UserWithIdentityToken = { identity_token, user }

The user object along their identity token.