Populations service


Populations

In PingOne, a population defines a set of users, similar to an organizational unit (OU). In a given environment, you can use populations to simplify the management of users. For example, you can create a population for similar types of users and apply a password policy to that population.

The populations API implements functions to create, read, update, delete, and search for population resources within a specified environment. You must create at least one population before you can create users. An individual user cannot belong to more than one population simultaneously, but users can be moved to a different populations.

Populations API operations

The populations service supports the following endpoint operations:

For hands-on experience with the populations API endpoints, click the Run in Postman button below to download a Postman collection that you can import and open in your local Postman application.

Populations data model

Property Description
createdAt The time the resource was created.
description A string that specifies the description of the population.
environment.id A string that specifies the environment resource’s unique identifier associated with the population.
id A string that specifies the resource’s unique identifier.
name A string that specifies the population name, which must be provided and must be unique within an environment.
updatedAt The time the resource was last updated.
userCount The number of users that belong to the population. This is a read-only property.

Response codes

Code Message
200 Successful operation.
201 Successfully created.
204 Successfully removed. No content.
400 The request was invalid.
401 You weren’t authenticated to perform this operation.
404 The specified object doesn’t exist.
409 Uniqueness constraint violation (e.g., duplicate name).

Endpoint examples

Get populations

The following sample shows the GET /environments/{environmentId}/populations operation to return the complete list of population resources associated with the specified environment.

curl -X "GET" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/populations" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

The request returns a list of populations resources. The returned data includes the id, which is the population ID required for many user-related API calls. It also shows the userCount attribute, which identifies the number of users associated with the population.

The response data for an environment with two populations resources looks like this:

{
    "_links": {
        "self": {
            "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations"
        }
    },
    "_embedded": {
        "populations": [
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/5e5cf2d4-2e11-4efc-89f1-73110c277ded"
                    }
                },
                "id": "5e5cf2d4-2e11-4efc-89f1-73110c277ded",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Accounting",
                "userCount": 6,
                "createdAt": "2018-06-12T19:09:23.756Z"
            },
            {
                "_links": {
                    "self": {
                        "href": "https://api.pingone.com/v1/environments/0bda42bc-d54f-449f-8d46-d5b8990c43ba/populations/14865d2f-5c28-40a2-97e7-10cb921e2ade"
                    }
                },
                "id": "14865d2f-5c28-40a2-97e7-10cb921e2ade",
                "environment": {
                    "id": "0bda42bc-d54f-449f-8d46-d5b8990c43ba"
                },
                "name": "Engineering",
                "userCount": 31,
                "createdAt": "2018-06-12T19:09:42.504Z"
            }
        ]
    },
    "count": 2,
    "size": 2
}

Get one population

You can use GET /environments/{environmentId}/populations/{populationId} to view a population in the specified environment. The following sample shows the operation to get information about a single population. The population ID is specified in the request URL.

curl -X "GET" "https://api.pingone.com/v1/environments/b7372995-824b-44ff-99f8-ab151dac3263/populations/21731b50-6b54-41b0-8454-9cd9de62a7a1" \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer jwtToken'

Create populations

You can use POST /environments/{environmentId}/populations/ to create a new population resource in the specified environment.

curl -X POST "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede/populations" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name" : "Accounting",
  "description" : "Accounting group"
}"

In the request body, the population name is a required property. The description property is optional.

Update populations

To update a population resource, you need to know the environment ID and the ID of the population to modify. You can use PUT /environments/{environmentId}/populations/{populationId} to update the attribute values for a population in the specified environment.

curl -X PUT "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede/populations/21731b50-6b54-41b0-8454-9cd9de62a7a1" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \
-d "{
  "name" : "Finance and Accounting",
  "description" : "Finance and accounting group"
}"

In the request body, the population name is changed to Finance and Accounting, and the value of the description attribute is modified to indicate that the population includes finance and accounting users.

Delete populations

You can perform a DELETE operation on the population resource to remove it from the environment. the population must not have any associated users before it can be deleted. You can verify that the population resource is empty by calling GET /environments/{environmentId}/populations/{populationId} to view the userCount value.

The following sample shows the DELETE /environments/{environmentId}/populations/{populationId} operation to delete the empty population from the specified environment.

curl -X DELETE "https://api.pingone.com/v1/environments/f29547a1-841c-45f8-977e-00d0fdb73ede/populations/21731b50-6b54-41b0-8454-9cd9de62a7a1" \
-H "Content-type: application/json" \
-H "Authorization: Bearer jwtToken" \

When successful, the DELETE request returns a code 204 No Content message.