Bulk User Imports
If you already have a user database, you can use the POST /api/v2/jobs/users/post_users_imports 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.
Using the bulk import endpoints, you can:
- Request a bulk import of users to a connection and receive a response.
- Query job's status.
- Check for details on any failed entries in your job.
Prerequisites
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 application. For more information on how to configure a database connection at your dashboard, refer to Database Identity Providers. For database file schema information and examples, see Bulk Import Database Schema and Example.
Request bulk import
The users import endpoint requires that your POST request be of encoding type multipart/form-data.
Create a request that contains 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:
{
"status":"pending",
"type":"users_import",
"id":"job_abcdef1234567890",
"connection":"abcd",
"external_id":"contoso"
}
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 email 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.