Bulk Import Users

Endpoints for adding users to bulk import queue

Add Users for Bulk Import

cURL

curl -X POST https://your-domain.com/bulk-import/users \
  -H "Content-Type: application/json" \
  -d '{
    "users": [
      {
        "externalUserId": "user-123",
        "userMetadata": {"plan": "premium"},
        "userRoles": ["admin"],
        "totpDevices": [],
        "loginMethods": [
          {
            "recipeId": "emailpassword",
            "email": "[e-mail]",
            "passwordHash": "$2a$11$hashed_password",
            "hashingAlgorithm": "bcrypt",
            "isPrimary": true,
            "isVerified": true,
            "timeJoinedInMSSinceEpoch": 1234567890000,
            "tenantIds": ["public"]
          }
        ]
      }
    ]
  }'

200 OK

{
  "status": "OK",
  "users": [
    {
      "id": "generated-bulk-import-id",
      "status": "NEW"
    }
  ]
}

users · array · required

Array of user objects to import (max 10,000 users)

users[].externalUserId · string

External user identifier from source system

users[].userMetadata · object

Custom user metadata as key-value pairs

users[].userRoles · array

Array of role names to assign to the user

users[].totpDevices · array

Array of TOTP device configurations

users[].loginMethods · array · required

Array of login method objects (at least one required)

users[].loginMethods[].recipeId · string · required

Recipe ID: “emailpassword”, “thirdparty”, or “passwordless”

users[].loginMethods[].email · string

Email address for the login method

users[].loginMethods[].passwordHash · string

Hashed password (for emailpassword recipe)

users[].loginMethods[].hashingAlgorithm · string

Hashing algorithm used: “bcrypt”, “argon2”, etc.

users[].loginMethods[].isPrimary · boolean

Whether this is the primary login method

users[].loginMethods[].isVerified · boolean

Whether the email/phone is verified

users[].loginMethods[].timeJoinedInMSSinceEpoch · number

Original join timestamp in milliseconds

users[].loginMethods[].tenantIds · array

Array of tenant IDs this login method belongs to

status · string

“OK”

users · array

Array of objects containing the generated bulk import ID and status for each user

users[].id · string

Generated bulk import user ID

users[].status · string

Initial status: “NEW”

---

Import User Immediately

cURL

curl -X POST https://your-domain.com/bulk-import/import \
  -H "Content-Type: application/json" \
  -d '{
    "externalUserId": "user-123",
    "userMetadata": {"plan": "premium"},
    "userRoles": ["admin"],
    "totpDevices": [],
    "loginMethods": [
      {
        "recipeId": "emailpassword",
        "email": "[e-mail]",
        "passwordHash": "$2a$11$hashed_password",
        "hashingAlgorithm": "bcrypt",
        "isPrimary": true,
        "isVerified": true,
        "timeJoinedInMSSinceEpoch": 1234567890000,
        "tenantIds": ["public"]
      }
    ]
  }'

200 OK

{
  "status": "OK",
  "user": {
    "id": "user-id",
    "isPrimaryUser": false,
    "tenantIds": ["public"],
    "emails": ["[e-mail]"],
    "phoneNumbers": [],
    "thirdParty": [],
    "loginMethods": [
      {
        "recipeId": "emailpassword",
        "recipeUserId": "recipe-user-id",
        "tenantIds": ["public"],
        "email": "[e-mail]",
        "timeJoined": 1234567890,
        "verified": true
      }
    ],
    "timeJoined": 1234567890
  }
}

* · object

Same user object structure as batch import (see above)

status · string

“OK” on success

user · object

Imported user object with all login methods and metadata

errors · array

Array of error messages if import failed