---
title: "Create User"
method: POST
path: "/v1/users"
tags: ["Users"]
---

# Create User

`POST /v1/users`

Create a new user with linked accounts. Optionally pre-generate embedded wallets for the user.

## Headers

- `privy-app-id` string, required — ID of your Privy app.

## Request body

- object
  - `custom_metadata` CustomMetadata — Custom metadata associated with the user.
  - `linked_accounts` LinkedAccountInput[], required
    - union — The input for adding a linked account to a user.
      - object — The payload for importing a wallet account.
        - `address` union, required
          - string
          - string
        - `chain_type` 'ethereum' | 'solana', required — The wallet chain types that offer first class support.
        - `type` 'wallet', required
      - object — The payload for importing an email account.
        - `address` string, email, required
        - `type` 'email', required
      - object — The payload for importing a phone account.
        - `number` string, required
        - `type` 'phone', required
      - object — The payload for importing a Google account.
        - `email` string, email, required
        - `name` string, required
        - `subject` string, required
        - `type` 'google_oauth', required
      - object — The payload for importing a Twitter account.
        - `name` string, required
        - `profile_picture_url` string, uri
        - `subject` string, required
        - `type` 'twitter_oauth', required
        - `username` string, required
      - object — The payload for importing a Discord account.
        - `email` string, email
        - `subject` string, required
        - `type` 'discord_oauth', required
        - `username` string, required
      - object — The payload for importing a Github account.
        - `email` string, email
        - `name` string
        - `subject` string, required
        - `type` 'github_oauth', required
        - `username` string, required
      - object — The payload for importing a Spotify account.
        - `email` string, email
        - `name` string
        - `subject` string, required
        - `type` 'spotify_oauth', required
      - object — The payload for importing an Instagram account.
        - `subject` string, required
        - `type` 'instagram_oauth', required
        - `username` string, required
      - object — The payload for importing a Tiktok account.
        - `name` string, nullable, required
        - `subject` string, required
        - `type` 'tiktok_oauth', required
        - `username` string, required
      - object — The payload for importing a LINE account.
        - `email` string, email
        - `name` string
        - `profile_picture_url` string, uri
        - `subject` string, required
        - `type` 'line_oauth', required
      - object — The payload for importing a Twitch account.
        - `subject` string, required
        - `type` 'twitch_oauth', required
        - `username` string
      - object — The payload for importing an Apple account.
        - `email` string, email
        - `subject` string, required
        - `type` 'apple_oauth', required
      - object — The payload for importing a LinkedIn account.
        - `email` string, email
        - `name` string
        - `subject` string, required
        - `type` 'linkedin_oauth', required
        - `vanityName` string
      - object — The payload for importing a Farcaster account.
        - `bio` string
        - `display_name` string
        - `fid` integer, required
        - `homepage_url` string
        - `owner_address` string, required
        - `profile_picture_url` string
        - `type` 'farcaster', required
        - `username` string
      - object — The payload for importing a Telegram account.
        - `first_name` string
        - `last_name` string
        - `photo_url` string
        - `telegram_user_id` string, required
        - `type` 'telegram', required
        - `username` string
      - object — The payload for importing a Custom JWT account.
        - `custom_user_id` string, required
        - `type` 'custom_auth', required
      - object — The payload for importing a passkey account.
        - `credential_device_type` 'singleDevice' | 'multiDevice', required — WebAuthn credential device type indicating platform or cross-platform authenticator residency.
        - `credential_id` string, required
        - `credential_public_key` string, required
        - `credential_username` string, required
        - `type` 'passkey', required
  - `wallets` object[] — Wallets to create for the user.
    - `additional_signers` object[] — Additional signers for the wallet.
      - `override_policy_ids` string[] — The array of policy IDs that will be applied to wallet requests. If specified, this will override the base policy IDs set on the wallet. Currently, only one policy is supported per signer.
      - `signer_id` string, cuid2, required — The key quorum ID for the signer.
    - `chain_type` 'ethereum' | 'solana' | 'cosmos' | 'stellar' | 'sui' | 'aptos' | 'movement' | 'tron' | 'bitcoin-segwit' | 'bitcoin-taproot' | 'pearl' | 'near' | 'ton' | 'starknet' | 'spark', required — The wallet chain types.
    - `create_smart_wallet` boolean — Create a smart wallet with this wallet as the signer. Only supported for wallets with `chain_type: "ethereum"`.
    - `policy_ids` string[] — Policy IDs to enforce on the wallet. Currently, only one policy is supported per wallet.

## Response `200`

Newly created user object.

- User — A Privy user object.
  - `created_at` number, required — Unix timestamp of when the user was created in seconds.
  - `custom_metadata` CustomMetadata — Custom metadata associated with the user.
  - `has_accepted_terms` boolean, required — Indicates if the user has accepted the terms of service.
  - `id` string, required
  - `is_guest` boolean, required — Indicates if the user is a guest account user.
  - `linked_accounts` LinkedAccount[], required
    - union — A linked account for the user.
      - object — An email account linked to the user.
        - `address` string, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `type` 'email', required
        - `verified_at` number, required
      - object — A phone number account linked to the user.
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `number` string
        - `phoneNumber` string, required
        - `type` 'phone', required
        - `verified_at` number, required
      - object — An Ethereum wallet account linked to the user.
        - `address` string, required
        - `chain_id` string
        - `chain_type` 'ethereum', required
        - `connector_type` string
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `type` 'wallet', required
        - `verified_at` number, required
        - `wallet_client` 'unknown', required
        - `wallet_client_type` string
      - object — A Solana wallet account linked to the user.
        - `address` string, required
        - `chain_type` 'solana', required
        - `connector_type` string
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `type` 'wallet', required
        - `verified_at` number, required
        - `wallet_client` 'unknown', required
        - `wallet_client_type` string
      - object — A smart wallet account linked to the user.
        - `address` string, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `smart_wallet_type` 'safe' | 'kernel' | 'light_account' | 'biconomy' | 'coinbase_smart_wallet' | 'thirdweb' | 'nexus', required — The supported smart wallet providers.
        - `smart_wallet_version` string
        - `type` 'smart_wallet', required
        - `verified_at` number, required
      - object — An Ethereum embedded wallet account linked to the user.
        - `address` string, required
        - `chain_id` string, required
        - `chain_type` 'ethereum', required
        - `connector_type` 'embedded', required
        - `delegated` boolean, required
        - `first_verified_at` number, nullable, required
        - `id` string, nullable, required
        - `imported` boolean, required
        - `latest_verified_at` number, nullable, required
        - `recovery_method` 'privy' | 'user-passcode' | 'google-drive' | 'icloud' | 'recovery-encryption-key' | 'privy-v2', required — The method used to recover an embedded wallet account.
        - `type` 'wallet', required
        - `verified_at` number, required
        - `wallet_client` 'privy', required
        - `wallet_client_type` 'privy', required
        - `wallet_index` number, required
      - object — A Solana embedded wallet account linked to the user.
        - `address` string, required
        - `chain_id` string, required
        - `chain_type` 'solana', required
        - `connector_type` 'embedded', required
        - `delegated` boolean, required
        - `first_verified_at` number, nullable, required
        - `id` string, nullable, required
        - `imported` boolean, required
        - `latest_verified_at` number, nullable, required
        - `public_key` string, required
        - `recovery_method` 'privy' | 'user-passcode' | 'google-drive' | 'icloud' | 'recovery-encryption-key' | 'privy-v2', required — The method used to recover an embedded wallet account.
        - `type` 'wallet', required
        - `verified_at` number, required
        - `wallet_client` 'privy', required
        - `wallet_client_type` 'privy', required
        - `wallet_index` number, required
      - object — A Bitcoin SegWit embedded wallet account linked to the user.
        - `address` string, required
        - `chain_id` string, required
        - `chain_type` 'bitcoin-segwit', required
        - `connector_type` 'embedded', required
        - `delegated` boolean, required
        - `first_verified_at` number, nullable, required
        - `id` string, nullable, required
        - `imported` boolean, required
        - `latest_verified_at` number, nullable, required
        - `public_key` string, required
        - `recovery_method` 'privy' | 'user-passcode' | 'google-drive' | 'icloud' | 'recovery-encryption-key' | 'privy-v2', required — The method used to recover an embedded wallet account.
        - `type` 'wallet', required
        - `verified_at` number, required
        - `wallet_client` 'privy', required
        - `wallet_client_type` 'privy', required
        - `wallet_index` number, required
      - object — A Bitcoin Taproot embedded wallet account linked to the user.
        - `address` string, required
        - `chain_id` string, required
        - `chain_type` 'bitcoin-taproot', required
        - `connector_type` 'embedded', required
        - `delegated` boolean, required
        - `first_verified_at` number, nullable, required
        - `id` string, nullable, required
        - `imported` boolean, required
        - `latest_verified_at` number, nullable, required
        - `public_key` string, required
        - `recovery_method` 'privy' | 'user-passcode' | 'google-drive' | 'icloud' | 'recovery-encryption-key' | 'privy-v2', required — The method used to recover an embedded wallet account.
        - `type` 'wallet', required
        - `verified_at` number, required
        - `wallet_client` 'privy', required
        - `wallet_client_type` 'privy', required
        - `wallet_index` number, required
      - object — A curve signing embedded wallet account linked to the user.
        - `address` string, required
        - `chain_id` string, required
        - `chain_type` 'cosmos' | 'stellar' | 'sui' | 'aptos' | 'movement' | 'tron' | 'bitcoin-segwit' | 'bitcoin-taproot' | 'pearl' | 'near' | 'ton' | 'starknet', required — The wallet chain types that support curve-based signing.
        - `connector_type` 'embedded', required
        - `delegated` boolean, required
        - `first_verified_at` number, nullable, required
        - `id` string, nullable, required
        - `imported` boolean, required
        - `latest_verified_at` number, nullable, required
        - `public_key` string, required
        - `recovery_method` 'privy' | 'user-passcode' | 'google-drive' | 'icloud' | 'recovery-encryption-key' | 'privy-v2', required — The method used to recover an embedded wallet account.
        - `type` 'wallet', required
        - `verified_at` number, required
        - `wallet_client` 'privy', required
        - `wallet_client_type` 'privy', required
        - `wallet_index` number, required
      - object — A Google OAuth account linked to the user.
        - `email` string, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string, nullable, required
        - `subject` string, required
        - `type` 'google_oauth', required
        - `verified_at` number, required
      - object — A Twitter OAuth account linked to the user.
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string, nullable, required
        - `profile_picture_url` string, nullable, required
        - `subject` string, required
        - `type` 'twitter_oauth', required
        - `username` string, nullable, required
        - `verified_at` number, required
      - object — A Discord OAuth account linked to the user.
        - `email` string, nullable, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `subject` string, required
        - `type` 'discord_oauth', required
        - `username` string, nullable, required
        - `verified_at` number, required
      - object — A GitHub OAuth account linked to the user.
        - `email` string, nullable, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string, nullable, required
        - `subject` string, required
        - `type` 'github_oauth', required
        - `username` string, nullable, required
        - `verified_at` number, required
      - object — A Spotify OAuth account linked to the user.
        - `email` string, nullable, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string, nullable, required
        - `subject` string, required
        - `type` 'spotify_oauth', required
        - `verified_at` number, required
      - object — An Instagram OAuth account linked to the user.
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `subject` string, required
        - `type` 'instagram_oauth', required
        - `username` string, nullable, required
        - `verified_at` number, required
      - object — A TikTok OAuth account linked to the user.
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string, nullable, required
        - `subject` string, required
        - `type` 'tiktok_oauth', required
        - `username` string, nullable, required
        - `verified_at` number, required
      - object — A LINE OAuth account linked to the user.
        - `email` string, nullable, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string, nullable, required
        - `profile_picture_url` string, nullable, required
        - `subject` string, required
        - `type` 'line_oauth', required
        - `verified_at` number, required
      - object — A Twitch OAuth account linked to the user.
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `subject` string, required
        - `type` 'twitch_oauth', required
        - `username` string, nullable, required
        - `verified_at` number, required
      - object — A LinkedIn OAuth account linked to the user.
        - `email` string, nullable, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string
        - `subject` string, required
        - `type` 'linkedin_oauth', required
        - `vanity_name` string
        - `verified_at` number, required
      - object — An Apple OAuth account linked to the user.
        - `email` string, nullable, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `subject` string, required
        - `type` 'apple_oauth', required
        - `verified_at` number, required
      - object — A custom OAuth account linked to the user.
        - `email` string
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `name` string
        - `profile_picture_url` string
        - `subject` string, required
        - `type` string, required — The ID of a custom OAuth provider, set up for this app. Must start with "custom:".
        - `username` string
        - `verified_at` number, required
      - object — A custom JWT account linked to the user.
        - `custom_user_id` string, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `type` 'custom_auth', required
        - `verified_at` number, required
      - object — A Farcaster account linked to the user.
        - `bio` string
        - `display_name` string
        - `fid` number, required
        - `first_verified_at` number, nullable, required
        - `homepage_url` string
        - `latest_verified_at` number, nullable, required
        - `owner_address` string, required
        - `profile_picture` string
        - `profile_picture_url` string
        - `signer_public_key` string
        - `type` 'farcaster', required
        - `username` string
        - `verified_at` number, required
      - object — A passkey account linked to the user.
        - `authenticator_name` string
        - `created_with_browser` string
        - `created_with_device` string
        - `created_with_os` string
        - `credential_id` string, required
        - `enrolled_in_mfa` boolean, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `public_key` string
        - `type` 'passkey', required
        - `verified_at` number, required
      - object — A Telegram account linked to the user.
        - `first_name` string, nullable
        - `first_verified_at` number, nullable, required
        - `last_name` string, nullable
        - `latest_verified_at` number, nullable, required
        - `photo_url` string, nullable
        - `telegram_user_id` string, required
        - `type` 'telegram', required
        - `username` string, nullable
        - `verified_at` number, required
      - object — A cross-app account linked to the user.
        - `embedded_wallets` CrossAppEmbeddedWallet[], required
          - `address` string, required
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `provider_app_id` string, required
        - `smart_wallets` CrossAppSmartWallet[], required
          - `address` string, required
        - `subject` string, required
        - `type` 'cross_app', required
        - `verified_at` number, required
      - object — An authorization key linked to the user.
        - `first_verified_at` number, nullable, required
        - `latest_verified_at` number, nullable, required
        - `public_key` string, required
        - `type` 'authorization_key', required
        - `verified_at` number, required
  - `mfa_methods` LinkedMfaMethod[], required
    - union — A multi-factor authentication method linked to the user.
      - object — A SMS MFA method.
        - `type` 'sms', required
        - `verified_at` number, required
      - object — A TOTP MFA method.
        - `type` 'totp', required
        - `verified_at` number, required
      - object — A Passkey MFA method.
        - `type` 'passkey', required
        - `verified_at` number, required

---

[API](https://skmtc.net/privy-io/apis/privy-api.md) · [All operations](https://skmtc.net/privy-io/apis/privy-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/privy-io/privy-api/versions/bb2eb34156cc/schema)