/documents/v1

post

https://api.safetyculture.io/documents/v1

Use this endpoint to upload PDFs, Word documents, spreadsheets, or images to Documents. It is commonly used to migrate business documents from platforms like SharePoint into SafetyCulture. Files are stored in a centralized location, helping teams work from the most up-to-date version across the web and mobile apps.

This is a two-step process:

POST to create the file record and receive a temporary upload_url (valid for ~20 minutes).
PUT the raw file bytes to the returned upload_url to complete the upload. If you skip this step, the file record is created but the media won’t render in SafetyCulture. You can also automatically create folders by specifying a path in your request.

Requirements

Limitations

You can upload files up to 50MB in DOCX, DOC, JPEG, JPG, PNG, PDF, XLS, and XLSX formats.
You can add up to 10,000 files in total. Each folder can contain up to 200 items, which includes both files and subfolders.

🚧
Although you can specify each file's name and description, the endpoint does not support storing external or third-party IDs as metadata. We recommend maintaining your own mapping between SafetyCulture file IDs and your external system IDs.

Body Params

path

array of strings

An array of folder names that defines the path where the file will be stored.
The path is relative to the parent_id if it is provided. If not, it starts from the root folder.
The API will automatically create any folders in the path that don’t exist.
Each folder name must be 1-255 characters and exclude invalid characters.

path

name

string

The name of the file.
Must be between 1-255 characters and exclude invalid characters.

file_type

string

enum

MEDIA_TYPE_IMAGE: An image file (GIF, JPG, PNG, WEBP).
MEDIA_TYPE_VIDEO: A video file (MP4, MOV).
MEDIA_TYPE_PDF: A PDF document.
MEDIA_TYPE_DOCX: A Microsoft Word document (DOCX, DOC).
MEDIA_TYPE_XLSX: A Microsoft Excel spreadsheet (XLSX, XLS).
MEDIA_TYPE_PPTX: A Microsoft PowerPoint presentation (PPTX, PPT).
MEDIA_TYPE_CSV: A CSV file.

Allowed:

file_size

int64

The size of the file in bytes. Must not exceed 50MB.
This field is required if file_type is provided.

parent_id

string

The ID of the folder where the file should be stored.
Any folders defined in the path will be created inside the parent folder.
If you don’t provide a parent_id, the file will be stored in the root folder.
To get the parent_id, open the folder in the SafetyCulture web app and copy the last part of the URL.
For example, in this link https://app.safetyculture.com/documents/9dd76834-65ef-41d3-815c-964df32450e4,
the parent ID is 9dd76834-65ef-41d3-815c-964df32450e4.

Responses

Requirements

Limitations

200A successful response.

defaultAn unexpected error response.