Sequenzy Events API

openapi: 3.2.0
info:
  title: Sequenzy Events API
  description: Sequenzy API for managing subscribers, tags, events, sequences, and transactional emails
  version: 1.0.0
servers:
- url: https://api.sequenzy.com/api/v1
  description: Production server
- url: https://api.sequenzy.com/v1
  description: Legacy production server alias
security:
- bearerAuth: []
tags:
- name: Events
  description: Published payload schemas for built-in events
paths:
  /events/sample:
    get:
      operationId: getEventSample
      summary: Get latest received event sample
      description: Requires subscribers:read and company access. Reads the latest retained exact-name event across workspace subscribers, including older history. Trims surrounding whitespace; does not resolve aliases. No additional recent-only cutoff. Equal timestamps have no guaranteed tie order. Copy sample.properties into a sequence test run customVariables object; the test recipient is unchanged. This read has no side effects and can be retried safely.
      tags:
      - Events
      parameters:
      - name: eventName
        in: query
        required: true
        description: Exact recorded event name, including custom names. Must not be blank.
        schema:
          type: string
          minLength: 1
      responses:
        '200':
          description: Latest retained event, or sample null when none exists
          content:
            application/json:
              schema:
                type: object
                required:
                - eventName
                - sample
                properties:
                  eventName:
                    type: string
                  sample:
                    type:
                    - object
                    - 'null'
                    required:
                    - eventTime
                    - subscriberId
                    - properties
                    properties:
                      eventTime:
                        type: string
                        description: UTC event timestamp
                      subscriberId:
                        type: string
                        description: Source subscriber ID; may differ from your test recipient
                      properties:
                        type: object
                        additionalProperties: true
                        description: Recorded payload, preserving nested JSON; may be empty
        '400':
          description: Missing or blank eventName, or missing company selection
        '401':
          description: Missing or invalid authentication
        '403':
          description: Missing subscribers:read scope or company access
        '500':
          description: Analytics lookup failed; safe to retry this read
  /events/schemas:
    get:
      operationId: getEventSchemas
      summary: Get event schemas
      description: Returns the published payload of a built-in event - a real example payload per provider, plus every property path with its type, the merge tag that resolves it, and a description wherever the example alone is ambiguous (a null sample, an empty list, a unit that is not obvious, or a type that differs per provider). Omit eventName to list every documented event. Static reference data describing the shape of an event, not what the account has received. An event with no published payload returns documented false; it is still valid to trigger and to build a sequence on, because custom events carry exactly the properties you send.
      tags:
      - Events
      parameters:
      - name: eventName
        in: query
        required: false
        description: Event to describe, such as ecommerce.order_placed. Legacy aliases like order.completed resolve to their current name. Omit to list every documented event.
        schema:
          type: string
      - name: provider
        in: query
        required: false
        description: 'Return only this provider''s payload: shopify, woocommerce, manual, api, or stripe.'
        schema:
          type: string
          enum:
          - shopify
          - woocommerce
          - manual
          - api
          - stripe
      responses:
        '200':
          description: Event schemas returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  eventName:
                    type:
                    - string
                    - 'null'
                    description: Normalized name of the event described, or null when listing every documented event.
                    example: ecommerce.order_placed
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/EventSchema'
                  note:
                    type: string
                    description: Present in listing mode only.
        '400':
          description: Unknown provider
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          $ref: '#/components/responses/TransientDatabaseUnavailable'
components:
  headers:
    RetryAfter:
      description: Number of seconds to wait before retrying the request.
      schema:
        type: integer
        minimum: 1
        example: 1
  responses:
    TransientDatabaseUnavailable:
      description: The database was temporarily unavailable. The request may be retried after the delay in Retry-After.
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: The service could not reach its database for a moment. Retry the request.
            code: SERVICE_UNAVAILABLE
  schemas:
    EventSchema:
      type: object
      description: The published payload of one event. Listing mode returns the summary fields only; asking for a single eventName adds providers, mergeTagPrefix, and notes.
      properties:
        eventName:
          type: string
          description: Normalized event name - the name to trigger and to configure triggers on.
          example: ecommerce.order_placed
        requestedEventName:
          type: string
          description: The name as asked for, before alias normalization.
        documented:
          type: boolean
          description: Whether a reference payload is published. False never means the event name is invalid - custom events carry exactly the properties you send and are never rejected.
        label:
          type:
          - string
          - 'null'
        category:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        documentedProviders:
          type: array
          description: Providers with a reference payload for this event.
          items:
            type: string
            enum:
            - shopify
            - woocommerce
            - manual
            - api
            - stripe
        providers:
          type: array
          description: Single-event mode only. One entry per provider.
          items:
            type: object
            properties:
              provider:
                type: string
                enum:
                - shopify
                - woocommerce
                - manual
                - api
                - stripe
              examplePayload:
                type: object
                description: A representative sample payload, not a contract.
                additionalProperties: true
              properties:
                type: array
                items:
                  type: object
                  properties:
                    path:
                      type: string
                      description: Dot path into the payload. Object array elements use [], e.g. lineItems[].priceCents.
                    type:
                      type: string
                      description: Human-readable type, e.g. string, string | null, object[].
                    description:
                      type: string
                      description: Present only where the sample value alone is ambiguous.
                    mergeTag:
                      type: string
                      description: Merge tag that resolves this path. Scalar paths only.
        mergeTagPrefix:
          type: string
          example: event.
        notes:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          description: Optional stable machine-readable error discriminator when available.
          example: COMPANY_CREATE_REQUIRES_PERSONAL_KEY
        retryable:
          type: boolean
          description: Whether retrying the request can recover from the error.
        issues:
          type: array
          description: Field-level problems with the request, when the endpoint reports them. Up to ten entries; `error` summarizes the first three.
          items:
            $ref: '#/components/schemas/InputIssue'
      required:
      - error
    InputIssue:
      type: object
      properties:
        path:
          type: string
          description: Dotted field path, such as `audience.subscriberIds[0]`. Empty when the problem is with the request body itself.
          example: kind
        message:
          type: string
          description: What is wrong with the field.
          example: must be "add_tags"
        allowedValues:
          type: array
          description: Accepted values when the field only takes a fixed set of values.
          items: {}
          example:
          - add_tags
      required:
      - path
      - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key passed as Bearer token