Skip to main content
To import existing users, Privy allows you to create users with their linked accounts (wallet, email, etc.) in batches via REST API to simplify the migration process. To create users, pass in an array of user objects which each represent a new user. You can also create wallets with wallet pregeneration. Once a user has been created, all of their accounts (wallet, email, etc.) will be included in their user object when they log in. If the user has an embedded wallet, that wallet will be available to the user upon sign in.
  • REST API
Make a POST request to:
https://auth.privy.io/api/v1/users/import
In the body of the request, include a users field with an array of up to 20 user objects.Below is a sample cURL command for creating multiple new users:
$ curl --request POST https://auth.privy.io/api/v1/users/import \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H "Content-Type: application/json" \
-d '{
   "users": [
       {
           "linked_accounts": [
               {
                   "type": "email",
                   "address": "[email protected]"
               }
           ]
       },
       {
           "linked_accounts": [
               {
                   "type": "wallet",
                   "chain_type": "ethereum",
                   "address": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045"
               }
           ]
       },
       {
           "linked_accounts": [
               {
                   "type": "email",
                   "address": "[email protected]"
               }
           ]
       }
   ]
}'

Parameters

linked_accounts
LinkedAccount[]
required
An array including all of the user’s linked accounts. These objects are in the same shape as the linked accounts returned by getUser. For each linked account, you must specify the type and must not include a verifiedAt timestamp.
FieldTypeDescription
type'apple_oauth'N/A
emailstringEmail address associated with the user’s Apple account.
subjectnumberID of user from Apple’s user API.
FieldTypeDescription
type'custom_auth'N/A
API: custom_user_id
SDK: customUserId
stringID of user from custom auth provider.
FieldTypeDescription
type'discord_oauth'N/A
subjectstringID of user from Discord user API response.
emailstringEmail of user from Discord user API response
usernamestringUsername of user from Discord user API response. Include the 4-digit discriminator prefixed by ’#’.
(See Discord docs)
FieldTypeDescription
type'email'N/A
addressstringEmail address of user account.
FieldTypeDescription
type'farcaster'N/A
fidnumberFID of the user from Farcaster user API response.
API: owner_address
SDK: ownerAddress
stringWallet address of the user from Farcaster user API response. Note that this is the Farcaster wallet address, and not the Privy embedded wallet address.
usernamestring(Optional) Username of user from Farcaster user API response. Do not include the ’@’.
API: display_name
SDK: displayName
string(Optional) Display name of user from Farcaster user API response.
biostring(Optional) Bio of user from Farcaster user API response.
API: profile_picture_url
SDK: profilePictureUrl
string(Optional) Profile picture URL of the user from Farcaster user API response. Must be a valid image URL.
API: homepage_url
SDK: homepageUrl
string(Optional) Profile URL of the user from Farcaster user API response.
(See Farcaster docs. Note that the Privy import interface differs slightly from the Farcaster public interface in order to maintain consistency with other Privy LinkedAccount types.)
FieldTypeDescription
type'github_oauth'N/A
subjectstringID of user from GitHub user API response.
emailstringEmail of user from GitHub user API response
namestringName of user from GitHub user API response
usernamestringUsername of user from GitHub user API response
(See GitHub docs)
FieldTypeDescription
type'google_oauth'N/A
subjectstringsub pulled from Google-provided JWT with “openid” scope.
emailstringemail from Google-provided JWT with “email” scope.
namestringname from Google-provided JWT with “profile” scope.
FieldTypeDescription
type'instagram_oauth'N/A
subjectstringID of user from Instagram user API response.
usernamestringThe name displayed on a user’s profile from Instagram’s /me API response.
(See Instagram docs)
FieldTypeDescription
type'linkedin_oauth'N/A
subjectstringID of user from LinkedIn user API response.
emailstringEmail of user from LinkedIn user API response
namestringName of user from LinkedIn user API response. Do not include the ’@’.
(See Linkedin docs)
FieldTypeDescription
type'phone'N/A
numberstringPhone number of user account (non-international numbers default to US).
While number is accepted as input, phoneNumber is returned in the response.
FieldTypeDescription
type'spotify_oauth'N/A
subjectstringID of user from Spotify user API response.
emailstringEmail of user from Spotify user API.
namestringThe name displayed on a user’s profile from Spotify display_name API response.
(See Spotify docs)
FieldTypeDescription
type'telegram'N/A
telegramUserIdstringID of a user’s telegram account.
firstNamestringThe first name displayed on a user’s telegram account.
lastNamestring(Optional) The last name displayed on a user’s telegram account.
usernamestring(Optional) The username displayed on a user’s telegram account.
photo_urlstring(Optional) The url of a user’s telegram account profile picture.
(See Telegram docs)
FieldTypeDescription
type'twitter_oauth'N/A
subjectstringID of user from Twitter user API response.
namestringName of user from Twitter user API response
usernamestringUsername of user from Twitter user API response. Do not include the ’@’.
API: profile_picture_url<br/>SDK: profilePictureUrlstring(Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL.
(See Twitter docs)
FieldTypeDescription
type'smart_wallet'N/A
addressstringChecksummed smart wallet address.
smart_wallet_typeSmartWalletTypeOne of 'kernel', 'safe', 'biconomy', 'thirdweb', 'light_account' or 'coinbase_smart_wallet'
FieldTypeDescription
type'wallet'N/A
API:chain_type
SDK: chainType
'ethereum' | 'solana'Type of chain for the wallet. EVM chains ('ethereum') and Solana ('solana') are currently supported.
addressstringChecksummed wallet address.
wallets
WalletCreateRequestType[]
(Optional) An array of wallets to create for the user.

Response Format

A successful response will include a list of results along with details about which succeeded and which failed:
{
  "results": [
    {
      "action": "create",
      "index": 0,
      "success": true,
      "id": "did:privy:clfn2wysq01ijykc8gyq2j2t1"
    },
    {
      "action": "create",
      "index": 1,
      "success": false,
      "code": 101,
      "error": "Account conflict caused by an existing user. Multiple users cannot share the same account.",
      "cause": "did:privy:clfmxole300rmykc89nojp3v2"
    },
    {
      "action": "create",
      "index": 2,
      "success": true,
      "id": "did:privy:clfn2wysq01ijykc8gyq2j2t3"
    }
  ]
}
Each result in the response includes:
action
string
The action taken (“create”).
index
number
The index of the user in the request array.
success
boolean
Whether the user creation succeeded.
id
string
The Privy DID of the user (if successful).
code
number
Error code (if unsuccessful).
error
string
Error message (if unsuccessful).
cause
string
The conflicting DID (if there was an account conflict).
User creation endpoints have a rate limit of 240 users per minute. If you are being rate limited, responses will have status code 429. We suggest you set up exponential back-offs starting at 1 second to seamlessly recover.