Importing a single user

Privy allows you to import a single user into your Privy app. If you'd prefer, you can also import users in bulk.

Using @privy-io/server-auth

Use the PrivyClient's importUser method to import a single user into your Privy app.

const user = await privy.importUser({
  linkedAccounts: [
    {
      type: 'email',
      address: '[email protected]',
    },
  ],
  createEmbeddedWallet: true,
});

As a parameter to the method, pass an ImportUserInput object with the following fields:

Field	Type	Description
linkedAccounts	LinkedAccount[]	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.
createEmbeddedWallet	boolean	(Optional) Whether to pregenerate an embedded wallet for the imported user. Defaults to false.

Using the REST API

Make a POST request to:

https://auth.privy.io/api/v1/users

In the body of the request, include the following fields:

• linked_accounts: (required) a list of LinkedAccount objects. See the types for this object below.
• create_embedded_wallet: (optional) a boolean indicating whether to pregenerate an embedded wallet for this user. Defaults to false.

INFO

User import endpoints have heavier rate limit of 240 users in total 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.

 See the types for LinkedAccount objects

Note:

• Each account should be a JSON object including all the necessary fields for that account type. Valid account types are 'custom_jwt', 'discord_oauth', 'farcaster', 'github_oauth', 'google_oauth', 'instagram_oauth', 'linkedin_oauth', 'spotify_oauth', 'telegram_oauth', 'twitter_oauth', 'email', 'phone' and 'wallet'. See below for what additional information for each account type. Please exclude the verifiedAt field.
• If importing a user with a custom_jwt account, the custom_jwt account must be the only element of the linked_accounts array. It is not permitted to import a user with a custom_jwt account and other linked_accounts.

CustomJwtAccount extends LinkedAccount

Field	Type	Description
type	'custom_jwt'	N/A
custom_id	string	ID of user from Twitter user API response.

DiscordAccount extends LinkedAccount

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 extends LinkedAccount

Field	Type	Description
type	'email'	N/A
address	string	Email address of user account.

FarcasterAccount extends LinkedAccount

Field	Type	Description
type	'farcaster'	N/A
fid	string	FID of the user from Farcaster user API response.
owner_address	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 '@'.
display_name	string	(Optional) Display name of user from Farcaster user API response.
bio	string	(Optional) Bio of user from Farcaster user API response.
profile_picture_url	string	(Optional) Profile picture URL of the user from Farcaster user API response. Must be a valid image URL.
homepage_url	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 extends LinkedAccount

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 extends LinkedAccount

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 extends LinkedAccount

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 extends LinkedAccount

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 extends LinkedAccount

Field	Type	Description
type	'email'	N/A
number	true	Phone number of user account (non-international numbers default to US).

SpotifyAccount extends LinkedAccount

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 extends LinkedAccount

Field	Type	Description
type	'telegram_oauth'	N/A
subject	string	ID of user from Telegram user API response.
first_name	string	The name displayed on a user's telegram account.
username	string	(Optional) The username displayed on a user's telegram account.

(See Telegram docs)

TwitterAccount extends LinkedAccount

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 '@'.
profile_picture_url	string	(Optional) Profile picture URL of the user from Twitter user API response. Must be a valid image URL.

(See Twitter docs)

WalletAccount extends LinkedAccount

Field	Type	Description
type	'wallet'	N/A
chain_type	'ethereum'	Type of chain for the wallet. Only EVM chains ('ethereum') are currently supported.
address	string	Checksummed wallet address.

---

Below is a sample cURL command for importing a new user into Privy:

$ curl --request POST https://auth.privy.io/api/v1/users \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-d '{
  "linked_accounts": [
    {
      "subject": "1234567890",
      "username": "batman#1234",
      "email": "[email protected]",
      "type": "discord_oauth"
    },
    {
      "number": "+1 123 456 7890",
      "type": "phone"
    },
    {
      "subject": "1234567890",
      "email": "[email protected]",
      "name": "Bruce Wayne",
      "type": "google_oauth"
    },
    {
      "address": "[email protected]",
      "type": "email"
    },
    {
      "address": "0x3DAF84b3f09A0E2092302F7560888dBc0952b7B7",
      "type": "wallet",
      "chain_type": "ethereum"  # "ethereum" is the only valid value for chain_type
    },
    {
      "subject": "1234567890",
      "username": "batman",
      "name": "Batman",
      "type": "twitter_oauth"
    },
    {
      "subject": "1234567890",
      "username": "joker",
      "name": "Joker",
      "type": "github_oauth",
    }
  ]
}'

A successful response will include the new user object along with their DID, like below. 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 a pregenerated embedded wallet, that wallet will be available to the user upon sign in.

Below is a sample successful response for importing a new user into Privy:

{
	"id": "did:privy:clddy332f002tyqpq3b3lv327",
	"created_at": 1674788927,
	"linked_accounts": [
    {
      "subject": "1234567890",
      "username": "batman#1234",
      "email": "[email protected]",
      "type": "discord_oauth",
      "verified_at": 1674788927
    },
   ...
    {
      "subject": "1234567890",
      "username": "joker",
      "name": "Joker",
      "type": "github_oauth",
      "verified_at": 1674788927
    }
  ]
}