Breadcrumbs

Create file

Requirements

  • Authentication token

How to:

1. Create a file

JavaScript
POST /files/saveFile?token=:authenticationToken

  • Creates new file from BLOB.

  • This request uses Content-Type: multipart/form-data.

Example

Request

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

Response

JavaScript
{
  "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.

JavaScript
<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

JavaScript
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();
}