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

# Create a list

> Creates a new static or dynamic list. Static lists are populated by adding members directly. Dynamic lists are materialised from a rule tree and refreshed when users change.

Idempotent — pass an `Idempotency-Key` header to make safely retryable. On a replay the original response is returned with `Idempotent-Replayed: true`. See the API conventions guide for the full state machine, TTL, and mismatch behaviour.



## OpenAPI

````yaml https://apix.spotzee.com/api/openapi.json post /lists
openapi: 3.1.0
info:
  title: Spotzee API
  version: '2026-04-28'
  description: >-
    Programmatic access to Spotzee. Use this API to manage users, lists,
    segments, campaigns, journeys, templates, and events from your own systems.
  contact:
    name: Spotzee Support
    url: https://docs.spotzee.com
  license:
    name: Proprietary
    url: https://docs.spotzee.com/
servers:
  - url: https://apix.spotzee.com/api
    description: >-
      Public unauthenticated surface — used for form-token submissions and other
      token-scoped callbacks.
  - url: https://apix.spotzee.com/api/client
    description: >-
      Project-scoped surface — use with `sk_` (secret) or `pk_` (publishable)
      API keys.
  - url: https://apix.spotzee.com/api/admin
    description: >-
      Organisation-scoped surface — use with `ok_` API keys for cross-project
      administration.
security: []
tags:
  - name: Projects
    description: >-
      The project the calling key belongs to. Read-only on the project surface —
      use organisation-level keys for project lifecycle.
  - name: Users
    description: >-
      People you message. Identify each one by your own `external_id`; attach
      any custom attributes you want to segment on.
  - name: Events
    description: >-
      Behavioural signals from your application. Drive trigger campaigns and
      journeys, enrich segments, and personalise message content.
  - name: Form submissions
    description: >-
      Token-scoped website form submissions. Use generated form URLs for
      browser-safe opt-ins without exposing secret API keys.
  - name: Lists
    description: >-
      Static and dynamic groups of users. Static lists are explicit memberships;
      dynamic lists evaluate their current membership rule when queried.
  - name: Subscriptions
    description: >-
      Channel-level opt-in state per user. Each subscription type maps to a
      channel (email, push, SMS, webhook, in-app).
  - name: Templates
    description: >-
      Channel-specific message bodies with Handlebars personalisation. Preview,
      proof, and version each template independently.
  - name: Campaigns
    description: >-
      One-off `blast` sends and per-user `trigger` sends. Each campaign targets
      one channel and one subscription type.
  - name: CRM
    description: >-
      Customer relationship records for contacts, companies, pipeline stages,
      activities, and saved views within the calling project.
  - name: Source Sync
    description: >-
      Sync contacts, companies, source-managed CRM properties, and company
      memberships from your own backend systems into the calling project.
  - name: Journeys
    description: >-
      Multi-step automation flows triggered by events, list memberships, or
      campaign sends. Branch on attributes, wait between steps, and send across
      channels.
  - name: Tags
    description: >-
      Free-form labels you can attach to campaigns, journeys, lists, and
      templates for organisation and bulk filtering.
  - name: API keys
    description: >-
      Project-scoped credentials. Create, list, and revoke `sk_` and `pk_` keys
      for the project the calling key belongs to.
  - name: Organisation
    description: >-
      Organisation-scoped operations. Use with `ok_` keys to manage projects
      across an organisation, including the org-level API key catalogue.
  - name: Webhooks
    description: >-
      Outgoing event delivery. Configure HTTPS endpoints, choose events, and
      verify inbound deliveries with the `Spotzee-Signature` HMAC header.
paths:
  /lists:
    post:
      tags:
        - Lists
      summary: Create a list
      description: >-
        Creates a new static or dynamic list. Static lists are populated by
        adding members directly. Dynamic lists are materialised from a rule tree
        and refreshed when users change.


        Idempotent — pass an `Idempotency-Key` header to make safely retryable.
        On a replay the original response is returned with `Idempotent-Replayed:
        true`. See the API conventions guide for the full state machine, TTL,
        and mismatch behaviour.
      operationId: createList
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListCreate'
      responses:
        '200':
          description: The newly created list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '400':
          description: Malformed request — bad parameters, body, or version header.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required or the supplied API key is invalid.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Authenticated, but the credential lacks scope or role for this
            resource.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: >-
            The referenced resource does not exist or is not visible to this
            key.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — duplicate resource or idempotency-key body mismatch.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: >-
            Request was syntactically valid but semantically rejected (failed
            validation).
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate-limit bucket exhausted. Honour `Retry-After`.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unhandled server error. `request_id` should be reported to support.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - projectApiKey: []
      servers:
        - url: https://apix.spotzee.com/api/client
components:
  schemas:
    ListCreate:
      anyOf:
        - $ref: '#/components/schemas/ListCreateDynamic'
        - $ref: '#/components/schemas/ListCreateStatic'
      description: >-
        Create a new list. The `type` discriminator chooses between dynamic
        (rule-driven) and static (manual) membership.
    List:
      type: object
      properties:
        id:
          type: integer
          description: Numeric list identifier.
          example: 91
        project_id:
          type: integer
          description: Identifier of the project the list belongs to.
          example: 42
        name:
          type: string
          description: Human-readable list name.
          example: Newsletter subscribers — Q2 2026
        type:
          type: string
          enum:
            - static
            - dynamic
          description: >-
            A static list has explicit members. A dynamic list is materialised
            from a rule tree.
        state:
          type: string
          enum:
            - draft
            - ready
            - loading
          description: >-
            Current list state. `loading` while a refresh is in progress;
            `ready` once members are materialised.
        rule:
          allOf:
            - $ref: '#/components/schemas/RuleNode'
            - description: Membership rule tree for dynamic lists. Absent on static lists.
        rule_id:
          type:
            - integer
            - 'null'
          description: Internal identifier of the persisted root rule, when present.
        version:
          type: integer
          description: Monotonically incrementing version. Bumped on rule edits.
          example: 3
        users_count:
          type:
            - integer
            - 'null'
          description: Cached size of the list. May lag a few seconds behind reality.
          example: 12584
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Tags applied to the list. Used for organisation and filtering.
        is_visible:
          type: boolean
          description: Whether the list is shown in the in-product UI list directory.
        refreshed_at:
          type:
            - string
            - 'null'
          description: Time the dynamic list was last refreshed.
        created_at:
          type:
            - string
            - 'null'
          description: Time the list was created. ISO 8601.
        updated_at:
          type:
            - string
            - 'null'
          description: Time the list was last modified. ISO 8601.
      required:
        - id
        - project_id
        - name
        - type
        - state
        - version
        - is_visible
        - created_at
        - updated_at
      description: >-
        A static or dynamic group of users. Used to send campaigns and as a
        segment input.
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
          description: Constant marker indicating this payload is an error response.
        code:
          $ref: '#/components/schemas/ErrorCode'
        title:
          type: string
          description: Short, human-readable summary suitable for a heading. en-AU.
          example: Resource missing
        message:
          type: string
          description: Human-readable, en-AU explanation. May include identifiers.
          example: User usr_01HXY7Z9K8M5J2N4P6Q8R0S1T2 was not found in this project.
        error:
          type: string
          description: >-
            Legacy human-readable mirror of `message`. Retained while in-product
            clients migrate; new integrations should read `message`.
        type:
          type: string
          format: uri
          description: Documentation URL for this error class (RFC 7807).
          example: https://docs.spotzee.com/main-api/errors#resource_missing
        request_id:
          type: string
          description: >-
            Server-generated correlation ID. Echoed in the X-Request-ID response
            header.
          example: req_01HXY7Z9K8M5J2N4P6Q8R0S1T2
        param:
          type: string
          description: Name of the offending parameter, when a single field is at fault.
          example: id
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
          description: Field-level errors when multiple parameters fail validation.
      required:
        - status
        - code
        - message
        - error
      description: >-
        Spotzee error envelope (RFC 7807 + Stripe-style extensions). Served as
        `application/problem+json`.
    ListCreateDynamic:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Human-readable list name.
          example: High-value customers
        type:
          type: string
          enum:
            - dynamic
        rule:
          allOf:
            - $ref: '#/components/schemas/RuleNode'
            - description: Membership rule tree. Members are materialised from this rule.
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Tags applied to the list. Used for organisation and filtering.
        is_visible:
          type:
            - boolean
            - 'null'
          description: When true, the list appears in the in-product UI list directory.
      required:
        - name
        - type
        - rule
      description: Create a dynamic list materialised from a rule tree.
    ListCreateStatic:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          description: Human-readable list name.
          example: VIP — manual entries
        type:
          type: string
          enum:
            - static
        tags:
          type:
            - array
            - 'null'
          items:
            type: string
          description: Tags applied to the list. Used for organisation and filtering.
        is_visible:
          type:
            - boolean
            - 'null'
          description: When true, the list appears in the in-product UI list directory.
      required:
        - name
        - type
      description: Create a static list with manually managed membership.
    RuleNode:
      type: object
      description: >-
        Recursive rule tree node. `wrapper` nodes group children with
        `and`/`or`; leaves compare a `path` against a `value`.
      required:
        - uuid
        - type
        - group
        - path
        - operator
      properties:
        id:
          type:
            - number
            - 'null'
          description: >-
            Internal numeric identifier of a persisted rule node. Omit on
            create.
        uuid:
          type: string
          description: >-
            Stable client-supplied UUID for this rule node — preserved across
            edits.
          example: b1f4a2c8-3d9e-4a1b-9b3a-1f0c8d4e2a91
        root_uuid:
          type:
            - string
            - 'null'
          description: UUID of the root wrapper of the rule tree this node belongs to.
        parent_uuid:
          type:
            - string
            - 'null'
          description: UUID of the immediate parent wrapper.
        type:
          $ref: '#/components/schemas/RuleType'
        group:
          $ref: '#/components/schemas/RuleGroup'
        path:
          type: string
          description: Dotted path on the user or event payload. For wrappers, leave empty.
          example: data.country
        operator:
          type: string
          description: >-
            Comparison or logical operator. See RuleOperator for the canonical
            list.
        value:
          description: Right-hand side of a leaf comparison. Omitted on wrapper nodes.
          oneOf:
            - type: string
            - type: number
            - type: boolean
            - type: 'null'
        frequency:
          $ref: '#/components/schemas/RuleFrequency'
        children:
          type:
            - array
            - 'null'
          description: Nested rule nodes — present on `wrapper` types.
          items:
            $ref: '#/components/schemas/RuleNode'
    ErrorCode:
      type: string
      enum:
        - resource_missing
        - resource_already_exists
        - state_conflict
        - archived_user_conflict
        - user_capacity_exhausted
        - parameter_missing
        - parameter_invalid_empty
        - parameter_invalid_format
        - parameter_unknown
        - validation_failed
        - authentication_required
        - permission_denied
        - idempotency_key_mismatch
        - idempotency_key_invalid
        - idempotency_in_progress
        - rate_limited
        - version_unsupported
        - version_required
        - webhook_signature_invalid
        - quota_exceeded
        - service_unavailable
        - internal_error
      description: Stable, machine-readable error code. Safe to switch on; never localised.
      example: resource_missing
    FieldError:
      type: object
      properties:
        param:
          type: string
          description: Dotted path to the offending request field.
          example: email
        code:
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
            - description: Per-field error code.
              example: parameter_invalid_format
        message:
          type: string
          description: Human-readable, English (en-AU) explanation of this field error.
          example: Must be a valid email address.
      required:
        - param
        - code
        - message
    RuleType:
      type: string
      enum:
        - wrapper
        - string
        - number
        - boolean
        - date
        - array
        - shopify_purchase
      description: >-
        Type of value the rule node holds. `wrapper` is a logical group; the
        rest are leaf comparisons.
    RuleGroup:
      type: string
      enum:
        - user
        - event
        - parent
      description: >-
        Where the rule applies — to the user (`user`), an event (`event`), or
        inherited from the parent wrapper.
    RuleFrequency:
      type: object
      properties:
        period:
          $ref: '#/components/schemas/RuleFrequencyPeriod'
        operator:
          type: string
          enum:
            - '='
            - <
            - <=
            - '>'
            - '>='
        count:
          type: number
      required:
        - period
        - operator
        - count
      description: >-
        Required event count and operator over a time period — used by
        event-frequency rules.
    RuleFrequencyPeriod:
      anyOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - rolling
            unit:
              type: string
              enum:
                - hour
                - minute
                - day
                - week
                - month
                - year
            value:
              type: number
          required:
            - type
            - unit
            - value
        - type: object
          properties:
            type:
              type: string
              enum:
                - fixed
            start_date:
              type: string
            end_date:
              type: string
          required:
            - type
            - start_date
      description: >-
        Time window for an event-frequency rule — rolling (relative) or fixed
        (absolute).
  securitySchemes:
    projectApiKey:
      type: http
      scheme: bearer
      description: >-
        Project-scoped secret API key (`sk_…`). Pass in the `Authorization:
        Bearer <key>` header. Grants access to the project the key was issued
        for.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.