Account relationships

You can use the PolicyCenter Cloud API to associate accounts with one another. In PolicyCenter, accounts that are associated with one another are referred to as related accounts.

The Cloud API uses the following fields to manage the account relationships for related accounts:
accountId
The ID of the account for which you are adding, updating, or deleting the account relationship.
relationshipType
The relationship of a related account is identified by one of the following names and codes:
Name Code
Parent of parent
Child of child
Common Ownership commonowner
relationshipId
Each account relationship on an account has a relationshipId that you use to update or delete the relationship. The GET /accounts/{accountId}/relationships endpoint returns the relationshipId for existing account relationships.

When you add an account relationship, PolicyCenter updates both accounts with the appropriate relationship. For example, if you add account B with a Child of relationship to account A, PolicyCenter also updates account B to reflect a Parent of relationship to account A.

For more information on related accounts, see Application Guide.

Query account relationships on an account

You can query an account to view its account relationships. Use the following endpoints to get a list of account relationships:
  • GET /accounts/{accountId}/relationships
  • GET /accounts/{accountId}/relationships/{relationshipId}

For example, the following query returns a list of account relationships for account pc:2:

Command 
GET /accounts/pc:2/relationships
Response
{
  "count": 1,
  "data": [
    {
      "attributes": {
        "id": "pc:1",
        "relatedAccount": {
          "displayName": "9736776741",
          "id": "pc:68",
          "type": "Account",
          "uri": "/account/v1/accounts/pc:68"
        },
        "relationshipType": {
          "code": "parent",
          "name": "Parent of"
        }
      },
      "checksum": "0",
      "links": {
        "self": {
          "href": "/account/v1/accounts/pc:2/relationships/pc:1",
          "methods": [
            "delete",
            "get",
            "patch"
          ]
        }
      }
    }
  ],
  "links": {
    "first": {
      "href": "/account/v1/accounts/pc:2/relationships",
      "methods": [
        "get"
      ]
    },
    "self": {
      "href": "/account/v1/accounts/pc:2/relationships",
      "methods": [
        "get"
      ]
    }
  }
}
In the response, the id pc:1 is the relationshipId that you can use to update or delete this particular account relationship.

Add an account relationship

Use the following endpoint to add an account relationship.
  • POST /accounts/{accountId}/relationships
When you add an account relationship, you define the relationship that associates this account to another account. This endpoint requires the following fields:
  • id of the relatedAccount
  • code of the relationshipType

For example, the following request adds a common owner relationship between account pc:69 and account pc:2:

Command 
POST /accounts/pc:2/relationships
Request body
{
  "data": {
    "attributes": {
      "relatedAccount": {
      "id": "pc:69"
      },
      "relationshipType": {
        "code": "commonowner"
      }
    }
  }
}

Update an account relationship

You can update the relationship type of an existing account relationship. However, you cannot update the account id associated with an existing account relationship.

Use the following endpoint to update the relationship type of the account relationship:
  • PATCH /accounts/{accountId}/relationships/{relationshipId}

This endpoint requires the code field of the relationshipType.

For example, the following request updates the pc:1 relationship on account pc:2 to a parent relationship:

Command
PATCH accounts/pc:2/relationships/pc:1
Request body
{
  "data": {
    "attributes": {
      "relationshipType": {
        "code": "parent"
      }
   }
  }
}
Response body
{
    "data": {
        "attributes": {
            "id": "pc:1",
            "relatedAccount": {
                "displayName": "9736776741",
                "id": "pc:68",
                "type": "Account",
                "uri": "/account/v1/accounts/pc:68"
            },
            "relationshipType": {
                "code": "parent",
                "name": "Parent of"
            }
        },
        "checksum": "0",
        "links": {
            "self": {
                "href": "/account/v1/accounts/pc:2/relationships/pc:1",
                "methods": [
                    "delete",
                    "get",
                    "patch"
                ]
            }
        }
    }
}

The request also updates account pc:68 to reflect the change in relationship type between it and pc:2

Delete an account relationship

Use the following endpoint to delete the relationship between two accounts:
  • DELETE /accounts/{accountId}/relationships/{relationshipId}

For example, the following request deletes account relationship pc:1 from account pc:2:

Command 
DELETE /accounts/pc:2/relationships/pc:1

This request also deletes account relationship pc:1 from the related account.