Raw bulk import

Trebellar can automatically pull raw data you already produce — occupancy feeds, badge events, work-order exports, utility usage, and anything else you want to put to work in the platform — and import it on a recurring schedule.

This page explains the two transport options (SFTP and object storage) and the two hosting options (your infrastructure or Trebellar-managed) that combine to form the four setup modes available from the admin panel.

At a glance

How the pipeline works

Regardless of transport, the flow is the same:

1. You (or your upstream systems) drop one or more files into the configured location.
2. Trebellar polls the location on a schedule.
3. New files are fetched, validated, and enqueued for ingestion. Already-processed files are skipped based on a content hash, so re-uploads are idempotent.
4. Each file is transformed according to the dataset mapping you configured in the admin panel, then loaded into Trebellar.
5. The original file is moved to an archive/ prefix (or an archive/ directory on SFTP) with a timestamp suffix. If validation fails, it is moved to errors/ instead, alongside a sibling .error.json explaining what went wrong.

Option 1 — Object storage (S3 or GCS)

Use object storage when your upstream systems already export to a bucket, or when you want to land files over HTTPS using the AWS/GCS SDKs.

Option 1a — Bring your own bucket

Recommended when the source data must stay in your cloud tenancy for compliance or contractual reasons.

You provide:

Steps:

1. Create (or reuse) a bucket in your cloud provider.
2. Provision an IAM principal for Trebellar with the minimum permissions:
   • S3: s3:GetObject, s3:ListBucket, s3:PutObject (used to move files into archive/ or errors/), and s3:DeleteObject on the configured prefix only.
   • GCS: storage.objects.get, storage.objects.list, storage.objects.create, storage.objects.delete on the configured prefix only.
3. Generate long-lived credentials for that principal.
4. In Admin panel → Organization → Settings → Data Management, choose S3 / GCS → Bring your own bucket and paste the values above.
5. Click Test connection. Trebellar will try to connect against the source.
6. Pick a polling schedule and save.

Locking the bucket to Trebellar’s IP ranges

If your security policy requires bucket access to be pinned to a known set of source IPs, Trebellar publishes a stable list of egress addresses used by the ingestion workers. You can attach these to your bucket policy (aws:SourceIp on S3 or a VPC Service Controls perimeter on GCS) so that reads, writes, and deletes are only accepted from Trebellar’s infrastructure.

To avoid drift between these docs and the live set, we don’t publish the ranges inline. To request the current list:

1. Contact your Customer Success representative, or email support@trebellar.com.
2. Specify the cloud provider (AWS or GCP) and the region your bucket lives in — we’ll send back the narrowest range that covers ingestion for that region.
3. Trebellar announces changes to the egress set at least 30 days in advance in the changelog. Subscribe to the changelog to be notified before you need to update your bucket policy.

Option 1b — Trebellar-managed bucket

Trebellar provisions a tenant-isolated bucket and issues you write-only credentials scoped to a single prefix. Your upstream systems use these to drop files exactly as they would against a bucket you own.

Steps:

1. In Admin panel → Organization → Settings → Data Management, choose S3 / GCS → Use Trebellar bucket.
2. The admin panel will display:
   • The bucket URI and prefix to upload to
   • A client ID and client secret that your systems should use
3. Point your upstream exporter at the bucket and start pushing files.

Option 2 — SFTP

Use SFTP when your upstream systems can’t write to object storage — common with legacy BAS/BMS exports, facility-management vendors, and scheduled jobs running on on-prem servers.

Option 2a — Bring your own SFTP server

Trebellar connects to an SFTP endpoint you operate.

You provide:

Steps:

1. Create a dedicated SFTP user on your server with read/write access to the inbox path, and to the archive/ and errors/ subdirectories Trebellar will create.
2. In Admin panel → Organization → Settings → Data Management, choose SFTP → Bring your own server.
3. Paste the host, port, username, password or public SSH key and remote path.
4. (Optional) Paste the host key fingerprint to enforce strict host-key checking.
5. Click Test connection and then save.

Locking the SFTP server to Trebellar’s IP ranges

If your SFTP server is exposed to the internet and you’d like to restrict inbound connections to Trebellar only, request the current egress IP ranges for the ingestion workers from your Customer Success representative or at support@trebellar.com. Specify the region you expect connections from — we’ll send back the narrowest range. Add them to your firewall / security group rules on port 22.

We keep the live list out of these docs on purpose so customers never pin a stale range. Changes are announced 30 days in advance in the changelog.

Option 2b — Trebellar-managed SFTP endpoint

Trebellar spins up a per-organization SFTP endpoint. This is the fastest path when you want an SFTP drop but don’t want to run a server.

You receive:

• A hostname — e.g. sftp.trebellar.app
• A username — scoped to your organization
• A choice of SSH key (recommended — you upload your public key) or a generated password
• A fixed remote path — /inbox

That’s it — point your upstream job at the endpoint and start pushing.

Client-side encryption (both SFTP modes)

For SFTP you can optionally configure client-side PGP encryption so that the file contents are encrypted end-to-end, from your exporter all the way to Trebellar’s decryption step.

How it works:

1. In the admin panel, enable Client-side encryption for the SFTP configuration.
2. Trebellar generates a PGP keypair scoped to your organization and displays the public key. Download it and hand it to whoever writes files into the SFTP inbox.
3. Your exporter encrypts each file against the public key before upload — e.g. gpg --encrypt --recipient trebellar@yourorg .... Encrypted files should use the .gpg or .pgp extension.
4. Upon ingestion, Trebellar decrypts the file in memory using the private key (which never leaves our KMS) and then runs the usual validation pipeline.

You can also use your own PGP keypair instead of the Trebellar-generated one — upload the public key to the admin panel and keep the private key on your side, decrypting files yourself via an egress to your environment. Ask Customer Success if you need this mode; it’s a small variant of Option 2a.

Preparing your files

Initial data requirements

Before uploading, see the Initial Data Requirements article in our help center for the complete list of supported data types and the required fields for each.

Naming & folder conventions

Each upload folder should contain the dated snapshot of your data based on the date provided in the folder’s name.

For every snapshot, create a folder named in YYYY-MM-DD format using the date the data reflects. All files placed in that folder should correspond to that same snapshot date.

Each file within a folder should follow this naming pattern:

<datatype>_<date>

For example, if your employee and building data reflects your organization as of 2026-05-02, upload both files into:

2026-05-02/
   employees_2026-05-02.csv
   buildings_2026-05-02.csv

This tells Trebellar that all files in that folder are semantically linked and belong to the same reporting snapshot.

Other origins

Trebellar’s raw bulk importer is focused on SFTP and S3/GCS because those cover the vast majority of enterprise data export paths. If your source is something else — FTPS, Azure Blob Storage, a vendor-specific REST API, an email attachment pipeline, or a file drop behind a VPN — contact your Customer Success representative. We’ll scope a bespoke connector; most common variants can be onboarded in under a week.

Troubleshooting