PingOne Platform APIs

Step 4: Create a population

 

POST {{apiPath}}/environments/{{envID}}/populations

Use the POST {{apiPath}}/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:

  • {{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 {{solutionPopID}} to this value. The {{solutionPopID}} 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.

  • 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 region.

Headers

Authorization      Bearer {{accessToken}}

Content-Type      application/json

Body

raw ( application/json )

{
    "name": "New-Solution-Population_{{$timestamp}}",
    "description": "Population for a PingOne journey"
}

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": "New-Solution-Population_{{$timestamp}}",
    "description": "Population for a PingOne journey"
}'
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"": ""New-Solution-Population_{{$timestamp}}""," + "\n" +
@"    ""description"": ""Population for a PingOne journey""" + "\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": "New-Solution-Population_{{$timestamp}}",
    "description": "Population for a PingOne journey"
}`)

  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": "New-Solution-Population_{{$timestamp}}",
    "description": "Population for a PingOne journey"
}
OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"name\": \"New-Solution-Population_{{$timestamp}}\",\n    \"description\": \"Population for a PingOne journey\"\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": "New-Solution-Population_{{$timestamp}}",
    "description": "Population for a PingOne journey"
  }),
};

$.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": "New-Solution-Population_{{$timestamp}}",
    "description": "Population for a PingOne journey"
  })

};
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": "New-Solution-Population_{{$timestamp}}",
  "description": "Population for a PingOne journey"
})
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": "New-Solution-Population_{{$timestamp}}",\n    "description": "Population for a PingOne journey"\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": "New-Solution-Population_{{\$timestamp}}",
  "description": "Population for a PingOne journey"
})

response = http.request(request)
puts response.read_body
let parameters = "{\n    \"name\": \"New-Solution-Population_{{$timestamp}}\",\n    \"description\": \"Population for a PingOne journey\"\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/d93dbbfc-a639-4b78-85fd-6d588ef26982"
        },
        "environment": {
            "href": "https://api.pingone.com/v1/environments/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
        }
    },
    "id": "d93dbbfc-a639-4b78-85fd-6d588ef26982",
    "environment": {
        "id": "abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6"
    },
    "name": "New-Solution-Population_1680720357",
    "description": "Population for a PingOne journey",
    "userCount": 0,
    "createdAt": "2023-04-05T18:45:57.631Z",
    "updatedAt": "2023-04-05T18:45:57.631Z",
    "default": false
}