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

# Send an event

> Post an event from your site or backend to trigger or stop a workflow. Authenticated with an event token. Try it live below.

<Info>
  Authenticated with an **event token** (from **Settings → Event tokens**), not an API key. The event `name` becomes a trigger you can pick when building a playbook. Included with the [Workflows add-on](/add-ons/workflows). Full guide: [Event tokens](/workflows/event-tokens).
</Info>

## Scenarios

An event is anything meaningful that happens on your site. It doesn't have to be a SaaS app. Any website can send one: a form submit, a booked meeting, a purchase, a call. The name you send is the trigger.

<AccordionGroup>
  <Accordion title="They fill out a form or book a demo → stop chasing them">
    Send `form_submitted` (or `demo_booked`) the moment someone converts on your site. It pulls them out of every cold campaign they're in, so you're not still cold-emailing a person who just raised their hand.

    ```json theme={null}
    { "event": "form_submitted", "email": "jane@acme.com", "properties": { "form": "contact" } }
    ```
  </Accordion>

  <Accordion title="They buy → suppress outreach">
    Send `purchase` (or `order_placed`) to stop any active outreach the instant money changes hands.

    ```json theme={null}
    { "event": "purchase", "email": "jane@acme.com", "properties": { "amount": 1200 } }
    ```
  </Accordion>

  <Accordion title="A milestone your site knows about → start a sequence">
    Any event your site or backend tracks works: `quote_requested`, `call_booked`, `signed_up`, a downloaded resource. Send it to start the right follow-up the moment it happens.

    ```json theme={null}
    { "event": "quote_requested", "email": "jane@acme.com", "properties": { "product": "enterprise" } }
    ```
  </Accordion>
</AccordionGroup>

<Info>You can only trigger a playbook on an event you have **already sent** at least once. Send it here, then it appears in the trigger picker when you build a playbook.</Info>

## Notes

* **`email` is the identity key.** It's how Squid ID knows which person the event is about. Use the same email your site knows them by. An event with no email is rejected.
* **One event does both jobs.** It stops any playbook that exits on that event name AND starts any playbook triggered by it, each a no-op unless a playbook opts in.
* **Retention.** Raw events are validated at the edge and purged after 24 hours. What persists is the effect (a playbook started or stopped) and the catalog of event names you've sent.

See the [Event tokens](/workflows/event-tokens) guide for token management and language examples (Node, Python, PHP, Ruby).


## OpenAPI

````yaml openapi.json POST /events
openapi: 3.0.3
info:
  title: Squid ID API (read-only)
  version: 1.0.0
  description: >-
    Read-only API for retrieving an identified visitor by id. Requests go
    through the Squid ID broker and authenticate with your Squid ID API key.
servers:
  - url: https://id-api.asksquid.ai/api
security:
  - BearerAuth: []
paths:
  /events:
    post:
      summary: Send a custom event
      description: >-
        Send an event from your app to trigger (or stop) a workflow.
        Authenticated with an event token (Settings, Event tokens), NOT an API
        key. The event name becomes a trigger you can pick when building a
        playbook.
      operationId: events.ingest
      parameters:
        - $ref: '#/components/parameters/Authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EventRequest'
            examples:
              signup:
                summary: A signup
                value:
                  event: signed_up
                  email: jane@acme.com
                  properties:
                    plan: pro
              trial:
                summary: A trial start
                value:
                  event: trial_started
                  email: jane@acme.com
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
        '401':
          description: Invalid or missing event token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Validation failed (bad event name, missing email, or bad properties)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    Authorization:
      name: Authorization
      in: header
      required: true
      description: 'Your Squid ID API key, format: `Bearer <key>` (keys start with `sqid_`).'
      schema:
        type: string
      example: Bearer sqid_xxxxxxxxxxxxxxxxxxxxxxxx
  schemas:
    EventRequest:
      type: object
      required:
        - event
        - email
      properties:
        event:
          type: string
          description: 'The event name (letters, numbers, _ . : -), up to 64 chars.'
          example: signed_up
        email:
          type: string
          format: email
          description: The person the event is about. The identity key.
          example: jane@acme.com
        properties:
          type: object
          description: Optional context, one level deep. String, number, or boolean values.
          additionalProperties: true
          example:
            plan: pro
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````