Bulk User Imports with the Management API

If you already have a user base, you can use our /post_users_imports Management API endpoint to populate a database connection with this information. The user data should first be exported in JSON format. You can then import that file using our API.

Each affected user will need to reset their password when they log in the first time after the bulk import.


Before you launch the import users job, a database (to which the users will be imported) must already exist and it must be enabled for at least one client. For more information on how to configure a database connection at your dashboard, refer to Database Identity Providers.

File schema

The users file must have an array with the users' information in JSON format. The following JSON schema describes valid users:

    "type": "object",
    "properties": {
        "email_verified": {
            "type": "boolean"
        "email": {
            "type": "string",
            "description": "The email of the user.",
            "format": "email"
        "username": {
            "type": "string",
            "description": "The username."
        "app_metadata": {
            "type": "object",
            "description": "Data related to the user that does affect the application's core functionality."
        "user_metadata": {
            "type": "object",
            "description": "Data related to the user that does not affect the application's core functionality."
    "required": ["email", "email_verified"],
    "additionalProperties": false

User app_metadata schema

Additionally, the app_metadata should not contain any of these properties:

  • clientID
  • globalClientID
  • global_client_id
  • email_verified
  • user_id
  • identities
  • lastIP
  • lastLogin
  • metadata
  • created_at
  • loginsCount
  • _id

The app_metadata stores information that can impact how an application functions or what the user can access (for example, a user's support plan or roles and access groups). For more information, refer to User Metadata.

File example

A file with the following contents is valid:

    "email": "john.doe@contoso.com",
    "email_verified": false,
    "app_metadata": {
        "roles": ["admin"],
        "plan": "premium"
    "user_metadata": {
        "theme": "light"

The file size limit for a bulk import is 500KB. You will need to start multiple imports if your data exceeds this size.

How does it work?

Using the bulk import endpoints, you should be able to request a bulk import of users to a connection, receive a response, check on a job's status, and check for details on any failed entries in your job.

Request a Bulk Import

The users import endpoint requires that your POST request be of encoding type multipart/form-data.

Your request should contain the following parameters:

Parameter Description
users The file, that containing the users to import, in JSON format.
connection_id The id of the connection to which the above users will be inserted. You can retrieve this information, using the GET /api/v2/connections endpoint.
upsert A boolean value, false by default. If it is false, users will only be inserted. If there are already user(s) with the same emails as one or more of those being inserted, they will fail. If this value is set to true and the user being imported already exists, the user will be updated with the new information.
external_id This is an optional user defined string that can be used for correlating multiple jobs, and is returned as part of the job status response.
send_completion_email A boolean value which when set to true, sends a completion email to all tenant owners when the job is finished. The default is true, so you must explicitly set this parameter to false if you do not want emails sent.

If it works, you will get a response similar to the following one:


The returned entity represents the import job.

Once the job finishes, whether it failed or was successful, the owner of the Auth0 tenant that the job is being run on will get an e-mail notifying them about the result (if send_completion_email was set to true). A notification email for a job that failed might notify the owner(s) that it failed to parse the users file JSON when importing users.

Query for Job Status

You can query a job's status using the GET /api/v2/jobs/{id} endpoint. If the job is complete, the job status response will show summary totals of successful/failed/inserted/updated records, as well. If there is an error in the job, it will return as failed (however, note that invalid user information, such as an invalid email, for example, will not make the entire job fail).

Additionally, the job status is added to Tenant Logs, which allows for a custom WebHook to be triggered using the WebHook Logs Extension.

Retrieve Failed Entries

You can query and retrieve details on failed entries via the API using the GET /api/v2/jobs/{id}/errors endpoint.

Was this article helpful?