Skip to main content

Importing a user

You can easily import data for your existing users into Privy. This allows your users to interact with all their linked accounts normally after your migration to Privy.

To import an existing user record into Privy, make a POST request to https://auth.privy.io/api/v1/users.

In the request body, include the following parameters:

  • linked_accounts: a list of LinkedAccount objects.
LinkedAccount Type Definitions

Note: each account should be a JSON object including all the necessary fields for that account type. Valid account types are 'wallet', 'email', 'phone', 'discord_oauth', 'github_oauth', 'twitter_oauth', and 'google_oauth'. For more details, see the pages linked for each account type to determine what fields to include. Please exclude the verifiedAt field.

EmailAccount (LinkedAccount)

namemandatorytypedescription
typetrue"email"N/A
addresstruestringEmail address of user account.

PhoneAccount (LinkedAccount)

namemandatorytypedescription
typetrue"phone"N/A
numbertruestringPhone number of user account (non-international numbers default to US).

WalletAccount (LinkedAccount)

namemandatorytypedescription
typetrue"wallet"N/A
chain_typetrue"ethereum"Ethereum is the only supported chain type at the moment.
addresstruestringChecksummed wallet address of user account.

GoogleAccount (LinkedAccount)

namemandatorytypedescription
typetrue"google_oauth"N/A
subjecttruestring"sub" pulled from Google-provided JWT with "openid" scope.
emailtruestring"email" from Google-provided JWT with "email" scope.
nametruestring"name" from Google-provided JWT with "profile" scope.

GithubAccount (LinkedAccount)

namemandatorytypedescription
typetrue"github_oauth"N/A
subjecttruestring"ID" of user pulled from GitHub user API response.
emailfalsestring"Email" address of user pulled from GitHub user API response.
namefalsestring"Name" of user pulled from GitHub user API response.
usernametruestring"Login" of user pulled from GitHub user API response.

(see GitHub docs)

DiscordAccount (LinkedAccount)

namemandatorytypedescription
typetrue"discord_oauth"N/A
subjecttruestring"ID" of user pulled from Discord user API response.
emailfalsestring"Email" of user pulled from Discord user API response.
usernametruestringUsername of user including 4-digit discriminator prefixed by a "#" (ex: 'johndoe#1234'). Pulled from Discord user API response.

(see Discord docs)

TwitterAccount (LinkedAccount)

namemandatorytypedescription
typetrue"twitter_oauth"N/A
subjecttruestring"ID" of user pulled from Twitter user API response.
nametruestring"Name" of user pulled from Twitter user API response.
usernametruestring"Username" of user (do NOT include the "@") pulled from Twitter user API response.

(see Twitter docs)

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.

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
}
]
}