Flat and nested entities

In the standard entities.ftm.json export that includes one entity per line, or when using GET /entities/<id>?nested=false (the flat representation), an entity's properties contain only scalar values and entity IDs.

You can get nested entities from the entities API endpoint (which defaults to nested=true) or from the targets.nested.json bulk data export.

To illustrate, we use Alexander Zakharov (NK-aU5ybkbRFJucf8YMwsJvDw) as a running example.

The flat representation#

Here is a trimmed flat representation of the entity:

{
  "id": "NK-aU5ybkbRFJucf8YMwsJvDw",
  "schema": "Person",
  "properties": {
    "name": ["Alexander Vyacheslavovich ZAKHAROV"],
    "birthDate": ["1965-09-21"],
    "country": ["ru"],
    "position": ["Owner of LLC CST"],
    "addressEntity": ["addr-a300b5bf407e387d2cf1f1a2f74b8178edde276e"]
  }
}

The addressEntity property contains only an opaque entity ID. Despite him being sanctioned by many different authorities, his entity has no sanctions property. That is because sanctions data works the other way around: each Sanction entity points at the person it applies to via its own entity property. The Person entity itself does not own the reference. One of those sanctions, in the flat format:

{
  "id": "ofac-927f7a4547f68cd05570180fed763dd2d5d8eca7",
  "schema": "Sanction",
  "properties": {
    "authority": ["Office of Foreign Assets Control"],
    "program": ["RUSSIA-EO14024"],
    "country": ["us"],
    // reference to Zakharov
    "entity": ["NK-aU5ybkbRFJucf8YMwsJvDw"]
  }
}

The same is true for his ownership records, family connections, and directorships — they all live as separate entities that you would need to find independently.

The nested representation#

The nested format includes inbound relationships as additional properties and replaces entity IDs with the full data of the entity they refer to:

{
  "id": "NK-aU5ybkbRFJucf8YMwsJvDw",
  "schema": "Person",
  "properties": {
    "name": ["Alexander Vyacheslavovich ZAKHAROV"],
    "birthDate": ["1965-09-21"],
    "country": ["ru"],
    "position": ["Owner of LLC CST"],
    "addressEntity": [ // an entity ID in the flat representation
      {
        "id": "addr-a300b5bf407e387d2cf1f1a2f74b8178edde276e",
        "schema": "Address",
        "properties": {
          "full": ["272 Pushkinskaya Street, Apt 41, Izhevsk, 426008"],
          "street": ["272 Pushkinskaya Street, Apt 41"],
          "city": ["Izhevsk"],
          "postalCode": ["426008"],
          "country": ["ru"]
        }
      }
    ],
    "ownershipOwner": [ // inverse of Ownership:owner
      {
        "id": "ru-770bdf5f22537fa2a94176f53fa87fe28ecf94fa",
        "schema": "Ownership",
        "properties": {
          // back-reference to main entity
          "owner": ["NK-aU5ybkbRFJucf8YMwsJvDw"],
          "percentage": ["50"],
          "startDate": ["2015-11-25"],
          "endDate": ["2023-03-02"],
          "asset": [
            {
              "id": "NK-abdzbEBkqyT29GyREbiURZ",
              "schema": "Company",
              "properties": {
                "name": ["LLC CST"],
                "country": ["ru"]
              }
            }
          ]
        }
      }
    ],
    "sanctions": [ // inverse of Sanction:entity
      {
        "id": "ofac-927f7a4547f68cd05570180fed763dd2d5d8eca7",
        "schema": "Sanction",
        "properties": {
          "authority": ["Office of Foreign Assets Control"],
          "program": ["RUSSIA-EO14024"],
          "country": ["us"],
          // back-reference to main entity
          "entity": ["NK-aU5ybkbRFJucf8YMwsJvDw"]     
        }
      }
    ],
    "familyRelative": [ // inverse of Family:relative
      {
        "id": "ofac-b933fd32f149a0c4e27e748b4f8a44f30caccc38",
        "schema": "Family",
        "properties": {
          "relationship": ["Family member of"],
           // back-reference to main entity
          "relative": ["NK-aU5ybkbRFJucf8YMwsJvDw"], 
          "person": [
            {
              "id": "NK-hUAjuiA3vTKXF6v2X6MYnS",
              "schema": "Person",
              "properties": {
                "name": ["Lavrentii Aleksandrovich Zakharov"],
                "birthDate": ["1999-02-26"],
                "country": ["ru"]
              }
            }
          ]
        }
      }
    ]
  }
}

Three things are happening here:

Outbound references are expanded inline#

Some schemas define properties that directly reference other entities by ID — for example, addressEntity on a Person. In the flat format these contain only entity IDs; in the nested format they are expanded inline, just like stub properties. For a full list of schemas and their properties, see the data dictionary.

Inbound relationships appear as stub properties #

sanctions does not exist as a property on the Person schema. It is a stub property: the reverse direction of Sanction:entity, which points from a Sanction to the person it applies to. The nested format collects all entities that reference the entity through this property and attaches them to it.

Interstitial entities connect two entities#

ownershipOwner and familyRelative are also stub properties — the inverses of Ownership:owner and Family:relative respectively. But Ownership and Family are interstitial entities: they exist to connect two other entities and can carry metadata about the relationship, such as date ranges or ownership percentages. Interstitial entities get an extra level of nesting so that the entity on the other end is included too.

In the ownership example, the asset property is expanded to show LLC CST as a full Company entity. In the family example, the person property is expanded to show Lavrentii Zakharov as a full Person with a birthDate and other properties.

This extra layer of nesting is what makes ownership structures, family ties, and directorships useful in the nested format. Without the extra level, you would see the Ownership or Family entity but still need a separate lookup to find out who or what is on the other end.