Bulk Import Contacts using an XLS File (Excel)

Importing contacts lets you add large numbers of contacts to RapidPro.app using an XLS/XLSX spreadsheet.
You must have at least one channel connected in your workspace before you can import contacts.

[CAPTURE: Workspace settings showing at least one connected channel.]

Your spreadsheet should include columns for the information you want to import.

Typical required columns

Most imports include an address column (URN) and a Name column. Address columns can include Phone (E.164),
Telegram, Email, and other supported address types.

[CAPTURE: Example spreadsheet headers showing Phone + Name.]

When to use UUID (updating existing contacts)

Use a UUID column when your import is meant to update existing contacts, especially when adding a new address type
(for example, adding Email) or adding an additional address value to existing contacts. In these cases, UUID can replace Name.

[CAPTURE: Spreadsheet headers showing UUID + Phone/Email columns.]

Optional columns

• Language (preferred language) using ISO language codes
• Custom fields (extra columns mapped to contact fields)

Rules for custom-field column headers:

• Max 36 characters
• No special characters
• Cannot start with a number

[CAPTURE: Spreadsheet with custom fields columns like village, age, team.]

Date and time behavior

• If you import a date without a time, RapidPro.app sets the time to 00:00.
• If you later manually update a date-only field, RapidPro.app may update the time portion based on when you saved the change.

[CAPTURE: Spreadsheet date column + how it appears after import.]

Group membership during import

Group membership is selected during the import process, not inside the Excel file. You can add contacts to an existing group,
create a new group, or import them with no group selected.

[CAPTURE: Import screen showing group selection options.]

1. Go to the Contacts tab.
2. Click Import (top left).

[CAPTURE: Contacts page with the “Import” button.]

1. Download the provided template (or use your own file), then click Choose File and upload your spreadsheet.

[CAPTURE: Import page with template download + Choose File.]

1. Click Preview.
2. Confirm headers are detected correctly, select group membership (optional), then start the import.

[CAPTURE: Preview step showing detected headers + group selection + import button.]

After import, review results such as how many contacts were created or updated, and any group membership changes.

[CAPTURE: Import results summary.]

Importing multiple address types

You can import multiple address types (for example, Phone + Email), but typically one address per type per row.

[CAPTURE: Spreadsheet row showing Phone + Email columns filled.]

To add addresses to existing contacts, include the contact UUID so RapidPro.app updates the correct contact rather than creating a duplicate.

Exporting contacts to get UUIDs

Exports include contact UUIDs, names, addresses, and custom fields. To export:

1. Go to Contacts.
2. Open the menu (☰ / ⋮) and choose Export.

[CAPTURE: Contacts menu showing “Export”.]

Removing duplicates

If your spreadsheet contains duplicates (for example, the same phone number repeated), clean them before importing to avoid conflicts and unexpected results.