Import data through the API
For an ongoing feed rather than a one-off spreadsheet. The same rules apply, except nobody is watching this time.
An API feed has the same failure modes as a spreadsheet import — bad phone formats, duplicates, unmapped data — with one important difference: nobody eyeballs it. A spreadsheet gets a glance before upload. A feed runs at 3am forever.
So the two things to settle before the first write are your deduplication key and your phone number format. Retrofitting either to a workspace full of records is painful.
Before you start
- Your contact schema defined first.
- An API key.
- A deduplication key agreed: phone, email or an external ID.
- A monitoring plan — how you will know if it stops.
Steps
Define the schema before you write anything
The API writes into attributes. Attributes that do not exist cannot be written, and adding them later means a backfill.
Agree what makes two records the same person
Phone number, email, or an external ID from the source system. Decide before the first write — retrofitting a dedupe rule to a workspace full of duplicates is the worst job in CRM administration.
Normalise phone numbers with country codes
Same problem as spreadsheet import, except nobody reviews it. Numbers without country codes will not dial, and a feed can produce thousands of them before anyone notices.
Upsert, never create
Networks retry, sources resend, and jobs re-run. A create-only feed duplicates on every one of those.
Run it against twenty records first
Then read those twenty in the UI before letting it loose on everything.
Set owner and lead stage
Without an owner a contact reaches no calling list; without a stage it may fall outside the filters your campaigns rely on.
Monitor it
A silent feed that stopped three weeks ago looks exactly like a quiet market. Something needs to notice — a scheduled check, or a workflow that alerts when nothing has arrived.
Check it worked
A week after going live, count the contacts created by the feed and compare against the source system. If the numbers do not match, find out why now while the volume is still small.
The parts people get wrong
- The consent question does not go away because the data arrived by API. If anything it is harder, because nobody reviewed the list.
- Values outside a dropdown's defined choices are rejected, so the feed has to speak your schema's vocabulary rather than its own.