--- title: Create User (Import) description: The import users operation gives privileged applications the ability to create a new user and set the user's password. The password attribute in this operation uses the same format for specifying passwords as the set password request, allowing both cleartext and pre-encoded password values. Refer to Password encoding for our supported encodings for passwords. component: pingone-api page_id: pingone-api:platform:users/users-1/create-user-import canonical_url: https://developer.pingidentity.com/pingone-api/platform/users/users-1/create-user-import.html section_ids: prerequisites: Prerequisites headers: Headers body: Body example-request: Example Request example-response: Example Response --- # Create User (Import) ## ```none POST {{apiPath}}/v1/environments/{{envID}}/users ``` The import users operation gives privileged applications the ability to create a new user and set the user's password. The `password` attribute in this operation uses the same format for specifying passwords as the [set password](../user-passwords/update-password-set.html) request, allowing both cleartext and pre-encoded password values. Refer to [Password encoding](../../reference/password-encoding.html) for our supported encodings for passwords. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This request does not address bulk user import operations. For information about using the PingOne User Import Tool, refer to [PingIdentity PingOne User Import Tool](https://github.com/pingidentity/pingone-user-import-tool). | The `POST {{apiPath}}/v1/environments/{{envID}}/users` operation imports a new user resource to the specified environment. This operation uses the `application/vnd.pingidentity.user.import+json` custom content type in the request header. New users must be assigned to a `population` resource identified by its ID, and the request must set a value for the `username` attribute. In addition, this operation supports the `password` attribute, which can accept a pre-encoded password value and a `forceChange` value of false. The `username` attribute must be unique to an environment (spanning populations). Access to populations is determined by roles. It's possible that `username` conflicts may arise, if you or your worker application attempt to create a user that exists in a population to which you have no access. You can set a read-only `emailVerified` flag to initiate the email verification workflow. This flag can be set to `true` or `false` for the Create User (Import) operation. For the [Create User](create-user.html) operation, the flag can only be set to `false`. If a user's `emailVerified` flag is set to `false` and they run the [Verify User](verify-user-1.html) operation or [Verify Email (Code)](../user-email-verification/verify-email-code.html) operation, the flag will be set to `true`. Optionally, you can set the `lifecycle.status` property to `VERIFICATION_REQUIRED` and the `lifecycle.suppressVerificationCode` property to `false` if you want the user to receive a verification email automatically. For this use case, you must provide a valid `email` address for the imported user. The user's `verifyStatus` property is returned as `NOT_INITIATED` and remains in that state until the user verifies the account. New users who are not authenticating with PingOne must be assigned an identity provider with the `identityProvider.id` attribute. If `identityProvider.id` is not provided, PingOne is set as the default identity provider. The `identityProvider.type` value is read-only, and its value is dependent on the value of `identityProvider.id`. If `identityProvider.id` is not provided, the default value of `identityProvider.type` is PING\_ONE. If you're authenticating using an external gateway, the `identityProvider.id` attribute must be null. Refer to [Gateway Management](../../gateway-management.html) for more information about external gateways. When a user is imported you can add correlation attributes that will get sent as as the link attributes value. For example if you had correlationAttributes.customAttribute1 and you set the link attribute to customAttribute1, the value in the correlationAttributes is used to identify the user in the remote directory. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | You can enable multi-factor authentication by setting `mfaEnabled` to `true` with [POST Create User](create-user.html), [POST Create User (Import)](create-user-import.html), or [PUT Update User MFA Enabled](../../../mfa/users/enable-users-mfa/update-user-mfa-enabled.html). You cannot update `mfaEnabled` with [PUT Update User](update-user-put.html) or [PATCH Update User](update-user-patch.html). | If successful, the response returns a `201 Successfully created` message and shows the new user resource's property data. ### Prerequisites * Refer to [Users](../../users.html) and [User Operations](../users-1.html) for important overview information. * Create a population to get a `popID`. Refer to [Create Population](../../populations/create-population.html). Run [Read All Populations](../../populations/read-all-populations.html) to find an existing population. > **Collapse: Request Model** > > | Property | Type | Required? | > | ------------------------------------ | ------- | --------- | > | `email` | String | Optional | > | `name.given` | String | Optional | > | `name.family` | String | Optional | > | `population.id` | String | Optional | > | `lifecycle.status` | String | Optional | > | `lifecycle.suppressVerificationCode` | Boolean | Optional | > | `username` | String | Required | > | `password.value` | String | Optional | > | `password.forceChange` | Boolean | Optional | > > Refer to the [User operations](../users-1.html) data model for full property descriptions. ### Headers Authorization      Bearer {{accessToken}} Content-Type      application/vnd.pingidentity.user.import+json ### Body raw ( application/vnd.pingidentity.user.import+json ) ```json { "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": false }, "username": "import-user_{{$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": false } } ``` ## ### Example Request * cURL * C# * Go * HTTP * Java * jQuery * NodeJS * Python * PHP * Ruby * Swift ```shell curl --location --globoff '{{apiPath}}/v1/environments/{{envID}}/users' \ --header 'Content-Type: application/vnd.pingidentity.user.import+json' \ --header 'Authorization: Bearer {{accessToken}}' \ --data '{ "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": false }, "username": "import-user_{{$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": false } }' ``` ```csharp var options = new RestClientOptions("{{apiPath}}/v1/environments/{{envID}}/users") { MaxTimeout = -1, }; var client = new RestClient(options); var request = new RestRequest("", Method.Post); request.AddHeader("Content-Type", "application/vnd.pingidentity.user.import+json"); request.AddHeader("Authorization", "Bearer {{accessToken}}"); var body = @"{" + "\n" + @" ""email"": ""{{email}}""," + "\n" + @" ""name"": {" + "\n" + @" ""given"": ""Test""," + "\n" + @" ""family"": ""User""" + "\n" + @" }," + "\n" + @" ""population"": {" + "\n" + @" ""id"": ""{{popID}}""" + "\n" + @" }," + "\n" + @" ""lifecycle"": {" + "\n" + @" ""status"": ""VERIFICATION_REQUIRED""," + "\n" + @" ""suppressVerificationCode"": false" + "\n" + @" }," + "\n" + @" ""username"": ""import-user_{{$timestamp}}""," + "\n" + @" ""password"": {" + "\n" + @" ""value"": ""{{userPassword}}""," + "\n" + @" ""forceChange"": false" + "\n" + @" }" + "\n" + @"}"; request.AddStringBody(body, DataFormat.Json); RestResponse response = await client.ExecuteAsync(request); Console.WriteLine(response.Content); ``` ```golang package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "{{apiPath}}/v1/environments/{{envID}}/users" method := "POST" payload := strings.NewReader(`{ "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": false }, "username": "import-user_{{$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": false } }`) client := &http.Client { } req, err := http.NewRequest(method, url, payload) if err != nil { fmt.Println(err) return } req.Header.Add("Content-Type", "application/vnd.pingidentity.user.import+json") req.Header.Add("Authorization", "Bearer {{accessToken}}") res, err := client.Do(req) if err != nil { fmt.Println(err) return } defer res.Body.Close() body, err := io.ReadAll(res.Body) if err != nil { fmt.Println(err) return } fmt.Println(string(body)) } ``` ```http POST /v1/environments/{{envID}}/users HTTP/1.1 Host: {{apiPath}} Content-Type: application/vnd.pingidentity.user.import+json Authorization: Bearer {{accessToken}} { "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": false }, "username": "import-user_{{$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": false } } ``` ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/vnd.pingidentity.user.import+json"); RequestBody body = RequestBody.create(mediaType, "{\n \"email\": \"{{email}}\",\n \"name\": {\n \"given\": \"Test\",\n \"family\": \"User\"\n },\n \"population\": {\n \"id\": \"{{popID}}\"\n },\n \"lifecycle\": {\n \"status\": \"VERIFICATION_REQUIRED\",\n \"suppressVerificationCode\": false\n },\n \"username\": \"import-user_{{$timestamp}}\",\n \"password\": {\n \"value\": \"{{userPassword}}\",\n \"forceChange\": false\n }\n}"); Request request = new Request.Builder() .url("{{apiPath}}/v1/environments/{{envID}}/users") .method("POST", body) .addHeader("Content-Type", "application/vnd.pingidentity.user.import+json") .addHeader("Authorization", "Bearer {{accessToken}}") .build(); Response response = client.newCall(request).execute(); ``` ```javascript var settings = { "url": "{{apiPath}}/v1/environments/{{envID}}/users", "method": "POST", "timeout": 0, "headers": { "Content-Type": "application/vnd.pingidentity.user.import+json", "Authorization": "Bearer {{accessToken}}" }, "data": JSON.stringify({ "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": false }, "username": "import-user_{{$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": false } }), }; $.ajax(settings).done(function (response) { console.log(response); }); ``` ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': '{{apiPath}}/v1/environments/{{envID}}/users', 'headers': { 'Content-Type': 'application/vnd.pingidentity.user.import+json', 'Authorization': 'Bearer {{accessToken}}' }, body: JSON.stringify({ "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": false }, "username": "import-user_{{$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": false } }) }; request(options, function (error, response) { if (error) throw new Error(error); console.log(response.body); }); ``` ```python import requests import json url = "{{apiPath}}/v1/environments/{{envID}}/users" payload = json.dumps({ "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": False }, "username": "import-user_{{$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": False } }) headers = { 'Content-Type': 'application/vnd.pingidentity.user.import+json', 'Authorization': 'Bearer {{accessToken}}' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text) ``` ```php setUrl('{{apiPath}}/v1/environments/{{envID}}/users'); $request->setMethod(HTTP_Request2::METHOD_POST); $request->setConfig(array( 'follow_redirects' => TRUE )); $request->setHeader(array( 'Content-Type' => 'application/vnd.pingidentity.user.import+json', 'Authorization' => 'Bearer {{accessToken}}' )); $request->setBody('{\n "email": "{{email}}",\n "name": {\n "given": "Test",\n "family": "User"\n },\n "population": {\n "id": "{{popID}}"\n },\n "lifecycle": {\n "status": "VERIFICATION_REQUIRED",\n "suppressVerificationCode": false\n },\n "username": "import-user_{{$timestamp}}",\n "password": {\n "value": "{{userPassword}}",\n "forceChange": false\n }\n}'); try { $response = $request->send(); if ($response->getStatus() == 200) { echo $response->getBody(); } else { echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' . $response->getReasonPhrase(); } } catch(HTTP_Request2_Exception $e) { echo 'Error: ' . $e->getMessage(); } ``` ```ruby require "uri" require "json" require "net/http" url = URI("{{apiPath}}/v1/environments/{{envID}}/users") http = Net::HTTP.new(url.host, url.port); request = Net::HTTP::Post.new(url) request["Content-Type"] = "application/vnd.pingidentity.user.import+json" request["Authorization"] = "Bearer {{accessToken}}" request.body = JSON.dump({ "email": "{{email}}", "name": { "given": "Test", "family": "User" }, "population": { "id": "{{popID}}" }, "lifecycle": { "status": "VERIFICATION_REQUIRED", "suppressVerificationCode": false }, "username": "import-user_{{\$timestamp}}", "password": { "value": "{{userPassword}}", "forceChange": false } }) response = http.request(request) puts response.read_body ``` ```swift let parameters = "{\n \"email\": \"{{email}}\",\n \"name\": {\n \"given\": \"Test\",\n \"family\": \"User\"\n },\n \"population\": {\n \"id\": \"{{popID}}\"\n },\n \"lifecycle\": {\n \"status\": \"VERIFICATION_REQUIRED\",\n \"suppressVerificationCode\": false\n },\n \"username\": \"import-user_{{$timestamp}}\",\n \"password\": {\n \"value\": \"{{userPassword}}\",\n \"forceChange\": false\n }\n}" let postData = parameters.data(using: .utf8) var request = URLRequest(url: URL(string: "{{apiPath}}/v1/environments/{{envID}}/users")!,timeoutInterval: Double.infinity) request.addValue("application/vnd.pingidentity.user.import+json", forHTTPHeaderField: "Content-Type") request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization") request.httpMethod = "POST" request.httpBody = postData let task = URLSession.shared.dataTask(with: request) { data, response, error in guard let data = data else { print(String(describing: error)) return } print(String(data: data, encoding: .utf8)!) } task.resume() ``` ### Example Response 201 Created ```json { "_links": { "self": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32" }, "environment": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" }, "population": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/populations/f22842c9-f1eb-41a5-8072-20041b609cf1" }, "devices": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/devices" }, "roleAssignments": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/roleAssignments" }, "password": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/password" }, "password.reset": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/password" }, "password.set": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/password" }, "password.check": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/password" }, "password.recover": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/password" }, "linkedAccounts": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/linkedAccounts" }, "user.verify": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32" }, "account.sendVerificationCode": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32" }, "memberOfGroups": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/users/01dee5b5-48fa-4a6b-a574-f2ff28ab5b32/memberOfGroups" } }, "id": "01dee5b5-48fa-4a6b-a574-f2ff28ab5b32", "environment": { "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" }, "account": { "canAuthenticate": true, "status": "OK" }, "createdAt": "2022-06-07T22:48:14.677Z", "email": "joe@pingidentity.com", "enabled": true, "identityProvider": { "type": "PING_ONE" }, "lifecycle": { "status": "VERIFICATION_REQUIRED" }, "mfaEnabled": false, "name": { "given": "Test", "family": "User" }, "population": { "id": "f22842c9-f1eb-41a5-8072-20041b609cf1" }, "updatedAt": "2022-06-07T22:48:14.677Z", "username": "import-user_1654642094", "verifyStatus": "NOT_INITIATED" } ```