Key limits
| Limit | Value |
|---|---|
| Maximum file size | 50 KB |
| Batch size | 100 rows at a time (processed in the background) |
| Invalid rows | Skipped per-row; valid rows still import |
What you need before you start
- A CSV file in UTF-8 encoding.
- A header row naming each column. Header names are case-insensitive but must match Xobito’s field names exactly — there is no column-mapping UI.
- All phone numbers in E.164 format.
- Any statuses, sources, and custom fields already created in Xobito (the CSV refers to them by their ID).
Download a sample CSV
The import screen offers a sample CSV you can download. It has the correct header row and one example data row. Use it as a template.Required columns
These columns must be present in your CSV. Rows missing any required value are skipped.| Column | Description | Validation |
|---|---|---|
firstname | First / given name | Max 191 characters |
lastname | Last / family name | Max 191 characters |
type | Contact type | Must be lead or customer |
phone | Phone in E.164 format | Must match /^\+[1-9]\d{5,14}$/. Unique within your workspace. |
status_id | Status identifier | Must be the ID of an existing status |
source_id | Source identifier | Must be the ID of an existing source |
status_id and source_id are the numeric IDs assigned to the status/source records you created in Contacts → Status and Contacts → Source. Check those screens to find the IDs before building your CSV.Optional columns
| Column | Description |
|---|---|
company | Company name |
description | Free-text notes |
email | Email address — if provided, must be unique in your workspace |
country_id | Country identifier |
city, state, zip, address | Address details |
assigned_id | Staff user ID assigned to the contact |
group_id | Group identifier(s) — See Groups |
| Custom-field slugs | Any custom field’s field_name can be used as a column |
Sample CSV
Leave a cell empty for optional fields you don’t have — don’t write
null or -.Phone number format
Phone numbers are the number-one cause of failed imports. The rules:- Must start with
+followed by the country code. - No spaces, no dashes, no parentheses.
- No leading zero after the country code (UK
07911…becomes+447911…). - Total length between 7 and 15 digits after the
+.
| Example | Accepted |
|---|---|
+14155551234 | Yes |
+447911123456 | Yes |
+919876543210 | Yes |
415-555-1234 | No |
(415) 555 1234 | No |
07911123456 | No — missing country code |
14155551234 | No — missing + |
Step-by-step import
Create your statuses, sources, and custom fields first
CSV references them by ID — they must exist before you import.
Prepare your CSV
Build the spreadsheet using the required columns above. Save as CSV UTF-8. Confirm the file is under 50 KB.
Upload your file
Drag and drop or click to browse. Xobito checks the file size — if over 50 KB you’ll see an error before any rows are processed.
Start the import
Xobito processes rows in batches of 100. Very small imports finish almost instantly; larger ones run in the background.
What happens to each row
| Case | Result |
|---|---|
| All required fields present and valid | Contact is created. |
| Phone number already exists for another contact | Row is skipped with “phone already exists”. |
| Phone number is invalid (bad format) | Row is skipped with a format error. |
type is not lead or customer | Row is skipped with a validation error. |
status_id or source_id doesn’t exist | Row is skipped with a reference error. |
| Custom field value fails validation | Row is skipped with the field name and reason. |
| Email already exists for another contact | Row is skipped with “email already exists”. |
Import log
Every import writes a log entry containing:- Which file was uploaded and when.
- Total rows, successful rows, and skipped rows.
- For each skipped row: row number + specific field errors.
Best practices
Keep files small
Keep files small
The hard limit is 50 KB. Split large exports into several small files. This is faster and easier to recover from if something goes wrong.
Create IDs first
Create IDs first
Get the
status_id, source_id, and any country_id values you need before building the CSV. Without them every row will fail.Test with 5 rows first
Test with 5 rows first
Before uploading your main file, upload a trimmed 5-row version. Check the log, open one of the created contacts, then run the full import.
Use UTF-8
Use UTF-8
Non-Latin names (Hindi, Arabic, Chinese) need UTF-8 encoding. Export from Excel as CSV UTF-8, not plain CSV.
Never import opted-out numbers
Never import opted-out numbers
Only import contacts who have agreed to receive WhatsApp messages from you. Unsolicited messages hurt your quality rating.
Troubleshooting
'File too large' error
'File too large' error
Your CSV exceeds the 50 KB limit. Split it into smaller files.
All my rows were skipped
All my rows were skipped
Open the import log — it lists the exact reason per row. The most common causes are phone numbers without a country code, and missing
status_id or source_id.Non-English names show as question marks
Non-English names show as question marks
Your CSV is in the wrong encoding. Re-export as CSV UTF-8 from your spreadsheet tool.
Column header doesn't seem to be recognised
Column header doesn't seem to be recognised
Column names must match Xobito’s field names exactly (case-insensitive). There is no mapping UI. Check spelling and avoid extra spaces.
Dates in custom fields aren't accepted
Dates in custom fields aren't accepted
Xobito expects dates in a standard format — see Custom Fields for details.
Next steps
Organise into groups
Segment your imported contacts for targeted campaigns.
Run a campaign
Broadcast to your freshly imported list.