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

# Server Events API — POST /server-events

> Send a single authenticated server-side conversion event — purchase, signup, lead, or any backend action — attributed to a QR Code scan.

Use this endpoint to report a single backend conversion event. For sending multiple events in one request, use [POST /server-events/batch](/conversion-tracking/api/events-batch).

Generate the required `X-API-Key` from your tracking site: **Integrations → Conversion Tracking → (select site) → API Keys**.

See [Send Server Events](/conversion-tracking/server/send-events) for code examples in Node.js, Python, PHP, and cURL.


## OpenAPI

````yaml POST /server-events
openapi: 3.1.0
info:
  title: Scanova Conversion Tracking API
  description: Server-side conversion event ingestion API for Scanova tracking sites.
  version: 1.0.0
servers:
  - url: https://track.scanova.io
    description: Production
security: []
tags:
  - name: Server Events
    description: Authenticated server-side conversion/event ingestion
paths:
  /server-events:
    post:
      tags:
        - Server Events
      summary: Send server-side event
      description: >-
        Receives server-side events from customer backends. Requires X-API-Key
        authentication.
      operationId: serverEvent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServerEventRequest'
      responses:
        '200':
          description: Event accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerEventResponse'
        '400':
          description: Invalid request body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Invalid API key or unauthorized site_id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ServerEventRequest:
      type: object
      required:
        - site_id
        - event_name
      properties:
        site_id:
          type: string
          minLength: 1
          maxLength: 64
          description: Tracking site ID
        event_name:
          type: string
          minLength: 1
          maxLength: 64
          description: Event name (normalized to lowercase/underscore by API)
        scan_session_id:
          type: string
          format: uuid
          description: QR scan session id from scnv redirect
        event_id:
          type: string
          format: uuid
          description: Unique event ID for deduplication
        event_time:
          type: string
          format: date-time
          description: Event occurrence time
        user_identifiers:
          $ref: '#/components/schemas/UserIdentifiers'
        conversion_value:
          $ref: '#/components/schemas/ConversionValue'
        properties:
          type: object
          additionalProperties: true
          description: >-
            Custom properties. Max serialized size 10KB. Do not include raw
            email addresses.
        consent:
          type: string
          nullable: true
          enum:
            - granted
            - denied
            - pending
          description: Consent signal propagated from browser-side tracking
      example:
        site_id: site_abc123
        event_name: purchase
        scan_session_id: 550e8400-e29b-41d4-a716-446655440000
        conversion_value:
          amount: 99.99
          currency: USD
        user_identifiers:
          email_hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
          external_id: user_12345
        properties:
          order_id: order_789
          product_ids:
            - prod_1
            - prod_2
    ServerEventResponse:
      type: object
      required:
        - success
        - event_id
        - message
      properties:
        success:
          type: boolean
          example: true
        event_id:
          type: string
          format: uuid
        message:
          type: string
          example: Event received
    ErrorResponse:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: boolean
          example: true
        code:
          type: string
          example: RATE_LIMIT_EXCEEDED
        message:
          type: string
          example: Too many requests. Retry after 60 seconds.
    UserIdentifiers:
      type: object
      properties:
        email_hash:
          type: string
          minLength: 64
          maxLength: 64
          description: SHA-256 hash of normalized lowercase email
        phone_hash:
          type: string
          minLength: 64
          maxLength: 64
          description: SHA-256 hash of normalized E.164 phone number
        external_id:
          type: string
          maxLength: 128
          description: Your internal user ID
    ConversionValue:
      type: object
      required:
        - amount
      properties:
        amount:
          type: number
          minimum: 0
          description: Conversion amount
        currency:
          type: string
          minLength: 3
          maxLength: 3
          default: USD
          description: ISO 4217 currency code
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Site-scoped server API key generated from Dashboard > Integrations >
        Conversion Tracking > Script/API > API tab

````