Import tasks service


Import tasks

The import tasks service provides the ability to bulk import users from a comma-separated value (csv) file. During bulk import, the entries in the import file are treated as command events in which each row of the file is processed as a separate task.

Note: User attributes such as password encoding and user state (enabled/disabled) are specified in the file. For example, if the password supplied in the file is formatted as a BCRYPT-encoded password, it is imported as a pre-encoded password. If the password is not BCRYPT formatted, it is imported as a cleartext password. For more information about pre-encoded passwords, see Set password. To enable or disable users on import, the csv file can include an enabled field that accepts the Boolean values true or false.

Note: The import tasks service requires the dir:import:user permission, which is associated with the p1:import:env:user scope. Administrators who perform bulk import tasks must have the p1:import:env:user scope encoded in their access token.

Import tasks API operations

The import tasks service supports the following endpoint operations:

For hands-on experience with the import tasks API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Import tasks data model

Property Description
file.name A string that specifies the name of the import file.
file.columns An integer that specifies the number of columns in the import file.
file.length A string that specifies the size of the import file.
id A string that specifies the resource’s unique identifier.
notifications.emails A string that specifies the notification email message.
results.created An integer that specifies the total number of users created from the import task.
results.errors The error details associated with each failure. Information includes line number, error code, target, and message text.
results.failures An integer that specifies the number of rows not processed.
results.total An integer that specifies the number of rows processed.
status A string that specifies the status of the import task job. Options are PENDING, PROCESSING, COMPLETE, and CANCELED.
users.population.id A string that specifies the population resource’s unique identifier to associate with the imported users.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
403 You lack either the necessary permissions or the licensing to perform this operation.
404 The specified object doesn’t exist.

Endpoint examples

Get import tasks

The GET /environments/{environmentId}/importTasks endpoint returns a list of all import tasks associated with the specified environment.

curl -X "GET" "https://api.pingone.com/v1/environments/{environmentId}/importTasks" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/{environmentId}/importTasks"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/{environmentId}"
        }
    },
    "_embedded": {
        "importTasks": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}"
                    },
                    "environment": {
                        "href": "https://api.pingone.com/v1/environments/{environmentId}"
                    },
                    "file": {
                        "href": "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}/file"
                    }
                },
                "id": "ab6b24ea-011c-4c70-98a8-df902236a58d",
                "status": "PROCESSING",
                "users": {
                    "population": {
                        "id": "7a83c51e-e81f-429c-8961-0f56299878fd"
                    }
                },
                "file": {
                    "name": "5000_users_to_import.csv",
                    "length": "6.7kB",
                    "columns": 6
                },
                "results": {
                    "total": 5000,
                    "created": 4913,
                    "failures": 86,
                    "errors": [
                        {
 ...

Get one import task

To get data for a single import task associated with a specified environment resource, the GET /environments/{environmentId}/importTasks/{taskId} operation returns data for the import task resource ID specified in the request URL.

curl -X GET "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"

The response data (with the errors list removed) looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}"
        },
        "file": {
            "href": "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}/file"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/{environmentId}"
        }
    },
    "id": "ab6b24ea-011c-4c70-98a8-df902236a58d",
    "status": "PROCESSING",
    "users": {
        "population": {
            "id": "7a83c51e-e81f-429c-8961-0f56299878fd"
        }
    },
    "file": {
        "name": "100000_users_to_import.csv",
        "length": "8.2kB",
        "columns": 6
    },
    "results": {
        "total": 100000,
        "created": 0,
        "failures": 0
    }
}

Create import tasks

The POST /environments/{environmentId}/importTasks operation creates a new import task resource. The request body for the POST must provide values for these properties:

  • emails

    Specifies the email address for the user, required for the notifications list.

  • users

    Identifies the populationId, which specifies the populations resource to associate with the imported user.

curl -X POST "https://api.pingone.com/v1/environments/{environmentId}/importTasks" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken"
-d "{
    "notifications": {
       "emails": [
         "<emailAddress>"
       ]
    },
    "users": {
        "population": {
            "id": "<populationId>"  
        }
    }
}"

The response data looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/{environmentId}"
        }
    },
    "id": "ab6b24ea-011c-4c70-98a8-df902236a58d",
    "status": "PENDING",
    "users": {
        "population": {
            "id": "7a83c51e-e81f-429c-8961-0f56299878fd"
        }
    }
}

Upload an import file

The POST /environments/{environmentId}/importTasks/{taskId}/file operation uploads and processes the specified csv file.

The request for this POST must include the following HTTP headers:

  • Content-Type: text/csv

    Specifies text (comma-separated values) as the input type for the file.

  • Content-Disposition: attachment; filename="<fileName>"

    Specifies an attachment, which identifies the file to be uploaded. The filename="filename.csv" parameter uses quoted string syntax.

  • Transfer-Encoding: chunked

    Divides the data stream into non-overlapping chunks. This parameter is required for any large file attachment. If omitted, the response returns a 413 Request entity too large error.

curl -X POST "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}/file" \
-H "Content-type: text/csv" \
-H "Content-Disposition: attachment; filename="<fileName>"" \
-H "Transfer-Encoding: chunked" \
-H "Authorization: Bearer jwtToken"

The response returns a 202 Accepted message and starts processing the task.

Note: A bulk user import task can process a maximum of 100,000 users or a file size of 200 MB.

Delete import tasks

You can use the DELETE /environments/{environmentId}/importTasks/{taskId} operation to delete the specified import task resource.

curl -X "DELETE" "https://api.pingone.com/v1/environments/{environmentId}/importTasks/{taskId}" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

When successful, the DELETE request returns a code 204 No Content message.