> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events reference

> Profound Pixel events, their fields, and usage

## Standard events

Profound Pixel recognizes the following standard events. Each event accepts a set of optional fields. See [Field sets](#field-sets) for what each set accepts.

| Event | When to send it | Field set |
| - | - | - |
| `page_viewed` | A visitor views a page | `contents` |
| `contents_viewed` | A visitor views a product, listing, article, or other content unit | `contents` |
| `items_added` | A visitor adds items to a cart or selection | `contents` |
| `checkout_started` | A visitor begins checkout | `contents` |
| `order_created` | A purchase completes | `contents` |
| `subscription_created` | A paid subscription starts | `plan_enrollment` |
| `trial_started` | A free trial starts | `plan_enrollment` |
| `lead_created` | A visitor submits a lead form or requests contact | `customer_action` |
| `registration_completed` | A visitor finishes account or event registration | `customer_action` |
| `appointment_scheduled` | A visitor books a meeting, demo, or consultation | `customer_action` |

### Field sets

| Field set | Recognized fields |
| - | - |
| `contents` | `amount`, `currency`, `contents[]` |
| `plan_enrollment` | `plan_id`, `amount`, `currency`, `contents[]` |
| `customer_action` | `amount`, `currency` |

<Accordion title="contents set properties">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `amount` | number | no | A whole number in minor units for the given currency (cents for US dollars). For example, \$129.99 = `12999`. Always pair it with `currency` |
  | `currency` | string | yes, if `amount` is present | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD` |
  | `contents[]` | array | no | A list of items involved in the event. Each entry takes `id`, `name`, `content_type`, `quantity` (a whole number), `amount`, and `currency` |

  ```javascript Example event theme={null}
    pfq('track', 'order_created', {
      amount: 12999, currency: 'USD',
      contents: [
        {
          id: 'SKU123',
          name: 'Widget',
          content_type: 'product',
          quantity: 1,
          amount: 12999,
          currency: 'USD'
        }
      ]
    });
  ```
</Accordion>

<Accordion title="plan_enrollment set properties">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `plan_id` | string | no | Your internal plan identifier |
  | `amount` | number | no | A whole number in minor units for the given currency (cents for US dollars). For example, \$129.99 = `12999`. Always pair it with `currency`. |
  | `currency` | string | yes, if `amount` is present | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD` |
  | `contents[]` | array | no | A list of items involved in the event. Each entry takes `id`, `name`, `content_type`, `quantity` (a whole number), `amount`, and `currency` |

  ```javascript Example event theme={null}
    pfq('track', 'subscription_created', {
      plan_id: 'pro-monthly',
      amount: 4900,
      currency: 'USD',
      contents: [
        {
          id: 'pro-monthly',
          name: 'Pro plan, monthly billing',
          content_type: 'plan',
          quantity: 1,
          amount: 4900,
          currency: 'USD'
        }
      ]
    });
  ```
</Accordion>

<Accordion title="customer_action set properties">
  | Property | Type | Required | Description |
  | - | - | - | - |
  | `amount` | number | no | A whole number in minor units for the given currency (cents for US dollars). For example, \$129.99 = `12999`. Always pair it with `currency`. |
  | `currency` | string | yes, if `amount` is present | An [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code, such as `USD`. |

  ```javascript Example event theme={null}
    pfq('track', 'lead_created', {
      amount: 50000,
      currency: 'USD',
      form: 'contact-sales'
    });
  ```
</Accordion>

### Custom properties

Add your own custom properties (such as `order_id` or `product_id`) alongside the recognized fields. Two limits apply: up to 128 properties per event, and up to 64 KiB per request body. An event that exceeds either limit is rejected with a `400` error.

## Custom events

For anything outside the standard set, send a custom event: call `pfq('trackCustom', …)` with any event name and any properties you choose.

```javascript theme={null}
  pfq('trackCustom', 'requested_demo', { plan: 'enterprise' });
```

Maximum length for event names is 128 characters. The suggested naming convention is lowercase letters, numbers, underscores or dashes, and a name that doesn't match a [standard event](#standard-events) name, so your custom events are easy to tell apart in reporting.

<Warning>
  **Never send customers' personal data in events.** This includes emails, phone numbers, names, government IDs, payment data, street addresses, and special-category data, such as health, financial account details, or biometrics. As a safety measure, Profound drops personal data keys and redacts values that look like personal data.
</Warning>

## Tie events to your own user IDs

If you need to match conversions to records in your own systems, make an `identify` call with your internal identifiers after the customer logs in and before any events are sent:

```javascript theme={null}
  pfq('identify', {
    external_user_id: 'u_123',
    external_account_id: 'acct_456'
  });
```

The following fields are accepted:

| Field | Type | Required |
| - | - | - |
| `external_user_id` | string | no |
| `external_account_id` | string | no |

Any other fields are silently ignored.

The pixel holds the IDs in memory until your consent signal allows sending, then attaches them to the events that follow.

<Warning>
  Send internal IDs only, never customers' names, emails, phone numbers, or other identifiers. Personal data in the `identify` fields causes the whole event to be rejected with a `400` error.
</Warning>