Uploading files

Use the File API to send customer selfies, identification documents, and more securely.

When you upload a file to Falu using the Files API, a file identifier and other information about the document is returned. This guide provides a detailed walk-through of how to use this identifier in other API calls.

Falu supports uploading files directly from the browser. The code (mostly in JavaScript) should call the appropriate endpoint using your publishable API key. However, if you want to perform other operations on that file, e.g. creating links, you have to use the secret API key.

Uploading a file

To upload a file, send a multipart/form-data request to https://api.falu.io/v1/files. The request should specify a purpose and a file. See Files API for more information. The following example uploads a file located locally at /dir1/sub-dir1/selfie.png with the purpose customer.selfie:

curl -X POST https://api.falu.io/v1/files \
     -H 'X-Falu-Version: 2024-06-01' \
     -u "fskt_1234567890:" \
     -F "file"="@/dir1/sub-dir1/selfie.pnf" \
     -F "purpose"="customer.selfie"

The following example uploads a file using the Falu Android SDK with the purpose customer.selfie:

class UserProfileActivity : AppCompatActivity() {
  private val falu: Falu by lazy {
    Falu(this, "fpkt_1234567890")
  }
 
  private fun uploadFile(file: File) {
    falu.createFile(
      FaluFileParams(
        file,
        "customer.selfie"
      ),
      callback = object : ApiResultCallback<FaluFile> {
        override fun onSuccess(result: FaluFile) {
          // File upload succeeded
        }
 
        override fun onError(e: Exception) {
          // File upload failed
        }
      }
    )
  }
}

Below are some purposes for which you can upload a file. Specified are the allowed format and size requirements in Falu.

PURPOSEDESCRIPTIONALLOWED CONTENT TYPESMAX SIZEDOWNLOAD ALLOWED
business.iconA business icon.image/gif, image/jpeg, image/png, image/webp, image/svg+xml512KiBtrue
business.logoA business logo.image/gif, image/jpeg, image/png, image/webp, image/svg+xml512KiBtrue
customer.signatureCustomer-provided signature image.image/jpeg, application/pdf4MiBtrue
customer.selfieImage of a selfie collected for identification purposes.image/jpeg, image/png4MiBtrue
customer.tax.documentCustomer-provided tax document.application/pdf, image/jpeg, image/png16MiBtrue
identity.documentDocument to verify the identity of an entity.application/pdf, image/jpeg, image/png16MiBfalse
identity.videoVideo to verify the liveness of an entity's identity verification.video/mp4128MiBfalse
message.mediaMedia attached to a message.image/jpeg, image/png, image/webp, audio/amr, audio/mpeg, audio/mp4, audio/ogg, application/pdf, video/mp4, text/vcard16MiBtrue

All image files must be smaller than 8,000px by 8,000px.

Handling upload errors

When you use the File API to upload a file, Falu runs it through a series of checks to validate that it is correctly formatted and meets required specifications. An error is returned for uploads that fail any of the checks.

Try the following to fix some common errors:

  • Remove annotations or additional media that you may have added to a PDF document.
  • If you cannot remove the annotations or media, or if you combined several PDF into one, try using your computer's Print to PDF functionality to create a fresh document.