Documentation | Users › Create Custom Metadata

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.

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.

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.

path Parameters

user_id: string

ID of the user.

Response fields

User

Request example

curl https://api.privy.io/v1/users/$USER_ID/custom_metadata \
    -H 'Content-Type: application/json' \
    -H "Authorization: Basic $PRIVY_APP_ID:$PRIVY_APP_SECRET" \
    -d '{
          "custom_metadata": {
            "key": "value"
          }
        }'

200Example

{
  "id": "did:privy:cm3np4u9j001rc8b73seqmqqk",
  "created_at": 1731974895,
  "has_accepted_terms": true,
  "is_guest": false,
  "linked_accounts": [
    {
      "address": "[email protected]",
      "first_verified_at": 1674788927,
      "latest_verified_at": 1674788927,
      "type": "email",
      "verified_at": 1674788927
    },
    {
      "fid": 4423,
      "first_verified_at": 1740678402,
      "latest_verified_at": 1741194370,
      "owner_address": "0xE6bFb4137F3A8C069F98cc775f324A84FE45FdFF",
      "type": "farcaster",
      "verified_at": 1740678402,
      "bio": "engineering at /privy. building pixelpool.xyz, the first Farcaster video client. nyc. 👨‍💻🍎🏳️‍🌈  nf.td/payton",
      "display_name": "payton ↑",
      "homepage_url": "homepage_url",
      "profile_picture": "https://supercast.mypinata.cloud/ipfs/QmNexfCxdnFzWdJqKVgrjd27UGLMexNaw5FXu1XKR3cQF7?filename=IMG_2799.png",
      "profile_picture_url": "https://supercast.mypinata.cloud/ipfs/QmNexfCxdnFzWdJqKVgrjd27UGLMexNaw5FXu1XKR3cQF7?filename=IMG_2799.png",
      "signer_public_key": "signer_public_key",
      "username": "payton"
    },
    {
      "credential_id": "Il5vP-3Tm3hNmDVBmDlREgXzIOJnZEaiVnT-XMliXe-BufP9GL1-d3qhozk9IkZwQ_",
      "enrolled_in_mfa": true,
      "first_verified_at": 1741194420,
      "latest_verified_at": 1741194420,
      "type": "passkey",
      "verified_at": 1741194420,
      "authenticator_name": "1Password",
      "created_with_browser": "Chrome",
      "created_with_device": "Macintosh",
      "created_with_os": "Mac OS",
      "public_key": "pQECAyYgASFYIKdGwx5XxZ/7CJJzT8d5L6jyLNQdTH7X+rSZdPJ9Ux/QIlggRm4OcJ8F3aB5zYz3T9LxLdDfGpWvYkHgS4A8tPz9CqE="
    }
  ],
  "mfa_methods": [
    {
      "type": "passkey",
      "verified_at": 1741194420
    }
  ],
  "custom_metadata": {
    "foo": "string"
  }
}

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.

LinkedAccount = { address, first_verified_at, latest_verified_at, 2 more... } | { first_verified_at, latest_verified_at, phoneNumber, 3 more... } | { embedded_wallets, first_verified_at, latest_verified_at, 5 more... } | 25 more...

A linked account for the user.

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

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

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

LinkedAccountEmbeddedWallet =

LinkedAccountEthereumEmbeddedWallet

LinkedAccountSolanaEmbeddedWallet

LinkedAccountBitcoinSegwitEmbeddedWallet

| 2 more...

LinkedAccountEmbeddedWalletWithID =

LinkedAccountEthereumEmbeddedWallet

LinkedAccountSolanaEmbeddedWallet

LinkedAccountBitcoinSegwitEmbeddedWallet

| 2 more...

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

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

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

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

OAuth tokens associated with the user.

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

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

UserWithIdentityToken = { identity_token, user }

The user object along their identity token.