---
title: Create a relationship between two objects
description: In the default IDM schema, several user properties are defined as relationships, for example, the manager relationship.
component: pingoneaic
page_id: pingoneaic:idm-objects:relationships-between-objects
canonical_url: https://docs.pingidentity.com/pingoneaic/idm-objects/relationships-between-objects.html
keywords: ["Data Object Model", "Relationships", "REST API"]
---

# Create a relationship between two objects

In the default IDM schema, several user properties are defined as relationships, for example, the `manager` relationship.

Relationships let you *reference* one managed object from another using the `_ref*` relationship properties. Three properties make up a relationship reference:

* `_refResourceCollection` specifies the container of the referenced object, for example, `managed/realm-name_user`.

* `_refResourceId` specifies the ID of the referenced object. This is generally a system-generated UUID, such as `9dce06d4-2fc1-4830-a92b-bd35c2f6bcbb`.

* `_ref` is a derived path that is a combination of `_refResourceCollection` and a URL-encoded `_refResourceId`.

For example, imagine that you are creating a new user, `psmith`, and that `psmith`'s manager is `bjensen`. You would add `psmith`'s user entry, and *reference* `bjensen`'s entry with the `_ref` property.

First, retrieve `bjensen`'s UUID, displayed in the `_id` property value.

```
curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22bjensen%22"
{
  "result": [
    {
      "_id": "1dff18dc-ac57-4388-8127-dff309f80002",
      "_rev": "f4816053-aa01-4a7b-8380-8f3646787fd0-23348",
      "country": null,
      ...
    }
  ]
  ...
}
```

Next, add the new user `psmith` and specify `bjensen` as the manager using the `_ref` property. Make sure to use `bjensen`'s UUID, for example, `1dff18dc-ac57-4388-8127-dff309f80002`.

```
curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--header "Content-Type: application/json" \
--request POST \
--data '{
  "sn":"Smith",
  "userName":"psmith",
  "givenName":"Patricia",
  "displayName":"Patti Smith",
  "description" : "psmith - new user",
  "mail" : "psmith@example.com",
  "telephoneNumber" : "0831245986",
  "password" : "Passw0rd",
  "manager" : {"_ref" : "managed/realm-name_user/1dff18dc-ac57-4388-8127-dff309f80002"}
}' \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_action=create"
{
  "_id": "51257f1e-6562-4b67-a80b-47b84f693f1b",
  "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34787",
  "country": null,
  "frUnindexedString1": null,
  "mail": "psmith@example.com",
  "memberOfOrgIDs": [],
  ...
}
```

Note that relationship information is not returned by default. To show the relationship in `psmith`'s entry, you must explicitly request their manager entry, as follows:

```
curl \
--header "Authorization: Bearer <access-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": "51257f1e-6562-4b67-a80b-47b84f693f1b",
      "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34787",
      "manager": {
        "_ref": "managed/alpha_user/1dff18dc-ac57-4388-8127-dff309f80002",
        "_refResourceCollection": "managed/alpha_user",
        "_refResourceId": "1dff18dc-ac57-4388-8127-dff309f80002",
        "_refProperties": {
          "_id": "3dd2c42d-598e-4b78-bf59-0aab43113be7",
          "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34784"
        }
      }
    }
  ],
  ...
}
```

If a relationship changes, you can query the updated relationship state when any referenced managed objects are queried. So, after creating user `psmith` with manager `bjensen`, run a query on `bjensen`'s user entry. The query shows a reference to `psmith`'s entry in their `reports` property, which is configured as the `reversePropertyName` of the `manager` property.

The following query shows `bjensen`'s direct reports including the new user entry, `psmith`:

```
curl \
--header "Authorization: Bearer <access-token>" \
--header "Accept-API-Version: resource=1.0" \
--request GET \
"https://<tenant-env-fqdn>/openidm/managed/realm-name_user?_queryFilter=userName+eq+%22bjensen%22&_fields=reports"
{
  "result": [
    {
      "_id": "1dff18dc-ac57-4388-8127-dff309f80002",
      "_rev": "f4816053-aa01-4a7b-8380-8f3646787fd0-23348",
      "reports": [
        ...
        {
          "_ref": "managed/alpha_user/51257f1e-6562-4b67-a80b-47b84f693f1b",
          "_refResourceCollection": "managed/alpha_user",
          "_refResourceId": "51257f1e-6562-4b67-a80b-47b84f693f1b",
          "_refProperties": {
            "_id": "3dd2c42d-598e-4b78-bf59-0aab43113be7",
            "_rev": "6aad0f3b-eb20-4ae4-8c72-7e904b1062e5-34784"
          }
        }
      ]
    }
  ],
  ...
}
```

|   |                                                                                                                                                                                                                                                                      |
| - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | IDM maintains referential integrity by deleting the relationship reference if the object referred to by that relationship is deleted. In our example, if `bjensen`'s user entry is deleted, the corresponding reference in `psmith`'s `manager` property is removed. |