--- title: Create Population description: You can use POST {{apiPath}}/v1/environments/{{envID}}/populations/ to create a new population resource in the specified environment. component: pingone-api page_id: pingone-api:platform:populations/create-population canonical_url: https://developer.pingidentity.com/pingone-api/platform/populations/create-population.html section_ids: prerequisites: Prerequisites headers: Headers body: Body example-request: Example Request example-response: Example Response --- # Create Population ## ```none POST {{apiPath}}/v1/environments/{{envID}}/populations ``` You can use `POST {{apiPath}}/v1/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 * Refer to [Populations](../populations.html) for for full property descriptions. * Refer to [Create a password policy](../password-policies/create-password-policy.html) to get a `passwordPolicyID` for the body. Refer also to [Identity Management](../identity-management.html), especially [Password Policies](../password-policies.html). > **Collapse: 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 ) ```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 ```shell curl --location --globoff '{{apiPath}}/v1/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" ] }' ``` ```csharp var options = new RestClientOptions("{{apiPath}}/v1/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); ``` ```golang package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "{{apiPath}}/v1/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)) } ``` ```http POST /v1/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" ] } ``` ```java 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}}/v1/environments/{{envID}}/populations") .method("POST", body) .addHeader("Content-Type", "application/json") .addHeader("Authorization", "Bearer {{accessToken}}") .build(); Response response = client.newCall(request).execute(); ``` ```javascript var settings = { "url": "{{apiPath}}/v1/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); }); ``` ```javascript var request = require('request'); var options = { 'method': 'POST', 'url': '{{apiPath}}/v1/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); }); ``` ```python import requests import json url = "{{apiPath}}/v1/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 setUrl('{{apiPath}}/v1/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(); } ``` ```ruby require "uri" require "json" require "net/http" url = URI("{{apiPath}}/v1/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 ``` ```swift 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}}/v1/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 ```json { "_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" } } ```