FunBIM API

Overview

The FunBIM API gives read-only access to the data of all your company's projects:

• projects, their configuration (trades, statuses, types, priorities, companies) and spatial structure;
• members and their permissions;
• issues and forms, with their answers, comments, sub-tasks and signatories;
• document management files, coded documents and their approval workflow;
• photos, progress records and equipment;
• a full export of a project as a ZIP archive.

The API is included in the FunBIM 3D company subscription. Keys created in FunBIM are read-only: an integration cannot alter your projects.

Quick start

1. Create a key in FunBIM. You need to be an administrator of the company, on a FunBIM 3D subscription:

• in My Projects, open your organization's card ("Organization settings, applied to all your projects");
• in the left-hand menu, choose API;
• click Create a key, give it a name (for example "Power BI") and a validity period.

The key is shown only once: copy it straight away and keep it like a password. The same screen lists your keys and their last use, and lets you revoke one.

2. List your company's projects:

curl https://api.funbim.com/v1/projects \
  -H "Authorization: Bearer fbk_live_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

3. You get the list of your projects:

{
  "data": [
    {
      "id": "-NLKzINUsK6CcZspR6B6",
      "name": "Résidence Les Tilleuls",
      "customId": "2026-014",
      "status": "active",
      "address": "12 rue des Tilleuls, 69003 Lyon",
      "createdAt": "2026-01-09T10:04:37.722Z",
      "updatedAt": "2026-10-14T16:52:35.162Z",
      "createdBy": { "visId": "-MUiZYD9AXG_hj7GjYyr", "name": "Claire Martin" },
      "spatialLabels": { "buildings": "Bâtiments" }
    }
  ],
  "nextCursor": null
}

Authentication

Every request carries the key in the Authorization: Bearer fbk_live_… header. A key belongs to the company, not to a person: it gives access to all the company's projects, and to them only.

• A company can have up to 10 active keys, one per use (BI, ERP…).
• Each key has a validity period (1 year at most) and can be revoked at any time; revocation takes effect within a minute.
• Use the key server-side only. Never embed it in a web page or a mobile app.

A missing, invalid, revoked or expired key always gets the same 401 invalid_key response, whatever the cause.

Security and isolation

The API is built so that a key can never read anything but its own company's data.

• Isolation per company: every request is tied to the key's company, and the scope is checked before any read. A project of another company answers 404, exactly like a missing project: you cannot even tell it exists.
• Read-only: a key created in FunBIM never changes your data. Starting an export is the only accepted action.
• Protected keys: FunBIM never stores your key in clear text, only a fingerprint. It is shown once, when created; if you lose it, revoke it and create another one.
• Files: binaries are only served through short-lived signed links (15 minutes, 24 hours for an export archive), and only for files of the requested project.
• Minimal personal data: people are given by a public identifier and their name, never by their email or login identifier.
• Plain errors: error responses carry no internal technical detail.

Good practices:

• one key per tool (BI, ERP…), so you can revoke one without cutting the others;
• keep it in a secrets manager, never in source code or a shared spreadsheet;
• a key sees every project of the company: keep it for trusted tools.

These guarantees are checked by automated tests, including cross-company access attempts run against the deployed API.

Conventions

• Responses are UTF-8 JSON; a resource is in data, a list in data + nextCursor.
• Dates are ISO 8601 UTC (2026-10-14T08:30:00.000Z); a missing value is null.
• People are given as { visId, name }, configuration items (status, type, trade…) as { id, label }. The full lists are in /projects/{projectId}/config.
• name is null when a person's name is not set, or is only an email address: the API never publishes emails. The visId still identifies the person.
• Form answers are in formData, a label → value object ready to use.
• Deleted items are excluded, unless you pass includeDeleted=true.
• New fields may appear: ignore the ones you don't know.

Pagination and sync

Lists use cursor pagination: pass nextCursor back as the cursor parameter until you get null. limit defaults to 100, 500 at most.

A page may hold fewer items than limit, or none at all, without being the last one. Only nextCursor: null marks the end: always loop on the cursor, never on the page size.

const BASE = "https://api.funbim.com/v1";
const headers = { Authorization: `Bearer ${process.env.FUNBIM_API_KEY}` };

async function listAll(path) {
  const items = [];
  let cursor = null;
  do {
    const url = new URL(BASE + path);
    url.searchParams.set("limit", "500");
    if (cursor) url.searchParams.set("cursor", cursor);
    const res = await fetch(url, { headers });
    if (res.status === 429) {
      await new Promise((r) => setTimeout(r, Number(res.headers.get("Retry-After") ?? 1) * 1000));
      continue;
    }
    const body = await res.json();
    items.push(...body.data);
    cursor = body.nextCursor; // null = end of the list
  } while (cursor);
  return items;
}

const observations = await listAll("/projects/PROJECT_ID/observations");

import os, time, requests

BASE = "https://api.funbim.com/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['FUNBIM_API_KEY']}"}

def list_all(path, **params):
    items, cursor = [], None
    while True:
        query = {"limit": 500, **params, **({"cursor": cursor} if cursor else {})}
        res = requests.get(BASE + path, headers=HEADERS, params=query)
        if res.status_code == 429:
            time.sleep(int(res.headers.get("Retry-After", 1)))
            continue
        res.raise_for_status()
        body = res.json()
        items += body["data"]
        cursor = body["nextCursor"]
        if cursor is None:
            return items

forms = list_all("/projects/PROJECT_ID/observations", kind="form")

For an incremental sync, only ask for what changed since your last run, deletions included:

GET /v1/projects/PROJECT_ID/observations?updatedSince=2026-10-01T00:00:00Z&includeDeleted=true

Location on drawings and models

An issue or a form can be located in three ways, which can be combined: on a PDF drawing (planLocation), in the model (modelLocation) and in the project structure (spatialLocation). A field is null when the item isn't located that way. fileId gives the drawing or model concerned.

On a PDF drawing — the position is given on the page as displayed, rotation included, from the top-left corner:

"planLocation": {
  "fileId": "-NLLAA7v50nyjO5a2FEm",
  "page": 1,
  "x": 0.521,
  "y": 0.512,
  "rotation": 270,
  "xPt": 1350.43,
  "yPt": 884.62,
  "pageWidthPt": 2592,
  "pageHeightPt": 1728
}

• x, y: position as a fraction of the page (0 to 1). To place the pin on an image of the drawing: x × image width, y × image height.
• xPt, yPt: the same position in PDF points; pageWidthPt, pageHeightPt: the size of the displayed page, in PDF points.
• page starts at 1; rotation is the page rotation (0, 90, 180 or 270).
• The position stays right from one revision of the drawing to the next, even if the page is rotated differently.

In the model — kind tells which kind of point it is:

"modelLocation": {
  "kind": "3d",
  "fileId": "-O7_mttUaADaWQEW9EMM",
  "viewableGuid": "fe9402fe-49f5-4c05-9873-8601750db635-001e911a",
  "sheetName": null,
  "linkedFileId": null,
  "elementGuid": "ad3aac00-f6ca-4a67-9ecb-94800e6c7479-0013a9a2",
  "x": 94.99,
  "y": -79.56,
  "z": 20.53
}

• kind: "3d": a point in the model; x, y, z are model coordinates, elementGuid is the element pointed at.
• kind: "sheet": a point on a 2D sheet of the model, named by sheetName; x, y are coordinates on that sheet and z is 0.
• viewableGuid is the model view where the point was placed; linkedFileId the linked model, for a federated model.

In the project structure — building, level, area and unit, with their label:

"spatialLocation": {
  "buildingId": "-NQUhGd5NcOGBgfj8u8N",
  "levelId": null,
  "areaId": null,
  "housingId": null,
  "building": { "id": "-NQUhGd5NcOGBgfj8u8N", "label": "Building A" },
  "level": null,
  "area": null,
  "housing": null
}

The plain identifiers (buildingId…) are still there. The full structure is in /projects/{projectId}/spatial.

Files and photos

Binaries are never in JSON responses. Each file and photo carries a downloadPath: call it with your key and the API answers 302 to a signed download URL, valid for 15 minutes.

curl -L -o drawing.pdf \
  -H "Authorization: Bearer $FUNBIM_API_KEY" \
  https://api.funbim.com/v1/projects/PROJECT_ID/files/FILE_ID/download

For a photo, ?size=thumb returns the thumbnail when there is one.

ZIP export of a project

To archive a whole project or migrate your data, start an export: FunBIM builds a ZIP archive with all the data in the API format, an Excel sheet of issues and forms, and, if requested, the files, photos and signatures.

curl -X POST https://api.funbim.com/v1/projects/PROJECT_ID/exports \
  -H "Authorization: Bearer $FUNBIM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "includeMedia": true }'

# 202 Accepted
{ "data": { "id": "EXPORT_ID", "status": "pending", … } }

curl https://api.funbim.com/v1/projects/PROJECT_ID/exports/EXPORT_ID \
  -H "Authorization: Bearer $FUNBIM_API_KEY"

# once "status": "done"
{ "data": { "status": "done", "sizeBytes": 371160353,
            "downloadUrl": "https://storage.googleapis.com/…", … } }

• The archive is ready within minutes; poll the export every 10 to 30 seconds.
• The downloadUrl link is valid for 24 hours and can be requested again; the archive is kept for 7 days.
• Above 5 GB of files, the archive is built without them: download them afterwards through their downloadPath.
• One export at a time per project, 10 exports per day per company.

Limits

Beyond that, the API answers 429 with a Retry-After header giving the wait in seconds.

Errors

An error always returns an HTTP status and an error object:

HTTP/2 404
{ "error": { "code": "not_found", "message": "Resource not found." } }

Versioning

Version 1 (/v1) only receives additions: new fields, new endpoints. A breaking change will go through a version 2, announced at least 12 months ahead.

Reference

Every version 1 endpoint, generated from the API contract. Paths are relative to the base URL https://api.funbim.com/v1.