Skip to content

Contact imports

An import has two steps. First you upload the file and get back its columns, a sample and a suggested mapping. Then you confirm which column holds what, and the import runs in the background, 500 rows at a time. The file is stored encrypted until the import finishes, then deleted.

Field Type Description
id string imp_…
fileName string
status string uploaded, queued, processing, completed or failed.
rowCount integer Data rows, without the header.
columns string[] Header names.
sample string[][] Up to 5 rows as uploaded. Upload response only.
suggestedMapping object Field to header, guessed from English and Arabic header names. Upload response only.
processed, created, updated, skipped integer Progress counters.
report object or null { skipped: { reason: count }, rows: [{ line, reason, column? }] }, the first 500 skipped rows.
error string or null Why the import failed.
startedAt, completedAt, createdAt string or null

Skip reasons: missing_phone, invalid_phone, invalid_email, invalid_field, duplicate_in_file (a number seen earlier in the file), blacklisted, and already_exists (when updateExisting is false).

POST/v1/contact-importscontacts:manage

multipart/form-data with one part named file. Returns 201. Counts toward the bulk rate limit. Audited as contacts.import_uploaded.

File rule Limit
Type UTF-8 text: .csv, .txt or .tsv
Size 5 MB
Rows 100,000
Columns 50
Cell 1,000 characters
Delimiter ,, ; or tab, detected
Terminal window
curl https://api.smsfabric.com/v1/contact-imports \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-F "file=@customers.csv;type=text/csv"
{
"id": "imp_g2j5m8p1s4v7y0b3e6h9k2n5",
"fileName": "customers.csv",
"status": "uploaded",
"rowCount": 3,
"columns": ["Mobile", "First name", "Last name", "City"],
"sample": [
["0100 123 4567", "Mona", "Hassan", "Cairo"],
["+966501234567", "Omar", "Saleh", "Riyadh"],
["01001234568", "Youssef", "Adel", "Giza"]
],
"suggestedMapping": { "phone": "Mobile", "firstName": "First name", "lastName": "Last name" },
"processed": 0,
"created": 0,
"updated": 0,
"skipped": 0,
"report": null,
"error": null,
"startedAt": null,
"completedAt": null,
"createdAt": "2026-11-19T11:00:00.000Z"
}
Error When
400 file_required No file part.
413 payload_too_large The file is over 5 MB.
415 unsupported_file_type Not a CSV, a binary file, or not UTF-8.
400 csv_empty, csv_too_many_rows, csv_too_many_columns, csv_cell_too_long, csv_unterminated_quote, csv_duplicate_header The file doesn’t parse.
POST/v1/contact-imports/:id/startcontacts:manage

Confirms the mapping and queues the import. Returns 202 with status: "queued". Counts toward the bulk rate limit. Audited as contacts.import_started, and as contacts.import_completed with the counts when it ends.

Body field Type Required Description
mapping object Yes Header for each field: phone (required), firstName, lastName, email, tags (cells split on ;, , or |), timeZone, and custom ({ "snake_case_key": "Header" }).
defaultCountry string No ISO 3166-1 code for numbers without a country code, such as EG for 0100 123 4567. Numbers starting with 00 are accepted.
groupId string No Add every imported contact to this group.
tags string[] No Up to 5 tags added to every imported contact.
consent object No { source, at?, text? } written to new contacts, and to existing ones without consent.
updateExisting boolean No true (default) fills empty fields of existing contacts, merges custom fields and adds tags. false skips them as already_exists.
Terminal window
curl https://api.smsfabric.com/v1/contact-imports/imp_g2j5m8p1s4v7y0b3e6h9k2n5/start \
-H "X-Api-Key: $SMSFABRIC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mapping": { "phone": "Mobile", "firstName": "First name", "lastName": "Last name", "custom": { "city": "City" } },
"defaultCountry": "EG",
"groupId": "grp_t6w9z2c5f8i1l4o7r0u3x6a9",
"tags": ["import-nov"],
"consent": { "source": "import", "text": "Opted in at the store counter" }
}'
Error When
400 validation_failed A mapped header isn’t in the file (listed in errors[]).
404 not_found The import or groupId is not in your organization.
409 import_already_started The import was already started.
GET/v1/contact-importscontacts:read

Newest first, paginated with limit and cursor.

Terminal window
curl https://api.smsfabric.com/v1/contact-imports \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
GET/v1/contact-imports/:idcontacts:read

Poll this until status is completed or failed.

Terminal window
curl https://api.smsfabric.com/v1/contact-imports/imp_g2j5m8p1s4v7y0b3e6h9k2n5 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
{
"id": "imp_g2j5m8p1s4v7y0b3e6h9k2n5",
"fileName": "customers.csv",
"status": "completed",
"rowCount": 3,
"columns": ["Mobile", "First name", "Last name", "City"],
"processed": 3,
"created": 2,
"updated": 0,
"skipped": 1,
"report": {
"skipped": { "duplicate_in_file": 1 },
"rows": [{ "line": 4, "reason": "duplicate_in_file", "column": "Mobile" }]
},
"error": null,
"startedAt": "2026-11-19T11:01:02.000Z",
"completedAt": "2026-11-19T11:01:03.000Z",
"createdAt": "2026-11-19T11:00:00.000Z"
}