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 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 at /dir1/sub-dir1/selfie.png on your local file system with the purpose customer.selfie:

Bash

curl https://api.falu.io/v1/files \
    -U "fskt_1234567890:" \
    -F "file"="@/dir1/sub-dir1/selfie.pnf" \
    -F "purpose"="customer.selfie"

.NET

var path = "/dir1/sub-dir1/selfie.png";
using (var stream = System.IO.File.Open(path, FileMode.OpenRead));
var options = new FaluClientOptions { ApiKey = "fskt_123456879", };
var client = new FaluClient(Options.Create(options));
var request = new FileCreateRequest
{
    Content = stream,
    Purpose = "customer.selfie",
};
await client.Files.CreateAsync(request);

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

Kotlin

UserProfileActivity.kt

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
                }
            }
        )
    }
}

Java

UserProfileActivity.java

public class UserProfileActivity extends AppCompatActivity {
    private Falu falu;

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceBundle) {
        super.onCreate(savedInstanceState);
        falu = new Falu(
            this,
            "fpkt_123456789"
        );
    }

    private void uploadFile(@NotNull File file) {
        falu.createFile(
            new FaluFileParams(
                file,
                "customer.selfie"
            ),
            new ApiResultCallback<FaluFile>() {
                @Override
                public void onSuccess(@NonNull FaluFile result) {
                    // File upload succeeded
                }

                @Override
                public void onError(@NonNull Exception e) {
                    // File upload failed
                }
            }
        );
    }
}

Swift

UserProfileViewController.swift

let request = FileRequest(
    file: Data(),
    purpose: "customer.selfie"
)

falu.createFile(request: request) { result in
    if case .failure(let error) = result {
        DispatchQueue.main.async {
            // show errors on the UI thread
        }
    } else {
        DispatchQueue.main.async {
            // show on UI thread
        }
    }
}

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

PURPOSE	DESCRIPTION	ALLOWED CONTENT TYPES	MAX SIZE	DOWNLOAD ALLOWED
business.icon	A business icon.	image/jpeg, image/png, image/gif	512KiB	true
business.logo	A business logo.	image/jpeg, image/png, image/gif	512KiB	true
customer.signature	Customer provided signature image.	image/jpeg, application/pdf	4MiB	true
customer.selfie	Image of a selfie collected for identification purposes.	image/jpeg	4MiB	true
customer.tax.document	Customer provided tax document.	application/pdf	16MiB	true
identity.document	Document to verify the identity of an entity.	image/jpeg, image/png	16MiB	false
identity.video	Video to verify the liveness of an entity's identity verification.	video/mp4	128MiB	false
message.media	Media attached to a message.	image/jpeg, image/png, audio/mpeg, audio/mp3, application/ogg, audio/ogg, audio/amr, application/pdf, video/mp4, video/m4v, text/vcard	16MiB	true

caution

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.
  • Print to PDF with macOS
  • Print to PDF with Adobe Acrobat