PingOne for Enterprise Directory API

The PingOne Directory provides a hosted directory service that developers can use to store user authentication and profile data. The directory interface uses the System for Cross-Domain Identity Management (SCIM) v1.1 open standard protocol.

SCIM provides both a defined schema for user representation as well as a RESTful API for performing user and group CRUD actions (Create, Read, Update and Delete).

Functional Overview

Directory Actions

The SCIM protocol uses the REST concept to define the actions a SCIM Consumer can perform on a resource managed by the PingOne Directory (a SCIM Service Provider). These actions can be performed against User resources and Group resources in the directory:

HTML Verb Action
GET Reads / queries for a resource (or resources) from the Service Provider.
POST Creates a new resource at the Service Provider.
PUT Updates an existing resource. This action requires the entire resource provided in the body, making it more like a replace than an update.
PATCH Updates an existing resource with changes to multi-valued attributes (such as group membership).
DELETE Deletes a resource at the Service Provider.

User Resources

The User resource represents a user or identity profile in the directory. The PingOne Directory supports the following SCIM schema's:

  • SCIM Core Schema (urn:scim:schemas:core:1.0)
  • SCIM Enterprise User Schema (urn:scim:schemas:extension:enterprise:1.0)
  • PingOne Schema (urn:scim:schemas:com_pingone:1.0)

A user resource can be queried by the following API endpoint: https://directory-api.pingone.com/api/directory/user

User Actions

In addition to the core SCIM actions (Create, Read, Update, Delete), the PingOne directory also supports the following actions for users:

  • user authentication (/content/developer/en/api/pingone-directoryapi.html?wcmmode=disabled#user_authentication)
  • invitation of new new users to your directory (/content/developer/en/api/pingone-directoryapi.html?wcmmode=disabled#user_invitation)

Group Resources

Groups are represented by the SCIM group object. Groups can contain either group or user resources as members allowing for nested group support. The group object also supports the PATCH operation for group membership changes.

A group resource can be queried by the following API endpoint:

https://directory-api.pingone.com/api/directory/group

Group Actions

In addition to the core SCIM actions (Create, Read, Update, Delete) for groups, the PingOne directory also supports returning a count of the members of a group (/content/developer/en/api/pingone-directoryapi.html?wcmmode=disabled#group_membership_count)

PingOne Directory API

The PingOne directory leverages the SCIM v1.1 API to perform resource CRUD (Create, Read, Update, Delete) actions.

Find more information about the SCIM v1.1 API in the SCIM developers guide.

Creating the requests

A request consists of using the appropriate verb to call the SCIM resource endpoint (i.e. User or Group) when modifying a resource directly, perform the action on the resources location URL (the is the "location" attribute for a given resource).

Request authorization requires:

  • Basic authorization.
  • A Base64 encoding of the Client ID and API Key displayed in the Ping directory UI (Setup --> Directory --> API Credentials). See View or renew directory API credentials for more information.

For example: Basic base64encode(clientid:apiKey).

As an example, the following POST action to the user endpoint will create a new user in the directory:

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{
        "schemas":["urn:scim:schemas:core:1.0"],
        "userName":"marcher",
        "password":"2Federate",
        "active":true,
        "name":{ "familyName":"Archer", "givenName":"Meredith" },
        "emails": [ { "type": "work", "value": "meredith.archer@pingdevelopers.com }]
     }' \
     https://directory-api.pingone.com/api/directory/user

Handling responses

In most scenarios, the API response will be the complete SCIM representation of the resource (i.e. a DELETE action will not return a SCIM object). An example of a successful API response for a create request is included:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
    "schemas":[
        "urn:scim:schemas:core:1.0",
        "urn:scim:schemas:com_pingone:1.0"
    ],
    "urn:scim:schemas:com_pingone:1.0": {
        "createTimeStamp":1429123454227,
        "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
        "lastModifiedTimeStamp":1429123454227,
        "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
        "state":"ACTIVE" 
    },
    "name":{
        "familyName":"Archer",
        "givenName":"Meredith" 
    },
    "userName":"marcher",
    "active":true,
    "emails":[
        {
            "value":"meredith.archer@pingdevelopers.com",
            "type":"work" 
        }
    ],
    "meta":{
        "lastModified":"2015-04-15T12:44:14.227-06:00",
        "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
        "created":"2015-04-15T12:44:14.227-06:00"
    },
    "groups":[
        {
            "display":"Users",
            "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" 
        }
    ]
}

Handling errors

Errors use regular HTTP response codes to return an error message to the caller. These will be in the 400-499 range and relate directly to the request (for example if a resource is not found during an update, a 404 (NOT FOUND) error will be returned).

Create a Resource

Creating a user

A user create is performed by a POST operation. The JSON representation of the user (according to the SCIM schema) is POSTed to the User endpoint.

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"schemas":["urn:scim:schemas:core:1.0"],
"userName":"marcher",
"password":"2Federate",
"active":true,
"name":{ "familyName":"Archer", "givenName":"Meredith" },
"emails": [ { "type": "work", "value": "meredith.archer@pingdevelopers.com" }]
}' \
https://directory-api.pingone.com/api/directory/user?option=DEFAULT_USER_GROUP

If an externalId is specified in the request, and a user with that externalId already exists, the request is treated as an update.

If you specify the DEFAULT_USER_GROUP option, the user is added to the directory Users group (the default group for new users). You can also replace DEFAULT_USER_GROUP with the UUID of a specific group to add the user to that group instead of the Users group.

To force the user to change their password during their next logon, set "urn:scim:schemas:com_pingone:1.0" to {"passwordExpired": true}.

A successful request will result in a HTTP 200 OK response and the JSON representation of the user that was just created:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
  "schemas":[
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:com_pingone:1.0" 
  ],
  "urn:scim:schemas:com_pingone:1.0": {
    "createTimeStamp":1429123454227,
    "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
    "lastModifiedTimeStamp":1429123454227,
    "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
    "state":"ACTIVE" 
  },
  "name":{
    "familyName":"Archer",
    "givenName":"Meredith" 
  },
  "userName":"marcher",
  "active":true,
    "urn:scim:schemas:com_pingone:1.0":{
    "passwordExpired": true},
    "emails":[
    {
      "value":"meredith.archer@pingdevelopers.com",
      "type":"work" 
    }
  ],
  "meta":{
   "lastModified":"2015-04-15T12:44:14.227-06:00",
   "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
   "created":"2015-04-15T12:44:14.227-06:00" 
  },
  "groups":[
    {
     "display":"Users",
     "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" 
    }
  ]
}

In the response, the “id” attribute contains the unique identifier for this user in the PingOne Directory. To modify this user (such as adding them to other groups), you will reference them via the "id" attribute value. The “location” attribute contains the full resource URL that you will use to manipulate the resource in the next sections.

Creating a group

Creating a group is a similar process, performing a POST operation against the Group endpoint:

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d ' {
"schemas":["urn:scim:schemas:core:1.0"],
"displayName":"Software Developers" }' \
https://directory-api.pingone.com/api/directory/group

A successful request will result in a HTTP 200 OK response and the JSON representation of the group that was just created:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id":"7c513a7e-55d4-441c-858c-7329e6268084",
  "displayName":"Software Developers",
  "schemas":[
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:com_pingone:1.0" 
  ],
  "meta":{
    "lastModified":"2015-04-16T10:08:22.324-06:00",
    "created":"2015-04-16T10:08:22.324-06:00",
    "location":"https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-
    858c-7329e6268084" 
  },
  "urn:scim:schemas:com_pingone:1.0": {
    "createTimeStamp":1429200502324,
    "lastModifiedTimeStamp":1429200502324,
    "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
    "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137"
  }
}

Read a Resource

GET operation

You can retrieve a specific user's directory profile by:

  • Querying for the user by performing a GET operation against the User endpoint
  • Retrieving the user by performing a GET operation against the User resource directly

To query for a user you will use the SCIM query language to form your query, refer to the SCIM specifications for more information. To retrieve our recently created user we will use the filter: username eq “marcher” which will be urlencoded and appended to the User endpoint as the “filter” parameter:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X GET https://directory-api.pingone.com/api/directory/user?filter=userName%20eq%20%22marcher%22

or by performing a GET directly on the user resource (which is defined in the “location” attribute in the “meta” section of the user record). Both the example above and this one will return the same result. So, to retrieve Meredith’s profile directly I can also perform the following command:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X GET https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7

A successful request will result in a HTTP 200 OK response and the JSON representation of the user:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
  "schemas":[
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:com_pingone:1.0" 
   ],
  "urn:scim:schemas:com_pingone:1.0":{
    "createTimeStamp":1429123454227,
    "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
    "lastModifiedTimeStamp":1429123454227,
    "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
    "state":"ACTIVE" 
  },
  "name":{
    "familyName":"Archer",
    "givenName":"Meredith" 
  },
  "userName":"marcher",
  "active":true,
  "emails":[
    {
      "value":"meredith.archer@pingdevelopers.com",
      "type":"work"
    }
  ],
  "meta":{
    "lastModified":"2015-04-15T12:44:14.227-06:00",
    "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
    "created":"2015-04-15T12:44:14.227-06:00"
  },
  "groups":[
    {
      "display":"Users",
      "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" 
    }
  ]
}

Additionally, you can retrieve the details for all users in the directory. In this case, don't specify a user filter and set the startIndex and count parameters to determine the number of users to return:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-X GET https://directory-api.pingone.com/api/directory/user?sortBy=userName&sortOrder=ascending&startIndex=1&count=100

Where startIndex is the index at which user retrieval will begin, and count is the number of users to return per page. The maximum count value is 1,000. If you need to retrieve more than 1,000 users, you'll need to use multiple calls, increasing the startIndex value by 1,000 each time until all users are returned.

Update a Resource

Resource modifications are performed using a PUT operation returning the entire user profile with the changes applied. For example, to add a “title” to Meredith’s record I will take the contents of a GET request, add in the title attribute and PUT it back to Meredith’s User resource location.

curl -v “X PUT --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"schemas":[ "urn:scim:schemas:core:1.0", "urn:scim:schemas:com_pingone:1.0" ],
"urn:scim:schemas:com_pingone:1.0":{
"createTimeStamp":1429123454227,
"accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
"lastModifiedTimeStamp":1429123454227,
"directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
"state":"ACTIVE" },
"name":{ "familyName":"Archer", "givenName":"Meredith" },
"userName":"marcher",
"title":"Software Developer",
"active":true,
"emails":[{"value":"meredith.archer@pingdevelopers.com","type":"work" }],
"meta":{
"lastModified":"2015-04-15T12:44:14.227-06:00",
"location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
"created":"2015-04-15T12:44:14.227-06:00" },
"groups":[{ "display":"Users", "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" }]
}' \
https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7

A successful response from a modify operation is the user profile returned in full:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "id":"a7d67610-ceb5-4350-ba5a-746472c4f1f7",
  "schemas":[
    "urn:scim:schemas:core:1.0",
    "urn:scim:schemas:com_pingone:1.0" 
  ],
  "urn:scim:schemas:com_pingone:1.0":{
    "createTimeStamp":1429123454227,
    "accountId":"a6538050-412a-4bca-a44d-07deb4b073a8",
    "lastModifiedTimeStamp":1429123456527,
    "directoryId":"90b3dfe3-f8d0-45ad-8c04-047c88b03137",
    "state":"ACTIVE" 
  },
  "name":{
    "familyName":"Archer",
    "givenName":"Meredith" 
  },
  "userName":"marcher",
  "title":"Software Developer",
  "active":true,
  "emails":[
    {
      "value":"meredith.archer@pingdevelopers.com",
      "type":"work" 
    }
  ],
  "meta":{
    "lastModified":"2015-04-15T12:46:18.224-06:00",
    "location":"https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7",
    "created":"2015-04-15T12:44:14.227-06:00" 
  },
  "groups":[
    {
      "display":"Users",
      "value":"0b854f8d-a291-4e95-ad4b-68474a666e55" 
    }
  ]
}

Patch operation

The PATCH operation can be used to simplify changes to large multi-valued attributes, such as the membership of a group resource. To add a new member to a group resource you need to know the "id" of the resource you want to add and the type of resource it is (User or Group). The request to add a user (Meredith) to the "Software Developers" group using the PATCH operation is as follows:

curl -v -X PATCH --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "members" : [{ "value" : "a7d67610-ceb5-4350-ba5a-746472c4f1f7", "type" : "User" }] }' \
https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-858c-7329e6268084

To remove a member from the group, include an "operation" attribute with the value of "delete", for example to remove Meredith from the "Software Developers" group:

curl -v -X PATCH --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "members" : [{ "value" : "a7d67610-ceb5-4350-ba5a-746472c4f1f7", , "type" : "User", "operation" : "delete"
}] }' \
https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-858c-7329e6268084

Delete a Resource

To delete a resource (user or group) you will use the DELETE operation against the resource's endpoint. The following command will delete Meredith from the directory and return a 200 OK message if successful.

curl -v “X DELETE --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh
 -H "Content-Type: application/json" \
 -H "Accept: application/json" \
 https://directory-api.pingone.com/api/directory/user/a7d67610-ceb5-4350-ba5a-746472c4f1f7

User Authentication

The SCIM protocol doesn't define a method for authenticating a user. The PingOne Directory API uses the OAuth 2.0 Resource Owner Password Credential grant to facilitate user authentication.

To authenticate the Meredith user via her username/password, perform the following request:

curl -v -X POST --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
 -d "grant_type=password&username=marcher&password=2Federate" 
 https://directory-api.pingone.com/api/oauth/token

A response of 200 OK signals a successful login. Any other response is a failed authentication attempt.

Reset Password by Email

This operation sets a confirmation token for the user associated with the specified email address. By default, a confirmation email is sent to that address. The confirmation email contains a link to reset their password. A new confirmation token is set for the user each time this operation is called.

The endpoint to reset a password by email:

https://directory-api.pingone.com/api/directory/users/password-lost

Request parameters

Parameter Data Type Description
email string The email address of the user.
link string Optional. The URL used to reset user passwords. If specified, this is included in the confirmation email. If not specified, the standard PingOne password reset form is used.
skipSend string Optional. This can be "enabled" (do not send an email) or "disabled" (send an email).

Request example

This example sends an email with a link to a password-reset page:

{
   "email" : "jborder@anywhere.com",
   "link" : "https://anywhere.com/passwordReset"
   "skipSend" : "disabled"
}

If successful, the link is returned in the response, similar to the following:

HTTP/1.1 200 OK
{
  "link": "https://login.pingone.com/idp/directory/a/61197468-2e9b-11e7-93ae-92361f008429/forgotpassword/confirm/611976e8-2e9b-11e7-93ae-92361f002671/611977f6-2e9b-11e7-93ae-92361f008429/"
}

Reset Password

This operation resets a user password based on the supplied user ID. You can specify either the oldPassword or the confirmationToken in the request, but not both. You can use the confirmationToken only to reset the password of non-administrative users.

The endpoint to reset a user's password:

https://directory-api.pingone.com/api/directory/users/password-reset

Request parameters

Parameter Data Type Description
id string the ID of the user
newPassword string The new password to assign to the user.
oldPassword string Optional. The user's current password. You can specify this value or confirmationToken, but not both.
confirmationToken string Optional. The user's confirmation token. This cannot be used when you're resetting an administrator's password. You'll find the confirmation token on the user's account.

Request example

This example resets the user's password by supplying the old password:

{
 "id" : "4ec0bb1e-37b0-414e-b27e-b17ec8ee9321",
 "newPassword" : "$ecret@123"
 "oldPassword" : "$ecret@456"
}

If successful, HTTP 200 OK is returned in the response.

User Invitation

To invite a new user to your directory you can supply an email address to the /useractions/invite endpoint. This will return the activation link the user will use to complete the registration. The activation link is valid for 24 hours.

If the email invitation is sent to an existing user, this is a resend operation. The new activation link returned invalidates the previous activation link.

Here we invite Joe Border (jborder@pingdevelopers.com) to our directory instance:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{ "email" : "jborder@pingdevelopers.com" }' \
-X POST https://directory-api.pingone.com/api/directory/useractions/invite

The response is the invite activation URL contained in the email sent to the user:

{
  "value":"https://login.pingone.com/idp/directory/a/1234-aaaa-bbbb-5678/registration/confirm/xxyy-jj88-
abcd-12345678/abcd-9876-aaaa-87654321/"
}

Joe will need to click the activation button or link in the email to go to the registration page.

The email attribute is required, and will generate an email invitation using the default PingOne email invitation template. However, there are additional, optional attributes that you can specify to customize the email invitation for your organization. Here's an example:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
--data "@custom_email.json" \
-X POST https://directory-api.pingone.com/api/directory/useractions/invite

Where the content of custom_email.json looks like this:

{
  "email": "jborder@pingdevelopers.com",
  "alternateEmail": "jborder+home@pingdevelopers.com",
  "fromName": "Custom Corp.",
  "bodyText": "Custom email body",
  "titleText": "Welcome to PingOne's customized invitation emails!",
  "supportText": "Need support? Call ...",
  "subject": "Activate your Custom Corp directory membership",
  "activationButtonText": "This is a button!",
  "link": "https://custom.com/register",
  "footerText": "All your footers are belong to us.",
  "footerLogoImage": "https://custom.com/images/customCorpFooter.png",
  "headerImage": "http://custom.com/images/customCorpHeader.png",
  "skipSend": "disabled",
  "redirectLink": "https://mysite.custom.com"
 }

Attribute descriptions

All of these attributes are optional. Any attributes that you don't specify use the default PingOne values.

Attribute Description
alternateEmail If specified, the invitation email is sent to this address instead of the primary email address.
fromName The name of the email sender.
bodyText The body of the email.
titleText The title of the email (displayed above the body).
supportText Contact information for further support.
subject The email subject.
activationButtonText The label used for the activation button.
link The URL used for the activation button. This URL is also displayed below the button.
footerText Text displayed in the footer of the email.
footerLogoImage The URL for an image to be displayed in the email footer. Maximum size: 40 (width) x 70 (height).
headerImage The URL for an image to be displayed in the email header. Maximum size: 606 (width) x 273 (height).
skipSend When set to 'enabled', the email invitation isn't sent to the user, though the activation link is still returned in the response. If unspecified or set to any value other than 'enabled', the email is sent.
redirectLink If specified, the user is redirected to the specified URL when they've completed their invitation process. By default, users are redirected to the PingOne dock.

User Registration Notifications

Preferences

You can use the /userregistration/preferences endpoint to customize the notifications sent that are related to user registrations. Conditions where notifications occur include, password expirations, forgotten passwords, invitations to register, and account locks.

To get all of the current notification preferences for an account:

curl -X GET "https://directory-api.pingone.com/api/directory/userregistration/preferences"

This response will be similar to the following (shown only for invite notification preferences, though preferences for all types will be returned):

[
  {
    "notification_name": "invite",
    "preferences": [
      {
        "values": [
         {
           "name": "product",
           "default_value": "PingOne ®"
         },
         {
           "name": "titleText",
           "default_value": "Welcome to PingOne ®"
         },
         {
           "name": "headerImage",
            "default_value": "http://someImages.com/email/images/activation.jpg"
         },
         {
           "name": "footerText",
           "default_value": ""
         },
         {
           "name": "activationButtonText",
           "default_value": "Activate PingOne ®"
         },
         {
           "name": "subject",
           "default_value": "You have been invited to use PingOne ®"
         },
         {
           "name": "supportText",
           "default_value": ""
         },
         {
           "name": "redirectLink",
           "default_value": "The URL to your PingOne"
         },
         {
           "name": "link",
           "default_value": "https://login.pingone.com/idp/directory/a/${accountId}/
                                registration/confirm/${userId}/${confirmationToken}/"
         },
         {
           "name": "footerLogoImage",
           "default_value": "http://someImages.com/email/images/general/logo.2x.png"
         },
         {
           "name": "bodyText",
           "default_value": " has invited you to PingOne ®.  You're just a few clicks away from
                              the security and convenience of single sign-on access to applications
                              you need to get your job done.  To get started, click the button below."
         },
         {
           "name": "fromName",
           "default_value": "PingOne"
         }
        ]
      }
    ]
  },
 .
 .
 .
]

You can also get the preferences for a single, specified type of notification (shown for forgotten passwords):

curl -X GET
"https://test-directory-api.pingone.com/api/directory/userregistration/preferences/forgot_password"

This will return the preference settings used for forgotten password notifications, similar to the following:

{
  "notification_name": "forgot_password",
  "preferences": [
   {
     "values": [
       {
         "name": "product",
         "default_value": "PingOne ®"
       },
       {
         "name": "redirectLink",
         "default_value": "The URL to your PingOne"
       },
       {
         "name": "footerLogoImage",
         "default_value": "http://someImages.com/email/images/general/footer-logo.2x.png"
       },
       {
         "name": "fromName",
         "default_value": "PingOne"
       }
     ]
   }
  ]
}

You can also set or replace existing or default preference values, or remove preferences (only non-required fields). When notifications are sent, if you've not not assigned a notification preference, the default_value setting is used.

A replace operation with a null value is the same as executing a remove operation.

You can set required fields to null (which will then use the default values). However, you can't set a required field to an empty string.

Required fields

For all email types:

  • fromName
  • product
  • subject

Additional fields

For all email types:

  • bannerText
  • titleText
  • bodyText
  • footerText
  • footerLogoImage

For all email types except self_registered_welcome:

  • activationButtonText
  • link

For invite and forgot_password only:

  • redirectLink

For invite only:

  • headerImage
  • supportText

The following example uses a replace operation:

curl -X PATCH --header "Content-Type: application/json" -d "{
    \"operations\": [
        {\"op\": \"replace\",
              \"path\": \"/forgot_password/preferences/product\",
              \"value\": \"myProduct\"
         }]
}" "https://test-directory-api.pingone.com/api/directory/userregistration/preferences"

The operation returns all notification preferences for the account. In the forgot_password notification type you'll find the changed product name.

Group Membership Count

An example of querying for the number of direct user membership of a group is:

curl -v --user 1234-aaaa-bbbb-5678:eXJzbmVha3kh \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
https://directory-api.pingone.com/api/directory/group/7c513a7e-55d4-441c-858c-7329e6268084/users/count

Which will return the number of users in a JSON object:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "users" : 1
}