Create file

Requirements

Authentication token

How to:

1. Create a file

JS

POST /files/saveFile?token=:authenticationToken

Creates new file from BLOB.
This request uses Content-Type: multipart/form-data.

Example

Request

JS

POST /files/saveFile?token=ADFFQBYXP2NVGR6PAP3KOR27FETP6
{
    "fileName": "My file",
    "file": blob //File blob
}

Response

JS

{
  "file": {
    "additionalInfo": "{\"version\":1.5,\"xmp\":{\"Producer\":\"Skia/PDF m79\"}}",
    "category": [],
    "checksum": "50d02ebb076d0ff740c4e6279ace120b0a3971549062905a523458c2e8c3365cccf25919a9f443dddcd062b99c6e2fad47e91820afc35997eaeb79978bf79b6e",
    "createDate": "2023-01-24T12:51:38.724Z",
    "createdBy": "buli.oto@circularo.com",
    "documentname": "company_memorandum",
    "encoding": "7bit",
    "encryption": {
      "isEncrypted": false
    },
    "fileExtension": "pdf",
    "fileId": "dvab6ojbu0d4soh71ewo8kpxxeqlsa8odzbns5jwhwvd4c3nt44oudnnyyskek1d",
    "fileType": "pdf",
    "hasPassword": false,
    "hash": "dvab6ojbu0d4soh71ewo8kpxxeqlsa8odzbns5jwhwvd4c3nt44oudnnyyskek1d",
    "intent": "unknown",
    "mimetype": "application/pdf",
    "originalname": "company_memorandum.pdf",
    "pages": 2,
    "public": false,
    "revision": 1,
    "size": 73404,
    "temp": false,
    "id": "dvab6ojbu0d4soh71ewo8kpxxeqlsa8odzbns5jwhwvd4c3nt44oudnnyyskek1d",
    "isConvertible": false
  },
  "storage": null,
  "signFields": [],
  "formFields": []
}

Response object contains the file hash of newly created file:
dvab6ojbu0d4soh71ewo8kpxxeqlsa8odzbns5jwhwvd4c3nt44oudnnyyskek1d

Additional information regarding files

file can also be a signature image, profile image etc.
file is not a document → document is created from the file
in general first you create a file and then use it in some way (create a document, save it as a signature image etc….)
file hash is not created through hashing
file id vs file hash - when the file edited the hash changes, file id remains the same
some values work only for PDFs like pages

Example web form

This code sets up an event listener for the form's submit event, and in the handler, it prevents the default submit behavior.

It creates a new instance of FormData, appends the selected file to it, creates a new XMLHttpRequest object, opens a POST request to the API endpoint with the token added to the URL, sets the onload property to a callback function that logs the response or any errors, and finally sends the FormData object in the request body.

JS

<form id="file-form">
  <input type="file" id="file-input" name="file" />
  <button type="submit">Upload</button>
</form>

<script>
  const form = document.getElementById("file-form");
  const fileInput = document.getElementById("file-input");
  const token = "your-token-here";

  form.addEventListener("submit", (event) => {
    event.preventDefault();

    const formData = new FormData();
    formData.append("file", fileInput.files[0]);

    const xhr = new XMLHttpRequest();
    xhr.open(
      "POST",
      `https://sandbox.circularo.com/api/v1/files/saveFile?token=${token}`,
      true
    );

    xhr.onload = function () {
      if (this.status === 200) {
        console.log(JSON.parse(this.response));
      } else {
        console.error(this.response);
      }
    };

    xhr.send(formData);
  });
</script>

Download binary data

JS

async function download() {
    var oReq = new XMLHttpRequest();
    var url = "https://API_URL";

    oReq.onload = function(e) {
    var buffer = oReq.response;        // <= here is your final buffer
  }
  oReq.open("GET", url);
  oReq.responseType = "arraybuffer";   
  oReq.send();
}