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.
The import object
Section titled “The import object”| 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).
Upload a file
Section titled “Upload a file”/v1/contact-importscontacts:managemultipart/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 |
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. |
Start an import
Section titled “Start an import”/v1/contact-imports/:id/startcontacts:manageConfirms 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. |
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. |
List imports
Section titled “List imports”/v1/contact-importscontacts:readNewest first, paginated with limit and cursor.
curl https://api.smsfabric.com/v1/contact-imports \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Retrieve an import
Section titled “Retrieve an import”/v1/contact-imports/:idcontacts:readPoll this until status is completed or failed.
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"}