Data Imports & Validation

Earnest takes data two ways: CSV upload in the admin UI, and a REST API for programmatic ingestion from a warehouse, CRM or scheduled job. Both share the same validation rules.

Everything below is available under Admin → Data → Imports & API, which also shows your live endpoint URLs and a ready-made curl example.

CSV imports

Uploads are capped at 10 MB and 1,000 rows per file. Larger sets should be split, or sent through the API, which takes bigger batches.

The importer matches your header row case-insensitively and ignores spaces and underscores, so Reference Number, reference_number and referenceNumber all map to the same field. You get a column-mapping preview before anything is written.

1. Compensation

Loads or updates the roster with quotas, OTE and base salaries. Pick a compensation mode first:

• OTE mode — you supply ote, Earnest derives the commission rate.
• Commission Rate mode — you supply commissionRate, Earnest derives OTE.

2. People

A lighter roster import for adding users without compensation details.

• Required: email, name
• Optional: role, teamName, managerEmail, currency, ote, baseSalary, commissionRate, quota

managerEmail is what builds your reporting hierarchy — it matters for manager rollup quotas and for RATIO plans, whose denominator is the manager's subtree.

3. Activities / orders

Deals, bookings, meetings — anything that counts toward quota. The required columns depend on whether you are importing against a Revenue or a Unit plan.

Validation

Every row is validated before any write. A failing row is skipped with a specific message; passing rows still import. You get a per-row results summary at the end, and persistent import errors are recorded so they can be reviewed later.

Currency mismatches

If an activity's currency differs from the rep's quota currency, the row is accepted and converted at calculation time using the rate for its booking date. Nothing needs pre-converting. See Multi-Currency Explained.

Credit splits

Splits let two reps share credit for one activity.

1. The primary rep (userEmail) always receives 100% credit.
2. The split rep (splitEmail) receives their own independent credit at splitPercent.

Splits are independent, not zero-sum. Credits across one activity can total more than 100%. That is intentional — it reflects overlay credit, SE credit and management rollups, where the same deal legitimately counts for more than one person at full or partial value.

Rules: splitPercent must be greater than 0; you cannot split with the activity's own owner; the split rep must already exist; and re-importing a split replaces the existing split configuration for that activity.

Splits can also be edited directly from Admin → Data → Sales Data without re-importing.

Changing splits on a period that already has a draft payout makes that draft stale — the amounts no longer match what the reps earned. Regenerate before publishing.

API ingestion

Generate an API key under Admin → Data → Imports & API. Authenticate with the x-api-key header.

curl -X POST https://your-org.example.com/api/ingest/bigquery/activities \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"referenceNumber":"DEAL-001","userEmail":"rep@co.com","amount":25000,"currency":"USD","bookingDate":"2026-03-15"}'

The compensation endpoint takes email, effectiveDate, quota, baseSalary, and either ote or commissionRate — plus periodDivisor (12 for monthly, 4 for quarterly) to say how the annual figures split across periods.

Behaviour

• Upsert — users match on email, activities on reference number. Nothing duplicates.
• Auto-provisioning — unknown users, teams and titles are created as needed.
• Domain enforcement — user emails must match your organization's verified domain(s).
• Rate limiting — requests are throttled to prevent accidental overload.
• Import errors are logged — failures are recorded per row and summarized in a periodic digest.

CSV or API?

Tips

1. Import people before activities — activity rows need their rep to exist.
2. Use ISO 8601 dates.
3. Keep reference numbers stable — they are the update key. Changing one creates a second record.
4. Check the results summary — it names every skipped row and why.
5. Regenerate affected drafts after a corrective import, or publishing will be held.

Frequently asked questions

Q: What happens if I import the same activity twice? It updates in place. referenceNumber is the unique key within your org.

Q: What is the file size limit? 10 MB and 1,000 rows per CSV upload. The API takes 5,000 rows per batch request.

Q: Can I import activities dated in the future? Yes, but they only count toward the period containing their booking date, and you cannot draft payouts for a future month.

Q: Can I delete imported data? Individual activities can be deleted from Sales Data. Deleting an activity that a draft payout already used marks that draft stale so it cannot be published with out-of-date figures.

Q: Does importing compensation overwrite existing users? It upserts. Names and currencies update in place; a new position is created only when the compensation actually changed — so your history stays intact and date-scoped. See Scheduled Changes & History.

Q: My import failed on a published period. That is the published-period guard. Published periods are frozen; post the change forward as a correction instead — see Corrections & Clawbacks.