Import leads from a CSV
Load historical leads into a campaign, or update existing ones from a buyer's file, with a preview, a revert, and an optional postback fire.
This article shows how to bring leads into a campaign from a file, and how to update leads you already have from a file a buyer sent back.
Read the next section before your first import, because imported leads behave differently from leads that arrive through your API.
Imported leads are never sold
Imported rows are written straight into the campaign. They do not travel the ingest pipeline. No filters run, no duplicate check runs, no integrations fire, and the lead is never offered to a buyer.
Every lead an import creates therefore lands with the status Stored and the stage Imported. Stored here means saved but never distributed. It has no buyer, no sale, and no revenue, and it contributes nothing to caps or distribution reporting.
If you want the leads sold, this is the wrong tool. Post them to your ingest endpoint instead.
Rows that update an existing lead keep whatever status that lead already had, along with its buyer and its revenue.
Prerequisites
- A campaign with its fields defined
- A file saved as UTF-8, up to 500 MB. Excel exports are often not UTF-8, so re-save if you are unsure.
- For an update run, a column that uniquely identifies each lead
Run an import
- Go to Campaigns and open the campaign, then open the import drawer.
- Upload the file. Its headers are read and the first rows previewed.
- Map fields. Pair each column with a campaign field. You can also map the system fields for lead id, click id, and creation date, and switch on additional fields to expose extras such as sub IDs, affiliate id, traffic source, country, and the test flags. Save the mapping as a preset if you will use it again.
- Configure upsert, if you are updating existing leads. Turn it on and pick the field that identifies a match. Matching rows are overwritten and marked Modified.
- Preview the first mapped rows and check they read correctly.
- Start. A progress bar shows rows processed against total with an estimate. You can cancel mid-run, and closing the drawer does not stop the import.
- Review the run on the History tab.
Keep the original lead dates
Map a column to the created at system field and the leads keep their original dates instead of being stamped with the time you ran the import. This only applies to leads the import creates. An existing lead's date is never rewritten.
Most CSV dates carry no timezone. A source timezone selector appears as soon as you map that column, and it defaults to UTC. Set it to the zone the file's times are actually in, or the leads land at the wrong instant. A value that carries its own offset ignores the selector and uses the offset it has.
Unparseable dates are caught before the run and land in the invalid rows file rather than quietly falling back to today.
After the run
Each history row carries the run's status, counts, and who ran it, plus three actions.
| Action | What it does |
|---|---|
| Revert | Deletes the leads the import created and restores the ones it updated |
| Cancel | Stops a run that has not finished |
| Fire Postbacks | Fires the manual postback event for the leads this run updated |
Fire Postbacks is the reason the upsert flow exists. A buyer sends back a file saying which leads converted, you upsert those conversions onto the leads, then fire the postbacks so your traffic sources get told. Receivers should be idempotent, because you can fire more than once.
Revert is permanent and cannot be undone, and only the most recent import can be reverted.
Telling imported leads apart
| What you see on a lead | What it means |
|---|---|
| Stored, an Imported badge, no buyer | Created by an import |
| Stored, a buyer and a price, no badge | Sold to a buyer whose delivery method is Store Leads |
| Its original status, no badge, marked Modified | An existing lead updated by an import |
Always check whether a Stored lead has a buyer before answering a question about it. The word means two different things.
Expected result
The history row reads completed with the row counts you expected. Created leads appear in Leads as Stored with an Imported badge, and updated leads keep their original status while showing as Modified.
Troubleshooting
- Rows rejected for encoding. The file is not UTF-8. Re-save it as UTF-8 and run it again.
- A whole column came through empty. Check the mapping for that column, and check the header does not carry hidden characters.
- Dates are hours out. The source timezone selector was left on UTC while the file held local times.
- The import is very slow. Upsert checks every row against existing leads, which is inherently slower than a plain create.
- You cancelled and some leads are already in. Cancelling stops further processing. It does not remove what already landed. Revert the run if you want them gone.
- Revert is not available. Only the most recent import can be reverted, and only once it has completed, cancelled, or failed.
- Imported leads are not showing revenue. They never reached a buyer. That is how imports work.
Frequently asked questions
Comments
No comments yet — be the first to share your thoughts.