Mobile App Guide

Overview

The Questbee mobile app is an offline-first data collection tool for field workers. It runs on Android and iOS, works with no internet connection, and automatically syncs collected data to your Questbee server when back online.

Download and install the app for your platform:

Android: Download APK from GitHub Releases
iOS: Available on paid plans — contact us

White-label compilation (your organization's name, logo, and colors) is available on Professional and above.

Installation

Android

Download the latest APK from the releases page on GitHub
On your Android device go to Settings → Security → Unknown Sources and allow installation from unknown sources
Open the downloaded .apk file and tap Install
Open Questbee from the app drawer

iOS

A compiled standalone iOS app is available on paid plans. Contact us to discuss your requirements.

Pairing with Your Server

Before collecting data, the app must be connected to your organization's Questbee server. Pairing is done by scanning a QR code — no separate username or password is required on the device.

Step 1 — Generate a Pairing QR Code (Dashboard)

Log into the Questbee web dashboard
Go to Settings
Under Mobile Pairing, click Generate QR Code
A QR code appears — it is valid for a short time (shown on screen)

Important: Each QR code is single-use. If pairing fails or you need to pair again after unpairing, cancel the existing QR and generate a new one before scanning.

Step 2 — Connect the App

Open the Questbee app on your phone
Tap Scan QR Code
Point the camera at the QR code on the dashboard screen

The app will verify the connection, store your device token securely, and download your assigned forms automatically.

Managing Connected Devices

Administrators and managers can see all paired devices in the dashboard under Settings → Connected Devices. Each entry shows the device label, the user it is linked to, and the last sync time.

To disconnect a device, click Revoke next to it. The device will no longer be able to sync until re-paired.

Collecting Data

Start a Submission

Open the Forms tab
Tap the form you want to fill out
Fill in each field — swipe or tap Next to advance
Tap Submit when complete

Field Types

Field	How to Use
Text / Long text	Type your response
Number	Enter a number using the numeric keypad
Email / Phone	Type using the appropriate keyboard
Date / Time	Tap to open a date or time picker
Single choice	Tap one option
Multiple choice	Tap all options that apply
GPS location	Tap Capture to record your current position. Wait for accuracy to improve before confirming.
GPS trace	Tap Start to begin recording your path. Tap Stop when done.
Photo	Tap Take Photo to use the camera, or Choose from Gallery
Audio	Tap Record — tap again to stop
Signature	Draw with your finger on the signature pad
Barcode / QR	Tap Scan and point the camera at the code
File attachment	Tap to select a file from your device
Repeating group	Tap Add entry to fill in a set of fields multiple times (e.g., one per household member)

Conditional Questions

Some questions only appear based on your previous answers. The form shows only what is relevant to your responses.

Required Fields

Fields marked with * must be answered before you can submit. If you tap Submit with missing required fields, the form scrolls to the first unanswered required field.

Offline Mode

The app is designed to work without internet. When offline:

You can fill out and submit forms normally
Submissions are saved to the device queue
Photos, audio, and other media are stored on the device
GPS capture works using the device's GPS chip — no internet needed

The status indicator on the home screen shows:

Synced — all submissions have been uploaded
X pending — number of submissions waiting to sync
Offline — device has no internet connection

Syncing

Sync happens automatically when the device has a network connection. You do not need to do anything manually.

What Gets Synced

Submission data (all field responses)
Photos, audio recordings, signatures, and file attachments
GPS traces

Media files may take longer to upload than form data on slow connections. The app continues uploading in the background.

Reliability

Each submission is sent with a unique device-generated ID. If the connection drops mid-sync, the app retries automatically. The server ignores duplicate submissions — you will never get duplicate records even if the same submission is sent twice.

Troubleshooting

Can't connect after scanning QR code

Make sure your phone can reach the server (same Wi-Fi, or the server is publicly accessible)
Ask your administrator to verify the server is running: docker compose ps
The QR code expires after a short time — ask for a new one if it has been more than a few minutes
Each QR code can only be used once. If you unpaired and are trying to pair again, cancel the current QR in the dashboard and generate a fresh one before scanning

Forms not appearing after pairing

Pull down to refresh on the Forms tab
Check that your user account has published forms assigned to it

Submissions stuck as pending

Check your network connection
Open the app with a working connection — sync runs automatically
If it continues, check with your administrator that the server is reachable

GPS not capturing

Make sure location permission is granted: Phone Settings → Apps → Questbee → Permissions → Location → Allow all the time
Move to an open area — GPS is unreliable indoors and under heavy tree cover
Wait 30–60 seconds for accuracy to improve before confirming

Photo / camera not working

Make sure camera permission is granted: Phone Settings → Apps → Questbee → Permissions → Camera → Allow

App crashed or won't open

Force-stop the app and reopen it
Unsynced submissions are saved in the device database — they will not be lost unless you clear app storage