File API endpoints

Level: advanced

The File API interface in Creatio is a mechanism that provides endpoints to perform file operations such as uploading, downloading, and deleting through REST API calls.

Upload a file

Creatio lets you upload the file in one request or multiple requests using chunks.

Request string

POST /FileApiService/UploadFile

Upload a file that has specified parameters. We recommend verifying parameters in the browser since the request parameters depend on the object associated with the file.

Parameter	Description
fileId	The ID of the file record. For a new record, a random ID.
totalFileLength	The total length of the file.
mimeType	The MIME type of the file.
fileName	The name of the file.
columnName	The name of the column in the File database table to store the file body. If you store the file body in an external file storage, the columnName parameter value is ignored.
entitySchemaName	The code of the object schema.
parentColumnName	The name of the column in the File database table where the ID of the primary record is stored.
parentColumnValue	The ID of the primary record.

Request headers

Header	Description
Content-Range	The byte range that the current message represents within the entirety of the main resource. Learn more: Content-Range header (MDN Wed Docs). Header template: <unit> <range-start>-<range-end>/<size>, for example, "bytes 0-122/123," where: <unit> is the unit of range. By default, "bytes." <range-start> is the start position (zero-indexed and inclusive) of the request range. <range-end> is the end position (zero-indexed and inclusive) of the request range. <size> is the total length of the file. If you upload the file in multiple requests using chunks, do not forget to edit the Content-Range header. View the examples of the Content-Range header to upload the file in multiple requests below: First chunk: "bytes 0-524287/15122860." Second chunk: "bytes 524288-1048575/15122860." The last chunk: "bytes 14680064-15122859/15122860."
Content-Type	The media type of the resource. For example, "application/x-zip-compressed." Learn more: Content-Type Header Field (official RFC Editor documentation).
Content-Disposition	Specify how the server must handle the request or response content. By default, "attachment; filename=SomeFile." Learn more: Content-Disposition header (MDN Wed Docs).

Request body

Pass the binary contents of the file in the request body, i. e., Type: File (binary).

Usage example

View the example that uploads the file.zip file and attaches it to the "Contact" (Сontact code) object whose ID is "c4ed336c-3e9b-40fe-8b82-5632476472b4" below.

Upload a file in one request (C#)

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "http://CreatioURL/0/rest/FileApiService/UploadFile?fileId=51bc924d-7341-cdbd-0a98-b04a4e6d04cc&totalFileLength=123&mimeType=application%2Fx-zip-compressed&fileName=file.zip&columnName=Data&entitySchemaName=ContactFile&parentColumnName=Contact&parentColumnValue=c4ed336c-3e9b-40fe-8b82-5632476472b4");
request.Headers.Add("Content-Range", "bytes 0-122/123");
request.Headers.Add("Content-Disposition", "attachment; filename=file.zip");
request.Content = new StreamContent(File.OpenRead("SomeFilePath/file.zip"));
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Upload a file in one request (cURL)

curl --location 'http://CreatioURL/0/rest/FileApiService/UploadFile?fileId=71bc924d-7341-cdbd-0a98-b04a4e6d04cc&totalFileLength=123&mimeType=application%2Fx-zip-compressed&fileName=file.zip&columnName=Data&entitySchemaName=ContactFile&parentColumnName=Contact&parentColumnValue=c4ed336c-3e9b-40fe-8b82-5632476472b4' \
--header 'Content-Range: bytes 0-122/123' \
--header 'Content-Type: application/x-zip-compressed' \
--data '@/SomeFilePath/file.zip'

Upload a file in multiple requests (C#)

var fileName = "file.zip";
var filePath = "SomeFilePath/file.zip";
FileInfo fileInfo = new FileInfo(filePath);
using (FileStream fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read)){
    int uploadChunkLength = 10000;
    byte[] filePart = new byte[uploadChunkLength];
    int totalSize = (int) fileInfo.Length;
    int uploadedSize = 0;
    int currentChunkLength;
    while ((currentChunkLength = fileStream.Read(filePart, 0, filePart.Length)) != 0){
        int num = uploadedSize == 0 ? 0 : uploadedSize + 1;
        byte[] currentFileChunk = new byte[currentChunkLength];
        Array.Copy(filePart, currentFileChunk, currentChunkLength);
        using (MemoryStream memoryStream = new MemoryStream()) {
            memoryStream.Write(currentFileChunk, 0, currentChunkLength);
            var request = new HttpRequestMessage(HttpMethod.Post, $"localhost/0/rest/FileApiService/UploadFile?fileId=51bc924d-7341-cdbd-0a98-b04a4e6d04cc&totalFileLength={totalSize}&mimeType=application%2Fx-zipcompressed&fileName={fileName}&columnName=Data&entitySchemaName=ContactFile&parentColumnName=Contact&parentColumnValue=c4ed336c-3e9b-40fe8b82-5632476472b4");
            request.Headers.Add("Content-Range", $"bytes {num}-{uploadedSize + currentFileChunk.Length}/{totalSize}");
            request.Headers.Add("Content-Disposition", $"attachment; filename={fileName}");
        }
        uploadedSize += currentChunkLength;
        num = totalSize - uploadedSize;
        uploadChunkLength = num < uploadChunkLength ? num : uploadChunkLength;
        filePart = new byte[uploadChunkLength];
        Console.WriteLine($"Loaded {uploadedSize} from {totalSize}");
    }
}

Download a file

Request string

GET /FileService/Download

Download a file.

Parameter	Description
fileId	The ID of the file record. For a new record, a random ID.
entitySchemaName	The code of the object schema.

Usage example

View the example that downloads the file whose ID is "c4ed336c-3e9b-40fe-8b82-5632476472b4" below. The file is attached to the "Contact" (Сontact code) object.

Download a file (C#)

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "http://CreatioURL/0/rest/FileService/Download/ContactFile/71bc924d-7341-cdbd-0a98-b04a4e6d04cc");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

Download a file (cURL)

curl -X GET "http://CreatioURL/0/rest/FileService/Download/ContactFile/71bc924d-7341-cdbd-0a98-b04a4e6d04cc"

Delete a file

Request string

POST /GridUtilitiesService/DeleteRecords

Delete a file.

Request headers

Header	Description
Content-Type	The media type of the resource. By default, "application/json." Learn more: Content-Type Header Field (official RFC Editor documentation).

Request body

Parameter	Description
rootSchema	The root schema associated with the object.
primaryColumnValues	The ID of the file record. For a new record, a random ID.

View the example of a request body to delete the file whose ID is "71bc924d-7341-cdbd-0a98-b04a4e6d04cc" from the "Contact attachment" (СontactFile code) object below.

Example of a request body to delete the file

{
    "rootSchema": "ContactFile",
    "primaryColumnValues": [
        "71bc924d-7341-cdbd-0a98-b04a4e6d04cc"
    ]
}

Usage example

View the example that deletes the file whose ID is "71bc924d-7341-cdbd-0a98-b04a4e6d04cc" from the "Contact attachment" (СontactFile code) object below.

Delete a file (C#)

var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "http://localhost:8082/0/rest/GridUtilitiesService/DeleteRecords");
var content = new StringContent("{\r\n \"rootSchema\": \"ContactFile\",\r\n \"primaryColumnValues\": [\r\n \"71bc924d-7341-cdbd-0a98-b04a4e6d04cc\"\r\n]\r\n}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

---

Resources

Content-Range header (official MDN Wed Docs documentation)

Content-Disposition header (official MDN Wed Docs documentation)

Content-Type Header Field (official RFC Editor documentation)