Create User (Import)

POST {{apiPath}}/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 request, allowing both cleartext and pre-encoded password values. Refer to Password encoding 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.

The POST {{apiPath}}/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 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 operation or Verify Email (Code) 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 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, POST Create User (Import), or PUT Update User MFA Enabled. You cannot update mfaEnabled with PUT Update User or PATCH Update User.

If successful, the response returns a 201 Successfully created message and shows the new user resource’s property data.

Prerequisites

Refer to Users and User Operations for important overview information.
Create a population to get a popID. Refer to Create Population. Run Read All Populations to find an existing population.

Request Model

Property Type Required?

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

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 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 )

{
    "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 --location --globoff '{{apiPath}}/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
    }
}'

var options = new RestClientOptions("{{apiPath}}/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);

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/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))
}

POST /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
    }
}

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}}/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();

var settings = {
  "url": "{{apiPath}}/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);
});

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/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);
});

import requests
import json

url = "{{apiPath}}/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
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/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();
}

require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/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

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}}/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

{
    "_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"
}

PingOne Platform APIs

Create User (Import)

Prerequisites

Headers

Body

Example Request

Example Response