PingOne Advanced Identity Cloud

View relationships over REST

By default, information about relationships is not returned as the result of a GET request on a managed object. You must explicitly include the relationship property in the request. For example, if you request a user’s manager entry, the manager's _ref property returns the UUID (managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002) of the manager, bjensen.

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22psmith%22&_fields=manager"
{
  "result": [
    {
      "_id": "4121ae44-7bf4-4dcb-b853-cfc8b5b8581c",
      "_rev": "e7b5a983-c0dc-405d-9d6a-cf0e186e5abf-66315",
      "manager": {
        "_ref": "managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002",
        "_refResourceCollection": "managed/alpha_user",
        "_refResourceId": "1dff18dc-ac57-4388-8127-dff309f80002",
        "_refProperties": {
          "_id": "152ae6f2-d862-46df-8569-9cc2b2e6533a",
          "_rev": "a41bb123-7755-4ceb-9e49-e0f26b5912a8-15964"
        }
      }
    }
  ],
  ...
}

To obtain more information about the referenced object (psmith's manager, in this case), you can include additional fields from the referenced object in the query, using the syntax object/property (for a simple string value) or object/*/property (for an array of values).

The following example returns the email address and contact number for psmith's manager:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22psmith%22&_fields=manager/mail,manager/telephoneNumber"
{
  "result": [
    {
      "_id": "4121ae44-7bf4-4dcb-b853-cfc8b5b8581c",
      "_rev": "e7b5a983-c0dc-405d-9d6a-cf0e186e5abf-66315",
      "manager": {
        "_rev": "b5ae9a0e-cc07-45ba-8a9e-d8c43aa3ff13-4157",
        "_id": "1dff18dc-ac57-4388-8127-dff309f80002",
        "mail": "bjensen@example.com",
        "telephoneNumber": null,
        "_ref": "managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002",
        "_refResourceCollection": "managed/alpha_user",
        "_refResourceId": "1dff18dc-ac57-4388-8127-dff309f80002",
        "_refProperties": {
          "_id": "152ae6f2-d862-46df-8569-9cc2b2e6533a",
          "_rev": "a41bb123-7755-4ceb-9e49-e0f26b5912a8-15964"
        }
      }
    }
  ],
  ...
}

To query all the relationships associated with a managed object, query the reference (*_ref) property of that object. The following example shows all the objects referenced by psmith's entry:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22psmith%22&_fields=*_ref"
{
  "result": [
  {
    "_id": "4121ae44-7bf4-4dcb-b853-cfc8b5b8581c",
    "_rev": "e7b5a983-c0dc-405d-9d6a-cf0e186e5abf-66315",
    "reports": [],
    "manager": {
      "_ref": "managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002",
      "_refResourceCollection": "managed/alpha_user",
      "_refResourceId": "1dff18dc-ac57-4388-8127-dff309f80002",
      "_refProperties": {
        "_id": "152ae6f2-d862-46df-8569-9cc2b2e6533a",
        "_rev": "a41bb123-7755-4ceb-9e49-e0f26b5912a8-15964"
      }
    },
    "adminOfOrg": [],
    "memberOfOrg": [],
    "ownerOfOrg": [],
    "roles": [],
    "_meta": {
      "_ref": "managed/alpha_usermeta/95718189-7138-4e18-97c4-5fe42e4cabb5",
      "_refResourceCollection": "managed/alpha_usermeta",
      "_refResourceId": "95718189-7138-4e18-97c4-5fe42e4cabb5",
      "_refProperties": {
        "_id": "57306c2d-8a49-49cc-9088-ef269a16d067",
        "_rev": "a41bb123-7755-4ceb-9e49-e0f26b5912a8-15967"
      }
    },
    "authzRoles": [],
    "_notifications": []
  }
  ],
  ...
}

To expand that query to show all fields within each relationship, add a wildcard (*) as follows:

curl \
--header "Authorization: Bearer <token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22psmith%22&_fields=*_ref/*"
{
  "result": [
    {
      "_id": "4121ae44-7bf4-4dcb-b853-cfc8b5b8581c",
      "_rev": "e7b5a983-c0dc-405d-9d6a-cf0e186e5abf-66315",
      "reports": [],
      "manager": {
        "_rev": "b5ae9a0e-cc07-45ba-8a9e-d8c43aa3ff13-4157",
        "_id": "1dff18dc-ac57-4388-8127-dff309f80002",
        "accountStatus": "active",
        "aliasList": null,
        "assignedDashboard": null,
        "city": null,
        "consentedMappings": null,
        "country": null,
        "description": "Password = Password1!",
        "displayName": null,
        "effectiveAssignments": null,
        "effectiveRoles": null,
        "frIndexedDate1": null,
        ...
        "frIndexedInteger1": null,
        ...
        "frIndexedMultivalued1": null,
        ...
        "frIndexedString2": null,
        ...
        "frUnindexedDate1": null,
        ...
        "frUnindexedInteger1": null,
        ...
        "frUnindexedMultivalued1": null,
        ...
        "frUnindexedString1": null,
        ...
        "givenName": "Babs",
        "isMemberOf": [
          "cn=am-policy-evaluation,ou=groups,o=alpha,o=root,ou=identities"
        ],
        "kbaInfo": null,
        "mail": "bjensen@example.com",
        "memberOfOrgIDs": null,
        "postalAddress": null,
        "postalCode": null,
        "preferences": null,
        "profileImage": null,
        "sn": "Jensen",
        "stateProvince": null,
        "telephoneNumber": null,
        "userName": "bjensen",
        "_ref": "managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002",
        "_refResourceCollection": "managed/alpha_user",
        "_refResourceId": "1dff18dc-ac57-4388-8127-dff309f80002",
        "_refProperties": {
          "_id": "152ae6f2-d862-46df-8569-9cc2b2e6533a",
          "_rev": "a41bb123-7755-4ceb-9e49-e0f26b5912a8-15964"
        }
      },
      "adminOfOrg": [],
      "memberOfOrg": [],
      "ownerOfOrg": [],
      "roles": [],
      "_meta": {
        "_rev": "e7b5a983-c0dc-405d-9d6a-cf0e186e5abf-66336",
        "_id": "95718189-7138-4e18-97c4-5fe42e4cabb5",
        "createDate": "2022-11-02T16:35:20.112988Z",
        "lastChanged": {
          "date": "2022-11-02T16:35:20.113032Z"
        },
        "loginCount": 1,
        "_ref": "managed/alpha_usermeta/95718189-7138-4e18-97c4-5fe42e4cabb5",
        "_refResourceCollection": "managed/alpha_usermeta",
        "_refResourceId": "95718189-7138-4e18-97c4-5fe42e4cabb5",
        "_refProperties": {
          "_id": "57306c2d-8a49-49cc-9088-ef269a16d067",
          "_rev": "a41bb123-7755-4ceb-9e49-e0f26b5912a8-15967"
        }
      },
      "authzRoles": [],
      "_notifications": []
    }
  ],
  ...
}

Metadata is implemented using the relationships mechanism. When you request all relationships for a user with _ref/, you also get all the metadata for that user if metadata is being tracked. For more information, refer to Enable self-service by tracking user metadata.