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)

name	mandatory	type	description
type	true	"email"	N/A
address	true	string	Email address of user account.

PhoneAccount (LinkedAccount)

name	mandatory	type	description
type	true	"phone"	N/A
number	true	string	Phone number of user account (non-international numbers default to US).

WalletAccount (LinkedAccount)

name	mandatory	type	description
type	true	"wallet"	N/A
chain_type	true	"ethereum"	Ethereum is the only supported chain type at the moment.
address	true	string	Checksummed wallet address of user account.

GoogleAccount (LinkedAccount)

name	mandatory	type	description
type	true	"google_oauth"	N/A
subject	true	string	"sub" pulled from Google-provided JWT with "openid" scope.
email	true	string	"email" from Google-provided JWT with "email" scope.
name	true	string	"name" from Google-provided JWT with "profile" scope.

GithubAccount (LinkedAccount)

name	mandatory	type	description
type	true	"github_oauth"	N/A
subject	true	string	"ID" of user pulled from GitHub user API response.
email	false	string	"Email" address of user pulled from GitHub user API response.
name	false	string	"Name" of user pulled from GitHub user API response.
username	true	string	"Login" of user pulled from GitHub user API response.

(see GitHub docs)

DiscordAccount (LinkedAccount)

name	mandatory	type	description
type	true	"discord_oauth"	N/A
subject	true	string	"ID" of user pulled from Discord user API response.
email	false	string	"Email" of user pulled from Discord user API response.
username	true	string	Username of user including 4-digit discriminator prefixed by a "#" (ex: 'johndoe#1234'). Pulled from Discord user API response.

(see Discord docs)

TwitterAccount (LinkedAccount)

name	mandatory	type	description
type	true	"twitter_oauth"	N/A
subject	true	string	"ID" of user pulled from Twitter user API response.
name	true	string	"Name" of user pulled from Twitter user API response.
username	true	string	"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
    }
  ]
}