---
title: "Import custom events"
method: POST
path: "/api/customEvents.import"
---

# Import custom events

`POST /api/customEvents.import`

Imports multiple custom events in a single batch operation. Maximum 50 events per request. Auto-creates contacts if they don't exist.

## Request body

- ImportCustomEventsRequest
  - `workspace_id` string, required — The ID of the workspace
  - `events` object[], required — Array of custom events to import (1-50 events)
    - `event_name` string, required — Event type name
    - `external_id` string, required — External system identifier
    - `email` string, email, required — Contact email address
    - `properties` object — Event data
    - `occurred_at` string, date-time — When the event occurred
    - `source` 'api' | 'integration' | 'import' — Origin of the event
    - `integration_id` string — Integration reference
    - `goal_type` 'purchase' | 'subscription' | 'lead' | 'signup' | 'booking' | 'trial' | 'other' — Type of goal for conversion tracking
    - `goal_name` string — Optional goal name for categorization
    - `goal_value` number, double — Monetary value (required for purchase/subscription, can be negative for refunds)
    - `deleted_at` string, date-time — Soft delete timestamp

## Response `201`

Custom events imported successfully

- ImportCustomEventsResponse
  - `event_ids` string[] — External IDs of successfully imported events
  - `count` integer — Number of events created

## Other responses

- `400` — Bad request - validation failed
- `401` — Unauthorized - invalid or missing authentication token
- `403` — Forbidden - missing required permission
- `500` — Internal server error

## Changes

- **2025-11-30** `f018ea668217` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/pierre-b/apis/notifuse-api/changes/api/customEvents.import/post.md)

---

[API](https://skmtc.dev/pierre-b/apis/notifuse-api.md) · [All operations](https://skmtc.dev/pierre-b/apis/notifuse-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pierre-b/notifuse-api/revisions/d26605f2fc47/schema)