Contacts are the part of a migration that is easiest to get wrong, because the failures are quiet. A skipped record does not raise an error, and a lost opt-out does not show up until someone complains. This page covers the import in detail.
Furcata identifies a contact by their phone number. Everything else — name, email, language, note — is attached to that number. Two records with the same number are the same contact.
This has a consequence worth planning for: if your source data has the same person under two formats, you will get two contacts unless you normalise before importing.
- Use international format, with the country code, for every number.
- Strip spaces, dashes, brackets and any extension.
- Decide what to do with landlines and short codes — they cannot receive SMS.
- Deduplicate on the normalised number, not on the raw string.
{
"phone": "+15555550100",
"email": "alex@example.com",
"firstName": "Alex",
"lastName": "Morgan",
"language": "en",
"note": "Migrated from previous provider",
"unsubscribed": false
}Send the fields you actually have. A field you omit is left alone, so a partial record is safe — you can enrich contacts later.
Carry opt-out state across
Every contact who unsubscribed on the old platform must arrive marked as unsubscribed. If you import them as subscribed you will message people who have already asked you to stop, which is the fastest way to damage a new sending number.
Each record comes back with a status. A created record was new; a skipped record already existed or had a problem. Skipped records carry a reason, which is usually an unusable phone number.
One bad record never fails the whole import, so the way to find problems is to count: compare the number of records you sent with the number that were created or skipped for a reason you did not expect.
Import in batches rather than one enormous request. Batches give you a natural checkpoint, and if something is wrong with the data you find out after the first batch rather than after the whole list.
- Batch by source, so you know where a problem came from.
- Keep the response for each batch.
- Fix the data, then re-run only the batches that had unexpected skips.
- Count your contacts and compare against the export.
- Spot-check a handful of records for correct names and languages.
- Confirm the unsubscribed count matches what you exported.
- Run a small test campaign to internal numbers before any real audience.
The import brings numbers, not proof. Keep the consent records from your previous provider — the date, the source and the wording a person agreed to — alongside your export. If a carrier or a regulator asks, the number alone is not an answer.
Back to the migration guide
The provider-agnostic sequence covers the rest of the move, including sender registration and cutover.
Migrating from another provider