Uploading documents with the Documents API

Users can only upload a document to a project or project phase. In this example, we will focus on adding a new file to a project. The uploading process consists of three API actions:

Request an upload token for that project or phase.
Upload the file using the temporary upload URL.
Create or update the document by sending its details to the API.

1. Request an upload token

Option A: Postman:

Create a new POST request.

Paste the endpoint below in the URL field.

https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects/<project-id>/documents/upload-tokens

Option B: cURL

curl -X POST "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects/<project-id>/documents/upload-tokens" \
  -H "Authorization: Bearer <access-token>"

The response contains a temporary upload URL (preSignedUploadUrl) and a blobName you'll need in step 3:

{
  "preSignedUploadUrl": "<pre-signed-upload-url>",
  "blobName": "<blob-name>"
}

2. Upload the file

Send the actual file to the <pre-signed-upload-url> from the previous step.

Option A: Postman:

Create a new PUT request.
Paste the <pre-signed-upload-url> as URL.
On the Authorization tab, choose No Auth (this step doesn't use your token).
On the Headers tab, add:
Content-Type: application/octet-stream and x-ms-blob-type: BlockBlob.
On the Body tab, select binary and choose your file.
Click Send.

Option B: cURL

curl --location --request PUT "<pre-signed-upload-url>" \
  --header "Content-Type: application/octet-stream" \
  --header "x-ms-blob-type: BlockBlob" \
  --data-binary "@/path/to/file/ExampleFile.ifc"

📝 Note: this request goes to that URL directly; it does not need the Authorization header.

3. Create or update the document

Finally, tell the API about the file you just uploaded by sending its <blobName> and adding document details.

Option A: Postman:

Create a new PUT request.

Paste the endpoint below into the URL field.

https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects/<project-id>/documents

On the Body tab, select raw and set the format to JSON.

Paste the JSON object shown below and edit the values to match your file.

{
    "blobName": "<blob-name>",
    "documentNumber": "<document-number>",
    "documentDate": "<date>",
    "manufacturerId": "<company-id>",
    "versionNumber": "1",
    "fileName": "<file-name>",
    "versionDate": "<date>"
}

Click Send

Option B: cURL

curl -X PUT "https://api.eu.bimcollab.com/spaces/<space-id>/documents/v1/projects/<project-id>/documents" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "blobName": "<blob-name>",
    "documentNumber": "<document-number>",
    "documentDate": "<date>",
    "manufacturerId": "<company-id>",
    "versionNumber": "1",
    "fileName": "<file-name>",
    "versionDate": "<date>"
  }'

The response contains the created (or updated) document ID and version ID.

📝 Note: <file-name> should also include the file extension. Example: 01_BIMcollab_Example_ARC.ifczip

⚠️ Attention: The <company-id> field is required when uploading a document. You can retrieve your company ID using the following GET endpoint:

<https://api.eu.bimcollab.com/spaces/<space-id>/companies

Add a new document version

Once you've created a document, you can upload a new version without creating a completely new document.

The process is essentially the same:

Request an upload token.
Upload the new file.
Send the document details to BIMcollab.
Use a higher versionNumber.

For example, if the existing document has: "versionNumber": "1"

the next version can use: "versionNumber": "2"

BIMcollab keeps the versions together under the same document. This means you don't need to create a new document every time a file is updated.