Ingesting data

info

You will need to get a personal access token to use the ingestion APIs.

All ingestion requests use the ingestion API with the following structure:

📄 ingest.sh

#!/bin/sh -ex

# Your organization
STONAL_ORG=DEMO

# Fetch your token from here: https://app.stonal.io/users/app
STONAL_TOKEN=9631e269-e21e-4ce6-92a9-c6f7ed1fa98a

curl \
  https://api.stonal.io/datalake/v1/organizations/$STONAL_ORG/assets \
  -v \
  -X POST \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $STONAL_TOKEN" \
  -d @payload.json

Root level assets

BUILDING_GROUP, BUILDING

These are the top-level assets in your hierarchy. A BUILDING_GROUP represents a site containing multiple buildings, and BUILDING represents a logical building as managed in your ERP.

📄 root-assets.json

{
  "assets": [
    {
      "externalIds": {
        "CODE": "SITE_001"
      },
      "type": "BUILDING_GROUP",
      "name": "Residence du Parc",
      "properties": {
        "simple": {
          "ADDRESS": "123 Rue de la Paix, Paris, France"
        }
      }
    },
    {
      "externalIds": {
        "CODE": "SITE_001_BAT_001"
      },
      "type": "BUILDING",
      "name": "Bâtiment A",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001"
        }
      }
    }
  ]
}

Physical building structure

PLAN|INDOOR, LEVEL, SPACE

Physical assets describe the actual geometry of your buildings. A PLAN|INDOOR groups multiple floors, a LEVEL represents a single floor, and SPACE represents rooms.

📄 physical-assets.json

{
  "assets": [
    {
      "externalIds": {
        "CODE": "SITE_001_INDOOR_001"
      },
      "type": "PLAN|INDOOR",
      "name": "Plan Bâtiment A",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001"
        }
      },
      "groupedBy": [
        {
          "externalIds": {
            "CODE": "SITE_001_BAT_001"
          }
        }
      ]
    },
    {
      "externalIds": {
        "CODE": "SITE_001_LEVEL_RDC"
      },
      "type": "LEVEL",
      "name": "Rez-de-chaussée",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001_INDOOR_001"
        }
      }
    },
    {
      "externalIds": {
        "CODE": "SITE_001_SPACE_001"
      },
      "type": "SPACE",
      "name": "Bureau 101",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001_LEVEL_RDC"
        }
      },
      "groupedBy": [
        {
          "externalIds": {
            "CODE": "SITE_001_ZONE_001"
          }
        }
      ]
    }
  ]
}

tip

The groupedBy field on a PLAN|INDOOR links it to a logical BUILDING. This allows you to associate physical plans with your ERP's building structure.

Logical assets

RENTED_UNIT, ZONE

Logical assets organize spaces for business purposes. A RENTED_UNIT represents a housing unit that can be rented (linked to contracts), and a ZONE groups multiple spaces together (an apartment, a set of offices, etc.).

📄 logical-assets.json

{
  "assets": [
    {
      "externalIds": {
        "CODE": "SITE_001_APT_101"
      },
      "type": "RENTED_UNIT",
      "name": "Appartement 101",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001_BAT_001"
        }
      }
    },
    {
      "externalIds": {
        "CODE": "SITE_001_ZONE_001"
      },
      "type": "ZONE",
      "name": "Appartement T3",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001_LEVEL_RDC"
        }
      },
      "groupedBy": [
        {
          "externalIds": {
            "CODE": "SITE_001_APT_101"
          }
        }
      ]
    }
  ]
}

tip

The groupedBy field on a ZONE links it to a RENTED_UNIT, allowing you to associate physical spaces with rentable units and their contracts.

Equipments and Openings

EQUIPMENT, OPENING

Openings represent doors, windows, and other passages within a space. Equipments are items installed in openings (doors, windows) or directly in spaces (radiators, etc.).

📄 equipments-openings.json

{
  "assets": [
    {
      "externalIds": {
        "CODE": "SITE_001_OPENING_001"
      },
      "type": "OPENING",
      "name": "Porte entrée Bureau 101",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001_SPACE_001"
        }
      }
    },
    {
      "externalIds": {
        "CODE": "SITE_001_DOOR_001"
      },
      "type": "EQUIPMENT",
      "name": "Porte bois",
      "parent": {
        "externalIds": {
          "CODE": "SITE_001_OPENING_001"
        }
      }
    }
  ]
}

Response format

A successful ingestion returns the created/updated assets with their generated uid:

➡️ output

{
  "assets": [
    {
      "uid": "272e9b9c-31f1-4a6b-86af-a8737031a2bc",
      "externalIds": {
        "CODE": "SITE_001"
      },
      "type": "BUILDING_GROUP",
      "name": "Residence du Parc",
      "properties": {
        "source": "DEFAULT",
        "simple": {
          "ADDRESS": "123 Rue de la Paix, Paris, France"
        }
      }
    }
  ]
}