File Operations Methods

This page presents the main API methods for working with files in the Brainysoft system: upload, retrieve, edit, delete, batch operations, as well as linking files to various entities (clients, contracts, leads, loan applications) and public file uploads.

File API Methods

Method	URL	Description
POST	`api/files`	Upload file
GET\|HEAD	`api/files`	List all files
POST	`api/files/entities/clients/{id}` `api/files/entities/contracts/{id}` `api/files/entities/leads/{id}` `api/files/entities/loan-apps/{id}`	Upload client/contract/lead/loan application file
GET\|HEAD	`api/files/entities/clients/{id}` `api/files/entities/contracts/{id}` `api/files/entities/leads/{id}` `api/files/entities/loan-apps/{id}`	Get client/contract/lead/loan application files
GET\|HEAD	`api/files/{file}`	Get file information by ID
PUT\|PATCH	`api/files/{file}`	Edit file data
DELETE	`api/files/{file}`	Delete file
GET\|HEAD	`api/files/{file}/links`	Get file link
GET\|HEAD	`api/files/{file}/link-verified-copy`	Get verified file link
POST	`api/files/batch/links`	Get links for a group of files (by ID)
POST	`api/files/batch/select`	Get information for a group of files
GET\|HEAD	`api/files/public-uploader`	Public file upload

Upload File

POST /api/files

Description

This method allows uploading a new file to the system. The file is sent in the request body in multipart/form-data format.

Request Parameters (query string)

Parameter	Type	Required	Description
lead	integer	Choose one of the entities	Lead ID
client	integer	Choose one of the entities	Client ID
loanapp	integer	Choose one of the entities	Loan application ID
contract	integer	Choose one of the entities	Contract ID
collateral	integer	Choose one of the entities	Collateral ID
sharecontract	integer	Choose one of the entities	Share contract ID
depositcontract	integer	Choose one of the entities	Deposit contract ID
fundtransaction	integer	Choose one of the entities	Fund transaction ID
tags	integer	✅ Always required	Tag ID

:::note Important:

The tags parameter is required for all requests
At least one of the following parameters must be specified: lead, client, loanapp, contract, collateral, sharecontract, depositcontract, or fundtransaction :::

Request Body (form-data)

Field	Type	Description
file	file	File to upload (e.g., .pdf, .jpg, .png, .gif)

Request Example

POST /api/files?client=3168&tags=5

Content-Type: multipart/form-data

file: image.png

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750694475000, // Response time (UNIX timestamp, ms)
  "data": {
    "id": 235 // Unique file identifier
  }
}

List All Files

GET /api/files

Description

This method returns a list of files with detailed information about each file.

Request Example

GET /api/files

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750675264000, // Response time (UNIX timestamp, ms)
  "data": [
    {
      "id": 234, // Unique file identifier
      "name": "images.png", // File name
      "extension": "png", // File extension
      "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/234/2e276a16b5219e4e06a5c8070d9a1a0784737062146ad1931633c17d0d7cf736fde4791182d5bd6b65e249c512a5f87e4887f3e935c40c59a7a79da42ed5c224", // File preview/thumbnail URL
      "userId": 1357, // ID of user who uploaded the file
      "connections": {
        "lead": null, // Lead ID
        "client": 3168, // Client ID
        "loanapp": null, // Loan application ID
        "contract": null, // Contract ID
        "collateral": null, // Collateral ID
        "sharecontract": null, // Share contract ID
        "depositcontract": null, // Deposit contract ID
        "fundtransaction": null, // Fund transaction ID
        "comment": null, // Comment ID
        "collateralline": null, // Collateral line ID
        "deal": null, // Deal ID
        "extra": [] // Additional connections
      },
      "createdAt": "2025-06-23T07:36:41+0000", // File upload date and time (ISO 8601)
      "tags": [
        // List of tag identifiers
        "2"
      ],
      "size": 3789, // File size in bytes
      "sizeForHumans": "4 Kb", // Human-readable file size
      "ocr": null // OCR recognition result
    }
  ]
}

Upload Client/Contract/Lead/Loan Application File

POST /api/files/entities/clients/{id} - Upload client file

POST /api/files/entities/contracts/{id} - Upload contract file

POST /api/files/entities/leads/{id} - Upload lead file

POST /api/files/entities/loan-apps/{id} - Upload loan application file

Description

These methods allow uploading a file and immediately linking it to a specific entity: client, contract, lead, or loan application. The file is sent in the request body in multipart/form-data format.

Request Parameters

{id} (integer, required) — unique identifier of the corresponding entity (client, contract, lead, or loan application).

Request Parameters (query string)

Parameter	Type	Description
tags	integer	Tag identifier associated with the file

Request Body (form-data)

Field	Type	Description
file	file	File to upload (e.g., .pdf, .jpg, .png, .gif)

Request Example

POST /api/files/entities/clients/3168?tags=8

Content-Type: multipart/form-data

file: image.png

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750696263000, // Response time (UNIX timestamp, ms)
  "data": {
    "id": 237 // Unique file identifier
  }
}

Get Client/Contract/Lead/Loan Application Files

GET /api/files/entities/clients/{id} - Get client file

GET /api/files/entities/contracts/{id} - Get contract file

GET /api/files/entities/leads/{id} - Get lead file

GET /api/files/entities/loan-apps/{id} - Get loan application file

Description

These methods allow retrieving a list of all files associated with a specific entity: client, contract, lead, or loan application. The response returns an array of file objects with detailed information about each of them.

Request Parameters

{id} (integer, required) — unique identifier of the corresponding entity (client, contract, lead, or loan application).

Request Example

GET /api/files/entities/clients/3168

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750697332000, // Response time (UNIX timestamp, ms)
  "data": [
    {
      "id": 223, // Unique file identifier
      "name": "default_logo.png", // File name
      "extension": "png", // File extension
      "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/223/7a8a2e2296fadf0ea97c701f6edd2d5278ebf278ec2f87520e77687a89f2d59a003a94dd6f84094a682a5f2c3a44c8fd64bbb8f2b2b81098e654687f72f20e06", // File preview/thumbnail URL
      "userId": 1165, // ID of user who uploaded the file
      "connections": {
        "lead": null, // Lead ID
        "client": 3168, // Client ID
        "loanapp": null, // Loan application ID
        "contract": null, // Contract ID
        "collateral": null, // Collateral ID
        "sharecontract": null, // Share contract ID
        "depositcontract": null, // Deposit contract ID
        "fundtransaction": null, // Fund transaction ID
        "comment": null, // Comment ID
        "collateralline": null, // Collateral line ID
        "deal": null, // Deal ID
        "extra": [] // Additional connections
      },
      "createdAt": "2025-06-16T14:40:54+0000", // File upload date and time (ISO 8601)
      "tags": [
        // List of tag identifiers
        "14"
      ],
      "size": 6005, // File size in bytes
      "sizeForHumans": "6 Kb", // Human-readable file size
      "ocr": null // OCR recognition result
    },
    {
      "id": 234, // Unique file identifier
      "name": "images.png", // File name
      "extension": "png", // File extension
      "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/234/2e276a16b5219e4e06a5c8070d9a1a0784737062146ad1931633c17d0d7cf736fde4791182d5bd6b65e249c512a5f87e4887f3e935c40c59a7a79da42ed5c224", // File preview/thumbnail URL
      "userId": 1357, // ID of user who uploaded the file
      "connections": {
        "lead": null, // Lead ID
        "client": 3168, // Client ID
        "loanapp": null, // Loan application ID
        "contract": null, // Contract ID
        "collateral": null, // Collateral ID
        "sharecontract": null, // Share contract ID
        "depositcontract": null, // Deposit contract ID
        "fundtransaction": null, // Fund transaction ID
        "comment": null, // Comment ID
        "collateralline": null, // Collateral line ID
        "deal": null, // Deal ID
        "extra": [] // Additional connections
      }
    }
  ]
}

Get File Information by ID

GET /api/files/{file}

Description

This method allows retrieving detailed information about a specific file by its identifier.

Request Parameters

{file} (integer, required) — unique file identifier.

Request Example

GET /api/files/233

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750186181000, // Response time (UNIX timestamp, ms)
  "data": [
    {
      "id": 233, // Unique file identifier
      "name": "images.png", // File name
      "extension": "png", // File extension
      "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...", // File preview/thumbnail URL
      "userId": 1357, // ID of user who uploaded the file
      "connections": {
        "lead": 7315, // Lead ID
        "client": 3166, // Client ID
        "loanapp": 6755, // Loan application ID
        "contract": null, // Contract ID
        "collateral": null, // Collateral ID
        "sharecontract": null, // Share contract ID
        "depositcontract": null, // Deposit contract ID
        "fundtransaction": null, // Fund transaction ID
        "comment": null, // Comment ID
        "collateralline": null, // Collateral line ID
        "deal": null, // Deal ID
        "extra": [] // Additional connections
      },
      "createdAt": "2025-06-19T11:52:22+0000", // File upload date and time (ISO 8601)
      "tags": ["9"], // List of tag identifiers
      "size": 3789, // File size in bytes
      "sizeForHumans": "4 Kb", // Human-readable file size
      "ocr": null // OCR recognition result
    }
  ]
}

Edit File Data

PUT/PATCH /api/files/{file}

Description

This method allows updating file information (e.g., tags, name, object associations). To edit a file, you must first retrieve it using the "Get File Information by ID" method, then send a PATCH/PUT request with the required changes.

Request Parameters

{file} (integer, required) — unique file identifier.

PUT Request Example

PUT /api/files/233
Content-Type: application/json

json

{
  "id": 233, // Unique file identifier
  "name": "images.png", // File name
  "extension": "png", // File extension
  "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...", // File preview/thumbnail URL
  "userId": 1357, // ID of user who uploaded the file
  "connections": {
    "lead": 7315, // Lead ID
    "client": 3166, // Client ID
    "loanapp": 6755, // Loan application ID
    "contract": null, // Contract ID
    "collateral": null, // Collateral ID
    "sharecontract": null, // Share contract ID
    "depositcontract": null, // Deposit contract ID
    "fundtransaction": null, // Fund transaction ID
    "comment": null, // Comment ID
    "collateralline": null, // Collateral line ID
    "deal": null, // Deal ID
    "extra": [] // Additional connections
  },
  "createdAt": "2025-06-19T11:52:22+0000", // File upload date and time (ISO 8601)
  "tags": ["9", "12"], // List of tag identifiers
  "size": 3789, // File size in bytes
  "sizeForHumans": "4 Kb", // Human-readable file size
  "ocr": null // OCR recognition result
}

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750186181000, // Response time (UNIX timestamp, ms)
  "data": [
    {
      "id": 233, // Unique file identifier
      "name": "images.png", // File name
      "extension": "png", // File extension
      "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...", // File preview/thumbnail URL
      "userId": 1357, // ID of user who uploaded the file
      "connections": {
        "lead": 7315, // Lead ID
        "client": 3166, // Client ID
        "loanapp": 6755, // Loan application ID
        "contract": null, // Contract ID
        "collateral": null, // Collateral ID
        "sharecontract": null, // Share contract ID
        "depositcontract": null, // Deposit contract ID
        "fundtransaction": null, // Fund transaction ID
        "comment": null, // Comment ID
        "collateralline": null, // Collateral line ID
        "deal": null, // Deal ID
        "extra": [] // Additional connections
      },
      "createdAt": "2025-06-19T11:52:22+0000", // File upload date and time (ISO 8601)
      "tags": ["9", "12"], // List of tag identifiers
      "size": 3789, // File size in bytes
      "sizeForHumans": "4 Kb", // Human-readable file size
      "ocr": null // OCR recognition result
    }
  ]
}

PATCH Request Example

PATCH /api/files/233
Content-Type: application/json

json

{
  "tags": ["9", "12"]
}

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750186181000, // Response time (UNIX timestamp, ms)
  "data": [
    {
      "id": 233, // Unique file identifier
      "name": "images.png", // File name
      "extension": "png", // File extension
      "thumbUrl": "https://fs-stage-svc-stage.brainysoft.ru/web/files/thumb/qat1/193/...", // File preview/thumbnail URL
      "userId": 1357, // ID of user who uploaded the file
      "connections": {
        "lead": 7315, // Lead ID
        "client": 3166, // Client ID
        "loanapp": 6755, // Loan application ID
        "contract": null, // Contract ID
        "collateral": null, // Collateral ID
        "sharecontract": null, // Share contract ID
        "depositcontract": null, // Deposit contract ID
        "fundtransaction": null, // Fund transaction ID
        "comment": null, // Comment ID
        "collateralline": null, // Collateral line ID
        "deal": null, // Deal ID
        "extra": [] // Additional connections
      },
      "createdAt": "2025-06-19T11:52:22+0000", // File upload date and time (ISO 8601)
      "tags": ["9", "12"], // List of tag identifiers
      "size": 3789, // File size in bytes
      "sizeForHumans": "4 Kb", // Human-readable file size
      "ocr": null // OCR recognition result
    }
  ]
}

Delete File

DELETE /api/files/{file}

Description

This method allows deleting a file by its identifier.

Request Parameters

{file} (integer, required) — unique file identifier.

Request Example

DELETE /api/files/233

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750348133000, // Response time (UNIX timestamp, ms)
  "data": {
    "status": "deleted" // File deletion status
  }
}

Get File Link / Verified File Link

GET|HEAD /api/files/{file}/links

GET|HEAD /api/files/{file}/link-verified-copy

Description

These methods allow obtaining a download link for a file by its identifier.

/links — returns a regular file download link.
/link-verified-copy — returns a download link for a verified copy of the file, if such a copy is available.

Request Parameters

{file} (integer, required) — unique file identifier.

Request Example

GET /api/files/234/links

GET /api/files/234/link-verified-copy

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750690491000, // Response time (UNIX timestamp, ms)
  "data": {
    "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?ac-jar=..." // Download link for file or verified copy
  }
}

Get Links for a Group of Files (by ID)

POST /api/files/batch/links

Description

This method allows obtaining download links for multiple files by their identifiers at once. The response returns an object where the key is the file ID and the value is an object with the download link.

Request Body (application/json)

Field	Type	Description
ids	array[int]	Array of file identifiers

Request Example

json

{
  "ids": [234, 236, 237] // Array of file IDs
}

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1751285233000, // Response time (UNIX timestamp, ms)
  "data": {
    "234": {
      "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?..." // Download link for file with ID 234
    },
    "236": {
      "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?..." // Download link for file with ID 236
    },
    "237": {
      "download": "https://fs-stage-svc-stage.brainysoft.ru/web/files/download?..." // Download link for file with ID 237
    }
  }
}

Get Information for a Group of Files

POST /api/files/batch/select

Description

This method allows obtaining detailed information for multiple files by their identifiers at once. The response returns an array of file objects with a complete structure similar to the get file information by ID method.

Request Body (application/json)

Field	Type	Description
ids	array[int]	Array of file identifiers

Request Example

json

{
  "ids": [234, 236, 237] // Array of file IDs
}

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1751285601000, // Response time (UNIX timestamp, ms)
  "data": [
    {
      "id": 234, // Unique file identifier
      "name": "images.png", // File name
      "extension": "png", // File extension
      "thumbUrl": "https://...", // File preview/thumbnail URL
      "userId": 1357, // ID of user who uploaded the file
      "connections": {
        "lead": null, // Lead ID
        "client": 3168, // Client ID
        "loanapp": null, // Loan application ID
        "contract": null, // Contract ID
        "collateral": null, // Collateral ID
        "sharecontract": null, // Share contract ID
        "depositcontract": null, // Deposit contract ID
        "fundtransaction": null, // Fund transaction ID
        "comment": null, // Comment ID
        "collateralline": null, // Collateral line ID
        "deal": null, // Deal ID
        "extra": [] // Additional connections
      },
      "createdAt": "2025-06-23T07:36:41+0000", // File upload date and time (ISO 8601)
      "tags": ["2"], // List of tag identifiers
      "size": 3789, // File size in bytes
      "sizeForHumans": "4 Kb", // Human-readable file size
      "ocr": null // OCR recognition result
    }
    // ... other files
  ]
}

Public File Upload

GET|HEAD /api/files/public-uploader

Description

This method returns a unique public link (URL) that can be used to upload a file without authorization. This link can be used to provide file upload capability to external users, integrations, or third-party services.

INFO

This method is used for user uploads without using bsauth on the client side

Request Example

GET /api/files/public-uploader

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750757802000, // Response time (UNIX timestamp, ms)
  "data": {
    "url": "https://fs-stage-svc-stage.brainysoft.ru/web/files/public-uploader?ac-jar=tcBASegvBz5QslUbuPx3MbxfovoWmVfYHsBMMXcO7XrUzTowK19PN1RtcyWyKcbcTkCDc6Ui18GWC1XPg8SNPv9nYSXFD0Ekp3SlNcR9ZyptHzeL975HFfTGTOEhtqOlQWIwmdullkvTOr06xJTIRNQWCjto9DS2TFe5bB46gIbGWUzeqasJz8Za6NoTHF7cmxWLUQUsujyYSnmmC6RuLQWKtI0SWucn7mignXyk3HoYqkxxdAgleNdedmzAWCXkCwZl4Fvj7jGmI4v6By4c7ZXrHib3XyFnyJXUtcBHE8ik5TnaRXVwrsdzViiYZ3VbPMd4DnQEbtdPSe4eIp6RvNZMgbjKCkyeR1qJ8ld0gQkg1oKYIXLUSfH672K8Nhb7jFEP7nqg8uCFMQRl0v0hp8o25DrAliTURhuN0ZcEydFDTpUpg6sKFqrzwTzD8qVXe24hvpdh9R3DtSjCXozmDTFIyvYo2RrXHER6pgGrsMYBmEenOWvcLJUH9279a1z6" // Public link for file upload
  }
}

Field Descriptions

Field	Type	Description
status	string	Request execution status
timestamp	integer	Response time (UNIX timestamp, ms)
data	object/array	Main response data
id	integer	Unique file identifier
name	string	File name
extension	string	File extension
thumbUrl	string	File preview/thumbnail URL
userId	integer	User identifier
connections	object	Associations with system objects
lead	integer\|null	Lead ID
client	integer\|null	Client ID
loanapp	integer\|null	Loan application ID
contract	integer\|null	Contract ID
collateral	integer\|null	Collateral ID
sharecontract	integer\|null	Share contract ID
depositcontract	integer\|null	Deposit contract ID
fundtransaction	integer\|null	Fund transaction ID
comment	integer\|null	Comment ID
collateralline	integer\|null	Collateral line ID
deal	integer\|null	Deal ID
extra	array	Additional connections
createdAt	string	File upload date and time (ISO 8601)
tags	array	List of tag identifiers
size	integer	File size in bytes
sizeForHumans	string	Human-readable size (e.g., `4 Kb`)
ocr	string\|null	OCR recognition result
download	string	File download link
url	string	Public link for file upload

File Operations Methods ​

File API Methods ​

Upload File ​

List All Files ​

Upload Client/Contract/Lead/Loan Application File ​

Get Client/Contract/Lead/Loan Application Files ​

Get File Information by ID ​

Edit File Data ​

Delete File ​

Get File Link / Verified File Link ​

Get Links for a Group of Files (by ID) ​

Get Information for a Group of Files ​

Public File Upload ​

Field Descriptions ​

File Operations Methods

File API Methods

Upload File

List All Files

Upload Client/Contract/Lead/Loan Application File

Get Client/Contract/Lead/Loan Application Files

Get File Information by ID

Edit File Data

Delete File

Get File Link / Verified File Link

Get Links for a Group of Files (by ID)

Get Information for a Group of Files

Public File Upload

Field Descriptions