Deal Snapshot Documentation

Introduction

This endpoint’s response conforms to the JSON API compound document spec to return a snapshot of a specific deal’s data. This data consists of metadata related to snapshot as well related resources such as the deal the snapshot is of, the latest proposal on the deal, and other related resources.
The following document outlines the list of entities returned in a deal snapshot payload, and how they are structured

Related Resources

Below is a table outlining the related resources that are returned in a deal snapshot payload. Note that these are in hierarchical order, with each resource containing a relationship to the resource below it. Refer to the documentation links for each resource for a list of the attributes returned.

Payload Structure

For a more in-depth breakdown of the schema of a compound document, please refer to the JSON API compound document documentation.

There are 3 top-level sections in the API payload of a deal snapshot entity, data, relationships, and included.

Data

This contains the data tied directly to a deal snapshot entity, such as id and deal_id, among others. For a full list of the attributes, refer to the data object in the “RESPONSE” section of the deal snapshot endpoint documentation.

Relationships

This contains high-level information about the related resources, including the type of entity (e.g. deal) and the id of any specific related entities.

An example of a relationships section may look something like:

"relationships": {
	"deals": {
    "links": {
      "related": "..."
    },
    "data": { "type": "deals", "id": "1" }
  }
}

Where the data section provides information on each individual related resource (the related deal in this instance).

Included

📘

For information on how to parse information from this section, see the Parsing A Deal Snapshot Example

This contains a fully expanded list of all related resources, from the deal-level down. Note that this is a not a nested structure of related resources, each resource is an element of a list on the same level.

Refer to the Parsing A Deal Snapshot Example section for an example includes section.

Parsing A Deal Snapshot

Using a combination of the relationships and includes section we can pull data from the deal snapshot payload.

Starting from the root relationships section, we can use the id of a related resource to find the full object in the includes section. We can do for an arbitrary number of levels until we find the resource that contains the information needed.

Example

Say we wanted to pull the suite name of the space the deal is on given the deal snapshot payload shown below. We can use the following method to traverse the includes section to obtain that information.

1. First, we find the id of the related deal in the first relationships object. In this case, 1
2. Next, we locate deal object in the included section with id: 1
3. From there, we find the related proposal and note its id. In this case, 2
4. Then, we can repeat the last three steps until we come to the spaces object
   1. Find the proposal object with id: 2 and note the id of its related deal_term resource: 3
   2. Then find the deal_term object with id: 3 and note the id of its related spaces_office resource: 4
5. Once we locate the spaces_office object with id:4 we can simply pull the value for suite: 1A

{
  "data": {
    "type": "deal_snapshots",
    "id": "1",
    "attributes": {
      "user_id": 1,
      "account_id": 1
    },
    "relationships": {
      "deal": {
        "data": { "type": "deals", "id": "1" }
      }
    }
  },
  "included": [
    {
      "type": "deals",
      "id": "1",
      "attributes": { ... }
      "relationships": {
        "latest_proposal": {
          "links": { "related": "..." },
          "data": { "type": "proposals", "id": "2" }
        },
        "spaces": {
          "data": [
            { "type": "spaces_office", "id": "4" }
          ]
        }
      }
    },
    {
      "type": "proposals",
      "id": "2",
      "attributes": { ... },
      "relationships": {
        "deal_terms": {
          "links": { "related": "..." },
          "data": [
            { "type": "deal_terms", "id": "3" }
          ]
        }
      }
    },
    {
      "type": "deal_terms",
      "id": "3",
      "attributes": { ... },
      "relationships": {
        "spaces": {
          "links": { "related": "..." },
          "data": [
            { "type": "spaces_office", "id": "4" }
          ]
        }
      }
    },
    {
      "type": "spaces_office",
      "id": "4",
      "attributes": {
        "availability_date": "01-01-2023",
        "current_size": { "magnitude": 1000.0, "type": "area", "unit": "sf", "unit_components": { "area": "sf" } },
        "description": "Et perspiciatis dolorem qui.",
        "floor": { "name": "Floor 0" },
        "suite": "1A"
      },
      "relationships": {
        "asset": {
          "links": { "related": "..." },
          "data": { "type": "assets", "id": "5" }
        }
      }
    },
    {
      "type": "assets",
      "id": "5",
      "attributes": { ... },
      "relationships": {
        "multi_building_asset": {}
      }
    }
  ]
}