Import a batch of users
Privy allows you to import your users in batches via REST API to simplify the migration process. To import users, pass in an array of user objects which each represent a new user. You can also create wallets during import with wallet pregeneration.
Once a user has been imported into Privy, if they log in, all of their imported accounts (wallet, email, etc.) will be included in their user object. If the imported user has an embedded wallet, that wallet will be available to the user upon sign in.
Make a POST
request to:
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 importing multiple new users into Privy:
Parameters
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.
LinkedAccount types
LinkedAccount types
AppleAccount
AppleAccount
Field | Type | Description |
---|---|---|
type | 'apple_oauth' | N/A |
email | string | Email address associated with the user’s Apple account. |
subject | number | ID of user from Apple’s user API. |
CustomJwtAccount
CustomJwtAccount
Field | Type | Description |
---|---|---|
type | 'custom_auth' | N/A |
API: custom_user_id SDK: customUserId | string | ID of user from custom auth provider. |
DiscordAccount
DiscordAccount
Field | Type | Description |
---|---|---|
type | 'discord_oauth' | N/A |
subject | string | ID of user from Discord user API response. |
email | string | Email of user from Discord user API response |
username | string | Username of user from Discord user API response. Include the 4-digit discriminator prefixed by ’#’. |
(See Discord docs)
EmailAccount
EmailAccount
Field | Type | Description |
---|---|---|
type | 'email' | N/A |
address | string | Email address of user account. |
FarcasterAccount
FarcasterAccount
Field | Type | Description |
---|---|---|
type | 'farcaster' | N/A |
fid | number | FID of the user from Farcaster user API response. |
API: owner_address SDK: ownerAddress | string | Wallet address of the user from Farcaster user API response. Note that this is the Farcaster wallet address, and not the Privy embedded wallet address. |
username | string | (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. |
bio | string | (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.)
GithubAccount
GithubAccount
Field | Type | Description |
---|---|---|
type | 'github_oauth' | N/A |
subject | string | ID of user from GitHub user API response. |
email | string | Email of user from GitHub user API response |
name | string | Name of user from GitHub user API response |
username | string | Username of user from GitHub user API response |
(See GitHub docs)
GoogleAccount
GoogleAccount
Field | Type | Description |
---|---|---|
type | 'google_oauth' | N/A |
subject | string | sub pulled from Google-provided JWT with “openid” scope. |
email | string | email from Google-provided JWT with “email” scope. |
name | string | name from Google-provided JWT with “profile” scope. |
InstagramAccount
InstagramAccount
Field | Type | Description |
---|---|---|
type | 'instagram_oauth' | N/A |
subject | string | ID of user from Instagram user API response. |
username | string | The name displayed on a user’s profile from Instagram’s /me API response. |
(See Instagram docs)
LinkedinAccount
LinkedinAccount
Field | Type | Description |
---|---|---|
type | 'linkedin_oauth' | N/A |
subject | string | ID of user from LinkedIn user API response. |
email | string | Email of user from LinkedIn user API response |
name | string | Name of user from LinkedIn user API response. Do not include the ’@’. |
(See Linkedin docs)
PhoneAccount
PhoneAccount
Field | Type | Description |
---|---|---|
type | 'phone' | N/A |
number | string | Phone number of user account (non-international numbers default to US). |
While number
is accepted as input, phoneNumber
is returned in the response.
SpotifyAccount
SpotifyAccount
Field | Type | Description |
---|---|---|
type | 'spotify_oauth' | N/A |
subject | string | ID of user from Spotify user API response. |
email | string | Email of user from Spotify user API. |
name | string | The name displayed on a user’s profile from Spotify display_name API response. |
(See Spotify docs)
TelegramAccount
TelegramAccount
Field | Type | Description |
---|---|---|
type | 'telegram' | N/A |
telegramUserId | string | ID of a user’s telegram account. |
firstName | string | The first name displayed on a user’s telegram account. |
lastName | string | (Optional) The last name displayed on a user’s telegram account. |
username | string | (Optional) The username displayed on a user’s telegram account. |
photo_url | string | (Optional) The url of a user’s telegram account profile picture. |
(See Telegram docs)
TwitterAccount
TwitterAccount
Field | Type | Description |
---|---|---|
type | 'twitter_oauth' | N/A |
subject | string | ID of user from Twitter user API response. |
name | string | Name of user from Twitter user API response |
username | string | Username of user from Twitter user API response. Do not include the ’@’. |
API: profile_picture_url<br/> SDK: profilePictureUrl | string | (Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL. |
(See Twitter docs)
SmartWalletAccount
SmartWalletAccount
Field | Type | Description |
---|---|---|
type | 'smart_wallet' | N/A |
address | string | Checksummed smart wallet address. |
smart_wallet_type | SmartWalletType | One of 'kernel' , 'safe' , 'biconomy' , 'thirdweb' , 'light_account' or 'coinbase_smart_wallet' |
WalletAccount
WalletAccount
Field | Type | Description |
---|---|---|
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. |
address | string | Checksummed wallet address. |
(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 imports succeeded and which failed:
Each result in the response includes:
The action taken (“create”).
The index of the user in the request array.
Whether the import succeeded.
The Privy DID of the created user (if successful).
Error code (if unsuccessful).
Error message (if unsuccessful).
The conflicting DID (if there was an account conflict).
Make a POST
request to:
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 importing multiple new users into Privy:
Parameters
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.
LinkedAccount types
LinkedAccount types
AppleAccount
AppleAccount
Field | Type | Description |
---|---|---|
type | 'apple_oauth' | N/A |
email | string | Email address associated with the user’s Apple account. |
subject | number | ID of user from Apple’s user API. |
CustomJwtAccount
CustomJwtAccount
Field | Type | Description |
---|---|---|
type | 'custom_auth' | N/A |
API: custom_user_id SDK: customUserId | string | ID of user from custom auth provider. |
DiscordAccount
DiscordAccount
Field | Type | Description |
---|---|---|
type | 'discord_oauth' | N/A |
subject | string | ID of user from Discord user API response. |
email | string | Email of user from Discord user API response |
username | string | Username of user from Discord user API response. Include the 4-digit discriminator prefixed by ’#’. |
(See Discord docs)
EmailAccount
EmailAccount
Field | Type | Description |
---|---|---|
type | 'email' | N/A |
address | string | Email address of user account. |
FarcasterAccount
FarcasterAccount
Field | Type | Description |
---|---|---|
type | 'farcaster' | N/A |
fid | number | FID of the user from Farcaster user API response. |
API: owner_address SDK: ownerAddress | string | Wallet address of the user from Farcaster user API response. Note that this is the Farcaster wallet address, and not the Privy embedded wallet address. |
username | string | (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. |
bio | string | (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.)
GithubAccount
GithubAccount
Field | Type | Description |
---|---|---|
type | 'github_oauth' | N/A |
subject | string | ID of user from GitHub user API response. |
email | string | Email of user from GitHub user API response |
name | string | Name of user from GitHub user API response |
username | string | Username of user from GitHub user API response |
(See GitHub docs)
GoogleAccount
GoogleAccount
Field | Type | Description |
---|---|---|
type | 'google_oauth' | N/A |
subject | string | sub pulled from Google-provided JWT with “openid” scope. |
email | string | email from Google-provided JWT with “email” scope. |
name | string | name from Google-provided JWT with “profile” scope. |
InstagramAccount
InstagramAccount
Field | Type | Description |
---|---|---|
type | 'instagram_oauth' | N/A |
subject | string | ID of user from Instagram user API response. |
username | string | The name displayed on a user’s profile from Instagram’s /me API response. |
(See Instagram docs)
LinkedinAccount
LinkedinAccount
Field | Type | Description |
---|---|---|
type | 'linkedin_oauth' | N/A |
subject | string | ID of user from LinkedIn user API response. |
email | string | Email of user from LinkedIn user API response |
name | string | Name of user from LinkedIn user API response. Do not include the ’@’. |
(See Linkedin docs)
PhoneAccount
PhoneAccount
Field | Type | Description |
---|---|---|
type | 'phone' | N/A |
number | string | Phone number of user account (non-international numbers default to US). |
While number
is accepted as input, phoneNumber
is returned in the response.
SpotifyAccount
SpotifyAccount
Field | Type | Description |
---|---|---|
type | 'spotify_oauth' | N/A |
subject | string | ID of user from Spotify user API response. |
email | string | Email of user from Spotify user API. |
name | string | The name displayed on a user’s profile from Spotify display_name API response. |
(See Spotify docs)
TelegramAccount
TelegramAccount
Field | Type | Description |
---|---|---|
type | 'telegram' | N/A |
telegramUserId | string | ID of a user’s telegram account. |
firstName | string | The first name displayed on a user’s telegram account. |
lastName | string | (Optional) The last name displayed on a user’s telegram account. |
username | string | (Optional) The username displayed on a user’s telegram account. |
photo_url | string | (Optional) The url of a user’s telegram account profile picture. |
(See Telegram docs)
TwitterAccount
TwitterAccount
Field | Type | Description |
---|---|---|
type | 'twitter_oauth' | N/A |
subject | string | ID of user from Twitter user API response. |
name | string | Name of user from Twitter user API response |
username | string | Username of user from Twitter user API response. Do not include the ’@’. |
API: profile_picture_url<br/> SDK: profilePictureUrl | string | (Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL. |
(See Twitter docs)
SmartWalletAccount
SmartWalletAccount
Field | Type | Description |
---|---|---|
type | 'smart_wallet' | N/A |
address | string | Checksummed smart wallet address. |
smart_wallet_type | SmartWalletType | One of 'kernel' , 'safe' , 'biconomy' , 'thirdweb' , 'light_account' or 'coinbase_smart_wallet' |
WalletAccount
WalletAccount
Field | Type | Description |
---|---|---|
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. |
address | string | Checksummed wallet address. |
(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 imports succeeded and which failed:
Each result in the response includes:
The action taken (“create”).
The index of the user in the request array.
Whether the import succeeded.
The Privy DID of the created user (if successful).
Error code (if unsuccessful).
Error message (if unsuccessful).
The conflicting DID (if there was an account conflict).
User import 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.