​

Import or migrate contacts

​

1. Pick the surface: decision table

• Audience → Import — the CSV wizard itself (upload, map, preview, run). One wizard pass per file.
• Audience → Imports — the import-history page: every past job with status, per-job counters, the skipped-rows download, and a resume link into in-flight jobs. When you need “which import landed and what did it skip,” this is the answer.

​

2. Bulk CSV import to a contact list

1. One address per row. Each row needs a phone or an email; rows with neither are skipped. Rows you do not fix at export become the skipped-rows CSV after the run.
2. Phone format. E.164 (+14155552671) is preferred. The server tolerates whitespace and punctuation, and PBX-extension suffixes (x1234). Rows it cannot parse are skipped rather than guessed.
3. Opt-in columns. Consent is a property of the channel on the row, not of the row itself — decide before import which file column maps to which consent signal. The mapping makes send-time suppression deterministic instead of retroactive (see step 4).
4. Custom field headers. A header that names a custom field key maps into that field. Define the field first: values are typed and validated on write, and a row that fails the validator is skipped (see step 5).

​

3. The API path

• POST /api/v1/contacts/imports/preview — dry-run: validates row shape, counts invalid rows, and reports duplicates (inside the file and against the existing tenant). Writes nothing.
• POST /api/v1/contacts/imports — enqueue the job: accepts up to 1,000,000 rows, returns 202 with a job_id. Poll GET /api/v1/contacts/imports/{id} until status leaves pending / processing; statuses are pending → processing → {completed, failed, cancelled}.
• GET /api/v1/contacts/import-jobs/{id}/skipped.csv — the row-error report: one row per skipped input row, with row_index, a human-readable reason, and the original columns.
• POST /api/v1/contacts/imports/{id}/cancel and POST /api/v1/contacts/imports/{id}/rollback — cancel stops an in-flight job; rollback hard-deletes the contacts the job created. The rollback window is 24 hours after the job finishes.

​

4. Opt-in and suppression on import

• Rows whose opt-in column says “no” should land suppressed via an opt-out list before the first send — not merely tagged.
• Existing opted-out contacts must stay opted out across a re-import; choose merge on re-import only if the file’s consent column actually carries new, better-granted consent.
• The import rollback cascade (step 3) removes consent records along with created contacts, so rolling back a bad import never leaves orphaned opt-in flags.

​

5. Map custom fields without inventing headers

• Naming. Map the column header directly to the field key — no prefix, no Casing change. A header that does not match a defined key is either plain contact data (ignored on write) or a mistake that only shows up as skipped rows.
• Type coercion. CSV cells are strings; the validator coerces them into the field’s declared type on write. date fields reject unparseable dates, number fields reject non-numeric text, and boolean expects the declared truthy set.
• Common errors. A header that collides with another mapped header (duplicate), a column that maps to a required field but is missing from the file (violates the required-field constant), and a row whose value fails the type check — each lands in the skipped-rows report with its own reason string.

​

6. CDP profile import

• Identity merge on input. The CDP ingest surfaces (POST /api/v1/cdp/file-ingest for CSV/JSON batch files, the HMAC SDK surface for streams) run each row through the same identity rules the identity resolution model defines: an incoming userId deterministically merges onto one contact; the survivorship policy decides which value wins when two profiles collide.
• Re-import does not duplicate. Because ingest keys on identity, re-importing the same file merges onto the profile it already created — it never forks a second identity. The identity rules and survivorship policy you author in the Integrations → CDP tabs are documented in CDP data catalog and identity rules; preview the merge effects with simulation before any rule change (see that guide).
• When not to take this path. If all you have is a phone and a list of tags, the plain contact import is simpler — the CDP path pays for itself only when identity resolution is the point.

​

7. Migration jobs: moving off another CPaaS

• The operational lifecycle (connect → preview → run → reconcile, cancel, 24-hour rollback) is run a platform migration end-to-end.
• The concept page explains the state machine, the per-source entity kinds, and credential handling — import and migration lifecycle.
• Monitor, cancel, and rollback outside the wizard from Settings → Migrations — see migration jobs operations.
• The per-source concept mapping (what your Twilio numbers, Klaviyo lists, etc. become in Orbit) is migrate from Twilio and migrate from an enterprise CCaaS.

​

8. Post-import: preview the net reachable audience

curl -X POST "https://api.orbit.devotel.io/api/v1/campaigns/audience/preview" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "audience": { "segment_id": "seg_xyz" }, "channel": "sms" }'

​

9. Troubleshooting

​

See also

• Import and reconcile contacts — the CSV endpoint walkthrough this guide routes to
• Run a platform migration end-to-end — the connector path, chosen by the table above
• Import and migration lifecycle — the concept that explains the migration state machine
• Custom fields — define import targets before mapping
• Opt-out lists — where imported opt-outs land
• CDP data catalog and identity rules — author the merge policy CDP ingest obeys
• Campaign end-to-end — launch once the preview count is clean