--- title: "Step 4: Create a population" description: Use the POST {{apiPath}}/v1/environments/{{envID}}/populations operation to create a new population. All users in PingOne must be associated with a population. Although your new environment automatically includes a default population, creating a new population gives you the ability to associate this user with a more specific population grouping. component: pingone-api page_id: pingone-api:getting-started:create-a-test-environment/step-4-create-a-population canonical_url: https://developer.pingidentity.com/pingone-api/getting-started/create-a-test-environment/step-4-create-a-population.html section_ids: troubleshooting: Troubleshooting headers: Headers body: Body example-request: Example Request example-response: Example Response --- # Step 4: Create a population ## ```none POST {{apiPath}}/v1/environments/{{envID}}/populations ``` Use the `POST {{apiPath}}/v1/environments/{{envID}}/populations` operation to create a new population. All users in PingOne must be associated with a population. Although your new environment automatically includes a default population, creating a new population gives you the ability to associate this user with a more specific population grouping. In this request: * ``{{apiPath}}`is the geographic domain for the PingOne API endpoints for your PingOne environment. The PingOne top-level domain is `https://api.pingone.com/v1`` for the U.S. Refer to [PingOne API domains](../../before-you-begin/introduction.html) for the top-level domains for other regions. * `{{envID}}` is the ID of the environment you created in the previous step. If you're using Postman, this value is automatically set by the script in the Script tab used for the previous step. In the request body: * `name` is a String containing the name to assign to the new population. This is already specified for you in the request body, although you can choose to change it. * `description` is an optional property describing the new population. This is already specified for you in the request body, although you can choose to change it. When successful, the request returns a `Status: 201 created` message and shows the new population's configuration data. The response data includes the population's `id` property. If you're using Postman, the script in the Script tab automatically sets `{{sharedPopID}}` to this value. The `{{sharedPopID}}` property is needed to create the new user in the next step. ### Troubleshooting * Verify that `{{envID}}` is the ID for the new test environment you created. * Verify that you've assigned the Environment Admin role to your Worker app. Refer to [Assign roles to the Worker app](../create-an-admin-worker-app/step-3-assign-roles.html). * Verify that you're using Bearer authorization for this request (and all `{{apiPath}}` requests), and you have a valid access token. For Postman users, check that the Authorization tab in Postman is set to Bearer Token, and the access token variable is assigned (shown in blue, not red). * If you get a 401 Unauthorized message, this is likely due to the access token expiring (a 1 hour expiry time). Refer to the step to get an access token, and call this request again. * Verify that `{{apiPath}}` is correct for your geographic domain . ### Headers Authorization      Bearer {{accessToken}} Content-Type      application/json ### Body raw ( application/json ) ```json { "name": "Shared-Test-User-Population", "description": "Population for PingOne test users" } ``` ## ### 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": "Shared-Test-User-Population", "description": "Population for PingOne test users" }' ``` ```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"": ""Shared-Test-User-Population""," + "\n" + @" ""description"": ""Population for PingOne test users""" + "\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": "Shared-Test-User-Population", "description": "Population for PingOne test users" }`) 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": "Shared-Test-User-Population", "description": "Population for PingOne test users" } ``` ```java OkHttpClient client = new OkHttpClient().newBuilder() .build(); MediaType mediaType = MediaType.parse("application/json"); RequestBody body = RequestBody.create(mediaType, "{\n \"name\": \"Shared-Test-User-Population\",\n \"description\": \"Population for PingOne test users\"\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": "Shared-Test-User-Population", "description": "Population for PingOne test users" }), }; $.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": "Shared-Test-User-Population", "description": "Population for PingOne test users" }) }; 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": "Shared-Test-User-Population", "description": "Population for PingOne test users" }) 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": "Shared-Test-User-Population",\n "description": "Population for PingOne test users"\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": "Shared-Test-User-Population", "description": "Population for PingOne test users" }) response = http.request(request) puts response.read_body ``` ```swift let parameters = "{\n \"name\": \"Shared-Test-User-Population\",\n \"description\": \"Population for PingOne test users\"\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/fe09831e-bbf7-46f1-92e4-aafe10df56fd" }, "environment": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" }, "theme": { "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/themes/5ab94557-59c3-4afc-bbf6-046444bd04b8" } }, "id": "fe09831e-bbf7-46f1-92e4-aafe10df56fd", "environment": { "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6" }, "name": "Shared-Test-User-Population", "description": "Population for PingOne test users", "userCount": 0, "createdAt": "2026-03-23T16:34:44.760Z", "updatedAt": "2026-03-23T16:34:44.760Z", "preferredLanguage": "en", "theme": { "id": "5ab94557-59c3-4afc-bbf6-046444bd04b8" }, "default": false } ```