> ## Documentation Index
> Fetch the complete documentation index at: https://docs.4minds.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Spacebase

> Connect 4Minds to Spacebase to import lease-administration data for AI-powered analysis

## Overview

The 4Minds platform integrates with **Spacebase**, allowing you to import lease-administration data directly into your 4Minds datasets. You can pull in leases, lease custom fields, headcount and capacity history, invoices, invoice expenses and payments, journal entry exports, and company users. Each data type you select is imported as its own **Parquet** file.

The integration is **read-only**. 4Minds never creates, updates, or deletes anything in your Spacebase account.

***

## Getting Started

### Prerequisites

* A Spacebase account with **Enterprise API access** (included in Spacebase's Enterprise plan; ask your Spacebase account manager if you're not sure whether your contract includes it)
* A **Spacebase API token** (see below)
* The Spacebase modules and permissions required for the data types you want to import (see [Access Requirements](#access-requirements) below)

### Getting a Spacebase API Token

1. Log in to Spacebase.
2. Open the **Account** menu in the top right corner and select **Enterprise API**.
3. Copy your API token.

Alternatively, while signed in to Spacebase in your browser, open `https://spacebaseapp.com/api/token/`. The token is the `key` value in the response.

> **Note:** The Spacebase API is only available on the Enterprise plan, and your Spacebase user must be issued an API token. If you don't have a token, ask your Spacebase account manager to set one up. If your company isn't on the Enterprise plan, contact [support@spacebaseapp.com](mailto:support@spacebaseapp.com) about upgrading.

> **Note:** The API token has the same access as your Spacebase user. Your in-app permissions apply, so if your user is limited to certain leases, regions, or property types, 4Minds can only import those. Treat the token like a password.

### Connecting Your Spacebase Account

1. Open **Integrations** from the main navigation bar in 4Minds.
2. Find the **Spacebase** integration and click **Connect**.
3. Paste your token into the **API token** field.
4. Click **Test Connection** to verify your token. If it works, 4Minds shows how many leases your account can see.
5. Click **Save Credentials** to complete the setup.

### Disconnecting

To disconnect your Spacebase account, open **Integrations** from the main navigation bar, find Spacebase, and click **Disconnect**. This removes your stored token from 4Minds.

***

## Available Data Types

Spacebase data is grouped into four sections. Each data type you select produces one Parquet file in your dataset (for example, `spacebase_leases.parquet`).

| Section | Data Type | Description |
| - | - | - |
| **Leases** | **Leases** | Full lease records (published leases only; draft leases aren't available through the Spacebase API) |
| | **Lease custom field values** | The custom field values set on each lease |
| | **Headcount history** | Headcount history for each lease |
| | **Capacity history** | Capacity history for each lease |
| **Invoices and payments** | **Invoices** | Invoice records |
| | **Invoice expenses** | The expenses on each invoice |
| | **Invoice payments** | The payments recorded against each invoice |
| **Accounting** | **Journal entry exports** | Journal entry export records |
| **Company settings** | **Custom field definitions** | The custom fields defined for your company |
| | **Custom field options** | The options for each dropdown custom field |
| | **Users** | Users in your Spacebase company |

Some data types (lease custom field values, headcount, capacity, invoice expenses, invoice payments, and custom field options) are read **per parent record**. For example, 4Minds reads the list of leases first, then reads headcount history for each lease.

> [!NOTE]
>
> **Custom field definitions** and **custom field options** are offered on a provisional basis. Spacebase's public API documentation doesn't confirm read access for these endpoints, so importing them may fail on some accounts.

***

## Access Requirements

Every data type requires **Enterprise API access** on your Spacebase account. Some also need a specific module or user permission:

| Data Type | Additional Requirement |
| - | - |
| Leases | None |
| Headcount history, Capacity history | Headcount tracking enabled for the lease's property type |
| Lease custom field values, Custom field definitions, Custom field options | The **manage company settings** permission |
| Invoices, Invoice expenses, Invoice payments | The **payments** module |
| Journal entry exports | The **accounting** module |
| Users | The **manage company users** permission |

When you open the data type picker, 4Minds checks which data types your token can actually read. Data types you can't access are shown as unavailable with a reason (for example, missing permission), and can't be selected.

***

## Importing Data

### Creating a Dataset with Spacebase Data

1. Create a new dataset (or edit an existing one).
2. Select **Spacebase** as a data source.
3. The platform checks your Spacebase connection. If you're not connected, you'll be prompted to set up the connection first.
4. 4Minds checks which data types your account can read. Available data types are displayed by section with checkboxes.
5. Select the data types you want to import. Nothing is selected by default.
6. Click **Add** to stage the selected data types for import.
7. Complete the dataset creation to start the import.

### Tracking Import Progress

Each selected data type is imported and tracked separately in the activity tray. While an import runs, you can see how many records have been retrieved and written for each data type. For data types read per parent record, progress shows how many parent records have been checked.

If one data type fails, the other selected data types still import. The import is then marked as failed and lists every data type that didn't complete.

***

## Dataset Sync

Once you have imported Spacebase data into a dataset, you can set up **automatic syncing** to keep your dataset up to date.

### How Sync Works

* Each Spacebase data type is synced independently.
* Each sync takes a **full snapshot** of the data type and adds it as a new timestamped Parquet file. Earlier snapshots are kept, never overwritten or removed, so you have a history of your data over time.
* Only a complete snapshot counts as a successful sync. If a snapshot is incomplete, the sync is reported as failed.

### Configuring Sync

When creating a dataset with Spacebase data:

1. Toggle **Dataset Sync** on before completing the dataset.
2. Choose the sync frequency: hourly, daily, weekly, or monthly.

***

## Parquet File Format

Spacebase records are stored as Parquet with types taken directly from the API response:

* Nested objects and arrays are kept as nested columns (not flattened or converted to text).
* Whole numbers are stored as integers, and other numbers as exact decimals (never floating point).
* Dates, timestamps, and money values are stored as they come from Spacebase (usually as text or decimal values).
* If a field appears in some records but not others, it's a column that is empty where missing.

4Minds also adds a few columns to every file, all starting with `__sb_`:

| Column | Description |
| - | - |
| `__sb_resource` | The data type the row came from |
| `__sb_parent_resource` | For per-parent data types, the parent data type (e.g., `leases`) |
| `__sb_parent_uid` | For per-parent data types, the identifier of the parent record |
| `__sb_sync_run_id` | The import or sync run that produced the row |
| `__sb_fetched_at` | When the row was fetched from Spacebase |
| `__sb_page` | The API page the row came from |

***

## Import Outcomes

| Outcome | What it means |
| - | - |
| **Complete** | Every record for the data type was imported. |
| **Incomplete** | Child data couldn't be read for some parent records (for example, headcount for one lease). The data that was retrieved is kept, but the data type is reported as failed. |
| **Size limit reached** | Your plan's import size limit stopped retrieval. The data retrieved before the limit is kept, but the data type is reported as failed. |
| **Failed** | The data type couldn't be imported. See [Troubleshooting](#troubleshooting). |

***

## Troubleshooting

| Issue | Solution |
| - | - |
| **"API token is required" or "API token is invalid"** | Paste the full token from Spacebase **Account** > **Enterprise API**, without spaces. |
| **401 Unauthorized** | The token may be wrong or revoked. Check it in Spacebase, then update it or disconnect and reconnect in 4Minds. The whole import stops on a 401. |
| **403 / permission error for a data type** | Your Spacebase plan or user is missing something that data type needs. Check the [access requirements](#access-requirements). Other data types still import. |
| **A data type is unavailable in the picker** | 4Minds couldn't confirm your account can read it. The reason is shown under the data type, and **Show details** lists what it requires. Check the [access requirements](#access-requirements). |
| **"Access could not be checked: no parent records were visible"** | Per-parent data types (like headcount) are checked using the first parent record. If you have no leases or invoices, these can't be checked. |
| **Headcount or capacity history is incomplete** | Headcount and capacity aren't available for leases on property types without headcount tracking. Data for the other leases is kept. |
| **HTTP 405 for custom field definitions or options** | Your Spacebase account doesn't allow reading this endpoint. See the note under [Available Data Types](#available-data-types). |
| **Rate limited or Spacebase unavailable** | 4Minds retries automatically. If it still fails, try again later; a scheduled sync will try again on its next run. |
| **"Can't be imported in the same import as local file uploads"** | Import your local files and Spacebase as separate imports. |
| **Size limit reached** | Import fewer data types at once, or contact your 4Minds admin about your plan's limits. |

***

## Security & Privacy

* **Read-only:** 4Minds only reads from Spacebase. It never writes, updates, or deletes data in your Spacebase account.
* **Fixed destination:** Your API token is only ever sent to `https://spacebaseapp.com/api/`. The host can't be changed.
* **Encrypted token:** Your API token is encrypted at rest. After you save it, 4Minds only shows its last four characters.
* **Per-user access:** Each user connects their own Spacebase account. Your Spacebase connection is not shared with other users on the platform.

***

## FAQ

**Q: What Spacebase data can I access?** A: Any of the data types listed above that your Spacebase user and plan can read. See the [data types table](#available-data-types).

**Q: Can I import Spacebase data into an existing dataset?** A: Yes. You can add Spacebase data to both new and existing datasets.

**Q: Does sync replace my earlier Spacebase data?** A: No. Each sync adds a new timestamped snapshot file and keeps the earlier ones.

**Q: Does sync only fetch changed records?** A: Not yet. Each sync takes a full snapshot of the data type.

**Q: What happens to my data if I disconnect my Spacebase account?** A: Previously imported data remains in your datasets. However, automatic syncing will stop, and you won't be able to import new data from Spacebase until you reconnect.

**Q: Can I connect multiple Spacebase accounts?** A: Each user account on 4Minds supports one Spacebase connection at a time. To switch accounts, update your token or disconnect and reconnect with a different token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.