# Track event (/api-reference/public-api/trackEvent)

`POST /v1/track`

Base URL: `https://next-api.useplunk.com`

Track an event for a contact. Automatically creates or upserts the contact, then records the event. Tracked events can be used as workflow triggers, segment filters, and audience filters.

**Reserved event names** (rejected with `VALIDATION_ERROR` and code `reserved_event`): anything matching `email.*`, `contact.subscribed`, `contact.unsubscribed`, `segment.<slug>.entry`, `segment.<slug>.exit`. These are emitted by Plunk itself.

**Idempotency**: re-tracking the same event creates a new event record. Send an `Idempotency-Key` header to have a repeated request refused with `409` instead.

## Header parameters

- `Idempotency-Key`: string — Optional key that guarantees this request runs at most once. If the key was already used by your project, the request is refused with `409` instead of being performed a second time. Keys are scoped to your project, expire after 24 hours (configurable when self-hosting), and must be 1-255 printable ASCII characters.

## Request body

- `email`: string (email) (required) — Contact email. The contact is auto-created if it doesn't exist.
- `event`: string (required) — Event name. Cannot match the reserved patterns above.
- `subscribed`: boolean — Subscription state to apply to the contact. **New** contacts default to subscribed (`true`). **Existing** contacts keep their current state unless you pass an explicit value here. Pass `false` to track an event without resubscribing an unsubscribed contact.
- `data`: object — Contact data and one-off event variables. Persistent values (primitives, plain objects) are saved on the contact and become available as template variables. Pass `{ value, persistent: false }` for one-shot variables that should not be stored on the contact (e.g. order IDs, transaction details). `null` deletes a field. Empty strings are ignored. Reserved keys are filtered out — see the contacts concept page.

Example:

```json
{
  "email": "user@example.com",
  "event": "string"
}
```

## Responses

### `200` — Event tracked successfully

- `success`: boolean
- `data`: object
  - `contact`: string — Contact ID
  - `event`: string — Event ID
  - `timestamp`: string (date-time)

```json
{
  "success": false,
  "data": {
    "contact": "string",
    "event": "string",
    "timestamp": "2026-08-09T17:56:20.167Z"
  }
}
```

### `401` — Missing or invalid API key.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-09T17:56:20.167Z"
}
```

### `409` — Idempotency-Key already used. The request was refused, not performed.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-09T17:56:20.167Z"
}
```

### `422` — Request body failed schema validation. `error.errors` lists the offending fields.

- `success`: enum (false)
- `error`: object
  - `code`: string — Machine-readable error code, e.g. `VALIDATION_ERROR`, `INVALID_API_KEY`, `IDEMPOTENCY_KEY_REUSED`.
  - `message`: string
  - `statusCode`: integer
  - `requestId`: string — Correlation ID for this request. Include it when contacting support.
  - `errors`: array<object> — Field-level detail, present on validation failures.
    items:
      - `field`: string — Dot-path of the offending field, e.g. `attachments.0.filename`.
      - `message`: string
      - `code`: string — Validation issue code, e.g. `invalid_type`, `too_big`, `reserved_event`.
      - `received`: object — The value that was received, when available.
  - `details`: object — Additional error context.
  - `suggestion`: string — Hint for fixing the request.
- `timestamp`: string (date-time)

```json
{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "statusCode": 0,
    "requestId": "string",
    "errors": [
      {
        "field": "string",
        "message": "string",
        "code": "string",
        "received": null
      }
    ],
    "details": null,
    "suggestion": "string"
  },
  "timestamp": "2026-08-09T17:56:20.167Z"
}
```

## Example request

```bash
curl -X POST 'https://next-api.useplunk.com/v1/track' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"email":"user@example.com","event":"string"}'
```