Adding a New Contact (E164 Number Format)

You can manually create a contact in RapidPro.app when you need to add someone before they message you (for outreach, testing, or preparing data), by opening Contacts, creating a new contact, and saving at least one reachable address (URN)—typically a phone number in E.164 format with the country code—to ensure message delivery works correctly.
Reading time
6–7 min read
Category
Contacts
Updated on
Updated on: 23/12/2025

Create a new contact in a few steps

If you just need the essentials, follow this:

  1. Open the Contacts tab
  2. Open the right-side menu (⋮ / ☰) and select New Contact
  3. Enter a name (recommended) and at least one address (URN)
  4. Use E.164 format for phone numbers (country code included)
  5. Save and confirm the contact appears in Active contacts

You’re done. The contact is now available for messaging, testing, and data updates in your workspace.

Step-by-Step Process

1
Open Contacts

  1. Go to the Contacts tab.

2
Start a new contact

  1. Click the menu icon (⋮ / ☰) on the right side.
  2. Select New Contact.

[CAPTURE: Contacts tab with the right-side menu icon visible.]
[CAPTURE: Menu opened showing “New Contact”.]

💡
Tip: A contact must have a reachable address (like a phone number) if you want to message them.

3
Enter contact details

  1. Enter the Name (optional but recommended).
  2. Enter the Phone Number (or another address, depending on your workspace).

[CAPTURE: “New Contact” form showing Name + Phone Number fields.]

4
Use E.164 format for phone numbers

Phone numbers should include the country code (E.164). For example: +221XXXXXXXXX.

⚙️
Note: Phone numbers must include the country code (E.164). Avoid extra characters, spaces, or missing prefixes.

⚠️
Warning: Wrong format can cause delivery issues. If the phone number is missing the country code or has extra characters/spaces, messages may fail.

5
Save and confirm the contact was created

  1. Save the contact.
  2. Confirm the new contact appears at the top of the Active contacts list.

[CAPTURE: Active contacts list showing the newly created contact at the top.]

Common Issues & Quick Fixes

Problem: I can’t message the contact after creating it.

Fix: Confirm the contact has at least one reachable address (URN) and that the address type matches an enabled channel in your workspace (for example, SMS/phone for an SMS channel).

Problem: Messages fail because the phone number format is invalid.

Fix: Edit the contact’s phone number to include the country code in E.164 format (for example, +221XXXXXXXXX) and remove extra spaces or characters.

Problem: The contact doesn’t appear in the list after saving.

Fix: Refresh the Contacts page and make sure you are viewing Active contacts (not a filtered group or folder).

Related Resources
Searching and Filtering Contacts with Advanced Queries
Bulk Import Contacts using an XLS File (Excel)
Editing the Value of a Field (Manually or via Flow)