Skip to main content

Uploading files

When you upload a file to Falu using the API, a file identifier and other information about the file is returned. The identifier can be used in other API calls. This guide provides a detailed walk-through of this process.

Uploading files directly from the browser is supported. 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, such as creating links, you have to use the secret API key.

Uploading a file

To upload a file, send a multipart/form-data request to The request should specify a purpose and a file. See Files API for more information. The following example uploads a file located at /dir1/sub-dir1/selfie.png on your local file system with the purpose customer.selfie:

curl \
-U "fskt_1234567890:" \
-F "file"="@/dir1/sub-dir1/selfie.pnf" \
-F "purpose"="customer.selfie"

The following example uploads a file using our 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) {
callback = object : ApiResultCallback<FaluFile> {
override fun onSuccess(result: FaluFile) {
// File upload succeeded

override fun onError(e: Exception) {
// File upload failed

There are several purposes for which you can upload a file, each with format and size requirements.

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 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
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, we run it through a series of checks to validate that it is correctly formatted and meets required specifications. We return an error for uploads that fail any of our checks.

Try the following to fix errors that we detect:

  • 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.