Building Owners

Manage building owners (customers) and their resources. Building owners are the top-level organisational entity — each owns one or more buildings.

List Building Owners

GET/building_owners

List all building owners accessible to your API key. Results are paginated.

Authentication

x-api-key header

  • next_tokenstringPagination token — pass the nextToken value from a previous response

Examples

curl -H "x-api-key: YOUR_API_KEY" \
  https://api.findable.ai/building_owners
  • 200Success
  • 401Missing or invalid API key

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • buildingOwnersBuildingOwner[]Array of building owner objects
  • buildingOwners[].idstringUnique identifier
  • buildingOwners[].namestringDisplay name
  • buildingOwners[].createdAtstringISO 8601 creation timestamp
  • buildingOwners[].updatedAtstringISO 8601 last update timestamp
  • nextTokenstring | nullToken for the next page, null if this is the last page

Response

{
  "buildingOwners": [
    {
      "id": "cust-456",
      "name": "Barcode Properties AS",
      "createdAt": "2024-03-10T09:00:00Z",
      "updatedAt": "2025-11-15T12:30:00Z"
    }
  ],
  "nextToken": null
}

Create Building Owner

POST/building_owners

Create a new building owner.

Authentication

x-api-key header

  • namestringrequiredDisplay name for the building owner

Request Body Example

{ "name": "Barcode Properties AS" }
  • 201Building owner created
  • 400Invalid request body
  • 401Missing or invalid API key
  • 403API key lacks permission

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • idstringUnique identifier for the newly created building owner

Response

{ "id": "cust-789" }

Get Building Owner

GET/building_owners/{buildingOwnerId}

Get a single building owner by ID.

Authentication

x-api-key header

  • buildingOwnerIdstringBuilding owner ID
  • 200Success
  • 401Missing or invalid API key
  • 404Building owner not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • idstringUnique identifier
  • namestringDisplay name
  • createdAtstringISO 8601 creation timestamp
  • updatedAtstringISO 8601 last update timestamp

Response

{
  "id": "cust-456",
  "name": "Barcode Properties AS",
  "createdAt": "2024-03-10T09:00:00Z",
  "updatedAt": "2025-11-15T12:30:00Z"
}

Update Building Owner

PATCH/building_owners/{buildingOwnerId}

Update building owner details.

Authentication

x-api-key header

  • buildingOwnerIdstringBuilding owner ID
  • namestringUpdated display name

Request Body Example

{ "name": "Barcode Properties ASA" }
  • 200Building owner updated
  • 400Invalid request body
  • 401Missing or invalid API key
  • 403API key lacks permission
  • 404Building owner not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • idstringUnique identifier
  • namestringUpdated display name
  • createdAtstringISO 8601 creation timestamp
  • updatedAtstringISO 8601 last update timestamp

Response

{
  "id": "cust-456",
  "name": "Barcode Properties ASA",
  "createdAt": "2024-03-10T09:00:00Z",
  "updatedAt": "2025-12-01T08:15:00Z"
}

Delete Building Owner

DELETE/building_owners/{buildingOwnerId}

Delete a building owner and all associated resources.

Authentication

x-api-key header

  • buildingOwnerIdstringBuilding owner ID
  • 200Building owner deleted
  • 401Missing or invalid API key
  • 403API key lacks permission
  • 404Building owner not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • successbooleanAlways true on success

Response

{ "success": true }

Processing Status

GET/building_owners/{buildingOwnerId}/status

Get the aggregate processing status across all buildings for a building owner.

Authentication

x-api-key header

  • buildingOwnerIdstringBuilding owner ID
  • 200Success
  • 401Missing or invalid API key
  • 404Building owner not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • total_documentsnumberTotal number of documents
  • processed_documentsnumberNumber of documents that have been processed
  • categorized_documentsnumberNumber of documents that have been categorised
  • extracted_percentagenumberPercentage of documents with extracted text (0-100)
  • categorized_percentagenumberPercentage of documents that are categorised (0-100)
  • extracted_textbooleanWhether text extraction is complete
  • extracted_filebooleanWhether file extraction is complete
  • uncompressed_packagebooleanWhether package decompression is complete
  • valid_filebooleanWhether the file is valid
  • invalid_filebooleanWhether any files are invalid
  • categorisedbooleanWhether categorisation is complete
  • skip_extract_filebooleanWhether file extraction was skipped
  • text_extraction_errorbooleanWhether a text extraction error occurred

Response

{
  "total_documents": 5200,
  "processed_documents": 5100,
  "categorized_documents": 4980,
  "extracted_percentage": 98,
  "categorized_percentage": 96,
  "extracted_text": true,
  "extracted_file": true,
  "uncompressed_package": true,
  "valid_file": true,
  "invalid_file": false,
  "categorised": true,
  "skip_extract_file": false,
  "text_extraction_error": false
}

Search Across Buildings

GET/building_owners/{buildingOwnerId}/search

Search documents across all buildings for a building owner.

Authentication

x-api-key header

  • buildingOwnerIdstringBuilding owner ID
  • querystringrequiredSearch query
  • max_resultsnumberMaximum results (default: 10)
  • start_indexnumberOffset for pagination (default: 0)

Examples

curl -H "x-api-key: YOUR_API_KEY" \
  "https://api.findable.ai/building_owners/cust-456/search?query=fire+safety&max_results=5"
  • 200Success
  • 401Missing or invalid API key
  • 404Building owner not found

All endpoints may also return 429 (rate limit) and 500 (server error). See Common Patterns for details.

  • hitsSearchHit[]Array of matching documents
  • hits[].idstringDocument ID
  • hits[].buildingIdstringBuilding the document belongs to
  • hits[].filenamestringDocument filename
  • hits[].titlestringDocument title
  • hits[].buildingCategorystringAssigned building category
  • hits[].disciplinestringDocument discipline
  • hits[].isDrawingbooleanWhether the document is a drawing
  • hits[].md5ChecksumstringMD5 checksum of the file
  • hits[].originalCreatedAtstringOriginal creation date from the file metadata
  • hits[].originalPathstringOriginal file path
  • hits[].sizenumberFile size in bytes
  • hits[].informationTypestringPrimary information type
  • hits[].informationTypesstring[]All assigned information types
  • hits[].createdAtstringISO 8601 creation timestamp
  • hits[].updatedAtstringISO 8601 last update timestamp
  • hits[].externalIdsRecord<string, string>External system IDs (e.g. Plania)
  • numberOfHitsnumberTotal number of matching documents

Response

{
  "hits": [
    {
      "id": "doc-1",
      "buildingId": "bld-789",
      "filename": "fire-safety-report.pdf",
      "title": "Fire Safety Assessment 2025",
      "buildingCategory": "Fire Safety",
      "discipline": "Fire",
      "isDrawing": false,
      "md5Checksum": "a3f2b8c1e9d04567890abcdef1234567", // pragma: allowlist secret
      "originalCreatedAt": "2025-01-10T08:00:00Z",
      "originalPath": "/reports/fire-safety/",
      "size": 2048576,
      "informationType": "Report",
      "informationTypes": ["Report", "Assessment"],
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-06-20T14:00:00Z",
      "externalIds": {}
    }
  ],
  "numberOfHits": 156
}