Create Events Import Documentation

POST/imports/events

Required Tokens

Field	Type	Required	Description
Bearer	Authorization: Bearer <api-key>	Optional	Your API key. Pass it as the Bearer token on every request.
Organization token	x-Organization-Token	Optional	Run Get Tokens in the Organization API collection, then set `orgToken` as a variable here. This target is org-scoped, so an event token will not authorize it.

Creates the Import against the events target, resolves every row, and returns the plan. Writes no event data — nothing lands until Execute Import.

This request stores importId for the follow-on calls in this folder, so Get Import and Execute Import work against it unchanged.

Requires OrganizationAdmin.

What the sample body demonstrates

Set statusAttributeId to a Select attribute on the event type, with Confirmed and Cancelled among its options, or drop that column from the sample.

Row	Outcome	Why
2	`Update`	`rth-2291` matches a stored `RTH-2291`. Keys compare trimmed and lowercased on both sides. The blank `Notes` cell leaves the stored notes alone. `confirmed` resolves to the option as authored, so `resolvedValues` reads `Confirmed`.
3	`Create`	Nothing matches `RTH-9001`. Its misspelled `Confrmed` would have failed validation, but `valueOverrides` corrects it first.
4 and 5	`Skip` / `DuplicateInFile`	They share a key. Both are skipped — keeping the first would pick a winner silently when the rows disagree.
6	`Skip` / `ExcludedByUser`	Its `Status` is a value `excludedValues` names.

A key matching two or more existing events would instead skip as NotUnique, which is a different problem with a different fix — see Get Import.

Parameters

Same shape as Create Import, with this target's meanings:

Field	Type	Required	Description
contextId	Guid	Optional	The event type the rows are imported against. Omit for type-less events.
uniqueAttributeKey	string	Optional	The attribute to match on — `name`, or `attr:{attributeId}` for a custom one. Must be mapped. Null means every row creates, matching nothing.
rows[].values	object	Required	Cell text keyed by file column, not attribute key.
excludedValues	array	Optional	`{ attributeKey, rawValue }`. Every row carrying that value skips as `ExcludedByUser`.
valueOverrides	array	Optional	`{ attributeKey, rawValue, value }`. Every row carrying `rawValue` is planned and written as `value`.

Excluded values and overrides

Both are value-level, not row-level — a file with 300 rows carrying 4 distinct statuses is 4 decisions. Both match a cell trimmed and lowercased, and both name an attribute that must be mapped or the call is refused.

An excluded value is removed before the plan is computed, not filtered out of it. So a row excluded on its unique key does not make a surviving row that shares that key skip as DuplicateInFile — the collision was with a row nobody was importing.
Exclusion wins over every other skip reason. A row that is both excluded and carries an unreadable number reports ExcludedByUser. It was removed; a diagnostic about it is noise.
An override is applied before validation, so an override naming an invalid Select option is refused by the same check that refuses a bad cell — the row skips as ValidationFailed and the valid options are named.
rawValues always records what the file said. An override lands in resolvedValues only, which is the pair that makes the receipt say what was changed on the way in.
Every row excluded is not an error. The call returns 200 with an all-Skip plan.

`resolvedValues` is resolved, not a copy

The plan's resolvedValues carries the values as they will be written:

Kind	Resolved as
`Date`	`yyyy-MM-dd`
`DateTime`	ISO 8601, UTC
`Checkbox`	`true` / `false`
`Select`	the option as the organization authored it
`Number`	unchanged — validated, never reformatted, because the stored value is a string
`Text`, `Link`	trimmed

This matters most for dates. A CSV carries no locale, so 03/04/2026 is genuinely ambiguous and the handler accepts ISO 8601 plus invariant culture rather than guessing — resolvedValues is how a caller sees which reading it took before committing.

Behavior worth knowing before you call it

A blank cell leaves the field untouched on an update. It means no opinion, not clear this — a sparse export would otherwise wipe the omitted columns across every matched record, with no undo. On a create, a blank is simply an unset field.
name is required to create but not to update. A corrections export that carries only the reference and the changed columns is a normal thing to upload.
Matching is one query for the whole file, not one per row.
Created events land as Draft, so a bulk create consumes no license seats.

Errors

Status	Meaning
`400`	No rows, more than 2,000 rows, an attribute mapped twice, a unique key that is not mapped, an `excludedValues` or `valueOverrides` entry naming an unmapped attribute, or an archived event type.
`403`	The caller lacks `OrganizationAdmin`.
`404`	No such event type in this organization.

Create Events Import