Create Population
POST {{apiPath}}/environments/{{envID}}/populations
You can use POST {{apiPath}}/environments/{{envID}}/populations/ to create a new population resource in the specified environment.
In the request body, the population name is a required property. The description property is optional.
An optional default property can be used to assign the population as the default for the environment. When new users are created in an environment, they are assigned to the environment’s default population, unless otherwise specified. When default is set to true, all other populations within the environment are set to false.
Populations, by default, use the default password policy and default theme for the environment. However, you’ve the option to:
-
Assign a password policy specific to this population with the
passwordPolicy.idproperty in the request body. To unassign thepasswordPolicy.idproperty, omitpasswordPolicy.idfrom the request body, and the population again uses the default password policy for the environment. -
Assign a theme specific to this population with the
theme.idproperty in the request body. To unassign thetheme.idproperty, omittheme.idfrom the request body, and the population again uses the default theme for the environment.
Prerequisites
-
Refer to Populations for for full property descriptions.
-
Refer to Create a password policy to get a
passwordPolicyIDfor the body. Refer also to Identity Management, especially Password Policies.
Request Model
| Property | Type | Required? |
|---|---|---|
|
String[] |
Optional |
|
Boolean |
Optional |
|
String |
Optional |
|
String |
Required |
|
String |
Optional |
|
String |
Optional |
|
String |
Optional |
Example Request
-
cURL
-
C#
-
Go
-
HTTP
-
Java
-
jQuery
-
NodeJS
-
Python
-
PHP
-
Ruby
-
Swift
curl --location --globoff '{{apiPath}}/environments/{{envID}}/populations' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
"name" : "NA Eng Austin",
"description" : "NA Engineering",
"default" : false,
"passwordPolicy": {
"id": "{{passwordPolicyID}}"
},
"theme": {
"id": "{{themeID}}"
},
"alternativeIdentifiers": [
"Bob'\''s crew",
"Austin"
]
}'
var options = new RestClientOptions("{{apiPath}}/environments/{{envID}}/populations")
{
MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@" ""name"" : ""NA Eng Austin""," + "\n" +
@" ""description"" : ""NA Engineering""," + "\n" +
@" ""default"" : false," + "\n" +
@" ""passwordPolicy"": {" + "\n" +
@" ""id"": ""{{passwordPolicyID}}""" + "\n" +
@" }," + "\n" +
@" ""theme"": {" + "\n" +
@" ""id"": ""{{themeID}}""" + "\n" +
@" }," + "\n" +
@" ""alternativeIdentifiers"": [" + "\n" +
@" ""Bob's crew""," + "\n" +
@" ""Austin""" + "\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}}/populations"
method := "POST"
payload := strings.NewReader(`{
"name" : "NA Eng Austin",
"description" : "NA Engineering",
"default" : false,
"passwordPolicy": {
"id": "{{passwordPolicyID}}"
},
"theme": {
"id": "{{themeID}}"
},
"alternativeIdentifiers": [
"Bob's crew",
"Austin"
]
}`)
client := &http.Client {
}
req, err := http.NewRequest(method, url, payload)
if err != nil {
fmt.Println(err)
return
}
req.Header.Add("Content-Type", "application/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}}/populations HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}
{
"name" : "NA Eng Austin",
"description" : "NA Engineering",
"default" : false,
"passwordPolicy": {
"id": "{{passwordPolicyID}}"
},
"theme": {
"id": "{{themeID}}"
},
"alternativeIdentifiers": [
"Bob's crew",
"Austin"
]
}
OkHttpClient client = new OkHttpClient().newBuilder()
.build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n \"name\" : \"NA Eng Austin\",\n \"description\" : \"NA Engineering\",\n \"default\" : false,\n \"passwordPolicy\": {\n \"id\": \"{{passwordPolicyID}}\"\n },\n \"theme\": {\n \"id\": \"{{themeID}}\"\n },\n \"alternativeIdentifiers\": [\n \"Bob's crew\",\n \"Austin\"\n ]\n}");
Request request = new Request.Builder()
.url("{{apiPath}}/environments/{{envID}}/populations")
.method("POST", body)
.addHeader("Content-Type", "application/json")
.addHeader("Authorization", "Bearer {{accessToken}}")
.build();
Response response = client.newCall(request).execute();
var settings = {
"url": "{{apiPath}}/environments/{{envID}}/populations",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"Authorization": "Bearer {{accessToken}}"
},
"data": JSON.stringify({
"name": "NA Eng Austin",
"description": "NA Engineering",
"default": false,
"passwordPolicy": {
"id": "{{passwordPolicyID}}"
},
"theme": {
"id": "{{themeID}}"
},
"alternativeIdentifiers": [
"Bob's crew",
"Austin"
]
}),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
var request = require('request');
var options = {
'method': 'POST',
'url': '{{apiPath}}/environments/{{envID}}/populations',
'headers': {
'Content-Type': 'application/json',
'Authorization': 'Bearer {{accessToken}}'
},
body: JSON.stringify({
"name": "NA Eng Austin",
"description": "NA Engineering",
"default": false,
"passwordPolicy": {
"id": "{{passwordPolicyID}}"
},
"theme": {
"id": "{{themeID}}"
},
"alternativeIdentifiers": [
"Bob's crew",
"Austin"
]
})
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
import requests
import json
url = "{{apiPath}}/environments/{{envID}}/populations"
payload = json.dumps({
"name": "NA Eng Austin",
"description": "NA Engineering",
"default": False,
"passwordPolicy": {
"id": "{{passwordPolicyID}}"
},
"theme": {
"id": "{{themeID}}"
},
"alternativeIdentifiers": [
"Bob's crew",
"Austin"
]
})
headers = {
'Content-Type': 'application/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}}/populations');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n "name" : "NA Eng Austin",\n "description" : "NA Engineering",\n "default" : false,\n "passwordPolicy": {\n "id": "{{passwordPolicyID}}"\n },\n "theme": {\n "id": "{{themeID}}"\n },\n "alternativeIdentifiers": [\n "Bob\'s crew",\n "Austin"\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}}/populations")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
"name": "NA Eng Austin",
"description": "NA Engineering",
"default": false,
"passwordPolicy": {
"id": "{{passwordPolicyID}}"
},
"theme": {
"id": "{{themeID}}"
},
"alternativeIdentifiers": [
"Bob's crew",
"Austin"
]
})
response = http.request(request)
puts response.read_body
let parameters = "{\n \"name\" : \"NA Eng Austin\",\n \"description\" : \"NA Engineering\",\n \"default\" : false,\n \"passwordPolicy\": {\n \"id\": \"{{passwordPolicyID}}\"\n },\n \"theme\": {\n \"id\": \"{{themeID}}\"\n },\n \"alternativeIdentifiers\": [\n \"Bob's crew\",\n \"Austin\"\n ]\n}"
let postData = parameters.data(using: .utf8)
var request = URLRequest(url: URL(string: "{{apiPath}}/environments/{{envID}}/populations")!,timeoutInterval: Double.infinity)
request.addValue("application/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/populations/26a126c2-054f-4f18-b077-8226c0c4bf3e"
},
"environment": {
"href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
}
},
"id": "26a126c2-054f-4f18-b077-8226c0c4bf3e",
"environment": {
"id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
},
"name": "NA Eng Austin",
"description": "NA Engineering",
"userCount": 0,
"createdAt": "2024-11-04T17:27:17.377Z",
"updatedAt": "2024-11-04T17:27:17.377Z",
"passwordPolicy": {
"id": "cd502ee4-176a-438a-a947-a4d8cffb0fdb"
},
"default": false,
"theme": {
"id": "5ab94557-59c3-4afc-bbf6-046444bd04b8"
}
}