PingOne Platform APIs

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.id property in the request body. To unassign the passwordPolicy.id property, omit passwordPolicy.id from 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.id property in the request body. To unassign the theme.id property, omit theme.id from the request body, and the population again uses the default theme for the environment.

Prerequisites

Request Model
Property Type Required?

alternativeIdentifiers

String[]

Optional

default

Boolean

Optional

description

String

Optional

name

String

Required

passwordPolicy.id

String

Optional

preferredLanguage

String

Optional

theme.id

String

Optional

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
  "name" : "NA Eng Austin",
  "description" : "NA Engineering",
  "default" : false,
  "passwordPolicy": {
       "id": "{{passwordPolicyID}}"
   },
   "theme": {
    "id": "{{themeID}}"
   },
   "alternativeIdentifiers": [
    "Bob's crew",
    "Austin"
   ]
}

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