Graph Expressions

Graph Expressions are special filters applied to entity's ID. Graph Expression is resolved to a set of IDs matching the expression. Graph Expressions are used to query companies within Company Hierarchy structure. Graph expression specifies ID of a company and type of relation. It is then resolved to set of IDs of companies that are in specified relation with one whose ID was specified.

Available types of relations:

• parent - company's parent in relation tree
• siblings - children of company's parent in relation tree
• children - children of company in relation tree
• subtree - all companies in subtree rooted in company's node in relation tree
• root - root of company's relation tree
• ancestors - all companies on path from company to root of relation tree

For now graph expressions are only supported for companies.

The example query returns names and IDs of companies that are direct children of company with ID 56789 (which is BigCompany US):

Fetch children of a company

POST /v3/contacts/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "projection": [
            {
              "name": "company_name"
            }
          ],
          "filter": {
            "filter": {
              "attribute": {
                "name": "id"
              },
              "parameter": {
                "graph_expression": {
                  "association": "children",
                  "node": {
                    "id": 56789,
                    "type": "company"
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}

Content-Type: application/json; charset=UTF-8

{
  "items": [
    {
      "successful": true,
      "items": [
        {
          "data": {
            "company_name": "BigCompany US East",
            "id": 1111,
            "version": 5
          },
          "meta": {
            "type": "contact"
          }
        },
        {
          "data": {
            "company_name": "BigCompany US South",
            "id": 2222,
            "version": 11
          },
          "meta": {
            "type": "contact"
          }
        },
        {
          "data": {
            "company_name": "BigCompany US West",
            "id": 333,
            "version": 1
          },
          "meta": {
            "type": "contact"
          }
        }
      ],
      "meta": {
        "count": 3,
        "http_status": "200 OK",
        "links": {},
        "total_count": 3,
        "type": "collection"
      }
    }
  ]
}

---

Changing association parameter to siblings would result with following response:

Fetch siblings of a company

POST /v3/contacts/search

Authorization: Bearer $ACCESS_TOKEN
Content-Type: application/json

{
  "items": [
    {
      "data": {
        "query": {
          "projection": [
            {
              "name": "company_name"
            }
          ],
          "filter": {
            "filter": {
              "attribute": {
                "name": "id"
              },
              "parameter": {
                "graph_expression": {
                  "association": "siblings",
                  "node": {
                    "id": 56789,
                    "type": "company"
                  }
                }
              }
            }
          }
        }
      }
    }
  ]
}

Content-Type: application/json; charset=UTF-8

{
  "items": [
    {
      "successful": true,
      "items": [
      {
        "data": {
          "company_name": "BigCompany Asia",
          "id": 23456,
          "version": 21
        },
        "meta": {
          "type": "contact"
        }
      },
      {
        "data": {
          "company_name": "BigCompany Australia",
          "id": 45678,
          "version": 7
        },
        "meta": {
          "type": "contact"
        }
      },
      {
          "data": {
            "company_name": "BigCompany Europe",
            "id": 12345,
            "version": 3
          },
          "meta": {
            "type": "contact"
          }
        },
        {
          "data": {
            "company_name": "BigCompany South America",
            "id": 34567,
            "version": 2
          },
          "meta": {
            "type": "contact"
          }
        }
      ],
      "meta": {
        "count": 4,
        "http_status": "200 OK",
        "links": {},
        "total_count": 4,
        "type": "collection"
      }
    }
  ]
}