openapi: 3.0.0
info:
  title: Introduction
  description: >-
    V1 Public API with account based rate limiting. All requests require API key
    in Authorization header.
  version: 1.0.0
  contact:
    name: iClosed.io Support
    url: https://app.iclosed.io/support
  license:
    name: Proprietary
    url: https://app.iclosed.io/terms
servers:
  - url: https://public.api.iclosed.io
    description: Production
  - url: https://public-dev.api.iclosed.io
    description: >-
      Development (use for local integration tests; published specs avoid
      localhost per lint rules)
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'API key required in Authorization header. Format: `iclosed-<token>`'
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Contact management
  - name: Deals
    description: Deal management
  - name: Events
    description: Event dates and time slots
  - name: Products
    description: Product listing
  - name: Outcomes
    description: Call outcomes
paths:
  /v1/contacts:
    get:
      operationId: getContacts
      summary: Get Contacts
      description: >-
        List contacts for the authenticated account with pagination and filters.
        Query: contactId, userId, statuses, eventIds, search, limit, page,
        timeFrom, timeTo, orderBy, orderColumn, utmKeys, utmValues, tagIds,
        forSetters, setterIds, outcome, assigned, tag, isChatContact.
      tags:
        - Contacts
      parameters:
        - name: userId
          in: query
          schema:
            description: Return only contacts assigned to this user ID.
            type: integer
            minimum: 1
            maximum: 2147483647
          description: Return only contacts assigned to this user ID.
        - name: statuses
          in: query
          schema:
            type: array
            items:
              type: string
              enum:
                - POTENTIAL
                - QUALIFIED
                - DISQUALIFIED
                - STRATEGY_CALL_BOOKED
                - DISCOVERY_CALL_BOOKED
            description: >-
              Comma-separated contact statuses to filter by. Allowed values:
              POTENTIAL, QUALIFIED, DISQUALIFIED, STRATEGY_CALL_BOOKED,
              DISCOVERY_CALL_BOOKED.
          description: >-
            Comma-separated contact statuses to filter by. Allowed values:
            POTENTIAL, QUALIFIED, DISQUALIFIED, STRATEGY_CALL_BOOKED,
            DISCOVERY_CALL_BOOKED.
        - name: eventIds
          in: query
          schema:
            type: array
            items:
              type: integer
              minimum: 1
              maximum: 2147483647
            description: >-
              Comma-separated event IDs to filter by (positive integers only,
              for example 1,2,3).
          description: >-
            Comma-separated event IDs to filter by (positive integers only, for
            example 1,2,3).
        - name: search
          in: query
          schema:
            description: >-
              Case-insensitive single search value matched across firstName,
              lastName, email, and phoneNumber (not comma-separated values).
            type: string
          description: >-
            Case-insensitive single search value matched across firstName,
            lastName, email, and phoneNumber (not comma-separated values).
        - name: limit
          in: query
          schema:
            default: 20
            description: Maximum contacts returned per page (1 to 100). Default is 20.
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum contacts returned per page (1 to 100). Default is 20.
        - name: page
          in: query
          schema:
            default: 0
            description: Zero-based page index for pagination. Default is 0.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index for pagination. Default is 0.
        - name: timeFrom
          in: query
          schema:
            description: >-
              Lower bound for joinedTime filtering, in ISO 8601 date-time
              format.
            type: string
            format: date-time
          description: Lower bound for joinedTime filtering, in ISO 8601 date-time format.
        - name: timeTo
          in: query
          schema:
            description: >-
              Upper bound for joinedTime filtering, in ISO 8601 date-time
              format. Use with timeFrom for ranges.
            type: string
            format: date-time
          description: >-
            Upper bound for joinedTime filtering, in ISO 8601 date-time format.
            Use with timeFrom for ranges.
        - name: orderBy
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: >-
            Sort direction: asc or desc. Required together with orderColumn when
            sorting.
        - name: orderColumn
          in: query
          schema:
            type: string
            enum:
              - id
              - createdAt
              - updatedAt
              - joinedTime
              - firstName
              - lastName
              - email
          description: >-
            Field to sort by: id, createdAt, updatedAt, joinedTime, firstName,
            lastName, or email. Required together with orderBy when sorting.
      responses:
        '200':
          description: Paginated list of contacts
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: number
                      contacts:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Unique contact ID.
                            email:
                              description: Primary email address.
                              type: string
                            firstName:
                              description: Contact first name.
                              type: string
                            lastName:
                              description: Contact last name.
                              type: string
                            status:
                              description: Current contact status.
                              type: string
                            phoneNumber:
                              description: Primary phone number.
                              type: string
                            previewId:
                              description: Public-safe preview identifier for the contact.
                              type: string
                            country:
                              description: ISO country code or null when unset.
                              nullable: true
                              type: string
                            timeZone:
                              description: Time zone associated with the contact.
                              type: string
                            blockedId:
                              nullable: true
                              description: >-
                                Related block record ID, or null when not
                                blocked.
                              type: number
                            createdAt:
                              description: Creation timestamp.
                              type: string
                            secondary_email:
                              description: Secondary email when set.
                              nullable: true
                              type: string
                              format: email
                            secondary_phoneNumber:
                              description: Secondary phone number when set.
                              nullable: true
                              type: string
                            ContactEvents:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: number
                                    description: Event ID associated with the contact.
                                  name:
                                    type: string
                                    description: Event name associated with the contact.
                                required:
                                  - id
                                  - name
                                additionalProperties: false
                            user:
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: User ID of the assigned contact owner.
                                firstName:
                                  type: string
                                  description: Assigned user first name.
                                lastName:
                                  type: string
                                  description: Assigned user last name.
                                email:
                                  type: string
                                  description: Assigned user email address.
                              required:
                                - id
                                - firstName
                                - lastName
                                - email
                              additionalProperties: false
                          required:
                            - id
                            - blockedId
                          additionalProperties: false
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  count: 1
                  contacts:
                    - id: 2
                      email: genevieve@iclosed.io
                      firstName: Genevieve
                      lastName: Duke
                      status: STRATEGY_CALL_BOOKED
                      phoneNumber: '+18054666813'
                      secondary_email: null
                      secondary_phoneNumber: null
                      previewId: contact_xeKmDXhxrxGT
                      blockedId: null
                      country: null
                      timeZone: Asia/Karachi
                      createdAt: 12/10/2025
                      ContactEvents:
                        - id: 2
                          name: Phone Call
                      user:
                        id: 5
                        firstName: Development
                        lastName: ''
                        email: dev@iclosed.io
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    post:
      operationId: createContact
      summary: Create Contact
      description: >-
        Create a new contact or updates an existing contact. Either email or
        phoneNumber is required.
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                firstName:
                  type: string
                  maxLength: 25
                lastName:
                  type: string
                  maxLength: 25
                email:
                  type: string
                  maxLength: 255
                  format: email
                phoneNumber:
                  type: string
                  maxLength: 16
                  description: 'International (E.164) phone: optional + and up to 15 digits.'
                status:
                  type: string
                  enum:
                    - POTENTIAL
                    - QUALIFIED
                    - DISQUALIFIED
                tag:
                  type: string
                  maxLength: 100
                joinedTime:
                  description: >-
                    Date and time when the contact joined, in ISO 8601 format
                    (for example, 2024-01-15T10:00:00.000Z).
                  type: string
                  format: date-time
                linkPrefix:
                  type: string
                  maxLength: 255
                utm:
                  type: string
                  maxLength: 1000
                country:
                  description: >-
                    Two-letter ISO 3166-1 alpha-2 country code (for example, US
                    or GB).
                  type: string
                  maxLength: 2
                timeZone:
                  description: >-
                    IANA time zone identifier (for example, America/New_York,
                    Asia/Karachi, or Etc/UTC).
                  type: string
                  maxLength: 50
                ipAddress:
                  type: string
                  maxLength: 45
                referrerUrl:
                  type: string
                  maxLength: 500
                  format: uri
              additionalProperties: false
            example:
              firstName: Jane
              lastName: Doe
              email: jane.doe@example.com
              phoneNumber: '+15551234567'
              status: POTENTIAL
              tag: lead-2024
              joinedTime: '2024-01-15T10:00:00.000Z'
              linkPrefix: product-demo
              utm: utm_source=google&utm_medium=cpc
              country: US
              timeZone: America/New_York
              ipAddress: 192.168.1.1
              referrerUrl: https://example.com/signup
      responses:
        '201':
          description: Successfully created contact
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      contact:
                        nullable: true
                        description: >-
                          Created or updated contact payload, or null when
                          unavailable.
                        type: object
                        properties:
                          id:
                            type: number
                            description: Unique contact ID.
                          accountId:
                            type: number
                            description: Owning account ID for the contact.
                          userId:
                            nullable: true
                            description: Assigned user ID, or null when unassigned.
                            type: number
                          email:
                            description: Primary email address.
                            type: string
                          firstName:
                            description: Contact first name.
                            type: string
                          lastName:
                            description: Contact last name.
                            type: string
                          status:
                            description: Current contact status.
                            type: string
                          phoneNumber:
                            description: Primary phone number.
                            type: string
                          previewId:
                            description: Public-safe preview identifier for the contact.
                            type: string
                          tagId:
                            description: Associated tag ID when a tag is assigned.
                            type: number
                          blockedByRecaptcha:
                            description: >-
                              Whether the contact was flagged by reCAPTCHA
                              checks.
                            type: boolean
                          joinedTime:
                            description: Date and time when the contact joined.
                            type: string
                          country:
                            description: Country code associated with the contact.
                            type: string
                          timeZone:
                            description: Time zone associated with the contact.
                            type: string
                          blockedId:
                            nullable: true
                            description: Related block record ID, or null when not blocked.
                            type: number
                          referrerUrl:
                            description: Referrer URL where the contact originated.
                            type: string
                          createdAt:
                            description: Creation timestamp.
                            type: string
                          updatedAt:
                            description: Last update timestamp.
                            type: string
                          deletedAt:
                            nullable: true
                            description: Soft-delete timestamp, or null when active.
                            type: string
                        required:
                          - id
                          - accountId
                          - userId
                          - blockedId
                          - deletedAt
                        additionalProperties: false
                    required:
                      - contact
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  contact:
                    id: 139
                    accountId: 4
                    userId: null
                    email: jane.doe.updated@example.com
                    firstName: Jane
                    lastName: Doe
                    status: QUALIFIED
                    phoneNumber: '+15551234567'
                    previewId: contact_BpK9_yC5DFG7
                    tagId: 7
                    blockedByRecaptcha: false
                    joinedTime: '2026-03-04T20:38:06.409Z'
                    country: US
                    timeZone: America/New_York
                    blockedId: null
                    referrerUrl: https://example.com/referral
                    createdAt: '2026-03-04T20:38:06.410Z'
                    updatedAt: '2026-03-05T09:41:22.614Z'
                    deletedAt: null
        '400':
          description: Invalid input or contact already exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: string
                      contact:
                        type: object
                        properties:
                          id:
                            type: number
                            description: Unique contact ID.
                          accountId:
                            type: number
                            description: Owning account ID for the contact.
                          userId:
                            nullable: true
                            description: Assigned user ID, or null when unassigned.
                            type: number
                          email:
                            description: Primary email address.
                            type: string
                          firstName:
                            description: Contact first name.
                            type: string
                          lastName:
                            description: Contact last name.
                            type: string
                          status:
                            description: Current contact status.
                            type: string
                          phoneNumber:
                            description: Primary phone number.
                            type: string
                          previewId:
                            description: Public-safe preview identifier for the contact.
                            type: string
                          tagId:
                            description: Associated tag ID when a tag is assigned.
                            type: number
                          blockedByRecaptcha:
                            description: >-
                              Whether the contact was flagged by reCAPTCHA
                              checks.
                            type: boolean
                          joinedTime:
                            description: Date and time when the contact joined.
                            type: string
                          country:
                            description: Country code associated with the contact.
                            type: string
                          timeZone:
                            description: Time zone associated with the contact.
                            type: string
                          blockedId:
                            nullable: true
                            description: Related block record ID, or null when not blocked.
                            type: number
                          referrerUrl:
                            description: Referrer URL where the contact originated.
                            type: string
                          createdAt:
                            description: Creation timestamp.
                            type: string
                          updatedAt:
                            description: Last update timestamp.
                            type: string
                          deletedAt:
                            nullable: true
                            description: Soft-delete timestamp, or null when active.
                            type: string
                        required:
                          - id
                          - accountId
                          - userId
                          - blockedId
                          - deletedAt
                        additionalProperties: false
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    put:
      operationId: updateContact
      summary: Update Contact
      description: Update an existing contact by id.
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Contact ID to update.
                firstName:
                  description: Updated first name (max 25 chars).
                  type: string
                  maxLength: 25
                lastName:
                  description: Updated last name (max 25 chars).
                  type: string
                  maxLength: 25
                email:
                  description: Updated primary email address.
                  type: string
                  maxLength: 255
                  format: email
                secondary_email:
                  description: Updated secondary email address.
                  type: string
                  maxLength: 255
                  format: email
                phoneNumber:
                  type: string
                  maxLength: 16
                  description: Updated primary phone number in E.164 format.
                secondary_phoneNumber:
                  type: string
                  maxLength: 16
                  description: Updated secondary phone number in E.164 format.
                status:
                  description: Updated contact status.
                  type: string
                  enum:
                    - POTENTIAL
                    - QUALIFIED
                    - DISQUALIFIED
                referrerUrl:
                  description: Updated referrer URL.
                  type: string
                  maxLength: 500
                  format: uri
              required:
                - id
              additionalProperties: false
            example:
              id: 123
              firstName: Jane
              lastName: Doe
              email: jane.doe.updated@example.com
              secondary_email: jane.secondary@example.com
              phoneNumber: '+15559876543'
              secondary_phoneNumber: '+15551112222'
              status: QUALIFIED
              referrerUrl: https://example.com/referral
      responses:
        '200':
          description: Successfully updated contact
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      contact:
                        nullable: true
                        description: >-
                          Created or updated contact payload, or null when
                          unavailable.
                        type: object
                        properties:
                          id:
                            type: number
                            description: Unique contact ID.
                          accountId:
                            type: number
                            description: Owning account ID for the contact.
                          userId:
                            nullable: true
                            description: Assigned user ID, or null when unassigned.
                            type: number
                          email:
                            description: Primary email address.
                            type: string
                          firstName:
                            description: Contact first name.
                            type: string
                          lastName:
                            description: Contact last name.
                            type: string
                          status:
                            description: Current contact status.
                            type: string
                          phoneNumber:
                            description: Primary phone number.
                            type: string
                          previewId:
                            description: Public-safe preview identifier for the contact.
                            type: string
                          tagId:
                            description: Associated tag ID when a tag is assigned.
                            type: number
                          blockedByRecaptcha:
                            description: >-
                              Whether the contact was flagged by reCAPTCHA
                              checks.
                            type: boolean
                          joinedTime:
                            description: Date and time when the contact joined.
                            type: string
                          country:
                            description: Country code associated with the contact.
                            type: string
                          timeZone:
                            description: Time zone associated with the contact.
                            type: string
                          blockedId:
                            nullable: true
                            description: Related block record ID, or null when not blocked.
                            type: number
                          referrerUrl:
                            description: Referrer URL where the contact originated.
                            type: string
                          createdAt:
                            description: Creation timestamp.
                            type: string
                          updatedAt:
                            description: Last update timestamp.
                            type: string
                          deletedAt:
                            nullable: true
                            description: Soft-delete timestamp, or null when active.
                            type: string
                        required:
                          - id
                          - accountId
                          - userId
                          - blockedId
                          - deletedAt
                        additionalProperties: false
                    required:
                      - contact
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  contact:
                    id: 139
                    accountId: 4
                    userId: null
                    email: jane.doe.updated@example.com
                    firstName: Jane
                    lastName: Doe
                    status: QUALIFIED
                    phoneNumber: '+15551234567'
                    previewId: contact_BpK9_yC5DFG7
                    tagId: 7
                    blockedByRecaptcha: false
                    joinedTime: '2026-03-04T20:38:06.409Z'
                    country: US
                    timeZone: America/New_York
                    blockedId: null
                    referrerUrl: https://example.com/referral
                    createdAt: '2026-03-04T20:38:06.410Z'
                    updatedAt: '2026-03-05T09:41:22.614Z'
                    deletedAt: null
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/contacts/detail:
    get:
      operationId: getContactById
      summary: Get contact by ID
      description: >-
        Get a single contact by ID. Query: contactId (required). Stats and
        extended info are always included for this route.
      tags:
        - Contacts
      parameters:
        - name: contactId
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
            description: Contact ID to fetch details for.
          required: true
          description: Contact ID to fetch details for.
      responses:
        '200':
          description: Contact detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Unique contact ID.
                      firstName:
                        type: string
                        description: Contact first name.
                      lastName:
                        type: string
                        description: Contact last name.
                      email:
                        type: string
                        description: Primary contact email address.
                      phoneNumber:
                        description: Primary contact phone number.
                        type: string
                      secondary_email:
                        nullable: true
                        description: Secondary email address, or null when not set.
                        type: string
                      secondary_phoneNumber:
                        nullable: true
                        description: Secondary phone number, or null when not set.
                        type: string
                      status:
                        type: string
                        description: Current contact status.
                      joinedTime:
                        type: string
                        description: Joined timestamp as an ISO 8601 string.
                      createdAt:
                        type: string
                        description: Creation timestamp as an ISO 8601 string.
                      updatedAt:
                        type: string
                        description: Last update timestamp as an ISO 8601 string.
                      referrerUrl:
                        description: >-
                          Referrer URL where the contact originated, when
                          available.
                        type: string
                      previewId:
                        description: Public-safe preview identifier for the contact.
                        type: string
                      timeZone:
                        description: Contact time zone, when available.
                        type: string
                      user:
                        description: Assigned user summary for the contact.
                        nullable: true
                        type: object
                        properties:
                          id:
                            type: number
                            description: User ID of the assigned contact owner.
                          firstName:
                            type: string
                            description: Assigned user first name.
                          lastName:
                            type: string
                            description: Assigned user last name.
                          email:
                            type: string
                            description: Assigned user email address.
                        required:
                          - id
                          - firstName
                          - lastName
                          - email
                        additionalProperties: false
                      ContactEvents:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Event ID associated with the contact.
                            name:
                              type: string
                              description: Event name associated with the contact.
                            location:
                              type: string
                              description: Event location type or location label.
                            color:
                              type: string
                              description: Event color value used for display.
                          required:
                            - id
                            - name
                            - location
                            - color
                          additionalProperties: false
                        description: Events associated with the contact.
                      ContactStats:
                        nullable: true
                        description: >-
                          Aggregated contact statistics, or null when
                          unavailable.
                        type: object
                        properties:
                          initialStatus:
                            type: string
                            enum:
                              - POTENTIAL
                              - QUALIFIED
                              - DISQUALIFIED
                              - STRATEGY_CALL_BOOKED
                              - DISCOVERY_CALL_BOOKED
                            description: First recorded contact status.
                          statusUpdatedAt:
                            type: string
                            description: Timestamp of the latest status update.
                          lastInteractionStatus:
                            type: string
                            description: Status associated with the latest interaction.
                          lastInteractionType:
                            type: string
                            description: Type of the latest interaction.
                          totalCallsBooked:
                            type: number
                            description: Total number of booked calls.
                          strategyCallsBooked:
                            type: number
                            description: Number of booked strategy calls.
                          discoveryCallsBooked:
                            type: number
                            description: Number of booked discovery calls.
                          income:
                            type: number
                            description: Income amount attributed to the contact.
                        required:
                          - initialStatus
                          - statusUpdatedAt
                          - lastInteractionStatus
                          - lastInteractionType
                          - totalCallsBooked
                          - strategyCallsBooked
                          - discoveryCallsBooked
                          - income
                        additionalProperties: false
                      pastCallsCount:
                        type: number
                        description: Number of past calls linked to this contact.
                      upcomingCallsCount:
                        type: number
                        description: Number of upcoming calls linked to this contact.
                      CustomFieldAssociation:
                        type: array
                        items:
                          type: object
                          properties:
                            customField:
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Custom field ID.
                                name:
                                  type: string
                                  description: Custom field display name.
                                type:
                                  type: string
                                  description: Custom field object type/category.
                                inputType:
                                  type: string
                                  enum:
                                    - NUMBER
                                    - TEXT
                                    - TEXT_AREA
                                    - DATE
                                    - CHECK_BOX
                                    - RADIO_BUTTON
                                    - CONTACT
                                    - CONTACTS_MULTIPLE
                                    - USER
                                    - USERS_MULTIPLE
                                    - URL
                                    - SINGLE_SELECT
                                    - MULTIPLE_SELECT
                                    - EMAIL
                                    - RATING
                                  description: Configured input type for this custom field.
                                identifier:
                                  type: string
                                  description: Stable custom field identifier key.
                              required:
                                - id
                                - name
                                - type
                                - inputType
                                - identifier
                              additionalProperties: false
                            CustomFieldAnswer:
                              type: array
                              items:
                                type: object
                                properties:
                                  inputType:
                                    type: string
                                    enum:
                                      - NUMBER
                                      - TEXT
                                      - TEXT_AREA
                                      - DATE
                                      - CHECK_BOX
                                      - RADIO_BUTTON
                                      - CONTACT
                                      - CONTACTS_MULTIPLE
                                      - USER
                                      - USERS_MULTIPLE
                                      - URL
                                      - SINGLE_SELECT
                                      - MULTIPLE_SELECT
                                      - EMAIL
                                      - RATING
                                    description: >-
                                      Input type that determines which answer
                                      value field is used.
                                  answer:
                                    nullable: true
                                    description: >-
                                      String answer payload when applicable to
                                      the input type.
                                    type: string
                                  date:
                                    nullable: true
                                    description: >-
                                      Date answer payload when applicable to the
                                      input type.
                                    type: string
                                  number:
                                    nullable: true
                                    description: >-
                                      Numeric answer payload when applicable to
                                      the input type.
                                    type: number
                                  customFieldOptionId:
                                    nullable: true
                                    description: >-
                                      Selected custom-field option ID for
                                      select-like input types.
                                    type: number
                                  user:
                                    description: Referenced user for USER-type answers.
                                    nullable: true
                                    type: object
                                    properties:
                                      id:
                                        type: number
                                        description: User ID of the assigned contact owner.
                                      firstName:
                                        type: string
                                        description: Assigned user first name.
                                      lastName:
                                        type: string
                                        description: Assigned user last name.
                                    required:
                                      - id
                                      - firstName
                                      - lastName
                                    additionalProperties: false
                                required:
                                  - inputType
                                  - answer
                                  - date
                                  - number
                                  - customFieldOptionId
                                additionalProperties: false
                              description: >-
                                Answer rows stored for this custom field on the
                                contact.
                          required:
                            - customField
                            - CustomFieldAnswer
                          additionalProperties: false
                        description: >-
                          Answered custom fields for this contact only.
                          Unanswered fields are not returned. For
                          MULTIPLE_SELECT and similar types, a field can contain
                          multiple answers (for example, different
                          customFieldOptionId values). To render all available
                          fields, fetch CONTACT custom-field definitions and
                          merge by custom field id or identifier.
                    required:
                      - id
                      - firstName
                      - lastName
                      - email
                      - secondary_email
                      - secondary_phoneNumber
                      - status
                      - joinedTime
                      - createdAt
                      - updatedAt
                      - ContactEvents
                      - pastCallsCount
                      - upcomingCallsCount
                      - CustomFieldAssociation
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  id: 2
                  firstName: Genevieve
                  lastName: Duke
                  email: genevieve@iclosed.io
                  phoneNumber: '+18054666813'
                  secondary_email: null
                  secondary_phoneNumber: null
                  status: STRATEGY_CALL_BOOKED
                  joinedTime: '2025-12-10T10:08:28.566Z'
                  createdAt: '2025-12-10T10:08:28.568Z'
                  updatedAt: '2025-12-26T11:44:32.799Z'
                  referrerUrl: https://app.iclosed.io/e/example/phone-call
                  previewId: contact_xeKmDXhxrxGT
                  timeZone: Asia/Karachi
                  user:
                    id: 5
                    firstName: Development
                    lastName: ''
                    email: dev@iclosed.io
                  ContactEvents:
                    - id: 2
                      name: Phone Call
                      location: PHONE_CALL
                      color: '#0099FF'
                  ContactStats:
                    initialStatus: QUALIFIED
                    statusUpdatedAt: '2025-12-26T11:44:32.796Z'
                    lastInteractionStatus: NEW_CONTACT_NOTE
                    lastInteractionType: NEW_CONTACT_NOTE
                    totalCallsBooked: 3
                    strategyCallsBooked: 3
                    discoveryCallsBooked: 0
                    income: 223
                  pastCallsCount: 3
                  upcomingCallsCount: 0
                  CustomFieldAssociation:
                    - customField:
                        id: 248
                        name: Set by
                        type: CALL
                        inputType: USER
                        identifier: set_by
                      CustomFieldAnswer:
                        - inputType: USER
                          answer: null
                          date: null
                          number: null
                          customFieldOptionId: null
                          user:
                            id: 5
                            firstName: Development
                            lastName: ''
                    - customField:
                        id: 11
                        name: Number
                        type: CONTACT
                        inputType: NUMBER
                        identifier: number-1
                      CustomFieldAnswer:
                        - inputType: NUMBER
                          answer: null
                          date: null
                          number: 3434
                          customFieldOptionId: null
                          user: null
                    - customField:
                        id: 243
                        name: Objection
                        type: CALL
                        inputType: SINGLE_SELECT
                        identifier: objection
                      CustomFieldAnswer:
                        - inputType: SINGLE_SELECT
                          answer: MONEY
                          date: null
                          number: null
                          customFieldOptionId: 283
                          user: null
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/contacts/notes:
    get:
      operationId: getContactNotes
      summary: Get contact notes
      description: >-
        List notes for a contact (paginated). Query: contactId (required),
        limit, page, userId (optional).
      tags:
        - Contacts
      parameters:
        - name: contactId
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 2147483647
            description: Contact ID whose notes should be returned.
          required: true
          description: Contact ID whose notes should be returned.
        - name: limit
          in: query
          schema:
            default: 20
            description: Maximum notes returned per page. Default is 20.
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum notes returned per page. Default is 20.
        - name: page
          in: query
          schema:
            default: 0
            description: Zero-based page index for pagination. Default is 0.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index for pagination. Default is 0.
      responses:
        '200':
          description: Paginated list of contact notes with count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                    description: Total number of notes available for the contact.
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: Note ID.
                        text:
                          description: Note text content.
                          nullable: true
                          type: string
                        createdAt:
                          description: Note creation timestamp.
                          anyOf:
                            - type: string
                            - type: string
                              format: date-time
                        updatedAt:
                          description: Note last update timestamp.
                          anyOf:
                            - type: string
                            - type: string
                              format: date-time
                        type:
                          description: Note type/category when provided by the backend.
                          nullable: true
                          type: string
                        user:
                          description: Author summary for the note.
                          nullable: true
                          type: object
                          properties:
                            firstName:
                              description: Author first name.
                              nullable: true
                              type: string
                            lastName:
                              description: Author last name.
                              nullable: true
                              type: string
                          additionalProperties: false
                      required:
                        - id
                      additionalProperties: false
                    description: Paginated list of note records for the requested page.
                required:
                  - count
                  - data
                additionalProperties: false
              example:
                count: 2
                data:
                  - id: 101
                    text: Follow-up call scheduled for next week.
                    createdAt: '2026-04-01T10:00:00.000Z'
                    updatedAt: '2026-04-01T10:00:00.000Z'
                    type: NOTE
                    user:
                      firstName: Development
                      lastName: ''
                  - id: 102
                    text: Sent pricing deck.
                    createdAt: '2026-04-02T14:30:00.000Z'
                    updatedAt: '2026-04-02T14:30:00.000Z'
                    type: NOTE
                    user:
                      firstName: Development
                      lastName: ''
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    post:
      operationId: createContactNote
      summary: Create contact note
      description: 'Create a note for a contact. Required: contactId, note.'
      tags:
        - Contacts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contactId:
                  type: integer
                  minimum: 1
                  maximum: 2147483647
                  description: Contact ID. The contact to attach the note to.
                note:
                  type: string
                  minLength: 1
                  maxLength: 10000
                  description: Note body content. Supports plain text or HTML.
              required:
                - contactId
                - note
              additionalProperties: false
            example:
              contactId: 2
              note: Follow-up call scheduled for next week.
      responses:
        '201':
          description: Contact note created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Human-readable result message from the server.
                    type: string
                  status:
                    description: Numeric HTTP status code (for example, 201).
                    type: number
                additionalProperties: false
              example:
                message: Note created successfully
                status: 201
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/fields:
    post:
      operationId: createCustomField
      summary: Create a field
      description: >-
        Create a new custom field. Body: name (required), inputType (required),
        type (required), and optional identifier, description, configuration,
        options (array of option objects).
      tags:
        - Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 50
                  description: Custom field display name.
                identifier:
                  description: Optional unique identifier for API-based lookup.
                  type: string
                  maxLength: 1000
                description:
                  description: Optional field description text.
                  type: string
                  maxLength: 150
                inputType:
                  type: string
                  enum:
                    - NUMBER
                    - TEXT
                    - TEXT_AREA
                    - DATE
                    - CHECK_BOX
                    - RADIO_BUTTON
                    - USER
                    - USERS_MULTIPLE
                    - URL
                    - SINGLE_SELECT
                    - MULTIPLE_SELECT
                    - EMAIL
                    - RATING
                  description: Input type for value capture and validation.
                type:
                  type: string
                  enum:
                    - CONTACT
                    - CALL
                    - EVENT
                    - DEAL
                    - USER
                    - ISCORE
                  description: Object type this field is attached to.
                configuration:
                  description: Optional input-type-specific configuration object.
                  anyOf:
                    - type: object
                      properties:
                        dateTimeFormat:
                          type: string
                          enum:
                            - 12Hour
                            - 24Hour
                          description: >-
                            Time format: "12Hour" or "24Hour". Required when
                            includedTime is true.
                        dateType:
                          type: string
                          enum:
                            - US
                            - EU
                            - ISO
                            - FRIENDLY
                          description: >-
                            Date display format: "US", "EU", "ISO", or
                            "FRIENDLY".
                        includedTime:
                          type: boolean
                          enum:
                            - true
                          description: When true, time is shown and dateTimeFormat applies.
                      required:
                        - dateTimeFormat
                        - dateType
                        - includedTime
                      additionalProperties: false
                      description: Date field configuration when time is selected.
                      nullable: true
                    - type: object
                      properties:
                        dateType:
                          type: string
                          enum:
                            - US
                            - EU
                            - ISO
                            - FRIENDLY
                          description: >-
                            Date display format: "US", "EU", "ISO", or
                            "FRIENDLY".
                        includedTime:
                          type: boolean
                          enum:
                            - false
                          description: When false, only date is shown; no dateTimeFormat.
                      required:
                        - dateType
                        - includedTime
                      additionalProperties: false
                      description: Date field configuration when time is not selected.
                      nullable: true
                    - type: object
                      properties:
                        isColorCodeOptions:
                          type: boolean
                          description: >-
                            True if options have colors; false if colors are not
                            selected for options.
                      required:
                        - isColorCodeOptions
                      additionalProperties: false
                      description: Single Select or Multi Select field configuration.
                      nullable: true
                    - type: object
                      properties:
                        isMultipleUsers:
                          type: boolean
                          description: >-
                            True to allow multiple users; false for single user
                            selection.
                      required:
                        - isMultipleUsers
                      additionalProperties: false
                      description: User field configuration.
                      nullable: true
                    - type: object
                      properties:
                        maxRating:
                          type: string
                          description: Maximum rating value as string (e.g. "3").
                        ratingStyle:
                          type: string
                          enum:
                            - STAR
                          description: Display style for the rating (e.g. "STAR").
                      required:
                        - maxRating
                        - ratingStyle
                      additionalProperties: false
                      description: Rating field configuration.
                      nullable: true
                    - type: object
                      properties:
                        showMaxValue:
                          type: boolean
                          description: Whether to show the maximum value.
                      required:
                        - showMaxValue
                      additionalProperties: false
                      description: Number field configuration.
                      nullable: true
                options:
                  description: >-
                    Selectable options for select-like input types (name, color
                    enum, displayIndex only).
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 50
                        description: Option display label.
                      color:
                        nullable: true
                        description: >-
                          Semantic color token, or null when the option has no
                          color.
                        type: string
                        enum:
                          - blue
                          - indigo
                          - purple
                          - green
                          - yellow
                          - red
                          - pink
                          - gray
                      displayIndex:
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                        description: Ordering index for option display.
                    required:
                      - name
                      - color
                      - displayIndex
                    additionalProperties: false
                    description: Custom field option for create/update requests.
                isSecondaryQuestion:
                  description: >-
                    Marks field as a secondary question in invitee flow i.e.
                    Invitee Question. If true and type is CALL then the field
                    will be created as invitee question else the type will be
                    the type in payload i.e. CONTACT or CALL
                  type: boolean
              required:
                - name
                - inputType
                - type
              additionalProperties: false
              example:
                name: Lead source
                identifier: lead-source
                description: Where the lead originated
                inputType: SINGLE_SELECT
                type: CONTACT
                configuration:
                  isColorCodeOptions: true
                options:
                  - name: Inbound
                    color: blue
                    displayIndex: 0
                  - name: Outbound
                    color: gray
                    displayIndex: 1
            example:
              name: Lead source
              identifier: lead-source
              description: Where the lead originated
              inputType: SINGLE_SELECT
              type: CONTACT
              configuration:
                isColorCodeOptions: true
              options:
                - name: Inbound
                  color: blue
                  displayIndex: 0
                - name: Outbound
                  color: gray
                  displayIndex: 1
      responses:
        '201':
          description: Custom field created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Operation result message.
                    type: string
                  status:
                    description: HTTP-like status code from API layer.
                    type: number
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Custom field ID.
                      associationCount:
                        description: Number of linked associations/answers.
                        nullable: true
                        type: number
                      name:
                        description: Custom field display name.
                        nullable: true
                        type: string
                      identifier:
                        description: Programmatic identifier for this field.
                        nullable: true
                        type: string
                      description:
                        description: Field description text.
                        nullable: true
                        type: string
                      inputType:
                        type: string
                        enum:
                          - NUMBER
                          - TEXT
                          - TEXT_AREA
                          - DATE
                          - CHECK_BOX
                          - RADIO_BUTTON
                          - USER
                          - USERS_MULTIPLE
                          - URL
                          - SINGLE_SELECT
                          - MULTIPLE_SELECT
                          - EMAIL
                          - RATING
                        description: Configured input type.
                      type:
                        type: string
                        enum:
                          - CONTACT
                          - CALL
                          - EVENT
                          - DEAL
                          - USER
                          - ISCORE
                        description: Object type this field belongs to.
                      subType:
                        description: Optional subtype metadata from service/DB.
                        nullable: true
                        type: string
                      isSecondaryQuestion:
                        description: >-
                          Whether field is marked as invitee secondary question.
                          If true and type is CALL then the field will be
                          created as invitee question else the type will be the
                          type in payload i.e. CONTACT or CALL
                        nullable: true
                        type: boolean
                      isSystemField:
                        description: Whether field is system-defined.
                        nullable: true
                        type: boolean
                      hidden:
                        description: Whether field is hidden.
                        nullable: true
                        type: boolean
                      configuration:
                        description: Type-specific configuration returned with the field.
                        anyOf:
                          - type: object
                            properties:
                              dateTimeFormat:
                                type: string
                                enum:
                                  - 12Hour
                                  - 24Hour
                                description: >-
                                  Time format: "12Hour" or "24Hour". Required
                                  when includedTime is true.
                              dateType:
                                type: string
                                enum:
                                  - US
                                  - EU
                                  - ISO
                                  - FRIENDLY
                                description: >-
                                  Date display format: "US", "EU", "ISO", or
                                  "FRIENDLY".
                              includedTime:
                                type: boolean
                                enum:
                                  - true
                                description: >-
                                  When true, time is shown and dateTimeFormat
                                  applies.
                            required:
                              - dateTimeFormat
                              - dateType
                              - includedTime
                            additionalProperties: false
                            description: Date field configuration when time is selected.
                            nullable: true
                          - type: object
                            properties:
                              dateType:
                                type: string
                                enum:
                                  - US
                                  - EU
                                  - ISO
                                  - FRIENDLY
                                description: >-
                                  Date display format: "US", "EU", "ISO", or
                                  "FRIENDLY".
                              includedTime:
                                type: boolean
                                enum:
                                  - false
                                description: >-
                                  When false, only date is shown; no
                                  dateTimeFormat.
                            required:
                              - dateType
                              - includedTime
                            additionalProperties: false
                            description: >-
                              Date field configuration when time is not
                              selected.
                            nullable: true
                          - type: object
                            properties:
                              isColorCodeOptions:
                                type: boolean
                                description: >-
                                  True if options have colors; false if colors
                                  are not selected for options.
                            required:
                              - isColorCodeOptions
                            additionalProperties: false
                            description: Single Select or Multi Select field configuration.
                            nullable: true
                          - type: object
                            properties:
                              isMultipleUsers:
                                type: boolean
                                description: >-
                                  True to allow multiple users; false for single
                                  user selection.
                            required:
                              - isMultipleUsers
                            additionalProperties: false
                            description: User field configuration.
                            nullable: true
                          - type: object
                            properties:
                              maxRating:
                                type: string
                                description: Maximum rating value as string (e.g. "3").
                              ratingStyle:
                                type: string
                                enum:
                                  - STAR
                                description: Display style for the rating (e.g. "STAR").
                            required:
                              - maxRating
                              - ratingStyle
                            additionalProperties: false
                            description: Rating field configuration.
                            nullable: true
                          - type: object
                            properties:
                              showMaxValue:
                                type: boolean
                                description: Whether to show the maximum value.
                            required:
                              - showMaxValue
                            additionalProperties: false
                            description: Number field configuration.
                            nullable: true
                      createdAt:
                        anyOf:
                          - type: string
                            format: date-time
                          - type: string
                        description: Field creation timestamp.
                      updatedAt:
                        anyOf:
                          - type: string
                            format: date-time
                          - type: string
                        description: Field last update timestamp.
                      CustomFieldOptions:
                        default: []
                        description: Field options returned by create/update response.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Option ID.
                            color:
                              description: Option color value.
                              nullable: true
                              type: string
                            name:
                              description: Option label text.
                              nullable: true
                              type: string
                            displayIndex:
                              description: Option ordering index.
                              nullable: true
                              type: number
                            isArchived:
                              description: Whether option is archived.
                              nullable: true
                              type: boolean
                            createdAt:
                              anyOf:
                                - type: string
                                  format: date-time
                                - type: string
                              description: Option creation timestamp.
                            updatedAt:
                              anyOf:
                                - type: string
                                  format: date-time
                                - type: string
                              description: Option last update timestamp.
                          required:
                            - id
                            - createdAt
                            - updatedAt
                          additionalProperties: false
                    required:
                      - id
                      - inputType
                      - type
                      - createdAt
                      - updatedAt
                      - CustomFieldOptions
                    additionalProperties: false
                    description: Created custom field payload.
                required:
                  - data
                additionalProperties: false
              example:
                message: Custom Fields created successfully
                status: 201
                data:
                  id: 20660
                  associationCount: 0
                  name: mult select
                  identifier: mult-select
                  description: ''
                  inputType: MULTIPLE_SELECT
                  type: CONTACT
                  subType: null
                  isSecondaryQuestion: false
                  isSystemField: false
                  hidden: false
                  configuration:
                    isColorCodeOptions: true
                  createdAt: '2026-03-05T10:00:17.711Z'
                  updatedAt: '2026-03-05T10:00:17.711Z'
                  CustomFieldOptions:
                    - id: 90157
                      color: blue
                      name: '1'
                      displayIndex: 0
                      isArchived: false
                      createdAt: '2026-03-05T10:00:17.792Z'
                      updatedAt: '2026-03-05T10:00:17.792Z'
                    - id: 90158
                      color: blue
                      name: '2'
                      displayIndex: 1
                      isArchived: false
                      createdAt: '2026-03-05T10:00:17.830Z'
                      updatedAt: '2026-03-05T10:00:17.830Z'
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    put:
      operationId: updateCustomField
      summary: Update a field
      description: >-
        Update an existing custom field. Body: id (required), and optional name,
        identifier, description, inputType, type, configuration, options (array
        of option objects), hidden.
      tags:
        - Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  minimum: 1
                  maximum: 2147483647
                  description: Custom field ID to update.
                name:
                  description: Updated display name.
                  type: string
                  maxLength: 50
                identifier:
                  description: Updated programmatic identifier.
                  type: string
                  maxLength: 1000
                description:
                  description: Updated description text.
                  type: string
                  maxLength: 150
                configuration:
                  description: Updated type-specific configuration object.
                  anyOf:
                    - type: object
                      properties:
                        dateTimeFormat:
                          type: string
                          enum:
                            - 12Hour
                            - 24Hour
                          description: >-
                            Time format: "12Hour" or "24Hour". Required when
                            includedTime is true.
                        dateType:
                          type: string
                          enum:
                            - US
                            - EU
                            - ISO
                            - FRIENDLY
                          description: >-
                            Date display format: "US", "EU", "ISO", or
                            "FRIENDLY".
                        includedTime:
                          type: boolean
                          enum:
                            - true
                          description: When true, time is shown and dateTimeFormat applies.
                      required:
                        - dateTimeFormat
                        - dateType
                        - includedTime
                      additionalProperties: false
                      description: Date field configuration when time is selected.
                      nullable: true
                    - type: object
                      properties:
                        dateType:
                          type: string
                          enum:
                            - US
                            - EU
                            - ISO
                            - FRIENDLY
                          description: >-
                            Date display format: "US", "EU", "ISO", or
                            "FRIENDLY".
                        includedTime:
                          type: boolean
                          enum:
                            - false
                          description: When false, only date is shown; no dateTimeFormat.
                      required:
                        - dateType
                        - includedTime
                      additionalProperties: false
                      description: Date field configuration when time is not selected.
                      nullable: true
                    - type: object
                      properties:
                        isColorCodeOptions:
                          type: boolean
                          description: >-
                            True if options have colors; false if colors are not
                            selected for options.
                      required:
                        - isColorCodeOptions
                      additionalProperties: false
                      description: Single Select or Multi Select field configuration.
                      nullable: true
                    - type: object
                      properties:
                        isMultipleUsers:
                          type: boolean
                          description: >-
                            True to allow multiple users; false for single user
                            selection.
                      required:
                        - isMultipleUsers
                      additionalProperties: false
                      description: User field configuration.
                      nullable: true
                    - type: object
                      properties:
                        maxRating:
                          type: string
                          description: Maximum rating value as string (e.g. "3").
                        ratingStyle:
                          type: string
                          enum:
                            - STAR
                          description: Display style for the rating (e.g. "STAR").
                      required:
                        - maxRating
                        - ratingStyle
                      additionalProperties: false
                      description: Rating field configuration.
                      nullable: true
                    - type: object
                      properties:
                        showMaxValue:
                          type: boolean
                          description: Whether to show the maximum value.
                      required:
                        - showMaxValue
                      additionalProperties: false
                      description: Number field configuration.
                      nullable: true
                options:
                  description: >-
                    Updated option list for select-like types (name, color enum,
                    displayIndex only).
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                        maxLength: 50
                        description: Option display label.
                      color:
                        nullable: true
                        description: >-
                          Semantic color token, or null when the option has no
                          color.
                        type: string
                        enum:
                          - blue
                          - indigo
                          - purple
                          - green
                          - yellow
                          - red
                          - pink
                          - gray
                      displayIndex:
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                        description: Ordering index for option display.
                    required:
                      - name
                      - color
                      - displayIndex
                    additionalProperties: false
                    description: Custom field option for create/update requests.
                hidden:
                  description: Updated hidden flag.
                  type: boolean
                isSecondaryQuestion:
                  description: Updated secondary-question flag for invitee flow.
                  type: boolean
              required:
                - id
              additionalProperties: false
              example:
                id: 20660
                name: Lead source
                identifier: lead-source
                description: Where the lead originated
                configuration:
                  isColorCodeOptions: true
                options:
                  - name: Inbound
                    color: blue
                    displayIndex: 0
                  - name: Outbound
                    color: gray
                    displayIndex: 1
                hidden: false
            example:
              id: 20660
              name: Lead source
              identifier: lead-source
              description: Where the lead originated
              configuration:
                isColorCodeOptions: true
              options:
                - name: Inbound
                  color: blue
                  displayIndex: 0
                - name: Outbound
                  color: gray
                  displayIndex: 1
              hidden: false
      responses:
        '200':
          description: Custom field updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Operation result message.
                    type: string
                  status:
                    description: HTTP-like status code from API layer.
                    type: number
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Custom field ID.
                      associationCount:
                        description: Number of linked associations/answers.
                        nullable: true
                        type: number
                      name:
                        description: Custom field display name.
                        nullable: true
                        type: string
                      identifier:
                        description: Programmatic identifier for this field.
                        nullable: true
                        type: string
                      description:
                        description: Field description text.
                        nullable: true
                        type: string
                      inputType:
                        type: string
                        enum:
                          - NUMBER
                          - TEXT
                          - TEXT_AREA
                          - DATE
                          - CHECK_BOX
                          - RADIO_BUTTON
                          - USER
                          - USERS_MULTIPLE
                          - URL
                          - SINGLE_SELECT
                          - MULTIPLE_SELECT
                          - EMAIL
                          - RATING
                        description: Configured input type.
                      type:
                        type: string
                        enum:
                          - CONTACT
                          - CALL
                          - EVENT
                          - DEAL
                          - USER
                          - ISCORE
                        description: Object type this field belongs to.
                      subType:
                        description: Optional subtype metadata from service/DB.
                        nullable: true
                        type: string
                      isSecondaryQuestion:
                        description: >-
                          Whether field is marked as invitee secondary question.
                          If true and type is CALL then the field will be
                          created as invitee question else the type will be the
                          type in payload i.e. CONTACT or CALL
                        nullable: true
                        type: boolean
                      isSystemField:
                        description: Whether field is system-defined.
                        nullable: true
                        type: boolean
                      hidden:
                        description: Whether field is hidden.
                        nullable: true
                        type: boolean
                      configuration:
                        description: Type-specific configuration returned with the field.
                        anyOf:
                          - type: object
                            properties:
                              dateTimeFormat:
                                type: string
                                enum:
                                  - 12Hour
                                  - 24Hour
                                description: >-
                                  Time format: "12Hour" or "24Hour". Required
                                  when includedTime is true.
                              dateType:
                                type: string
                                enum:
                                  - US
                                  - EU
                                  - ISO
                                  - FRIENDLY
                                description: >-
                                  Date display format: "US", "EU", "ISO", or
                                  "FRIENDLY".
                              includedTime:
                                type: boolean
                                enum:
                                  - true
                                description: >-
                                  When true, time is shown and dateTimeFormat
                                  applies.
                            required:
                              - dateTimeFormat
                              - dateType
                              - includedTime
                            additionalProperties: false
                            description: Date field configuration when time is selected.
                            nullable: true
                          - type: object
                            properties:
                              dateType:
                                type: string
                                enum:
                                  - US
                                  - EU
                                  - ISO
                                  - FRIENDLY
                                description: >-
                                  Date display format: "US", "EU", "ISO", or
                                  "FRIENDLY".
                              includedTime:
                                type: boolean
                                enum:
                                  - false
                                description: >-
                                  When false, only date is shown; no
                                  dateTimeFormat.
                            required:
                              - dateType
                              - includedTime
                            additionalProperties: false
                            description: >-
                              Date field configuration when time is not
                              selected.
                            nullable: true
                          - type: object
                            properties:
                              isColorCodeOptions:
                                type: boolean
                                description: >-
                                  True if options have colors; false if colors
                                  are not selected for options.
                            required:
                              - isColorCodeOptions
                            additionalProperties: false
                            description: Single Select or Multi Select field configuration.
                            nullable: true
                          - type: object
                            properties:
                              isMultipleUsers:
                                type: boolean
                                description: >-
                                  True to allow multiple users; false for single
                                  user selection.
                            required:
                              - isMultipleUsers
                            additionalProperties: false
                            description: User field configuration.
                            nullable: true
                          - type: object
                            properties:
                              maxRating:
                                type: string
                                description: Maximum rating value as string (e.g. "3").
                              ratingStyle:
                                type: string
                                enum:
                                  - STAR
                                description: Display style for the rating (e.g. "STAR").
                            required:
                              - maxRating
                              - ratingStyle
                            additionalProperties: false
                            description: Rating field configuration.
                            nullable: true
                          - type: object
                            properties:
                              showMaxValue:
                                type: boolean
                                description: Whether to show the maximum value.
                            required:
                              - showMaxValue
                            additionalProperties: false
                            description: Number field configuration.
                            nullable: true
                      createdAt:
                        anyOf:
                          - type: string
                            format: date-time
                          - type: string
                        description: Field creation timestamp.
                      updatedAt:
                        anyOf:
                          - type: string
                            format: date-time
                          - type: string
                        description: Field last update timestamp.
                      CustomFieldOptions:
                        default: []
                        description: Field options returned by create/update response.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Option ID.
                            color:
                              description: Option color value.
                              nullable: true
                              type: string
                            name:
                              description: Option label text.
                              nullable: true
                              type: string
                            displayIndex:
                              description: Option ordering index.
                              nullable: true
                              type: number
                            isArchived:
                              description: Whether option is archived.
                              nullable: true
                              type: boolean
                            createdAt:
                              anyOf:
                                - type: string
                                  format: date-time
                                - type: string
                              description: Option creation timestamp.
                            updatedAt:
                              anyOf:
                                - type: string
                                  format: date-time
                                - type: string
                              description: Option last update timestamp.
                          required:
                            - id
                            - createdAt
                            - updatedAt
                          additionalProperties: false
                    required:
                      - id
                      - inputType
                      - type
                      - createdAt
                      - updatedAt
                      - CustomFieldOptions
                    additionalProperties: false
                    description: Updated custom field payload.
                required:
                  - data
                additionalProperties: false
              example:
                message: Custom field updated successfully
                status: 200
                data:
                  id: 20660
                  associationCount: 0
                  name: mult select
                  identifier: mult-select
                  description: ''
                  inputType: MULTIPLE_SELECT
                  type: CONTACT
                  subType: null
                  isSecondaryQuestion: false
                  isSystemField: false
                  hidden: false
                  configuration:
                    isColorCodeOptions: true
                  createdAt: '2026-03-05T10:00:17.711Z'
                  updatedAt: '2026-03-05T10:00:18.000Z'
                  CustomFieldOptions:
                    - id: 90157
                      color: blue
                      name: '1'
                      displayIndex: 0
                      isArchived: false
                      createdAt: '2026-03-05T10:00:17.792Z'
                      updatedAt: '2026-03-05T10:00:17.792Z'
                    - id: 90158
                      color: blue
                      name: '2'
                      displayIndex: 1
                      isArchived: false
                      createdAt: '2026-03-05T10:00:17.830Z'
                      updatedAt: '2026-03-05T10:00:17.830Z'
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/fields/answer:
    post:
      operationId: createCustomFieldAnswer
      summary: Upsert Field Answer
      description: >-
        Create or update a custom field answer for a contact (type CONTACT) or
        event call (type CALL). Provide exactly one of customFieldId or
        identifier. For CONTACT custom fields send contactId; for CALL send
        eventCallId. The answer array format depends on inputType:
        TEXT/TEXT_AREA = string(s), NUMBER/RATING/USER = numeric string(s), DATE
        = ISO date string, EMAIL = email string, URL = https URL,
        SINGLE_SELECT/MULTIPLE_SELECT = option name(s), USERS_MULTIPLE = user
        ID(s) as strings.
      tags:
        - Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customFieldId:
                  description: Target custom field ID (use either this or identifier).
                  type: integer
                  minimum: 1
                  maximum: 2147483647
                identifier:
                  description: >-
                    Target custom field identifier (use either this or
                    customFieldId).
                  type: string
                  minLength: 1
                  maxLength: 1000
                answer:
                  description: >-
                    Answer payload as string array. Interpretation depends on
                    inputType.
                  nullable: true
                  type: array
                  items:
                    type: string
                contactId:
                  description: Required when field type is CONTACT.
                  type: integer
                  minimum: 1
                  maximum: 2147483647
                eventCallId:
                  description: Required when field type is CALL.
                  type: integer
                  minimum: 1
                  maximum: 2147483647
              additionalProperties: false
            examples:
              contact_NUMBER:
                summary: NUMBER (Contact)
                value:
                  customFieldId: 22
                  contactId: 8
                  answer:
                    - '42'
              contact_TEXT:
                summary: TEXT (Contact)
                value:
                  customFieldId: 23
                  contactId: 8
                  answer:
                    - Short text value
              contact_TEXT_AREA:
                summary: TEXT_AREA (Contact)
                value:
                  customFieldId: 24
                  contactId: 8
                  answer:
                    - Longer paragraph or multi-line notes.
              contact_DATE:
                summary: DATE (Contact)
                value:
                  customFieldId: 27
                  contactId: 8
                  answer:
                    - '2026-04-10'
              contact_USER:
                summary: USER (Contact)
                value:
                  customFieldId: 28
                  contactId: 8
                  answer:
                    - '2'
              contact_USERS_MULTIPLE:
                summary: USERS_MULTIPLE (Contact)
                value:
                  customFieldId: 29
                  contactId: 8
                  answer:
                    - '2'
              contact_URL:
                summary: URL (Contact)
                value:
                  customFieldId: 26
                  contactId: 8
                  answer:
                    - https://docs.iclosed.io/
              contact_SINGLE_SELECT:
                summary: SINGLE_SELECT (Contact)
                value:
                  customFieldId: 12
                  contactId: 8
                  answer:
                    - Nurturing
              contact_MULTIPLE_SELECT:
                summary: MULTIPLE_SELECT (Contact)
                value:
                  customFieldId: 42
                  contactId: 8
                  answer:
                    - Newsletter
                    - Webinar
              contact_EMAIL:
                summary: EMAIL (Contact)
                value:
                  customFieldId: 25
                  contactId: 8
                  answer:
                    - user@example.com
              contact_RATING:
                summary: RATING (Contact)
                value:
                  customFieldId: 30
                  contactId: 8
                  answer:
                    - '4'
              call_NUMBER:
                summary: NUMBER (Call)
                value:
                  customFieldId: 32
                  eventCallId: 6
                  answer:
                    - '42'
              call_TEXT:
                summary: TEXT (Call)
                value:
                  customFieldId: 21
                  eventCallId: 6
                  answer:
                    - Call notes
              call_TEXT_AREA:
                summary: TEXT_AREA (Call)
                value:
                  customFieldId: 33
                  eventCallId: 6
                  answer:
                    - Detailed call summary.
              call_DATE:
                summary: DATE (Call)
                value:
                  customFieldId: 34
                  eventCallId: 6
                  answer:
                    - '2026-04-10T12:00:00.000Z'
              call_USER:
                summary: USER (Call)
                value:
                  customFieldId: 35
                  eventCallId: 6
                  answer:
                    - '2'
              call_USERS_MULTIPLE:
                summary: USERS_MULTIPLE (Call)
                value:
                  customFieldId: 36
                  eventCallId: 6
                  answer:
                    - '2'
              call_URL:
                summary: URL (Call)
                value:
                  customFieldId: 39
                  eventCallId: 6
                  answer:
                    - https://docs.iclosed.io/
              call_SINGLE_SELECT:
                summary: SINGLE_SELECT (Call)
                value:
                  customFieldId: 31
                  eventCallId: 6
                  answer:
                    - Completed
              call_MULTIPLE_SELECT:
                summary: MULTIPLE_SELECT (Call)
                value:
                  customFieldId: 40
                  eventCallId: 6
                  answer:
                    - Follow up
                    - Hot
              call_EMAIL:
                summary: EMAIL (Call)
                value:
                  customFieldId: 38
                  eventCallId: 6
                  answer:
                    - followup@example.com
              call_RATING:
                summary: RATING (Call)
                value:
                  customFieldId: 37
                  eventCallId: 6
                  answer:
                    - '5'
              by_identifier_contact:
                summary: By identifier (Contact)
                value:
                  identifier: contact_stage
                  contactId: 8
                  answer:
                    - Engaged
              by_identifier_call:
                summary: By identifier (Call)
                value:
                  identifier: docs-call-outcome
                  eventCallId: 6
                  answer:
                    - No show
      responses:
        '201':
          description: Custom field answer created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  contactId:
                    description: Contact ID for CONTACT-type association.
                    type: number
                  createdAt:
                    description: Association creation timestamp.
                    anyOf:
                      - type: string
                        format: date-time
                      - type: string
                  updatedBy:
                    description: User metadata for updater of the association.
                    nullable: true
                    type: object
                    properties:
                      id:
                        type: number
                        description: User ID of actor who last updated answer association.
                      firstName:
                        description: First name of updater.
                        nullable: true
                        type: string
                      lastName:
                        description: Last name of updater.
                        nullable: true
                        type: string
                    required:
                      - id
                    additionalProperties: false
                  contact:
                    description: Flattened contact payload for association.
                    nullable: true
                    type: object
                    properties:
                      id:
                        type: number
                        description: Contact ID linked to this answer association.
                      firstName:
                        description: Contact first name.
                        nullable: true
                        type: string
                      lastName:
                        description: Contact last name.
                        nullable: true
                        type: string
                      email:
                        description: Contact email address.
                        nullable: true
                        type: string
                      previewId:
                        description: Preview/public contact identifier when used.
                        nullable: true
                        type: string
                      phoneNumber:
                        description: Contact phone number.
                        nullable: true
                        type: string
                      status:
                        description: Contact status value from contact record.
                        nullable: true
                        type: string
                      joinedTime:
                        description: Contact joined timestamp.
                        anyOf:
                          - type: string
                            format: date-time
                            nullable: true
                          - type: string
                            nullable: true
                    required:
                      - id
                    additionalProperties: false
                  CustomFieldAnswer:
                    description: Detailed answer entries linked to the association.
                    type: array
                    items:
                      type: object
                      properties:
                        customFieldRelationId:
                          type: number
                          description: Association/relation ID for this answer row.
                        inputType:
                          description: Input type of the answered field.
                          nullable: true
                          type: string
                          enum:
                            - NUMBER
                            - TEXT
                            - TEXT_AREA
                            - DATE
                            - CHECK_BOX
                            - RADIO_BUTTON
                            - USER
                            - USERS_MULTIPLE
                            - URL
                            - SINGLE_SELECT
                            - MULTIPLE_SELECT
                            - EMAIL
                            - RATING
                        answer:
                          description: Raw stored answer string representation.
                          nullable: true
                          type: string
                        number:
                          description: Numeric projection of answer when applicable.
                          nullable: true
                          type: number
                        date:
                          description: Date projection of answer when applicable.
                          anyOf:
                            - type: string
                              format: date-time
                              nullable: true
                            - type: string
                              nullable: true
                        customFieldOptionId:
                          description: Selected custom field option ID when applicable.
                          nullable: true
                          type: number
                        user:
                          nullable: true
                          type: object
                          properties:
                            id:
                              description: Related user ID for USER/USERS_MULTIPLE answers.
                              type: number
                            firstName:
                              description: Related user first name.
                              nullable: true
                              type: string
                            lastName:
                              description: Related user last name.
                              nullable: true
                              type: string
                          additionalProperties: false
                        userId:
                          description: Related user ID (flat form).
                          nullable: true
                          type: number
                        createdAt:
                          anyOf:
                            - type: string
                              format: date-time
                            - type: string
                          description: Answer row creation timestamp.
                      required:
                        - customFieldRelationId
                        - createdAt
                      additionalProperties: false
                  customField:
                    description: Metadata of the custom field that was answered.
                    type: object
                    properties:
                      id:
                        type: number
                        description: Custom field ID.
                      name:
                        description: Custom field name.
                        nullable: true
                        type: string
                      inputType:
                        description: Custom field input type.
                        nullable: true
                        type: string
                        enum:
                          - NUMBER
                          - TEXT
                          - TEXT_AREA
                          - DATE
                          - CHECK_BOX
                          - RADIO_BUTTON
                          - USER
                          - USERS_MULTIPLE
                          - URL
                          - SINGLE_SELECT
                          - MULTIPLE_SELECT
                          - EMAIL
                          - RATING
                      type:
                        description: Custom field object type.
                        nullable: true
                        type: string
                        enum:
                          - CONTACT
                          - CALL
                          - EVENT
                          - DEAL
                          - USER
                          - ISCORE
                      isSystemField:
                        description: Whether custom field is system-defined.
                        type: boolean
                      identifier:
                        description: Custom field identifier.
                        nullable: true
                        type: string
                    required:
                      - id
                    additionalProperties: false
                  message:
                    description: Operation result message.
                    type: string
                additionalProperties: false
              example:
                contactId: 8
                createdAt: '2026-04-13T07:15:09.652Z'
                updatedBy:
                  id: 2
                  firstName: dhiashd hipasd
                  lastName: ''
                CustomFieldAnswer:
                  - customFieldRelationId: 28
                    inputType: NUMBER
                    answer: null
                    number: 42
                    date: null
                    customFieldOptionId: null
                    user: null
                    userId: null
                    createdAt: '2026-04-13T07:15:09.652Z'
                customField:
                  id: 22
                  name: Docs Sample Number
                  inputType: NUMBER
                  type: CONTACT
                  isSystemField: false
                  identifier: docs-sample-number
                message: Custom Fields Answer Created successfully
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/fields/inviteeAnswers:
    post:
      operationId: insertInviteeAnswers
      summary: Insert Invitee Answers
      description: >-
        Insert invitee question answers and secondary (custom field) answers for
        a contact on an event (disqualified lead flow). Secondary questions can
        be identified by customFieldId or identifier; answer is always an array.
        Backend resolves secondary answers to the event's custom fields and
        computes disqualifyingCondition and conditionalUsers from event logic
        (disqualification and conditional routing).
      tags:
        - Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkPrefix:
                  type: string
                  minLength: 1
                  description: Event link prefix used to resolve target event.
                contactId:
                  description: >-
                    Contact ID to attach answers to (use with authenticated
                    contact context).
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                previewId:
                  description: >-
                    Alternative contact reference when contactId is not
                    provided.
                  type: string
                inviteeQuestionAnswers:
                  minItems: 1
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - EMAIL
                          - PHONE_NO
                          - NAME
                          - FIRST_NAME
                          - LAST_NAME
                        description: >-
                          Answer type (e.g. EMAIL, PHONE_NO, NAME); must match
                          an invitee question type on the event
                      answer:
                        type: string
                        description: Answer value
                    required:
                      - type
                      - answer
                    additionalProperties: false
                  description: Primary invitee question answers.
                secondaryQuestionsAnswer:
                  default: []
                  description: Secondary custom-field question answers.
                  type: array
                  items:
                    type: object
                    properties:
                      customFieldId:
                        description: >-
                          Secondary custom field ID resolved against event
                          configuration.
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                      identifier:
                        description: >-
                          Secondary custom field identifier resolved against
                          event configuration.
                        type: string
                        minLength: 1
                      answer:
                        type: array
                        items:
                          type: string
                        description: Answer value(s); always an array
                    required:
                      - answer
                    additionalProperties: false
                publicSessionId:
                  description: >-
                    Optional public session identifier for event-call session
                    correlation.
                  type: string
              required:
                - linkPrefix
                - inviteeQuestionAnswers
                - secondaryQuestionsAnswer
              additionalProperties: false
            example:
              linkPrefix: amunim/new-event
              contactId: 12
              inviteeQuestionAnswers:
                - type: EMAIL
                  answer: invitee-sample@iclosed.io
              secondaryQuestionsAnswer: []
              publicSessionId: 793fd851-b570-4996-8d1a-ec63c839e0b9
      responses:
        '201':
          description: >-
            Answers inserted; returns message, disqualifyingCondition, and
            conditionalUsers
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        description: Operation result message.
                        type: string
                      disqualifyingCondition:
                        description: Triggered disqualification logic entries, if any.
                        type: array
                        items:
                          type: object
                          additionalProperties: {}
                      conditionalUsers:
                        description: User IDs selected by conditional routing logic.
                        type: array
                        items:
                          type: number
                      isDisqualified:
                        description: >-
                          True when at least one disqualification condition is
                          triggered.
                        type: boolean
                    additionalProperties: false
                    description: Invitee answer processing result payload.
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  message: Questions Answers Inserted Successfully
                  disqualifyingCondition: []
                  conditionalUsers: []
                  isDisqualified: false
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/fields/contact-stage:
    get:
      operationId: getContactStage
      summary: Get Contact Stages
      description: >-
        Retrieve the Contact Stages (lifecycle stages) custom field for the
        authenticated account.
      tags:
        - Fields
      responses:
        '200':
          description: Contact Stage field with options
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: number
                    description: Contact stage custom field ID.
                  name:
                    description: Contact stage field name.
                    nullable: true
                    type: string
                  identifier:
                    description: Contact stage field identifier.
                    nullable: true
                    type: string
                  description:
                    description: Contact stage field description.
                    nullable: true
                    type: string
                  inputType:
                    type: string
                    enum:
                      - NUMBER
                      - TEXT
                      - TEXT_AREA
                      - DATE
                      - CHECK_BOX
                      - RADIO_BUTTON
                      - USER
                      - USERS_MULTIPLE
                      - URL
                      - SINGLE_SELECT
                      - MULTIPLE_SELECT
                      - EMAIL
                      - RATING
                    description: Input type of the contact stage field.
                  type:
                    type: string
                    enum:
                      - CONTACT
                      - CALL
                      - EVENT
                      - DEAL
                      - USER
                      - ISCORE
                    description: Object type of the contact stage field.
                  CustomFieldOptions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: Option ID.
                        name:
                          description: Option display name.
                          nullable: true
                          type: string
                        displayIndex:
                          description: Ordering index for contact stage option.
                          nullable: true
                          type: number
                        isArchived:
                          description: Archive flag for option.
                          nullable: true
                          type: boolean
                        category:
                          description: Grouping category (for example ACTIVE/LOST).
                          nullable: true
                          type: string
                        icon:
                          description: Optional icon descriptor for stage option.
                          nullable: true
                          type: string
                        isDefault:
                          description: Whether option is default stage.
                          nullable: true
                          type: boolean
                        isSystemOption:
                          description: Whether option is system-provided.
                          nullable: true
                          type: boolean
                        color:
                          description: Optional color assigned to stage option.
                          nullable: true
                          type: string
                      required:
                        - id
                      additionalProperties: false
                    description: Flat list of contact stage options.
                  CustomFieldOptionsGrouped:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: number
                            description: Option ID.
                          name:
                            description: Option display name.
                            nullable: true
                            type: string
                          displayIndex:
                            description: Ordering index for contact stage option.
                            nullable: true
                            type: number
                          isArchived:
                            description: Archive flag for option.
                            nullable: true
                            type: boolean
                          category:
                            description: Grouping category (for example ACTIVE/LOST).
                            nullable: true
                            type: string
                          icon:
                            description: Optional icon descriptor for stage option.
                            nullable: true
                            type: string
                          isDefault:
                            description: Whether option is default stage.
                            nullable: true
                            type: boolean
                          isSystemOption:
                            description: Whether option is system-provided.
                            nullable: true
                            type: boolean
                          color:
                            description: Optional color assigned to stage option.
                            nullable: true
                            type: string
                        required:
                          - id
                        additionalProperties: false
                    description: Stage options grouped by category key.
                required:
                  - id
                  - inputType
                  - type
                  - CustomFieldOptions
                  - CustomFieldOptionsGrouped
                additionalProperties: false
              example:
                id: 12
                name: Contact Stage
                identifier: contact_stage
                description: Track the current stage of contacts in your sales pipeline
                inputType: SINGLE_SELECT
                type: CONTACT
                CustomFieldOptions:
                  - id: 53
                    name: New Lead
                    displayIndex: 1
                    isArchived: false
                    category: ACTIVE
                    icon: user-plus*#6B7280
                    isDefault: true
                    isSystemOption: true
                    color: null
                  - id: 54
                    name: Approved
                    displayIndex: 2
                    isArchived: false
                    category: ACTIVE
                    icon: check*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 55
                    name: Nurturing
                    displayIndex: 3
                    isArchived: false
                    category: ACTIVE
                    icon: seedling*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 56
                    name: Contacted
                    displayIndex: 4
                    isArchived: false
                    category: ACTIVE
                    icon: send*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 57
                    name: Follow-Up Scheduled
                    displayIndex: 5
                    isArchived: false
                    category: ACTIVE
                    icon: calendar-check*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 58
                    name: Engaged
                    displayIndex: 6
                    isArchived: false
                    category: ACTIVE
                    icon: check*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 59
                    name: Customer
                    displayIndex: 7
                    isArchived: false
                    category: WON
                    icon: user-check*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 60
                    name: Onboarded
                    displayIndex: 8
                    isArchived: false
                    category: WON
                    icon: sparkles*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 61
                    name: Premium Client
                    displayIndex: 9
                    isArchived: false
                    category: WON
                    icon: diamond*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 62
                    name: Ghosting
                    displayIndex: 10
                    isArchived: false
                    category: LOST
                    icon: ghost*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 63
                    name: Rejected
                    displayIndex: 11
                    isArchived: false
                    category: LOST
                    icon: cross*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 64
                    name: Budget Issue
                    displayIndex: 12
                    isArchived: false
                    category: LOST
                    icon: cash*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 65
                    name: No Decision
                    displayIndex: 13
                    isArchived: false
                    category: LOST
                    icon: hourglass*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                  - id: 66
                    name: Not a Fit
                    displayIndex: 14
                    isArchived: false
                    category: LOST
                    icon: block*#6B7280
                    isDefault: false
                    isSystemOption: true
                    color: null
                CustomFieldOptionsGrouped:
                  ACTIVE:
                    - id: 53
                      name: New Lead
                      displayIndex: 1
                      isArchived: false
                      category: ACTIVE
                      icon: user-plus*#6B7280
                      isDefault: true
                      isSystemOption: true
                      color: null
                    - id: 54
                      name: Approved
                      displayIndex: 2
                      isArchived: false
                      category: ACTIVE
                      icon: check*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 55
                      name: Nurturing
                      displayIndex: 3
                      isArchived: false
                      category: ACTIVE
                      icon: seedling*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 56
                      name: Contacted
                      displayIndex: 4
                      isArchived: false
                      category: ACTIVE
                      icon: send*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 57
                      name: Follow-Up Scheduled
                      displayIndex: 5
                      isArchived: false
                      category: ACTIVE
                      icon: calendar-check*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 58
                      name: Engaged
                      displayIndex: 6
                      isArchived: false
                      category: ACTIVE
                      icon: check*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                  WON:
                    - id: 59
                      name: Customer
                      displayIndex: 7
                      isArchived: false
                      category: WON
                      icon: user-check*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 60
                      name: Onboarded
                      displayIndex: 8
                      isArchived: false
                      category: WON
                      icon: sparkles*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 61
                      name: Premium Client
                      displayIndex: 9
                      isArchived: false
                      category: WON
                      icon: diamond*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                  LOST:
                    - id: 62
                      name: Ghosting
                      displayIndex: 10
                      isArchived: false
                      category: LOST
                      icon: ghost*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 63
                      name: Rejected
                      displayIndex: 11
                      isArchived: false
                      category: LOST
                      icon: cross*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 64
                      name: Budget Issue
                      displayIndex: 12
                      isArchived: false
                      category: LOST
                      icon: cash*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 65
                      name: No Decision
                      displayIndex: 13
                      isArchived: false
                      category: LOST
                      icon: hourglass*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
                    - id: 66
                      name: Not a Fit
                      displayIndex: 14
                      isArchived: false
                      category: LOST
                      icon: block*#6B7280
                      isDefault: false
                      isSystemOption: true
                      color: null
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/fields/objects:
    get:
      operationId: getCustomFieldsByObjectType
      summary: Get Object and Fields
      description: >-
        Get paginated custom fields for a specific object type. Query:
        objectType (required), page, limit, search, inputType, hidden,
        showSystemFields, allFields, forFilters, inviteeQuestions,
        includeRelations, identifiers.
      tags:
        - Fields
      parameters:
        - name: objectType
          in: query
          schema:
            type: string
            enum:
              - CONTACT
              - CALL
              - EVENT
              - DEAL
              - USER
              - ISCORE
          required: true
          description: Object type to filter fields by.
        - name: page
          in: query
          schema:
            description: Zero-based page index.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index.
        - name: limit
          in: query
          schema:
            default: 20
            description: Maximum number of fields returned per page.
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of fields returned per page.
        - name: search
          in: query
          schema:
            description: Search term applied on field name/identifier in service layer.
            type: string
            maxLength: 1000
          description: Search term applied on field name/identifier in service layer.
        - name: inputType
          in: query
          schema:
            type: string
            enum:
              - NUMBER
              - TEXT
              - TEXT_AREA
              - DATE
              - CHECK_BOX
              - RADIO_BUTTON
              - USER
              - USERS_MULTIPLE
              - URL
              - SINGLE_SELECT
              - MULTIPLE_SELECT
              - EMAIL
              - RATING
          description: Filter fields by input type.
        - name: showSystemFields
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Whether system fields should be included.
        - name: inviteeQuestions
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Whether to filter by invitee-question flag in service layer.
        - name: identifiers
          in: query
          schema:
            description: Comma-separated field identifiers filter.
            type: string
            maxLength: 500
          description: Comma-separated field identifiers filter.
      responses:
        '200':
          description: Paginated custom fields for the object type
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                    description: Total number of matching fields.
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: Custom field ID.
                        name:
                          description: Field display name.
                          nullable: true
                          type: string
                        identifier:
                          description: Field identifier key.
                          nullable: true
                          type: string
                        inputType:
                          description: Field input type.
                          nullable: true
                          type: string
                          enum:
                            - NUMBER
                            - TEXT
                            - TEXT_AREA
                            - DATE
                            - CHECK_BOX
                            - RADIO_BUTTON
                            - USER
                            - USERS_MULTIPLE
                            - URL
                            - SINGLE_SELECT
                            - MULTIPLE_SELECT
                            - EMAIL
                            - RATING
                        type:
                          description: Field object type.
                          nullable: true
                          type: string
                          enum:
                            - CONTACT
                            - CALL
                            - EVENT
                            - DEAL
                            - USER
                            - ISCORE
                        configuration:
                          description: Field configuration object.
                          anyOf:
                            - type: object
                              properties:
                                dateTimeFormat:
                                  type: string
                                  enum:
                                    - 12Hour
                                    - 24Hour
                                  description: >-
                                    Time format: "12Hour" or "24Hour". Required
                                    when includedTime is true.
                                dateType:
                                  type: string
                                  enum:
                                    - US
                                    - EU
                                    - ISO
                                    - FRIENDLY
                                  description: >-
                                    Date display format: "US", "EU", "ISO", or
                                    "FRIENDLY".
                                includedTime:
                                  type: boolean
                                  enum:
                                    - true
                                  description: >-
                                    When true, time is shown and dateTimeFormat
                                    applies.
                              required:
                                - dateTimeFormat
                                - dateType
                                - includedTime
                              additionalProperties: false
                              description: Date field configuration when time is selected.
                              nullable: true
                            - type: object
                              properties:
                                dateType:
                                  type: string
                                  enum:
                                    - US
                                    - EU
                                    - ISO
                                    - FRIENDLY
                                  description: >-
                                    Date display format: "US", "EU", "ISO", or
                                    "FRIENDLY".
                                includedTime:
                                  type: boolean
                                  enum:
                                    - false
                                  description: >-
                                    When false, only date is shown; no
                                    dateTimeFormat.
                              required:
                                - dateType
                                - includedTime
                              additionalProperties: false
                              description: >-
                                Date field configuration when time is not
                                selected.
                              nullable: true
                            - type: object
                              properties:
                                isColorCodeOptions:
                                  type: boolean
                                  description: >-
                                    True if options have colors; false if colors
                                    are not selected for options.
                              required:
                                - isColorCodeOptions
                              additionalProperties: false
                              description: >-
                                Single Select or Multi Select field
                                configuration.
                              nullable: true
                            - type: object
                              properties:
                                isMultipleUsers:
                                  type: boolean
                                  description: >-
                                    True to allow multiple users; false for
                                    single user selection.
                              required:
                                - isMultipleUsers
                              additionalProperties: false
                              description: User field configuration.
                              nullable: true
                            - type: object
                              properties:
                                maxRating:
                                  type: string
                                  description: Maximum rating value as string (e.g. "3").
                                ratingStyle:
                                  type: string
                                  enum:
                                    - STAR
                                  description: Display style for the rating (e.g. "STAR").
                              required:
                                - maxRating
                                - ratingStyle
                              additionalProperties: false
                              description: Rating field configuration.
                              nullable: true
                            - type: object
                              properties:
                                showMaxValue:
                                  type: boolean
                                  description: Whether to show the maximum value.
                              required:
                                - showMaxValue
                              additionalProperties: false
                              description: Number field configuration.
                              nullable: true
                        isSystemField:
                          description: Whether field is system-defined.
                          nullable: true
                          type: boolean
                        hidden:
                          description: Whether field is hidden.
                          nullable: true
                          type: boolean
                        slug:
                          description: Optional slug-like key returned by service.
                          type: string
                        createdAt:
                          anyOf:
                            - type: string
                              format: date-time
                            - type: string
                          description: Field creation timestamp.
                        isSecondaryQuestion:
                          description: Whether field is a secondary question.
                          nullable: true
                          type: boolean
                        CustomFieldOptions:
                          description: Field options list for select-like fields.
                          nullable: true
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                description: Option ID.
                                type: number
                              name:
                                description: Option display name.
                                nullable: true
                                type: string
                              color:
                                description: Option color token/value when available.
                                nullable: true
                                type: string
                              badge:
                                description: Badge text shown for option when configured.
                                nullable: true
                                type: string
                              tooltip:
                                description: Tooltip text shown for option when configured.
                                nullable: true
                                type: string
                              displayIndex:
                                description: Option ordering index.
                                nullable: true
                                type: number
                              isArchived:
                                description: Archive state of option.
                                nullable: true
                                type: boolean
                              icon:
                                description: Icon descriptor/value for option.
                                nullable: true
                                type: string
                              isDefault:
                                description: Whether this option is the default option.
                                nullable: true
                                type: boolean
                              actionId:
                                description: Linked action ID for option, when present.
                                nullable: true
                                type: number
                              category:
                                description: Grouping category key for option.
                                nullable: true
                                type: string
                            additionalProperties: false
                      required:
                        - id
                        - createdAt
                      additionalProperties: false
                    description: Paginated field items.
                  hasMore:
                    type: boolean
                    description: Whether a next page exists.
                  nextPage:
                    description: Next page index when hasMore is true.
                    type: number
                required:
                  - count
                  - data
                  - hasMore
                additionalProperties: false
              example:
                count: 43
                data:
                  - id: 27
                    name: Docs Sample Date
                    identifier: '{{contact.docs-sample-date}}'
                    inputType: DATE
                    type: CONTACT
                    isSystemField: false
                    hidden: false
                    configuration:
                      dateType: ISO
                      includedTime: false
                    createdAt: '2026-04-13T07:15:24.717Z'
                    isSecondaryQuestion: false
                    CustomFieldOptions: []
                    slug: contact.docs-sample-date
                  - id: 26
                    name: Docs Sample URL
                    identifier: '{{contact.docs-sample-url}}'
                    inputType: URL
                    type: CONTACT
                    isSystemField: false
                    hidden: false
                    configuration: null
                    createdAt: '2026-04-13T07:15:24.695Z'
                    isSecondaryQuestion: false
                    CustomFieldOptions: []
                    slug: contact.docs-sample-url
                  - id: 25
                    name: Docs Sample Email
                    identifier: '{{contact.docs-sample-email}}'
                    inputType: EMAIL
                    type: CONTACT
                    isSystemField: false
                    hidden: false
                    configuration: null
                    createdAt: '2026-04-13T07:15:24.669Z'
                    isSecondaryQuestion: false
                    CustomFieldOptions: []
                    slug: contact.docs-sample-email
                hasMore: true
                nextPage: 2
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/fields/objects/all:
    get:
      operationId: getAllObjectTypesCustomFields
      summary: Get All Objects and Fields
      description: >-
        Get custom fields for all object types (CONTACT, CALL, EVENT, DEAL,
        USER, etc.) in one response. Query: page, limit, search, inputType,
        hidden, showSystemFields, allFields, forFilters, inviteeQuestions.
      tags:
        - Fields
      parameters:
        - name: page
          in: query
          schema:
            description: Zero-based page index.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index.
        - name: limit
          in: query
          schema:
            default: 20
            description: Maximum number of items per object-type slice.
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of items per object-type slice.
        - name: search
          in: query
          schema:
            description: Search term applied in service layer.
            type: string
            maxLength: 1000
          description: Search term applied in service layer.
        - name: inputType
          in: query
          schema:
            type: string
            enum:
              - NUMBER
              - TEXT
              - TEXT_AREA
              - DATE
              - CHECK_BOX
              - RADIO_BUTTON
              - USER
              - USERS_MULTIPLE
              - URL
              - SINGLE_SELECT
              - MULTIPLE_SELECT
              - EMAIL
              - RATING
          description: Filter by input type across object types.
        - name: showSystemFields
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Whether to include system fields.
        - name: inviteeQuestions
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Whether to filter by invitee-question behavior.
      responses:
        '200':
          description: Custom fields grouped by object type
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      CONTACT:
                        description: Custom fields for CONTACT object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      CALL:
                        description: Custom fields for CALL object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      EVENT:
                        description: Custom fields for EVENT object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      DEAL:
                        description: Custom fields for DEAL object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      USER:
                        description: Custom fields for USER object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      UNIFIED_INBOX:
                        description: Custom fields for UNIFIED_INBOX object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      INVITEE_QUESTION:
                        description: Custom fields for INVITEE_QUESTION object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      ISCORE:
                        description: Custom fields for ISCORE object type.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Custom field ID.
                            name:
                              description: Field display name.
                              nullable: true
                              type: string
                            identifier:
                              description: Field identifier key.
                              nullable: true
                              type: string
                            inputType:
                              description: Field input type.
                              nullable: true
                              type: string
                              enum:
                                - NUMBER
                                - TEXT
                                - TEXT_AREA
                                - DATE
                                - CHECK_BOX
                                - RADIO_BUTTON
                                - USER
                                - USERS_MULTIPLE
                                - URL
                                - SINGLE_SELECT
                                - MULTIPLE_SELECT
                                - EMAIL
                                - RATING
                            type:
                              description: Field object type.
                              nullable: true
                              type: string
                              enum:
                                - CONTACT
                                - CALL
                                - EVENT
                                - DEAL
                                - USER
                                - ISCORE
                            configuration:
                              description: Field configuration object.
                              anyOf:
                                - type: object
                                  properties:
                                    dateTimeFormat:
                                      type: string
                                      enum:
                                        - 12Hour
                                        - 24Hour
                                      description: >-
                                        Time format: "12Hour" or "24Hour".
                                        Required when includedTime is true.
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - true
                                      description: >-
                                        When true, time is shown and
                                        dateTimeFormat applies.
                                  required:
                                    - dateTimeFormat
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    dateType:
                                      type: string
                                      enum:
                                        - US
                                        - EU
                                        - ISO
                                        - FRIENDLY
                                      description: >-
                                        Date display format: "US", "EU", "ISO",
                                        or "FRIENDLY".
                                    includedTime:
                                      type: boolean
                                      enum:
                                        - false
                                      description: >-
                                        When false, only date is shown; no
                                        dateTimeFormat.
                                  required:
                                    - dateType
                                    - includedTime
                                  additionalProperties: false
                                  description: >-
                                    Date field configuration when time is not
                                    selected.
                                  nullable: true
                                - type: object
                                  properties:
                                    isColorCodeOptions:
                                      type: boolean
                                      description: >-
                                        True if options have colors; false if
                                        colors are not selected for options.
                                  required:
                                    - isColorCodeOptions
                                  additionalProperties: false
                                  description: >-
                                    Single Select or Multi Select field
                                    configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    isMultipleUsers:
                                      type: boolean
                                      description: >-
                                        True to allow multiple users; false for
                                        single user selection.
                                  required:
                                    - isMultipleUsers
                                  additionalProperties: false
                                  description: User field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    maxRating:
                                      type: string
                                      description: >-
                                        Maximum rating value as string (e.g.
                                        "3").
                                    ratingStyle:
                                      type: string
                                      enum:
                                        - STAR
                                      description: >-
                                        Display style for the rating (e.g.
                                        "STAR").
                                  required:
                                    - maxRating
                                    - ratingStyle
                                  additionalProperties: false
                                  description: Rating field configuration.
                                  nullable: true
                                - type: object
                                  properties:
                                    showMaxValue:
                                      type: boolean
                                      description: Whether to show the maximum value.
                                  required:
                                    - showMaxValue
                                  additionalProperties: false
                                  description: Number field configuration.
                                  nullable: true
                            isSystemField:
                              description: Whether field is system-defined.
                              nullable: true
                              type: boolean
                            hidden:
                              description: Whether field is hidden.
                              nullable: true
                              type: boolean
                            slug:
                              description: Optional slug-like key returned by service.
                              type: string
                            CustomFieldOptions:
                              description: Options for select-like field types.
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    description: Option ID.
                                    type: number
                                  name:
                                    description: Option display name.
                                    nullable: true
                                    type: string
                                  color:
                                    description: Option color.
                                    nullable: true
                                    type: string
                                  displayIndex:
                                    description: Option ordering index.
                                    nullable: true
                                    type: number
                                  isArchived:
                                    description: Archive status for option.
                                    nullable: true
                                    type: boolean
                                  icon:
                                    description: Icon descriptor for option.
                                    nullable: true
                                    type: string
                                  isDefault:
                                    description: Whether option is default value.
                                    nullable: true
                                    type: boolean
                                  category:
                                    description: Category/group key for option.
                                    nullable: true
                                    type: string
                                additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  CONTACT:
                    - id: 22
                      name: Docs Sample Number
                      identifier: '{{contact.docs-sample-number}}'
                      inputType: NUMBER
                      type: CONTACT
                      isSystemField: false
                      hidden: false
                      configuration:
                        showMaxValue: false
                      createdAt: '2026-04-13T07:15:04.456Z'
                      isSecondaryQuestion: false
                      CustomFieldOptions: []
                      slug: contact.docs-sample-number
                    - id: 30
                      name: Docs Sample Rating
                      identifier: '{{contact.docs-sample-rating}}'
                      inputType: RATING
                      type: CONTACT
                      isSystemField: false
                      hidden: false
                      configuration:
                        maxRating: '5'
                        ratingStyle: STAR
                      createdAt: '2026-04-13T07:15:24.792Z'
                      isSecondaryQuestion: false
                      CustomFieldOptions: []
                      slug: contact.docs-sample-rating
                  CALL:
                    - id: 40
                      name: Docs Call Tags
                      identifier: '{{call.docs-call-tags}}'
                      inputType: MULTIPLE_SELECT
                      type: CALL
                      isSystemField: false
                      hidden: false
                      configuration:
                        isColorCodeOptions: true
                      createdAt: '2026-04-13T07:16:02.580Z'
                      isSecondaryQuestion: false
                      CustomFieldOptions:
                        - id: 106
                          name: Follow up
                          displayIndex: 0
                          isArchived: false
                          color: blue
                          icon: null
                          isDefault: false
                        - id: 107
                          name: Hot
                          displayIndex: 1
                          isArchived: false
                          color: red
                          icon: null
                          isDefault: false
                      slug: call.docs-call-tags
                    - id: 39
                      name: Docs Call URL
                      identifier: '{{call.docs-call-url}}'
                      inputType: URL
                      type: CALL
                      isSystemField: false
                      hidden: false
                      configuration: null
                      createdAt: '2026-04-13T07:16:02.560Z'
                      isSecondaryQuestion: false
                      CustomFieldOptions: []
                      slug: call.docs-call-url
                  EVENT: []
                  DEAL: []
                  USER: []
                  UNIFIED_INBOX: []
                  INVITEE_QUESTION:
                    - id: 21
                      name: Local Invitee Q
                      identifier: '{{call.invitee-local-1775678186}}'
                      inputType: TEXT
                      type: CALL
                      isSystemField: false
                      hidden: false
                      configuration: null
                      createdAt: '2026-04-08T19:56:27.006Z'
                      isSecondaryQuestion: true
                      CustomFieldOptions: []
                      slug: call.invitee-local-1775678186
                  ISCORE: []
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/deals:
    get:
      operationId: getDeals
      summary: Get deals
      description: >-
        List deals for the authenticated account. Query: contactId, userIds,
        productIds, transactionType, limit, page, timeFrom, timeTo, and other
        optional filters.
      tags:
        - Deals
      parameters:
        - name: contactId
          in: query
          schema:
            description: Filter deals linked to this contact id.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Filter deals linked to this contact id.
        - name: userIds
          in: query
          schema:
            description: >-
              Comma-separated user ids; resolved to account user ids for
              filtering deals by assignee.
            type: string
          description: >-
            Comma-separated user ids; resolved to account user ids for filtering
            deals by assignee.
        - name: productIds
          in: query
          schema:
            description: >-
              Comma-separated product ids; filters deals by productId in that
              set.
            type: string
          description: Comma-separated product ids; filters deals by productId in that set.
        - name: transactionType
          in: query
          schema:
            type: string
            enum:
              - WON
              - RECURRING
              - DEPOSIT
          description: Filter by deal transaction type (WON, RECURRING, DEPOSIT).
        - name: contactStatuses
          in: query
          schema:
            description: >-
              Comma-separated contact status values (POTENTIAL, QUALIFIED,
              DISQUALIFIED, STRATEGY_CALL_BOOKED, DISCOVERY_CALL_BOOKED);
              filters deals whose contact status is in the list.
            type: string
          description: >-
            Comma-separated contact status values (POTENTIAL, QUALIFIED,
            DISQUALIFIED, STRATEGY_CALL_BOOKED, DISCOVERY_CALL_BOOKED); filters
            deals whose contact status is in the list.
        - name: eventIds
          in: query
          schema:
            nullable: true
            description: >-
              Comma-separated event ids; filters deals with an eventCall tied to
              one of those events.
            type: string
          description: >-
            Comma-separated event ids; filters deals with an eventCall tied to
            one of those events.
        - name: search
          in: query
          schema:
            description: >-
              Case-insensitive search across provider, product name, and contact
              fields.
            type: string
          description: >-
            Case-insensitive search across provider, product name, and contact
            fields.
        - name: limit
          in: query
          schema:
            default: 20
            description: Maximum deals per page (1–200). Default 20.
            type: integer
            minimum: 1
            maximum: 200
          description: Maximum deals per page (1–200). Default 20.
        - name: page
          in: query
          schema:
            default: 0
            description: Zero-based page index for pagination.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index for pagination.
        - name: orderBy
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: >-
            Sort direction (asc or desc). Required together with orderColumn
            when sorting.
        - name: orderColumn
          in: query
          schema:
            type: string
            enum:
              - id
              - time
              - value
              - firstName
              - lastName
              - email
              - phoneNumber
          description: Deal field to sort by. Required together with orderBy when sorting.
        - name: timeFrom
          in: query
          schema:
            description: >-
              Inclusive lower bound for deal time (ISO date, e.g.
              2026-03-31T00:00:00.000Z).
            type: string
          description: >-
            Inclusive lower bound for deal time (ISO date, e.g.
            2026-03-31T00:00:00.000Z).
        - name: timeTo
          in: query
          schema:
            description: >-
              Inclusive upper bound for deal time (ISO date, e.g.
              2026-03-31T23:59:59.999Z).
            type: string
          description: >-
            Inclusive upper bound for deal time (ISO date, e.g.
            2026-03-31T23:59:59.999Z).
      responses:
        '200':
          description: List of deals with count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        type: number
                        description: Total deals matching the query (for pagination).
                      deals:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Deal id.
                            productId:
                              nullable: true
                              description: Linked product id.
                              type: number
                            contactId:
                              nullable: true
                              description: Linked contact id.
                              type: number
                            eventCallId:
                              nullable: true
                              description: Linked event call / booking id.
                              type: number
                            userId:
                              nullable: true
                              description: Assignee user id.
                              type: number
                            value:
                              description: Deal monetary value (number or string encoding).
                              anyOf:
                                - type: number
                                  nullable: true
                                - type: string
                                  nullable: true
                            time:
                              nullable: true
                              description: >-
                                Deal time in account time zone (formatted
                                string).
                              type: string
                            recurring:
                              nullable: true
                              description: Whether the deal is recurring.
                              type: boolean
                            transactionType:
                              nullable: true
                              description: Transaction type label on the deal.
                              type: string
                              enum:
                                - WON
                                - RECURRING
                                - DEPOSIT
                            createdAt:
                              nullable: true
                              description: Deal created at (formatted string).
                              type: string
                            updatedAt:
                              nullable: true
                              description: Deal updated at (formatted string).
                              type: string
                            user:
                              nullable: true
                              description: Assigned user summary.
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: User id.
                                firstName:
                                  nullable: true
                                  description: User first name.
                                  type: string
                                lastName:
                                  nullable: true
                                  description: User last name.
                                  type: string
                                email:
                                  nullable: true
                                  description: User email.
                                  type: string
                                  format: email
                              required:
                                - id
                              additionalProperties: false
                            event:
                              nullable: true
                              description: Related event summary when available.
                              type: object
                              properties:
                                name:
                                  nullable: true
                                  description: Event display name.
                                  type: string
                                color:
                                  nullable: true
                                  description: Event color (e.g. hex).
                                  type: string
                                eventType:
                                  nullable: true
                                  description: Event type discriminator.
                                  type: string
                              additionalProperties: false
                            contact:
                              nullable: true
                              description: Related contact when loaded.
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Contact id.
                                userId:
                                  nullable: true
                                  description: Owning user id when set.
                                  type: number
                                firstName:
                                  nullable: true
                                  description: Contact first name.
                                  type: string
                                lastName:
                                  nullable: true
                                  description: Contact last name.
                                  type: string
                                email:
                                  nullable: true
                                  description: Primary email.
                                  type: string
                                  format: email
                                phoneNumber:
                                  nullable: true
                                  description: Primary phone number.
                                  type: string
                                secondary_email:
                                  nullable: true
                                  description: Secondary email.
                                  type: string
                                  format: email
                                secondary_phoneNumber:
                                  nullable: true
                                  description: Secondary phone number.
                                  type: string
                                country:
                                  nullable: true
                                  description: Country code or label.
                                  type: string
                                timeZone:
                                  nullable: true
                                  description: IANA or stored time zone string.
                                  type: string
                                ipAddress:
                                  nullable: true
                                  description: Last known IP address.
                                  type: string
                                status:
                                  nullable: true
                                  description: Contact pipeline/status value.
                                  type: string
                                blockedByRecaptcha:
                                  nullable: true
                                  description: Whether contact is blocked by reCAPTCHA.
                                  type: boolean
                                joinedTime:
                                  nullable: true
                                  description: First join time (formatted string).
                                  type: string
                                referrerUrl:
                                  nullable: true
                                  description: Referrer URL when captured.
                                  type: string
                                previewId:
                                  nullable: true
                                  description: Preview / widget identifier.
                                  type: string
                                createdVia:
                                  nullable: true
                                  description: Source channel (e.g. scheduling widget).
                                  type: string
                                createdAt:
                                  nullable: true
                                  description: Contact created at (formatted string).
                                  type: string
                                updatedAt:
                                  nullable: true
                                  description: Contact updated at (formatted string).
                                  type: string
                              required:
                                - id
                              additionalProperties: false
                            tag:
                              nullable: true
                              description: Tag on the deal when present.
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Tag id.
                                name:
                                  nullable: true
                                  description: Tag name.
                                  type: string
                                value:
                                  description: Tag value (numeric or string).
                                  anyOf:
                                    - type: number
                                      nullable: true
                                    - type: string
                                      nullable: true
                                createdAt:
                                  nullable: true
                                  description: Tag created at.
                                  type: string
                                updatedAt:
                                  nullable: true
                                  description: Tag updated at.
                                  type: string
                              required:
                                - id
                              additionalProperties: false
                            product:
                              nullable: true
                              description: Product summary when loaded.
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Product id.
                                name:
                                  nullable: true
                                  description: Product name.
                                  type: string
                                createdAt:
                                  nullable: true
                                  description: Product created at (formatted string).
                                  type: string
                              required:
                                - id
                              additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                        description: Deal rows for the current page.
                    required:
                      - count
                      - deals
                    additionalProperties: false
                    description: 'Paginated list payload: count and deals array.'
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  count: 6
                  deals:
                    - id: 1
                      productId: 1
                      contactId: 2
                      eventCallId: 5
                      userId: 5
                      value: 100
                      time: '2025-12-10 19:23:01.299'
                      recurring: false
                      transactionType: WON
                      createdAt: '2025-12-10 19:23:40.076'
                      updatedAt: '2025-12-10 19:23:40.076'
                      user:
                        id: 5
                        firstName: Development
                        lastName: ''
                        email: dev@iclosed.io
                      event:
                        name: Email Only
                        color: '#0099FF'
                        eventType: STRATEGY_EVENT
                      contact:
                        id: 2
                        firstName: Genevieve
                        lastName: Duke
                        email: genevieve@iclosed.io
                        phoneNumber: '+18054666813'
                        secondary_email: null
                        secondary_phoneNumber: null
                        timeZone: Asia/Karachi
                        status: STRATEGY_CALL_BOOKED
                        joinedTime: '2025-12-10 15:08:54.913'
                        previewId: contact_xeKmDXhxrxGT
                        createdVia: SCHEDULING_WIDGET
                        createdAt: '2025-12-10 15:08:54.915'
                        updatedAt: '2025-12-26 16:44:32.799'
                      tag:
                        id: 2
                        name: mobile
                      product:
                        id: 1
                        name: Mobile
                        createdAt: '2025-12-10T10:57:41.205Z'
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    post:
      operationId: createDeal
      summary: Create a new deal
      description: >-
        Create a new deal. Required: eventCallId. Optional: productId,
        productName, value, transactionType, etc.
      tags:
        - Deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                eventCallId:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Event call / booking this deal is created from.
                productId:
                  description: Existing product id (validated for the account).
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                productName:
                  description: >-
                    Product name when creating without productId (at least one
                    of productId or productName required).
                  type: string
                value:
                  description: Deal value amount.
                  type: number
                time:
                  description: >-
                    Deal time as ISO 8601 datetime; must be in the future when
                    provided.
                  type: string
                  format: date-time
                transactionType:
                  description: Initial transaction type when set.
                  type: string
                  enum:
                    - WON
                    - RECURRING
                    - DEPOSIT
                transactionIds:
                  description: Existing transaction ids to associate with the new deal.
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 2147483647
              required:
                - eventCallId
              additionalProperties: false
              example:
                eventCallId: 5
                productId: 1
                value: 100
                time: '2026-06-15T15:00:00.000Z'
                transactionType: WON
            example:
              eventCallId: 5
              productId: 1
              value: 100
              time: '2026-06-15T15:00:00.000Z'
              transactionType: WON
      responses:
        '201':
          description: Successfully created deal
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Deal id.
                      productId:
                        nullable: true
                        description: Linked product id.
                        type: number
                      contactId:
                        nullable: true
                        description: Linked contact id.
                        type: number
                      eventCallId:
                        nullable: true
                        description: Linked event call id.
                        type: number
                      userId:
                        nullable: true
                        description: Assignee user id.
                        type: number
                      tagId:
                        nullable: true
                        description: Tag id on the deal when set.
                        type: number
                      value:
                        description: Deal value (number or string).
                        anyOf:
                          - type: number
                            nullable: true
                          - type: string
                            nullable: true
                      time:
                        nullable: true
                        description: Deal time (ISO or formatted string).
                        type: string
                      recurring:
                        nullable: true
                        description: Whether the deal is recurring.
                        type: boolean
                      transactionType:
                        nullable: true
                        description: Transaction type label.
                        type: string
                        enum:
                          - WON
                          - RECURRING
                          - DEPOSIT
                      createdAt:
                        nullable: true
                        description: Created at.
                        type: string
                      updatedAt:
                        nullable: true
                        description: Updated at.
                        type: string
                      product:
                        nullable: true
                        description: Minimal product info (name).
                        type: object
                        properties:
                          name:
                            nullable: true
                            description: Product display name on the deal response.
                            type: string
                        additionalProperties: false
                      eventCall:
                        nullable: true
                        description: >-
                          Booking / call context with nested user, contact,
                          event.
                        type: object
                        properties:
                          id:
                            type: number
                            description: Event call / booking id.
                          userId:
                            nullable: true
                            description: Host or assigned user id.
                            type: number
                          eventId:
                            nullable: true
                            description: Template event id.
                            type: number
                          previewId:
                            nullable: true
                            description: Preview or widget session id.
                            type: string
                          callType:
                            nullable: true
                            description: Kind of call or meeting.
                            type: string
                          dateTime:
                            nullable: true
                            description: Scheduled start as ISO or formatted string.
                            type: string
                          user:
                            nullable: true
                            description: User on the call.
                            type: object
                            properties:
                              id:
                                type: number
                                description: User id.
                              firstName:
                                nullable: true
                                description: First name.
                                type: string
                              lastName:
                                nullable: true
                                description: Last name.
                                type: string
                              email:
                                nullable: true
                                description: Email.
                                type: string
                                format: email
                              phoneNumber:
                                nullable: true
                                description: Phone number.
                                type: string
                            required:
                              - id
                            additionalProperties: false
                          contact:
                            nullable: true
                            description: Contact on the call.
                            type: object
                            properties:
                              id:
                                type: number
                                description: Contact id.
                              firstName:
                                nullable: true
                                description: First name.
                                type: string
                              lastName:
                                nullable: true
                                description: Last name.
                                type: string
                              email:
                                nullable: true
                                description: Email.
                                type: string
                                format: email
                              phoneNumber:
                                nullable: true
                                description: Phone number.
                                type: string
                            required:
                              - id
                            additionalProperties: false
                          event:
                            nullable: true
                            description: Event definition for the call.
                            type: object
                            properties:
                              id:
                                type: number
                                description: Event id.
                              eventType:
                                nullable: true
                                description: Event type discriminator.
                                type: string
                              name:
                                nullable: true
                                description: Event display name.
                                type: string
                              color:
                                nullable: true
                                description: Event color.
                                type: string
                              duration:
                                nullable: true
                                description: Scheduled duration magnitude.
                                type: number
                              durationUnit:
                                nullable: true
                                description: Unit for duration (e.g. minutes).
                                type: string
                            required:
                              - id
                            additionalProperties: false
                        required:
                          - id
                        additionalProperties: false
                      transaction:
                        nullable: true
                        description: Transactions associated with this deal.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              nullable: true
                              description: Transaction id.
                              type: number
                            accountId:
                              nullable: true
                              description: Owning account id.
                              type: number
                            syncedDeal:
                              nullable: true
                              description: Linked deal id when synced.
                              type: number
                            name:
                              nullable: true
                              description: Counterparty or transaction name.
                              type: string
                            email:
                              nullable: true
                              description: Email on the transaction.
                              type: string
                              format: email
                            phoneNumber:
                              nullable: true
                              description: Phone on the transaction.
                              type: string
                            description:
                              nullable: true
                              description: Free-text description.
                              type: string
                            value:
                              description: Transaction amount (number or string).
                              anyOf:
                                - type: number
                                  nullable: true
                                - type: string
                                  nullable: true
                            currency:
                              nullable: true
                              description: Currency code or label.
                              type: string
                            source:
                              nullable: true
                              description: Origin system or channel.
                              type: string
                            updatedBy:
                              nullable: true
                              description: Actor or label for last update.
                              type: string
                            createdAt:
                              nullable: true
                              description: Created at (ISO or formatted string).
                              type: string
                            updatedAt:
                              nullable: true
                              description: Updated at (ISO or formatted string).
                              type: string
                            deletedAt:
                              nullable: true
                              description: Soft-delete timestamp when set.
                              type: string
                          additionalProperties: false
                    required:
                      - id
                    additionalProperties: false
                    description: >-
                      Single deal after create or update, with nested product,
                      eventCall, and transactions.
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  id: 1
                  productId: 1
                  contactId: 1
                  eventCallId: 1
                  userId: 1
                  tagId: 1
                  value: 100
                  time: '2026-03-05T10:21:59.645Z'
                  recurring: false
                  transactionType: WON
                  createdAt: '2026-03-05T10:25:17.249Z'
                  updatedAt: '2026-03-05T10:25:17.249Z'
                  product:
                    name: Mobile
                  eventCall:
                    id: 1
                    userId: 1
                    eventId: 1
                    previewId: call_2R7eYeyxwmn6
                    callType: STRATEGY_EVENT
                    dateTime: '2025-12-16T05:45:00.000Z'
                    user:
                      id: 1
                      firstName: Development
                      lastName: ''
                      email: dev@iclosed.io
                      phoneNumber: null
                    contact:
                      id: 1
                      firstName: Eugenia
                      lastName: Castro
                      email: castro@iclsoed.io
                      phoneNumber: '+16676169152'
                    event:
                      id: 1
                      eventType: STRATEGY_EVENT
                      name: Phone Call
                      color: '#0099FF'
                      duration: 30
                      durationUnit: MINUTES
                  transaction: []
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    put:
      operationId: updateDeal
      summary: Update a deal
      description: >-
        Update an existing deal. Required: id. Optional: value, recurring,
        transactionType, closerId, etc.
      tags:
        - Deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Deal id to update.
                value:
                  description: Updated deal value.
                  type: number
                recurring:
                  description: Whether the deal is recurring.
                  type: boolean
                transactionType:
                  description: Updated transaction type.
                  type: string
                  enum:
                    - WON
                    - RECURRING
                    - DEPOSIT
                productId:
                  description: Reassign deal to another product.
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                closerId:
                  description: User id of the closer (assignee).
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                time:
                  description: >-
                    Updated deal time as ISO 8601 datetime; must be in the
                    future when provided.
                  type: string
                  format: date-time
                transactionIds:
                  description: Transaction ids to link or sync with this deal.
                  type: array
                  items:
                    type: integer
                    minimum: 0
                    maximum: 2147483647
                type:
                  description: Deal vs transaction classification.
                  type: string
                  enum:
                    - DEAL
                    - TRANSACTION
                email:
                  description: Email context for the update when required by the service.
                  type: string
                  format: email
              required:
                - id
              additionalProperties: false
              example:
                id: 1
                value: 150
                recurring: false
                transactionType: WON
            example:
              id: 1
              value: 150
              recurring: false
              transactionType: WON
      responses:
        '200':
          description: Successfully updated deal
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Deal id.
                      productId:
                        nullable: true
                        description: Linked product id.
                        type: number
                      contactId:
                        nullable: true
                        description: Linked contact id.
                        type: number
                      eventCallId:
                        nullable: true
                        description: Linked event call id.
                        type: number
                      userId:
                        nullable: true
                        description: Assignee user id.
                        type: number
                      tagId:
                        nullable: true
                        description: Tag id on the deal when set.
                        type: number
                      value:
                        description: Deal value (number or string).
                        anyOf:
                          - type: number
                            nullable: true
                          - type: string
                            nullable: true
                      time:
                        nullable: true
                        description: Deal time (ISO or formatted string).
                        type: string
                      recurring:
                        nullable: true
                        description: Whether the deal is recurring.
                        type: boolean
                      transactionType:
                        nullable: true
                        description: Transaction type label.
                        type: string
                        enum:
                          - WON
                          - RECURRING
                          - DEPOSIT
                      createdAt:
                        nullable: true
                        description: Created at.
                        type: string
                      updatedAt:
                        nullable: true
                        description: Updated at.
                        type: string
                      product:
                        nullable: true
                        description: Minimal product info (name).
                        type: object
                        properties:
                          name:
                            nullable: true
                            description: Product display name on the deal response.
                            type: string
                        additionalProperties: false
                      eventCall:
                        nullable: true
                        description: >-
                          Booking / call context with nested user, contact,
                          event.
                        type: object
                        properties:
                          id:
                            type: number
                            description: Event call / booking id.
                          userId:
                            nullable: true
                            description: Host or assigned user id.
                            type: number
                          eventId:
                            nullable: true
                            description: Template event id.
                            type: number
                          previewId:
                            nullable: true
                            description: Preview or widget session id.
                            type: string
                          callType:
                            nullable: true
                            description: Kind of call or meeting.
                            type: string
                          dateTime:
                            nullable: true
                            description: Scheduled start as ISO or formatted string.
                            type: string
                          user:
                            nullable: true
                            description: User on the call.
                            type: object
                            properties:
                              id:
                                type: number
                                description: User id.
                              firstName:
                                nullable: true
                                description: First name.
                                type: string
                              lastName:
                                nullable: true
                                description: Last name.
                                type: string
                              email:
                                nullable: true
                                description: Email.
                                type: string
                                format: email
                              phoneNumber:
                                nullable: true
                                description: Phone number.
                                type: string
                            required:
                              - id
                            additionalProperties: false
                          contact:
                            nullable: true
                            description: Contact on the call.
                            type: object
                            properties:
                              id:
                                type: number
                                description: Contact id.
                              firstName:
                                nullable: true
                                description: First name.
                                type: string
                              lastName:
                                nullable: true
                                description: Last name.
                                type: string
                              email:
                                nullable: true
                                description: Email.
                                type: string
                                format: email
                              phoneNumber:
                                nullable: true
                                description: Phone number.
                                type: string
                            required:
                              - id
                            additionalProperties: false
                          event:
                            nullable: true
                            description: Event definition for the call.
                            type: object
                            properties:
                              id:
                                type: number
                                description: Event id.
                              eventType:
                                nullable: true
                                description: Event type discriminator.
                                type: string
                              name:
                                nullable: true
                                description: Event display name.
                                type: string
                              color:
                                nullable: true
                                description: Event color.
                                type: string
                              duration:
                                nullable: true
                                description: Scheduled duration magnitude.
                                type: number
                              durationUnit:
                                nullable: true
                                description: Unit for duration (e.g. minutes).
                                type: string
                            required:
                              - id
                            additionalProperties: false
                        required:
                          - id
                        additionalProperties: false
                      transaction:
                        nullable: true
                        description: Transactions associated with this deal.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              nullable: true
                              description: Transaction id.
                              type: number
                            accountId:
                              nullable: true
                              description: Owning account id.
                              type: number
                            syncedDeal:
                              nullable: true
                              description: Linked deal id when synced.
                              type: number
                            name:
                              nullable: true
                              description: Counterparty or transaction name.
                              type: string
                            email:
                              nullable: true
                              description: Email on the transaction.
                              type: string
                              format: email
                            phoneNumber:
                              nullable: true
                              description: Phone on the transaction.
                              type: string
                            description:
                              nullable: true
                              description: Free-text description.
                              type: string
                            value:
                              description: Transaction amount (number or string).
                              anyOf:
                                - type: number
                                  nullable: true
                                - type: string
                                  nullable: true
                            currency:
                              nullable: true
                              description: Currency code or label.
                              type: string
                            source:
                              nullable: true
                              description: Origin system or channel.
                              type: string
                            updatedBy:
                              nullable: true
                              description: Actor or label for last update.
                              type: string
                            createdAt:
                              nullable: true
                              description: Created at (ISO or formatted string).
                              type: string
                            updatedAt:
                              nullable: true
                              description: Updated at (ISO or formatted string).
                              type: string
                            deletedAt:
                              nullable: true
                              description: Soft-delete timestamp when set.
                              type: string
                          additionalProperties: false
                    required:
                      - id
                    additionalProperties: false
                    description: >-
                      Single deal after create or update, with nested product,
                      eventCall, and transactions.
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  id: 1
                  productId: 1
                  contactId: 1
                  eventCallId: 1
                  userId: 1
                  tagId: 1
                  value: 100
                  time: '2026-03-05T10:21:59.645Z'
                  recurring: false
                  transactionType: WON
                  createdAt: '2026-03-05T10:25:17.249Z'
                  updatedAt: '2026-03-05T10:25:17.249Z'
                  product:
                    name: Mobile
                  eventCall:
                    id: 1
                    userId: 1
                    eventId: 1
                    previewId: call_2R7eYeyxwmn6
                    callType: STRATEGY_EVENT
                    dateTime: '2025-12-16T05:45:00.000Z'
                    user:
                      id: 1
                      firstName: Development
                      lastName: ''
                      email: dev@iclosed.io
                      phoneNumber: null
                    contact:
                      id: 1
                      firstName: Eugenia
                      lastName: Castro
                      email: castro@iclsoed.io
                      phoneNumber: '+16676169152'
                    event:
                      id: 1
                      eventType: STRATEGY_EVENT
                      name: Phone Call
                      color: '#0099FF'
                      duration: 30
                      durationUnit: MINUTES
                  transaction: []
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/eventCalls:
    post:
      operationId: createEventCall
      summary: Create Call
      description: >-
        Create a new event call with minimal payload. Adapter gets accountId
        from auth, validates event/contact belong to account, and fills invitee
        answers from contact. Optional secondaryQuestionsAnswer: identify each
        item by customFieldId or identifier; answer is always an array of
        strings (one element for single-value types, multiple for
        MULTIPLE_SELECT).
      tags:
        - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                contactId:
                  description: Contact ID (optional if email or phoneNumber is provided)
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                email:
                  description: >-
                    Invitee email (required when contactId is not provided);
                    must be valid when provided
                  anyOf:
                    - type: string
                      maxLength: 255
                      format: email
                    - type: string
                      enum:
                        - ''
                phoneNumber:
                  description: >-
                    Invitee phone (required when contactId is not provided);
                    must be valid when provided
                  type: string
                firstName:
                  description: Invitee first name
                  type: string
                lastName:
                  description: Invitee last name
                  type: string
                eventId:
                  description: Event ID (optional if linkPrefix is provided)
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                linkPrefix:
                  description: >-
                    Event link prefix (e.g. "company/meeting"); resolved to
                    eventId when provided
                  type: string
                  minLength: 1
                dateTime:
                  type: string
                  minLength: 1
                  format: date-time
                  description: ISO 8601 date-time in UTC (e.g. 2026-02-27T12:00:00.000Z)
                timeZone:
                  type: string
                  minLength: 1
                  description: IANA time zone for the booking
                conditionalUsers:
                  description: >-
                    Optional comma-separated user IDs used to restrict booking
                    assignment
                  type: string
                secondaryQuestionsAnswer:
                  default: []
                  description: >-
                    Optional secondary custom field answers to attach when
                    creating the booking
                  type: array
                  items:
                    type: object
                    properties:
                      customFieldId:
                        description: Custom field ID (use when identifier is not provided)
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                      identifier:
                        description: >-
                          Custom field identifier/slug (use when customFieldId
                          is not provided)
                        type: string
                        minLength: 1
                      answer:
                        type: array
                        items:
                          type: string
                        description: >-
                          Answer value(s); always an array (one element for
                          single-value types, multiple for MULTIPLE_SELECT)
                    required:
                      - answer
                    additionalProperties: false
                additionalGuests:
                  description: >-
                    Optional extra attendees when the event has
                    allowInviteeAdditionalGuests (max 5); merged with internal
                    host list server-side
                  maxItems: 5
                  type: array
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                        format: email
                        description: Additional guest email
                      name:
                        description: Optional display name
                        type: string
                        maxLength: 500
                    required:
                      - email
                    additionalProperties: false
              required:
                - dateTime
                - timeZone
                - secondaryQuestionsAnswer
              additionalProperties: false
            examples:
              byEventAndContactIds:
                summary: By eventId, contactId, and customFieldIds
                value:
                  eventId: 1
                  contactId: 42
                  dateTime: '2026-03-15T14:00:00.000Z'
                  timeZone: America/New_York
                  secondaryQuestionsAnswer:
                    - customFieldId: 2383
                      answer:
                        - 'No'
                    - customFieldId: 2
                      answer:
                        - '31'
                    - customFieldId: 3
                      answer:
                        - Option A
                        - Option B
                  additionalGuests:
                    - email: colleague@company.com
                      name: Alex Guest
              byLinkPrefixAndIdentifiers:
                summary: By linkPrefix, contact details, and identifiers
                value:
                  linkPrefix: company/discovery-call
                  firstName: Jane
                  lastName: Doe
                  email: jane.doe@example.com
                  phoneNumber: +1 (555) 123-4567
                  dateTime: '2026-03-15T14:00:00.000Z'
                  timeZone: America/New_York
                  secondaryQuestionsAnswer:
                    - identifier: preferred-time
                      answer:
                        - Morning
                    - identifier: company-size
                      answer:
                        - 11-50
                    - identifier: notes
                      answer:
                        - Looking forward to the call.
      responses:
        '201':
          description: Event call created
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      eventCall:
                        type: object
                        properties:
                          message:
                            type: string
                            description: Success message
                          status:
                            type: integer
                            minimum: 0
                            maximum: 2147483647
                            description: HTTP status
                          data:
                            type: object
                            properties:
                              startTime:
                                type: string
                                description: Booking start time (ISO 8601)
                              endTime:
                                type: string
                                description: Booking end time (ISO 8601)
                              id:
                                type: integer
                                minimum: 0
                                maximum: 2147483647
                                description: Created event call ID
                              closerId:
                                type: integer
                                minimum: 0
                                maximum: 2147483647
                                description: User ID assigned to the call
                              timeZone:
                                type: string
                                description: Call timezone
                              guestEmail:
                                type: string
                                description: Invitee email
                              token:
                                type: string
                                description: Encrypted link (e.g. for confirmation page)
                              closerName:
                                type: string
                                description: Assigned user full name
                              previewId:
                                type: string
                                description: Event call preview ID (e.g. call_xxxx)
                              closerEmail:
                                type: string
                                description: Assigned user email
                              redirectUrl:
                                description: >-
                                  URL to redirect the invitee to after booking.
                                  Present only when the event’s
                                  confirmationPageType is EXTERNAL.
                                type: string
                              confirmationLink:
                                type: string
                                description: Event confirmation link
                            required:
                              - startTime
                              - endTime
                              - id
                              - closerId
                              - timeZone
                              - guestEmail
                              - token
                              - closerName
                              - previewId
                              - closerEmail
                              - confirmationLink
                            additionalProperties: false
                            description: Created event call payload
                        required:
                          - message
                          - status
                          - data
                        additionalProperties: false
                    required:
                      - eventCall
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  eventCall:
                    message: Event call created successfully
                    status: 200
                    data:
                      startTime: '2026-03-15T14:00:00.000Z'
                      endTime: '2026-03-15T14:15:00.000Z'
                      id: 1585584
                      closerId: 3685
                      timeZone: America/New_York
                      guestEmail: nayyab142@iclosed.io
                      token: >-
                        ULC5lA1vKpS3OLD+m07eOz1U9/mAaXm6Q2j7wLCp1agN53Qt2gYOmbqAx3UQfMmMRQU4FIdSuh0kbIbUJBeBmw==
                      closerName: zarrar khan
                      previewId: call_fBdaH9gAZm8h
                      closerEmail: zarrar1961@gmail.com
                      confirmationLink: www.google.com
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    get:
      operationId: searchEventCall
      summary: Get Calls
      description: >-
        Search event calls. Supports single filters (id, eventId, userId,
        contactId, previewId, dateTime), location filter (comma-separated
        location values), scheduled date range (dateFrom, dateTo), creation date
        range (createdAtStart, createdAtEnd), eventType (e.g. PAST, UPCOMING,
        ALL), pagination (limit, page), ordering (orderColumn: createdAt |
        dateTime | updatedAt | id with orderBy: asc | desc), and comma-separated
        lists (ids, userIds, teamIds, eventIds, types, inviteeEmails, outcomes,
        noSaleReason, utmKeys, utmValues, callTypes, setterIds). Caller parses
        comma-separated values.
      tags:
        - Calls
      parameters:
        - name: ids
          in: query
          schema:
            description: Comma-separated event call IDs to include
            type: string
          description: Comma-separated event call IDs to include
        - name: contactId
          in: query
          schema:
            description: Filter by contact ID
            type: integer
            exclusiveMinimum: true
            maximum: 2147483647
            minimum: 0
          description: Filter by contact ID
        - name: eventType
          in: query
          schema:
            type: string
            enum:
              - PAST
              - UPCOMING
              - ALL
          description: 'Time-window filter: PAST, UPCOMING, or ALL'
        - name: search
          in: query
          schema:
            description: Free-text search across invitee/contact name, email, and phone
            type: string
          description: Free-text search across invitee/contact name, email, and phone
        - name: dateFrom
          in: query
          schema:
            description: Start of date range filter (inclusive)
            type: string
          description: Start of date range filter (inclusive)
        - name: dateTo
          in: query
          schema:
            description: End of date range filter (inclusive)
            type: string
          description: End of date range filter (inclusive)
        - name: createdAtStart
          in: query
          schema:
            description: Start of creation date range filter (inclusive)
            type: string
          description: Start of creation date range filter (inclusive)
        - name: createdAtEnd
          in: query
          schema:
            description: End of creation date range filter (inclusive)
            type: string
          description: End of creation date range filter (inclusive)
        - name: location
          in: query
          schema:
            description: >-
              Comma-separated location filter values (e.g.
              PHONE_CALL,GOOGLE_MEET)
            type: string
          description: Comma-separated location filter values (e.g. PHONE_CALL,GOOGLE_MEET)
        - name: orderColumn
          in: query
          schema:
            type: string
            enum:
              - createdAt
              - dateTime
              - updatedAt
              - id
          description: 'Sort column for result ordering: createdAt, dateTime, updatedAt, id'
        - name: orderBy
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: >-
            Sort direction: asc or desc. Required together with orderColumn when
            sorting
        - name: limit
          in: query
          schema:
            default: 20
            description: Maximum number of records per page
            type: integer
            minimum: 1
            maximum: 100
          description: Maximum number of records per page
        - name: page
          in: query
          schema:
            description: Zero-based page index
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index
        - name: userIds
          in: query
          schema:
            description: Comma-separated assigned user IDs
            type: string
          description: Comma-separated assigned user IDs
        - name: eventIds
          in: query
          schema:
            description: Comma-separated event template IDs
            type: string
          description: Comma-separated event template IDs
        - name: types
          in: query
          schema:
            description: >-
              Comma-separated. Allowed values: rescheduled_events,
              cancelled_events, scheduled_events
            type: string
          description: >-
            Comma-separated. Allowed values: rescheduled_events,
            cancelled_events, scheduled_events
        - name: inviteeEmails
          in: query
          schema:
            description: Comma-separated invitee email addresses
            type: string
          description: Comma-separated invitee email addresses
        - name: outcomes
          in: query
          schema:
            description: >-
              Comma-separated. Allowed values: WON, NO_SALE, QUALIFIED,
              UNQUALIFIED, PENDING, APPROVED, REJECTED, PENDING_OUTCOME
            type: string
          description: >-
            Comma-separated. Allowed values: WON, NO_SALE, QUALIFIED,
            UNQUALIFIED, PENDING, APPROVED, REJECTED, PENDING_OUTCOME
        - name: noSaleReason
          in: query
          schema:
            description: >-
              Comma-separated. Allowed values: FOLLOW_UP_SCHEDULE, UNQUALIFIED,
              NO_SHOW, CONTACT_CANCELLED, ADMIN_CANCELLED, NOT_INTERESTED,
              BAD_FIT, OTHER
            type: string
          description: >-
            Comma-separated. Allowed values: FOLLOW_UP_SCHEDULE, UNQUALIFIED,
            NO_SHOW, CONTACT_CANCELLED, ADMIN_CANCELLED, NOT_INTERESTED,
            BAD_FIT, OTHER
        - name: utmKeys
          in: query
          schema:
            description: Comma-separated UTM parameter keys to filter by
            type: string
          description: Comma-separated UTM parameter keys to filter by
        - name: utmValues
          in: query
          schema:
            description: Comma-separated UTM parameter values to filter by
            type: string
          description: Comma-separated UTM parameter values to filter by
        - name: callTypes
          in: query
          schema:
            description: 'Comma-separated. Allowed values: STRATEGY_EVENT, DISCOVERY_EVENT'
            type: string
          description: 'Comma-separated. Allowed values: STRATEGY_EVENT, DISCOVERY_EVENT'
        - name: setterIds
          in: query
          schema:
            description: Comma-separated setter user IDs linked via SettedClaim
            type: string
          description: Comma-separated setter user IDs linked via SettedClaim
      responses:
        '201':
          description: List of event calls with count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      eventCalls:
                        description: List of matching event calls
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Event call ID
                            eventId:
                              type: number
                              description: Event template ID
                            dateTime:
                              type: string
                              description: Event call start date-time
                            userId:
                              description: Assigned closer user ID
                              nullable: true
                              type: integer
                              minimum: 0
                              maximum: 2147483647
                            location:
                              description: Location type (e.g. PHONE_CALL, GOOGLE_MEET)
                              nullable: true
                              type: string
                            notes:
                              description: Notes attached to the event call
                              nullable: true
                              type: string
                            isCalendarConnected:
                              description: >-
                                Whether calendar sync was connected at booking
                                time
                              nullable: true
                              type: boolean
                            isZoomConnected:
                              description: >-
                                Whether Zoom integration was connected at
                                booking time
                              nullable: true
                              type: boolean
                            cancelReason:
                              description: Cancellation reason
                              nullable: true
                              type: string
                            locationLink:
                              description: Primary meeting location/join URL
                              nullable: true
                              type: string
                            locationLinkInvitee:
                              description: Invitee-facing location/join URL
                              nullable: true
                              type: string
                            rescheduledBy:
                              description: Actor that rescheduled the call
                              nullable: true
                              type: string
                            rescheduleReason:
                              description: Reason provided when call was rescheduled
                              nullable: true
                              type: string
                            cancelledBy:
                              description: Actor that cancelled the call
                              nullable: true
                              type: string
                            callType:
                              description: Event call type
                              nullable: true
                              type: string
                              enum:
                                - STRATEGY_EVENT
                                - DISCOVERY_EVENT
                            isSlotFree:
                              description: >-
                                Whether this event appears as
                                free/busy-transparent
                              nullable: true
                              type: boolean
                            overBooked:
                              description: Overbooking count for this call instance
                              type: number
                            totalOverBooked:
                              description: Total overbooking count for this slot
                              type: number
                            breakBefore:
                              description: Break before this event call
                              type: number
                            breakAfter:
                              description: Break after this event call
                              type: number
                            createdAt:
                              description: Event call creation timestamp
                              type: string
                            updatedAt:
                              description: Event call last update timestamp
                              type: string
                            googleResponseStatus:
                              description: Google Calendar attendee/response status
                              nullable: true
                              type: string
                            additionalGuests:
                              description: >-
                                Merged additional attendees for this booking
                                (internal list + invitee extras)
                              nullable: true
                              type: array
                              items:
                                type: object
                                properties:
                                  email:
                                    type: string
                                    description: Normalized email
                                  source:
                                    type: string
                                    enum:
                                      - internal
                                      - invitee
                                    description: From event template list vs invitee form
                                  name:
                                    description: Optional display name
                                    type: string
                                required:
                                  - email
                                  - source
                                additionalProperties: false
                            contactId:
                              description: Linked contact ID
                              nullable: true
                              type: number
                            user:
                              description: Assigned user summary
                              nullable: true
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Assigned user ID
                                firstName:
                                  description: Assigned user first name
                                  nullable: true
                                  type: string
                                lastName:
                                  description: Assigned user last name
                                  nullable: true
                                  type: string
                                email:
                                  description: Assigned user email
                                  nullable: true
                                  type: string
                              required:
                                - id
                              additionalProperties: false
                            callId:
                              type: number
                              description: Underlying call record ID
                            deals:
                              description: Deals linked to the contact/event call
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: number
                                    description: Deal ID
                                  value:
                                    type: number
                                    description: Deal value amount
                                  time:
                                    description: Deal timestamp
                                    nullable: true
                                    type: string
                                  transactionType:
                                    description: Transaction type associated with the deal
                                    nullable: true
                                    type: string
                                    enum:
                                      - WON
                                      - RECURRING
                                      - DEPOSIT
                                  product:
                                    description: Product associated with the deal
                                    nullable: true
                                    type: object
                                    properties:
                                      id:
                                        type: number
                                        description: Product ID linked to the deal
                                      name:
                                        description: Product name
                                        nullable: true
                                        type: string
                                    required:
                                      - id
                                    additionalProperties: false
                                  Transaction:
                                    description: Transaction record linked to the deal
                                    nullable: true
                                    type: object
                                    properties:
                                      id:
                                        type: number
                                        description: Transaction ID linked to this deal
                                    required:
                                      - id
                                    additionalProperties: false
                                required:
                                  - id
                                  - value
                                additionalProperties: false
                            task:
                              description: Linked task records
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: number
                                    description: Task ID linked to the event call
                                  completed:
                                    type: boolean
                                    description: Whether the task has been completed
                                  outcome:
                                    description: Recorded task outcome
                                    nullable: true
                                    type: string
                                  noSaleReason:
                                    description: No-sale reason when outcome is NO_SALE
                                    nullable: true
                                    type: string
                                  objection:
                                    description: Primary objection captured for the task
                                    nullable: true
                                    type: string
                                  notes:
                                    description: Task notes entered by the user
                                    nullable: true
                                    type: string
                                required:
                                  - id
                                  - completed
                                additionalProperties: false
                            inviteTimeZone:
                              description: Invitee-selected timezone
                              nullable: true
                              type: string
                            dateTimeUTC:
                              description: Event call start date-time normalized to UTC
                              type: string
                            inviteeEmail:
                              description: Invitee email captured at booking
                              nullable: true
                              type: string
                            inviteeName:
                              description: Invitee full name captured at booking
                              nullable: true
                              type: string
                            phoneNumber:
                              description: Invitee/contact primary phone number
                              nullable: true
                              type: string
                            questions:
                              description: Invitee question/answer pairs
                              type: array
                              items:
                                type: object
                                properties:
                                  statement:
                                    type: string
                                    description: Invitee question text
                                  answer:
                                    type: string
                                    description: Invitee answer text
                                required:
                                  - statement
                                  - answer
                                additionalProperties: false
                            secondaryAnswers:
                              description: Secondary custom field answers
                              type: array
                              items:
                                type: object
                                properties:
                                  statement:
                                    description: Secondary custom field question text
                                    nullable: true
                                    type: string
                                  isSecondaryQuestion:
                                    description: >-
                                      Whether this custom field is marked as
                                      secondary question
                                    type: boolean
                                  answer:
                                    description: >-
                                      Structured answer values for this
                                      secondary field
                                    type: array
                                    items:
                                      type: object
                                      properties:
                                        inputType:
                                          description: Custom field input type
                                          nullable: true
                                          type: string
                                          enum:
                                            - NUMBER
                                            - TEXT
                                            - TEXT_AREA
                                            - DATE
                                            - CHECK_BOX
                                            - RADIO_BUTTON
                                            - CONTACT
                                            - CONTACTS_MULTIPLE
                                            - USER
                                            - USERS_MULTIPLE
                                            - URL
                                            - SINGLE_SELECT
                                            - MULTIPLE_SELECT
                                            - EMAIL
                                            - RATING
                                        answer:
                                          description: String answer value
                                          nullable: true
                                          type: string
                                        date:
                                          description: Date answer value
                                          nullable: true
                                          type: string
                                        userId:
                                          description: >-
                                            User ID answer value when input type is
                                            user-based
                                          nullable: true
                                          type: number
                                        number:
                                          description: Numeric answer value
                                          nullable: true
                                          type: number
                                        user:
                                          description: >-
                                            Referenced user object for user-based
                                            answer values
                                          nullable: true
                                          type: object
                                          properties:
                                            firstName:
                                              description: Referenced user first name
                                              nullable: true
                                              type: string
                                            lastName:
                                              description: Referenced user last name
                                              nullable: true
                                              type: string
                                          additionalProperties: false
                                      additionalProperties: false
                                additionalProperties: false
                            eventType:
                              type: string
                              enum:
                                - UPCOMING
                                - PAST
                              description: Computed timing classification relative to now
                            utm:
                              description: UTM attributes tied to the contact/event
                              type: array
                              items:
                                type: object
                                properties:
                                  utmKey:
                                    type: string
                                    description: UTM parameter key
                                  utmValue:
                                    description: UTM parameter value
                                    nullable: true
                                    type: string
                                required:
                                  - utmKey
                                additionalProperties: false
                            contact:
                              description: Contact summary
                              nullable: true
                              type: object
                              properties:
                                email:
                                  description: Contact primary email
                                  nullable: true
                                  type: string
                                phoneNumber:
                                  description: Contact primary phone number
                                  nullable: true
                                  type: string
                                previewId:
                                  description: Contact preview ID
                                  nullable: true
                                  type: string
                                secondary_email:
                                  description: Contact secondary email
                                  nullable: true
                                  type: string
                                secondary_phoneNumber:
                                  description: Contact secondary phone number
                                  nullable: true
                                  type: string
                              additionalProperties: false
                            event:
                              description: Event template summary
                              nullable: true
                              type: object
                              properties:
                                allowInviteeAdditionalGuests:
                                  description: Whether invitee can add additional guests
                                  nullable: true
                                  type: boolean
                                allowReschedule:
                                  description: Whether invitee can reschedule this event
                                  nullable: true
                                  type: boolean
                                color:
                                  description: Event color
                                  nullable: true
                                  type: string
                                duration:
                                  description: Default event duration
                                  type: number
                                durationUnit:
                                  description: Default event duration unit
                                  nullable: true
                                  type: string
                                eventType:
                                  description: Event type
                                  nullable: true
                                  type: string
                                internalDescription:
                                  description: Internal event description
                                  nullable: true
                                  type: string
                                linkPrefix:
                                  description: Public booking link prefix
                                  nullable: true
                                  type: string
                                location:
                                  description: Event location type
                                  nullable: true
                                  type: string
                                name:
                                  description: Event name
                                  nullable: true
                                  type: string
                              additionalProperties: false
                          required:
                            - id
                            - eventId
                            - dateTime
                            - callId
                            - eventType
                          additionalProperties: false
                      count:
                        description: Total number of matching event calls
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  eventCalls:
                    - id: 4
                      eventId: 2
                      dateTime: '2025-12-16 10:15:00.000'
                      userId: 5
                      location: PHONE_CALL
                      notes: null
                      isCalendarConnected: false
                      isZoomConnected: false
                      cancelReason: null
                      locationLink: null
                      locationLinkInvitee: null
                      rescheduledBy: null
                      rescheduleReason: null
                      cancelledBy: null
                      callType: STRATEGY_EVENT
                      overBooked: 0
                      totalOverBooked: 0
                      duration: 30
                      durationUnit: MINUTES
                      breakBefore: 0
                      breakAfter: 0
                      createdAt: '2025-12-10T13:53:59.235Z'
                      updatedAt: '2025-12-10T13:54:00.951Z'
                      googleResponseStatus: null
                      additionalGuests: null
                      isSlotFree: false
                      contactId: 2
                      user:
                        id: 5
                        firstName: Development
                        lastName: ''
                        email: dev@iclosed.io
                      callId: 4
                      deals:
                        - id: 3
                          value: '123'
                          time: '2026-01-21T05:47:37.918Z'
                          transactionType: WON
                          product:
                            id: 1
                            name: Mobile
                          Transaction: []
                      task:
                        - id: 4
                          completed: true
                          outcome: WON
                          noSaleReason: null
                          objection: MONEY
                          notes: <!DOCTYPE quill-output-html><p>hello</p>
                      inviteTimeZone: Asia/Karachi
                      dateTimeUTC: '2025-12-16T05:15:00.000Z'
                      inviteeEmail: genevieve@iclosed.io
                      inviteeName: Genevieve Duke
                      phoneNumber: '+18054666813'
                      questions:
                        - statement: Phone Number
                          answer: '+18054666813'
                        - statement: Full Name
                          answer: Genevieve Duke
                      secondaryAnswers:
                        - statement: Set by
                          isSecondaryQuestion: false
                          answer:
                            - inputType: USER
                              answer: null
                              date: null
                              userId: 5
                              number: null
                              user:
                                firstName: Development
                                lastName: ''
                        - statement: Objection
                          isSecondaryQuestion: false
                          answer:
                            - inputType: SINGLE_SELECT
                              answer: MONEY
                              date: null
                              userId: null
                              number: null
                              user: null
                        - statement: Call Outcome
                          isSecondaryQuestion: false
                          answer:
                            - inputType: SINGLE_SELECT
                              answer: WON
                              date: null
                              userId: null
                              number: null
                              user: null
                      eventType: PAST
                      utm:
                        - utmKey: string
                          utmValue: ''
                        - utmKey: utm_source
                          utmValue: google
                        - utmKey: utm_medium
                          utmValue: cpc
                      contact:
                        email: genevieve@iclosed.io
                        phoneNumber: '+18054666813'
                        previewId: contact_xeKmDXhxrxGT
                        secondary_email: null
                        secondary_phoneNumber: null
                      event:
                        allowInviteeAdditionalGuests: false
                        allowReschedule: true
                        color: '#0099FF'
                        duration: 30
                        durationUnit: MINUTES
                        eventType: STRATEGY_EVENT
                        internalDescription: ''
                        linkPrefix: dev/phone-call
                        location: PHONE_CALL
                        name: Phone Call
                  count: 8
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/eventCalls/reschedule:
    put:
      operationId: rescheduleEventCall
      summary: Reschedule Call
      description: >-
        Reschedule an existing event call. Body: id, dateTime, timeZone,
        rescheduleReason, notes, userId.
      tags:
        - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  exclusiveMinimum: true
                  maximum: 2147483647
                  description: Event call ID to reschedule
                  minimum: 0
                dateTime:
                  type: string
                  minLength: 1
                  description: New call start date-time in ISO 8601 format
                timeZone:
                  type: string
                  minLength: 1
                  description: IANA time zone used to interpret the new dateTime
                rescheduleReason:
                  description: Reason provided for rescheduling the event call
                  type: string
                notes:
                  description: Optional internal notes for this reschedule action
                  type: string
                userId:
                  description: Optional reassigned closer user ID
                  type: integer
                  exclusiveMinimum: true
                  maximum: 2147483647
                  minimum: 0
                additionalGuests:
                  description: >-
                    Optional replacement list of invitee-supplied extra guests
                    when the event allows (max 5); omit to keep prior invitee
                    extras out of merge
                  maxItems: 5
                  type: array
                  items:
                    type: object
                    properties:
                      email:
                        type: string
                        format: email
                        description: Additional guest email
                      name:
                        description: Optional display name
                        type: string
                        maxLength: 500
                    required:
                      - email
                    additionalProperties: false
              required:
                - id
                - dateTime
                - timeZone
              additionalProperties: false
              example:
                id: 1585584
                dateTime: '2026-07-24T16:45:00.000Z'
                timeZone: America/New_York
                rescheduleReason: Client requested a different time
                notes: Internal note for the reschedule
                userId: 3685
                additionalGuests:
                  - email: colleague@company.com
                    name: Alex Guest
            example:
              id: 1585584
              dateTime: '2026-07-24T16:45:00.000Z'
              timeZone: America/New_York
              rescheduleReason: Client requested a different time
              notes: Internal note for the reschedule
              userId: 3685
              additionalGuests:
                - email: colleague@company.com
                  name: Alex Guest
      responses:
        '200':
          description: Call rescheduled
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: Success message
                  status:
                    type: integer
                    minimum: 0
                    maximum: 2147483647
                    description: HTTP status
                  data:
                    type: object
                    properties:
                      closerName:
                        type: string
                        description: Assigned user full name
                      closerEmail:
                        type: string
                        description: Assigned user email
                      dateTime:
                        type: string
                        description: New date-time of the call (ISO 8601)
                      duration:
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                        description: Call duration
                      durationUnit:
                        type: string
                        description: Duration unit (e.g. MINUTES)
                      name:
                        type: string
                        description: Event/call name
                      location:
                        type: string
                        description: Location type (e.g. GOOGLE_MEET)
                      inviteeEmail:
                        type: string
                        description: Invitee email
                      inviteeName:
                        type: string
                        description: Invitee name
                      previewId:
                        type: string
                        description: Event call preview ID
                      userId:
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                        description: User ID assigned to the call
                    required:
                      - closerName
                      - closerEmail
                      - dateTime
                      - duration
                      - durationUnit
                      - name
                      - location
                      - inviteeEmail
                      - inviteeName
                      - previewId
                      - userId
                    additionalProperties: false
                required:
                  - message
                  - status
                  - data
                additionalProperties: false
              example:
                message: Event call updated successfully
                status: 200
                data:
                  closerName: zarrar khan
                  closerEmail: zarrar1961@gmail.com
                  dateTime: '2026-07-24T16:45:00.000Z'
                  duration: 15
                  durationUnit: MINUTES
                  name: Strategy Call-Mar05Chrome/Saf
                  location: GOOGLE_MEET
                  inviteeEmail: qazi.esa@iclosed.io
                  inviteeName: 'Qazi Essa '
                  previewId: call_5_KhTJJn5yjY
                  userId: 3685
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/eventCalls/cancel:
    put:
      operationId: cancelEventCall
      summary: Cancel Call
      description: 'Cancel a scheduled event call. id is required. Optional: cancelReason.'
      tags:
        - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Event call ID
                cancelReason:
                  description: Reason for cancellation
                  type: string
              required:
                - id
              additionalProperties: false
              example:
                id: 1585584
                cancelReason: Client requested cancellation
            example:
              id: 1585584
              cancelReason: Client requested cancellation
      responses:
        '200':
          description: Call cancelled
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      eventCall:
                        type: object
                        properties:
                          message:
                            type: string
                            description: Success message
                          status:
                            type: integer
                            minimum: 0
                            maximum: 2147483647
                            description: HTTP status
                        required:
                          - message
                          - status
                        additionalProperties: false
                    required:
                      - eventCall
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  eventCall:
                    message: Call cancelled successfully
                    status: 200
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/eventCalls/markSlotFree:
    put:
      operationId: updateSlotFree
      summary: Mark Booked Slot as Free
      description: >-
        Update whether an event call slot is free (transparent) or busy (opaque)
        in calendar. Required: id (event call ID), isSlotFree (boolean).
      tags:
        - Calls
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Event call ID
                isSlotFree:
                  type: boolean
                  description: Whether the slot is free (true) or busy (false)
              required:
                - id
                - isSlotFree
              additionalProperties: false
              example:
                id: 6
                isSlotFree: true
            example:
              id: 6
              isSlotFree: true
      responses:
        '200':
          description: Slot free status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Whether slot-free update succeeded
                  message:
                    type: string
                    description: Result message
                  data:
                    type: object
                    properties:
                      id:
                        type: number
                        description: Updated event call ID
                      isSlotFree:
                        type: boolean
                        description: Updated slot-free value
                      googleEventId:
                        description: Linked Google Calendar event ID when available
                        type: string
                    required:
                      - id
                      - isSlotFree
                    additionalProperties: false
                    description: Updated event call payload
                required:
                  - success
                  - message
                additionalProperties: false
              example:
                success: true
                message: Slot free status updated successfully
                data:
                  id: 6
                  isSlotFree: true
                  googleEventId: event_google_calendar_id_123
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/events:
    get:
      operationId: getEvents
      summary: Get Events
      description: >-
        List events for the authenticated account, or get a single event by
        id/token. Query: limit, page, id, token, search, userId, teamId, and
        other optional filters.
      tags:
        - Events
      parameters:
        - name: limit
          in: query
          schema:
            default: 10
            description: Maximum number of events returned per page
            type: integer
            minimum: 1
            maximum: 500
          description: Maximum number of events returned per page
        - name: page
          in: query
          schema:
            description: Zero-based page index
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index
        - name: search
          in: query
          schema:
            description: Free-text search term for event name/details
            type: string
          description: Free-text search term for event name/details
        - name: userId
          in: query
          schema:
            description: Filter by owner/host user ID
            type: integer
            exclusiveMinimum: true
            maximum: 2147483647
            minimum: 0
          description: Filter by owner/host user ID
        - name: eventType
          in: query
          schema:
            type: string
            enum:
              - STRATEGY_EVENT
              - DISCOVERY_EVENT
          description: Filter by event type
      responses:
        '200':
          description: List of events or single event
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Event list payload
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: Event ID
                        name:
                          description: Event display name
                          nullable: true
                          type: string
                        color:
                          description: Event color
                          nullable: true
                          type: string
                        eventType:
                          description: Event type
                          nullable: true
                          type: string
                          enum:
                            - STRATEGY_EVENT
                            - DISCOVERY_EVENT
                        description:
                          description: Public event description
                          nullable: true
                          type: string
                        internalDescription:
                          description: Internal-only event description
                          nullable: true
                          type: string
                        deletedAt:
                          description: Soft-delete timestamp
                          anyOf:
                            - type: string
                              format: date-time
                              nullable: true
                            - type: string
                              nullable: true
                        language:
                          description: Language code used by the event
                          nullable: true
                          type: string
                        emailValidationEnabled:
                          description: Whether invitee email validation is enabled
                          nullable: true
                          type: boolean
                        phoneNumberValidationEnabled:
                          description: Whether invitee phone validation is enabled
                          nullable: true
                          type: boolean
                        creditCheck:
                          description: Credit-check settings for the event
                          nullable: true
                          type: object
                          properties:
                            type:
                              description: >-
                                Credit-check discriminator or provider type (for
                                example CREDIT_CHECK_DTI_RATIO).
                              nullable: true
                              type: string
                            toggle:
                              description: Whether credit check is enabled for this event
                              type: boolean
                          additionalProperties: false
                        userId:
                          description: Primary owner user ID
                          nullable: true
                          type: number
                        duration:
                          description: Event duration value
                          nullable: true
                          type: number
                        durationUnit:
                          description: Duration unit (typically MINUTES)
                          nullable: true
                          type: string
                        location:
                          description: Event location type/provider
                          nullable: true
                          type: string
                          enum:
                            - PHONE_CALL
                            - ZOOM
                            - GOOGLE_MEET
                            - STATIC_LINK
                            - MICROSOFT_TEAMS
                            - HOST_PERSONAL_LINK
                        dateRangeType:
                          description: Date-range strategy
                          nullable: true
                          type: string
                        dateRangeUnit:
                          description: Date-range unit
                          nullable: true
                          type: string
                        linkPrefix:
                          description: Public booking link prefix
                          nullable: true
                          type: string
                        status:
                          description: Activation status of the event
                          nullable: true
                          type: string
                          enum:
                            - ACTIVATED
                            - DEACTIVATED
                        allowReschedule:
                          description: Whether invitees can reschedule
                          nullable: true
                          type: boolean
                        phonePreferred:
                          description: Whether phone input is preferred
                          nullable: true
                          type: boolean
                        splitFullName:
                          description: Whether first/last names are collected separately
                          nullable: true
                          type: boolean
                        businessEmail:
                          description: Whether business email is required/enforced
                          nullable: true
                          type: boolean
                        disableDuplicateBooking:
                          description: Whether duplicate bookings are blocked
                          nullable: true
                          type: boolean
                        lockHostOnReschedule:
                          description: Whether host remains fixed on reschedule
                          nullable: true
                          type: boolean
                        dateRangeDays:
                          description: Number of days included in booking range
                          nullable: true
                          type: number
                        bypassQuestion:
                          description: Whether invitee questions are bypassed
                          nullable: true
                          type: boolean
                        internalGuestEmails:
                          description: Emails included on every booking from this event
                          nullable: true
                          type: array
                          items:
                            type: string
                        allowInviteeAdditionalGuests:
                          description: >-
                            Whether invitees may add extra guest emails when
                            booking
                          nullable: true
                          type: boolean
                      required:
                        - id
                      additionalProperties: false
                  count:
                    description: Count of items returned in current payload
                    type: number
                  totalCount:
                    description: Total count matching applied filters
                    type: number
                  hasVisibleEvents:
                    description: Whether account has any events visible to the caller
                    type: boolean
                additionalProperties: false
              example:
                count: 126
                totalCount: 126
                hasVisibleEvents: true
                data:
                  - id: 8022
                    userId: 3684
                    duration: 15
                    durationUnit: MINUTES
                    location: GOOGLE_MEET
                    dateRangeType: DEFINITE
                    dateRangeUnit: CALENDAR_DAYS
                    linkPrefix: support5/support5
                    status: ACTIVATED
                    allowReschedule: true
                    phonePreferred: true
                    splitFullName: true
                    businessEmail: false
                    disableDuplicateBooking: false
                    lockHostOnReschedule: false
                    dateRangeDays: 13
                    bypassQuestion: false
                  - id: 8023
                    name: Enoch
                    color: '#0099FF'
                    eventType: STRATEGY_EVENT
                    description: >-
                      <p>gjashgcjhvadsbnmc dsbcjkdsbjkfcbsdjk cdskjbckjebfckjbhs
                      hgjbrejbgvjkhegfbgvkjehbv
                      fjkgbejkrtbgnkjetgbnjkegtnbjkrebtgkjehtbghjkerbtdhgkdvjk</p>
                    internalDescription: >-
                      gjashgcjhvadsbnmc dsbcjkdsbjkfcbsdjk cdskjbckjebfckjbhs
                      hgjbrejbgvjkhegfbgvkjehbv fjkgbejkrtbgnkjetg
                    deletedAt: null
                    language: ENGLISH
                    emailValidationEnabled: true
                    phoneNumberValidationEnabled: true
                    creditCheck:
                      type: CREDIT_CHECK_DTI_RATIO
                      toggle: true
                    userId: 3684
                    duration: 15
                    durationUnit: MINUTES
                    location: GOOGLE_MEET
                    dateRangeType: DEFINITE
                    dateRangeUnit: CALENDAR_DAYS
                    linkPrefix: support5/sms-test
                    status: ACTIVATED
                    allowReschedule: true
                    phonePreferred: false
                    splitFullName: true
                    businessEmail: false
                    disableDuplicateBooking: false
                    lockHostOnReschedule: false
                    dateRangeDays: 14
                    bypassQuestion: false
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/events/detail:
    get:
      operationId: getEventById
      summary: Get Event By ID
      description: >-
        Get a single event by id for the authenticated account. Query: id
        (required) or linkPrefix (required).
      tags:
        - Events
      parameters:
        - name: id
          in: query
          schema:
            description: Event ID
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Event ID
        - name: linkPrefix
          in: query
          schema:
            description: Event link prefix
            type: string
          description: Event link prefix
      responses:
        '200':
          description: Single event detail
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Single event payload
                    type: object
                    properties:
                      id:
                        type: number
                        description: Event ID
                      name:
                        description: Event name
                        nullable: true
                        type: string
                      color:
                        description: Event color
                        nullable: true
                        type: string
                      eventType:
                        description: Event type
                        nullable: true
                        type: string
                        enum:
                          - STRATEGY_EVENT
                          - DISCOVERY_EVENT
                      description:
                        description: Public event description
                        nullable: true
                        type: string
                      internalDescription:
                        description: Internal-only event description
                        nullable: true
                        type: string
                      deletedAt:
                        description: Soft-delete timestamp
                        anyOf:
                          - type: string
                            format: date-time
                            nullable: true
                          - type: string
                            nullable: true
                      language:
                        description: Language code used by the event
                        nullable: true
                        type: string
                      emailValidationEnabled:
                        description: Whether invitee email validation is enabled
                        nullable: true
                        type: boolean
                      phoneNumberValidationEnabled:
                        description: Whether invitee phone validation is enabled
                        nullable: true
                        type: boolean
                      creditCheck:
                        description: Credit-check settings for the event
                        nullable: true
                        type: object
                        properties:
                          type:
                            description: >-
                              Credit-check discriminator or provider type (for
                              example CREDIT_CHECK_DTI_RATIO).
                            nullable: true
                            type: string
                          toggle:
                            description: Whether credit check is enabled for this event
                            type: boolean
                        additionalProperties: false
                      userId:
                        description: Primary owner/host user ID
                        type: number
                      duration:
                        description: Event duration value
                        nullable: true
                        type: number
                      durationUnit:
                        description: Duration unit (typically MINUTES)
                        nullable: true
                        type: string
                      location:
                        description: Event location type/provider
                        nullable: true
                        type: string
                        enum:
                          - PHONE_CALL
                          - ZOOM
                          - GOOGLE_MEET
                          - STATIC_LINK
                          - MICROSOFT_TEAMS
                          - HOST_PERSONAL_LINK
                      dateRangeType:
                        description: Date-range strategy
                        nullable: true
                        type: string
                      dateRangeUnit:
                        description: Date-range unit
                        nullable: true
                        type: string
                      linkPrefix:
                        description: Public booking link prefix
                        nullable: true
                        type: string
                      status:
                        description: Event activation status
                        nullable: true
                        type: string
                        enum:
                          - ACTIVATED
                          - DEACTIVATED
                      allowReschedule:
                        description: Whether invitees can reschedule
                        nullable: true
                        type: boolean
                      phonePreferred:
                        description: Whether phone input is preferred
                        nullable: true
                        type: boolean
                      splitFullName:
                        description: Whether first/last names are collected separately
                        nullable: true
                        type: boolean
                      businessEmail:
                        description: Whether business email is required/enforced
                        nullable: true
                        type: boolean
                      disableDuplicateBooking:
                        description: Whether duplicate bookings are blocked
                        nullable: true
                        type: boolean
                      lockHostOnReschedule:
                        description: Whether host remains fixed on reschedule
                        nullable: true
                        type: boolean
                      dateRangeDays:
                        description: Number of days included in booking range
                        nullable: true
                        type: number
                      bypassQuestion:
                        description: Whether invitee questions are bypassed
                        nullable: true
                        type: boolean
                      internalGuestEmails:
                        description: Emails included on every booking from this event
                        nullable: true
                        type: array
                        items:
                          type: string
                      allowInviteeAdditionalGuests:
                        description: >-
                          Whether invitees may add extra guest emails when
                          booking
                        nullable: true
                        type: boolean
                      eventImageId:
                        description: Linked event image record ID
                        nullable: true
                        type: number
                      accountId:
                        description: Owning account ID
                        type: number
                      staticLink:
                        description: Static public link when configured
                        nullable: true
                        type: string
                      linkHashForPublic:
                        description: Hash segment for public link
                        nullable: true
                        type: string
                      optimizePriorityType:
                        description: Host routing optimization mode (e.g. MANUAL)
                        nullable: true
                        type: string
                      dateRangeFrom:
                        description: Booking range start
                        anyOf:
                          - type: string
                            format: date-time
                            nullable: true
                          - type: string
                            nullable: true
                      dateRangeTo:
                        description: Booking range end
                        anyOf:
                          - type: string
                            format: date-time
                            nullable: true
                          - type: string
                            nullable: true
                      breakBefore:
                        description: Break duration before event
                        nullable: true
                        type: number
                      breakAfter:
                        description: Break duration after event
                        nullable: true
                        type: number
                      breakBeforeUnit:
                        description: Unit for break before
                        nullable: true
                        type: string
                      breakAfterUnit:
                        description: Unit for break after
                        nullable: true
                        type: string
                      limitation:
                        description: Scheduling limitation value
                        nullable: true
                        type: number
                      limitationUnit:
                        description: Unit for scheduling limitation
                        nullable: true
                        type: string
                      confirmationPageType:
                        description: Confirmation page destination type
                        nullable: true
                        type: string
                      replyWithHost:
                        description: Whether replies include host
                        nullable: true
                        type: boolean
                      includeLinkInEmail:
                        description: Whether booking link is included in emails
                        nullable: true
                        type: boolean
                      confirmationLink:
                        description: Custom confirmation link
                        nullable: true
                        type: string
                      addMiniEmbed:
                        description: Whether mini embed is enabled
                        nullable: true
                        type: boolean
                      enableParamsForwarding:
                        description: Whether query params are forwarded
                        nullable: true
                        type: boolean
                      confirmationEmailSubject:
                        description: Invitee confirmation email subject (HTML)
                        nullable: true
                        type: string
                      confirmationEmailBody:
                        description: Invitee confirmation email body (HTML)
                        nullable: true
                        type: string
                      cancellationEmailSubject:
                        description: Invitee cancellation email subject (HTML)
                        nullable: true
                        type: string
                      cancellationEmailBody:
                        description: Invitee cancellation email body (HTML)
                        nullable: true
                        type: string
                      confirmationEmailSubjectForCloser:
                        description: Host confirmation email subject (HTML)
                        nullable: true
                        type: string
                      confirmationEmailBodyForCloser:
                        description: Host confirmation email body (HTML)
                        nullable: true
                        type: string
                      cancellationEmailSubjectForCloser:
                        description: Host cancellation email subject (HTML)
                        nullable: true
                        type: string
                      cancellationEmailBodyForCloser:
                        description: Host cancellation email body (HTML)
                        nullable: true
                        type: string
                      disqualifiedMessage:
                        description: Message shown when invitee is disqualified
                        nullable: true
                        type: string
                      disqualifiedRedirectUrl:
                        description: Redirect URL for disqualified invitees
                        nullable: true
                        type: string
                      breakType:
                        description: Break configuration type
                        nullable: true
                        type: string
                      timeSlots:
                        description: Time slot increment in minutes
                        nullable: true
                        type: number
                      widgetColor:
                        description: Scheduler widget accent (CSS)
                        nullable: true
                        type: string
                      backgroundColor:
                        description: Scheduler background color
                        nullable: true
                        type: string
                      hideEventDetails:
                        description: Whether event details are hidden on widget
                        nullable: true
                        type: boolean
                      fontColor:
                        description: Scheduler text color
                        nullable: true
                        type: string
                      borderColor:
                        description: Scheduler border color
                        nullable: true
                        type: string
                      inputFieldsColor:
                        description: Form input background color
                        nullable: true
                        type: string
                      buttonFontColor:
                        description: Button text color
                        nullable: true
                        type: string
                      showHostAvatars:
                        description: Whether host avatars are shown
                        nullable: true
                        type: boolean
                      timeSensitiveBooking:
                        description: Whether time-sensitive booking copy is shown
                        nullable: true
                        type: boolean
                      timeSensitiveBookingMessage:
                        description: Copy for time-sensitive booking
                        nullable: true
                        type: string
                      highlightFirstField:
                        description: Whether first form field is highlighted
                        nullable: true
                        type: boolean
                      schedulerTheme:
                        description: Scheduler theme preset
                        nullable: true
                        type: string
                      timeSelectionView:
                        description: Calendar/time selection layout
                        nullable: true
                        type: string
                      autoExtendDays:
                        description: Whether bookable range auto-extends
                        nullable: true
                        type: boolean
                      arrangedByAI:
                        description: Whether event was arranged by AI
                        nullable: true
                        type: boolean
                      showCalendarWithForm:
                        description: Whether calendar shows alongside form
                        nullable: true
                        type: boolean
                      cookiesAllowed:
                        description: Cookie consent / usage flag
                        nullable: true
                        type: boolean
                      hideQuestionLabels:
                        description: Whether question labels are hidden
                        nullable: true
                        type: boolean
                      collapseAnswers:
                        description: Whether answers are collapsed in UI
                        nullable: true
                        type: boolean
                      customizationTipClosed:
                        description: Whether customization tip was dismissed
                        nullable: true
                        type: boolean
                      format12Hour:
                        description: Whether 12-hour time format is used
                        nullable: true
                        type: boolean
                      enableConfirmationEmail:
                        description: Whether invitee confirmation emails send
                        nullable: true
                        type: boolean
                      enableCancellationEmail:
                        description: Whether cancellation emails send
                        nullable: true
                        type: boolean
                      createdAt:
                        description: Event creation time
                        anyOf:
                          - type: string
                            format: date-time
                            nullable: true
                          - type: string
                            nullable: true
                      updatedAt:
                        description: Event last update time
                        anyOf:
                          - type: string
                            format: date-time
                            nullable: true
                          - type: string
                            nullable: true
                      disqualifyIfCreditNotAvailable:
                        description: >-
                          Whether invitees are disqualified when credit is
                          unavailable
                        nullable: true
                        type: boolean
                      isDefaultNotification:
                        description: Whether default notification template is used
                        type: boolean
                      optimizationPriorities:
                        description: Host priority order for routing
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Optimization-priority record ID
                            priority:
                              description: Priority rank value
                              nullable: true
                              type: number
                            userId:
                              description: Referenced user ID
                              nullable: true
                              type: number
                            eventId:
                              description: Referenced event ID
                              nullable: true
                              type: number
                            user:
                              description: Referenced user summary
                              nullable: true
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: User ID
                                firstName:
                                  description: User first name
                                  nullable: true
                                  type: string
                                lastName:
                                  description: User last name
                                  nullable: true
                                  type: string
                                email:
                                  description: User email
                                  nullable: true
                                  type: string
                                profilePictureKey:
                                  description: User profile-picture storage key
                                  nullable: true
                                  type: string
                                previewId:
                                  description: User preview/public identifier
                                  nullable: true
                                  type: string
                                signedUrl:
                                  description: Temporary signed URL for profile picture
                                  nullable: true
                                  type: string
                                userAccounts:
                                  description: User-account relationship metadata
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        type: number
                                        description: UserAccount record ID
                                      accountId:
                                        type: number
                                        description: Account ID
                                      userId:
                                        type: number
                                        description: User ID
                                      tagId:
                                        description: Tag ID on the membership
                                        nullable: true
                                        type: number
                                      trackedUser:
                                        description: Whether user is tracked for this account
                                        nullable: true
                                        type: boolean
                                      status:
                                        description: Membership status
                                        nullable: true
                                        type: string
                                      lastConnected:
                                        description: Last connection time
                                        anyOf:
                                          - type: string
                                            format: date-time
                                            nullable: true
                                          - type: string
                                            nullable: true
                                      inviteNotAccepted:
                                        description: Whether account invite is pending
                                        nullable: true
                                        type: boolean
                                      restore:
                                        description: Restore metadata
                                        nullable: true
                                        type: object
                                      readyToRestore:
                                        description: Ready-to-restore flag
                                        nullable: true
                                        type: object
                                      createdAt:
                                        description: Record creation time
                                        anyOf:
                                          - type: string
                                            format: date-time
                                            nullable: true
                                          - type: string
                                            nullable: true
                                      updatedAt:
                                        description: Record last update time
                                        anyOf:
                                          - type: string
                                            format: date-time
                                            nullable: true
                                          - type: string
                                            nullable: true
                                      deletedAt:
                                        description: Soft-delete timestamp
                                        anyOf:
                                          - type: string
                                            format: date-time
                                            nullable: true
                                          - type: string
                                            nullable: true
                                    required:
                                      - id
                                      - accountId
                                      - userId
                                    additionalProperties: false
                                calendarConnected:
                                  description: Whether calendar integration is connected
                                  type: boolean
                                zoomConnected:
                                  description: Whether Zoom integration is connected
                                  type: boolean
                                inviteNotAccepted:
                                  description: Whether invite has not been accepted
                                  nullable: true
                                  type: boolean
                                activeAvailability:
                                  description: Currently active availability
                                  nullable: true
                                  type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Availability profile ID
                                    name:
                                      description: Availability profile name
                                      nullable: true
                                      type: string
                                    timeZone:
                                      description: Timezone of this availability profile
                                      nullable: true
                                      type: string
                                    availabilityDays:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          id:
                                            type: number
                                            description: Availability-day ID
                                          name:
                                            type: string
                                            description: Weekday name
                                          timings:
                                            type: array
                                            items:
                                              type: object
                                              properties:
                                                startTime:
                                                  type: string
                                                  description: Start time for this availability window
                                                endTime:
                                                  type: string
                                                  description: End time for this availability window
                                              required:
                                                - startTime
                                                - endTime
                                              additionalProperties: false
                                            description: Time windows configured for this day
                                          active:
                                            type: boolean
                                            description: >-
                                              Whether this weekday is active for
                                              scheduling
                                        required:
                                          - id
                                          - name
                                          - timings
                                          - active
                                        additionalProperties: false
                                      description: Availability days under this profile
                                  required:
                                    - id
                                    - availabilityDays
                                  additionalProperties: false
                                availabilitySet:
                                  description: Whether user has availability configured
                                  nullable: true
                                  type: boolean
                              required:
                                - id
                              additionalProperties: false
                          required:
                            - id
                          additionalProperties: false
                      inviteeQuestions:
                        description: Invitee questions configured for this event
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Invitee question ID
                            statement:
                              description: Question text shown to invitees
                              nullable: true
                              type: string
                            type:
                              description: Stored question type
                              nullable: true
                              type: string
                            required:
                              description: Whether answer is required
                              nullable: true
                              type: boolean
                            options:
                              description: >-
                                Raw options payload for selectable question
                                types
                              nullable: true
                              type: object
                            inputType:
                              description: Normalized invitee input category
                              nullable: true
                              type: string
                              enum:
                                - FIRST_NAME
                                - LAST_NAME
                                - NAME
                                - EMAIL
                                - PHONE_NO
                            displayIndex:
                              description: Display order of the question
                              nullable: true
                              type: number
                            deletedAt:
                              description: Soft-delete timestamp
                              anyOf:
                                - type: string
                                  format: date-time
                                  nullable: true
                                - type: string
                                  nullable: true
                          required:
                            - id
                          additionalProperties: false
                      workflowEvents:
                        description: Workflows triggered by event lifecycle
                        type: array
                        items:
                          type: object
                          properties:
                            workflow:
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Workflow ID
                                eventCallStateId:
                                  description: Linked event-call state ID
                                  nullable: true
                                  type: number
                                name:
                                  description: Workflow name
                                  nullable: true
                                  type: string
                                immediate:
                                  description: Whether workflow runs immediately
                                  nullable: true
                                  type: boolean
                                minutes:
                                  description: Delay amount for scheduled workflow
                                  nullable: true
                                  type: number
                                unit:
                                  description: Delay unit for scheduled workflow
                                  nullable: true
                                  type: string
                                disabled:
                                  description: Whether workflow is disabled
                                  nullable: true
                                  type: boolean
                              required:
                                - id
                              additionalProperties: false
                              description: Workflow metadata linked to the event
                          required:
                            - workflow
                          additionalProperties: false
                      EventRules:
                        description: Rules associated with this event
                        type: array
                        items:
                          type: object
                          properties:
                            rule:
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Rule ID
                                name:
                                  description: Rule name
                                  nullable: true
                                  type: string
                                type:
                                  description: Rule type
                                  nullable: true
                                  type: string
                                disabled:
                                  description: Whether rule is disabled
                                  nullable: true
                                  type: boolean
                                multiBookingConditions:
                                  description: Multi-booking conditions
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      customFieldEvent:
                                        description: Referenced custom-field mapping
                                        nullable: true
                                        type: object
                                        properties:
                                          customFieldId:
                                            description: Referenced custom-field ID
                                            nullable: true
                                            type: number
                                        additionalProperties: false
                                      customFieldEventId:
                                        description: Custom-field mapping ID
                                        nullable: true
                                        type: number
                                      condition:
                                        description: Condition join/value mode
                                        nullable: true
                                        type: string
                                      value:
                                        description: Rule comparison value
                                        nullable: true
                                        type: string
                                      operator:
                                        description: Rule comparison operator
                                        nullable: true
                                        type: string
                                    additionalProperties: false
                              required:
                                - id
                              additionalProperties: false
                              description: Rule linked to this event
                          required:
                            - rule
                          additionalProperties: false
                      EventLogicGroup:
                        description: Conditional host assignment logic groups
                        type: array
                        items:
                          type: object
                          properties:
                            minSlotsCheck:
                              description: Whether minimum-slots check is enabled
                              nullable: true
                              type: boolean
                            EventLogicUsers:
                              description: Users targeted by this logic group
                              type: array
                              items:
                                type: object
                                properties:
                                  user:
                                    type: object
                                    properties:
                                      id:
                                        type: number
                                        description: User ID
                                      email:
                                        description: User email
                                        nullable: true
                                        type: string
                                      firstName:
                                        description: User first name
                                        nullable: true
                                        type: string
                                      lastName:
                                        description: User last name
                                        nullable: true
                                        type: string
                                      profilePictureKey:
                                        description: Profile-picture storage key
                                        nullable: true
                                        type: string
                                      signedUrl:
                                        description: Temporary signed URL for profile picture
                                        nullable: true
                                        type: string
                                    required:
                                      - id
                                    additionalProperties: false
                                required:
                                  - user
                                additionalProperties: false
                            EventLogics:
                              description: Logic rules in this group
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: number
                                    description: Event-logic rule ID
                                  eventId:
                                    description: Parent event ID
                                    nullable: true
                                    type: number
                                  inviteeQuestionId:
                                    description: Referenced invitee-question ID
                                    nullable: true
                                    type: number
                                  customFieldId:
                                    description: Referenced custom-field ID
                                    nullable: true
                                    type: number
                                  condition:
                                    description: Condition join/value mode
                                    nullable: true
                                    type: string
                                  value:
                                    description: Rule comparison value
                                    nullable: true
                                    type: string
                                  operator:
                                    description: Rule comparison operator
                                    nullable: true
                                    type: string
                                  customField:
                                    description: Raw custom-field payload used by the rule
                                    nullable: true
                                    type: object
                                  customFieldEvent:
                                    description: Raw event custom-field mapping payload
                                    nullable: true
                                    type: object
                                required:
                                  - id
                                additionalProperties: false
                          additionalProperties: false
                      CustomFieldEventMap:
                        description: Mapped secondary/custom fields for this event
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: CustomFieldEventMap record ID
                            statement:
                              description: Question/field statement shown in event form
                              nullable: true
                              type: string
                            required:
                              description: Whether this field is required
                              nullable: true
                              type: boolean
                            displayIndex:
                              description: Display order index
                              nullable: true
                              type: number
                            customField:
                              description: Custom-field definition payload
                              oneOf:
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - TEXT
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for TEXT
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  description: >-
                                    Custom field event map item: inputType TEXT.
                                    Example: { "id": 7972, "identifier":
                                    "what-is-e", "description": "", "inputType":
                                    "TEXT", "options": "", "optionsAttributes":
                                    null, "type": "CALL", "CustomFieldOptions":
                                    [] }
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - TEXT_AREA
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for TEXT_AREA
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  description: >-
                                    Custom field event map item: inputType
                                    TEXT_AREA. Example: { "id": 7973,
                                    "identifier": "explain-element",
                                    "description": "", "inputType": "TEXT_AREA",
                                    "options": "", "optionsAttributes": null,
                                    "type": "CALL", "CustomFieldOptions": [] }
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - NUMBER
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for NUMBER
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  description: >-
                                    Custom field event map item: inputType
                                    NUMBER. Example: { "id": 7977, "identifier":
                                    "num", "description": "", "inputType":
                                    "NUMBER", "options": "",
                                    "optionsAttributes": null, "type": "CALL",
                                    "CustomFieldOptions": [] }
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - URL
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for URL
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  description: >-
                                    Custom field event map item: inputType URL.
                                    Example: { "id": 11996, "identifier":
                                    "add-url", "description": null, "inputType":
                                    "URL", "options": "", "optionsAttributes":
                                    null, "type": "CALL", "CustomFieldOptions":
                                    [] }
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - DATE
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for DATE
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  description: >-
                                    Custom field event map item: inputType DATE.
                                    Example: { "id": 35113, "identifier":
                                    "date-time", "description": "", "inputType":
                                    "DATE", "options": "", "optionsAttributes":
                                    null, "type": "CALL", "CustomFieldOptions":
                                    [] }
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized selectable-options definition
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - SINGLE_SELECT
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: Resolved selectable options
                                      nullable: true
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          id:
                                            type: number
                                            description: Custom-field option ID
                                          name:
                                            description: Option label
                                            nullable: true
                                            type: string
                                          color:
                                            description: Display color
                                            nullable: true
                                            type: string
                                          badge:
                                            description: Badge text
                                            nullable: true
                                            type: string
                                          tooltip:
                                            description: Tooltip text
                                            nullable: true
                                            type: string
                                          isArchived:
                                            description: Whether option is archived
                                            nullable: true
                                            type: boolean
                                          displayIndex:
                                            description: Display order index
                                            nullable: true
                                            type: number
                                          actionId:
                                            description: Associated action ID
                                            nullable: true
                                            type: number
                                          category:
                                            description: Option category
                                            nullable: true
                                            type: string
                                            enum:
                                              - ACTIVE
                                              - WON
                                              - LOST
                                          icon:
                                            description: Icon key/name
                                            nullable: true
                                            type: string
                                          isDefault:
                                            description: Whether option is default
                                            nullable: true
                                            type: boolean
                                        required:
                                          - id
                                        additionalProperties: false
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  description: >-
                                    Custom field event map item: inputType
                                    SINGLE_SELECT. Example: { "id": 13015,
                                    "identifier": "zain-test", "description":
                                    "", "inputType": "SINGLE_SELECT", "options":
                                    "[{\"w1\":false},{\"21w\":false}]",
                                    "optionsAttributes": null, "type": "CALL",
                                    "CustomFieldOptions": [{ "id": 54038,
                                    "name": "w1", "color": null, "badge": null,
                                    "tooltip": null, "isArchived": false,
                                    "displayIndex": 0, "actionId": null }, {
                                    "id": 54138, "name": "21w", "color": null,
                                    "badge": null, "tooltip": null,
                                    "isArchived": false, "displayIndex": 1,
                                    "actionId": null }] }
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized selectable-options definition
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - MULTIPLE_SELECT
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: Resolved selectable options
                                      nullable: true
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          id:
                                            type: number
                                            description: Custom-field option ID
                                          name:
                                            description: Option label
                                            nullable: true
                                            type: string
                                          color:
                                            description: Display color
                                            nullable: true
                                            type: string
                                          badge:
                                            description: Badge text
                                            nullable: true
                                            type: string
                                          tooltip:
                                            description: Tooltip text
                                            nullable: true
                                            type: string
                                          isArchived:
                                            description: Whether option is archived
                                            nullable: true
                                            type: boolean
                                          displayIndex:
                                            description: Display order index
                                            nullable: true
                                            type: number
                                          actionId:
                                            description: Associated action ID
                                            nullable: true
                                            type: number
                                          category:
                                            description: Option category
                                            nullable: true
                                            type: string
                                            enum:
                                              - ACTIVE
                                              - WON
                                              - LOST
                                          icon:
                                            description: Icon key/name
                                            nullable: true
                                            type: string
                                          isDefault:
                                            description: Whether option is default
                                            nullable: true
                                            type: boolean
                                        required:
                                          - id
                                        additionalProperties: false
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  description: >-
                                    Custom field event map item: inputType
                                    MULTIPLE_SELECT. Example: { "id": 15794,
                                    "identifier":
                                    "what-specific-breakthroasfasughs-are-you-",
                                    "description": "", "inputType":
                                    "MULTIPLE_SELECT", "options":
                                    "[{\"asfasfsfsf\":false},{\"asfasf\":false},{\"bretta\":false},{\"wrangler\":false}]",
                                    "optionsAttributes": null, "type": "CALL",
                                    "CustomFieldOptions": [{ "id": 47790,
                                    "name": "asfasf", "displayIndex": 1 }, {
                                    "id": 47853, "name": "asfasfsfsf",
                                    "displayIndex": 0 }, { "id": 659889, "name":
                                    "bretta", "displayIndex": 2 }, { "id":
                                    659890, "name": "wrangler", "displayIndex":
                                    3 }] }
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized selectable-options definition
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - CHECK_BOX
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: Resolved selectable options
                                      nullable: true
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          id:
                                            type: number
                                            description: Custom-field option ID
                                          name:
                                            description: Option label
                                            nullable: true
                                            type: string
                                          color:
                                            description: Display color
                                            nullable: true
                                            type: string
                                          badge:
                                            description: Badge text
                                            nullable: true
                                            type: string
                                          tooltip:
                                            description: Tooltip text
                                            nullable: true
                                            type: string
                                          isArchived:
                                            description: Whether option is archived
                                            nullable: true
                                            type: boolean
                                          displayIndex:
                                            description: Display order index
                                            nullable: true
                                            type: number
                                          actionId:
                                            description: Associated action ID
                                            nullable: true
                                            type: number
                                          category:
                                            description: Option category
                                            nullable: true
                                            type: string
                                            enum:
                                              - ACTIVE
                                              - WON
                                              - LOST
                                          icon:
                                            description: Icon key/name
                                            nullable: true
                                            type: string
                                          isDefault:
                                            description: Whether option is default
                                            nullable: true
                                            type: boolean
                                        required:
                                          - id
                                        additionalProperties: false
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized selectable-options definition
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - RADIO_BUTTON
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: Resolved selectable options
                                      nullable: true
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          id:
                                            type: number
                                            description: Custom-field option ID
                                          name:
                                            description: Option label
                                            nullable: true
                                            type: string
                                          color:
                                            description: Display color
                                            nullable: true
                                            type: string
                                          badge:
                                            description: Badge text
                                            nullable: true
                                            type: string
                                          tooltip:
                                            description: Tooltip text
                                            nullable: true
                                            type: string
                                          isArchived:
                                            description: Whether option is archived
                                            nullable: true
                                            type: boolean
                                          displayIndex:
                                            description: Display order index
                                            nullable: true
                                            type: number
                                          actionId:
                                            description: Associated action ID
                                            nullable: true
                                            type: number
                                          category:
                                            description: Option category
                                            nullable: true
                                            type: string
                                            enum:
                                              - ACTIVE
                                              - WON
                                              - LOST
                                          icon:
                                            description: Icon key/name
                                            nullable: true
                                            type: string
                                          isDefault:
                                            description: Whether option is default
                                            nullable: true
                                            type: boolean
                                        required:
                                          - id
                                        additionalProperties: false
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - EMAIL
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for EMAIL
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - RATING
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for RATING
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - USER
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for USER
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  nullable: true
                                - type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Custom-field ID
                                    identifier:
                                      description: Custom-field identifier/slug
                                      nullable: true
                                      type: string
                                    description:
                                      description: Custom-field description
                                      nullable: true
                                      type: string
                                    options:
                                      description: Serialized options payload
                                      nullable: true
                                      type: string
                                    optionsAttributes:
                                      description: Serialized options-attributes payload
                                      nullable: true
                                      type: string
                                    type:
                                      description: Custom-field scope/type
                                      nullable: true
                                      type: string
                                      enum:
                                        - CONTACT
                                        - EVENT
                                        - CALL
                                        - DEAL
                                        - SHARED
                                        - BACK_OFFICE
                                        - USER
                                        - TRANSACTION
                                        - SETTER
                                        - CONTACT_STATS
                                        - COMMUNICATION
                                        - UNIFIED_INBOX
                                        - ISCORE
                                        - CREDITSCORE
                                        - FPJS
                                    inputType:
                                      type: string
                                      enum:
                                        - USERS_MULTIPLE
                                      description: Custom-field input type
                                    CustomFieldOptions:
                                      description: No selectable options for USERS_MULTIPLE
                                      type: array
                                      items:
                                        anyOf: []
                                      minItems: 0
                                      maxItems: 0
                                  required:
                                    - id
                                    - inputType
                                  additionalProperties: false
                                  nullable: true
                          required:
                            - id
                          additionalProperties: false
                          description: >-
                            One custom field event map entry. customField is
                            discriminated by inputType (TEXT, TEXT_AREA, NUMBER,
                            URL, DATE, SINGLE_SELECT, MULTIPLE_SELECT, etc.).
                            Examples: TEXT { "id": 114695, "statement": "What is
                            E", "required": false, "displayIndex": 0,
                            "customField": { "id": 7972, "identifier":
                            "what-is-e", "inputType": "TEXT", "type": "CALL",
                            "CustomFieldOptions": [] } }; SINGLE_SELECT { "id":
                            114697, "statement": "witch", "required": true,
                            "displayIndex": 2, "customField": { "id": 13015,
                            "identifier": "zain-test", "inputType":
                            "SINGLE_SELECT", "options":
                            "[{\"w1\":false},{\"21w\":false}]", "type": "CALL",
                            "CustomFieldOptions": [{ "id": 54038, "name": "w1",
                            "displayIndex": 0 }, { "id": 54138, "name": "21w",
                            "displayIndex": 1 }] } }.
                      DisqualificationLogicGroup:
                        description: Disqualification rules and redirect behavior
                        type: array
                        items:
                          type: object
                          properties:
                            redirectUrl:
                              description: >-
                                Redirect URL used when disqualification rules
                                match
                              nullable: true
                              type: string
                            EventConditionalLogics:
                              description: Conditional rules in this disqualification group
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: number
                                    description: Conditional-logic rule ID
                                  eventId:
                                    description: Parent event ID
                                    nullable: true
                                    type: number
                                  statement:
                                    description: >-
                                      Question/field statement referenced by
                                      this rule
                                    nullable: true
                                    type: string
                                  operator:
                                    description: Comparison operator used for evaluation
                                    nullable: true
                                    type: string
                                  value:
                                    description: Comparison value used by the rule
                                    nullable: true
                                    type: string
                                  condition:
                                    description: >-
                                      Condition join type (e.g. AND/OR
                                      semantics)
                                    nullable: true
                                    type: string
                                  disqualificationGroupId:
                                    description: Parent disqualification logic-group ID
                                    nullable: true
                                    type: number
                                required:
                                  - id
                                additionalProperties: false
                          additionalProperties: false
                      eventImage:
                        description: Event image metadata
                        nullable: true
                        type: object
                        properties:
                          id:
                            type: number
                            description: Event image record ID
                          imageUrl:
                            description: Stored image URL
                            nullable: true
                            type: string
                          imageKey:
                            description: Storage key for event image
                            nullable: true
                            type: string
                          signedUrl:
                            description: Temporary signed URL for image access
                            nullable: true
                            type: string
                        required:
                          - id
                        additionalProperties: false
                      account:
                        description: Account-level settings snapshot
                        nullable: true
                        type: object
                        properties:
                          emailValidationEnabled:
                            description: Account-level email validation setting
                            nullable: true
                            type: boolean
                          phoneNumberValidationEnabled:
                            description: Account-level phone validation setting
                            nullable: true
                            type: boolean
                          usCreditCheckEnabled:
                            description: Account-level US credit-check setting
                            nullable: true
                            type: boolean
                          signedUrl:
                            description: Temporary signed URL for account media
                            nullable: true
                            type: string
                        additionalProperties: false
                      user:
                        description: Primary user summary
                        nullable: true
                        type: object
                        properties:
                          id:
                            type: number
                            description: User ID
                          firstName:
                            description: User first name
                            nullable: true
                            type: string
                          lastName:
                            description: User last name
                            nullable: true
                            type: string
                          email:
                            description: User email
                            nullable: true
                            type: string
                          profilePictureKey:
                            description: User profile-picture storage key
                            nullable: true
                            type: string
                          previewId:
                            description: User preview/public identifier
                            nullable: true
                            type: string
                          signedUrl:
                            description: Temporary signed URL for profile picture
                            nullable: true
                            type: string
                          userAccounts:
                            description: User-account relationship metadata
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: UserAccount record ID
                                accountId:
                                  type: number
                                  description: Account ID
                                userId:
                                  type: number
                                  description: User ID
                                tagId:
                                  description: Tag ID on the membership
                                  nullable: true
                                  type: number
                                trackedUser:
                                  description: Whether user is tracked for this account
                                  nullable: true
                                  type: boolean
                                status:
                                  description: Membership status
                                  nullable: true
                                  type: string
                                lastConnected:
                                  description: Last connection time
                                  anyOf:
                                    - type: string
                                      format: date-time
                                      nullable: true
                                    - type: string
                                      nullable: true
                                inviteNotAccepted:
                                  description: Whether account invite is pending
                                  nullable: true
                                  type: boolean
                                restore:
                                  description: Restore metadata
                                  nullable: true
                                  type: object
                                readyToRestore:
                                  description: Ready-to-restore flag
                                  nullable: true
                                  type: object
                                createdAt:
                                  description: Record creation time
                                  anyOf:
                                    - type: string
                                      format: date-time
                                      nullable: true
                                    - type: string
                                      nullable: true
                                updatedAt:
                                  description: Record last update time
                                  anyOf:
                                    - type: string
                                      format: date-time
                                      nullable: true
                                    - type: string
                                      nullable: true
                                deletedAt:
                                  description: Soft-delete timestamp
                                  anyOf:
                                    - type: string
                                      format: date-time
                                      nullable: true
                                    - type: string
                                      nullable: true
                              required:
                                - id
                                - accountId
                                - userId
                              additionalProperties: false
                          calendarConnected:
                            description: Whether calendar integration is connected
                            type: boolean
                          zoomConnected:
                            description: Whether Zoom integration is connected
                            type: boolean
                          inviteNotAccepted:
                            description: Whether invite has not been accepted
                            nullable: true
                            type: boolean
                          activeAvailability:
                            description: Currently active availability
                            nullable: true
                            type: object
                            properties:
                              id:
                                type: number
                                description: Availability profile ID
                              name:
                                description: Availability profile name
                                nullable: true
                                type: string
                              timeZone:
                                description: Timezone of this availability profile
                                nullable: true
                                type: string
                              availabilityDays:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    id:
                                      type: number
                                      description: Availability-day ID
                                    name:
                                      type: string
                                      description: Weekday name
                                    timings:
                                      type: array
                                      items:
                                        type: object
                                        properties:
                                          startTime:
                                            type: string
                                            description: Start time for this availability window
                                          endTime:
                                            type: string
                                            description: End time for this availability window
                                        required:
                                          - startTime
                                          - endTime
                                        additionalProperties: false
                                      description: Time windows configured for this day
                                    active:
                                      type: boolean
                                      description: >-
                                        Whether this weekday is active for
                                        scheduling
                                  required:
                                    - id
                                    - name
                                    - timings
                                    - active
                                  additionalProperties: false
                                description: Availability days under this profile
                            required:
                              - id
                              - availabilityDays
                            additionalProperties: false
                          availabilitySet:
                            description: Whether user has availability configured
                            nullable: true
                            type: boolean
                        required:
                          - id
                        additionalProperties: false
                      eventEmailTemplateVariables:
                        description: Template variables used in event emails
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Template-variable record ID
                            eventId:
                              description: Parent event ID
                              nullable: true
                              type: number
                            variableKey:
                              description: Template variable key
                              nullable: true
                              type: string
                            variableValue:
                              description: Template variable value
                              nullable: true
                              type: string
                          required:
                            - id
                          additionalProperties: false
                    required:
                      - id
                    additionalProperties: false
                additionalProperties: false
              example:
                data:
                  id: 4
                  linkPrefix: amunim/new-event
                  name: new-event
                  color: '#0099FF'
                  eventType: STRATEGY_EVENT
                  status: ACTIVATED
                  userId: 2
                  duration: 30
                  durationUnit: MINUTES
                  location: PHONE_CALL
                  allowReschedule: true
                  phonePreferred: true
                  splitFullName: true
                  dateRangeType: DEFINITE
                  dateRangeUnit: CALENDAR_DAYS
                  dateRangeDays: 14
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/events/status:
    put:
      operationId: updateEventStatus
      summary: Update Event Status
      description: >-
        Update an event status to ACTIVATED or DEACTIVATED. Body: id (required),
        status (required).
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  exclusiveMinimum: true
                  maximum: 2147483647
                  description: Event ID
                  minimum: 0
                status:
                  type: string
                  enum:
                    - ACTIVATED
                    - DEACTIVATED
                  description: Event status
              required:
                - id
                - status
              additionalProperties: false
              example:
                id: 4
                status: ACTIVATED
            example:
              id: 4
              status: ACTIVATED
      responses:
        '200':
          description: Event status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: Status-update result message
                    type: string
                  status:
                    description: HTTP status code
                    type: number
                additionalProperties: false
              example:
                message: Event status updated successfully
                status: 200
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/events/troubleshootSlots:
    get:
      operationId: troubleshootSlots
      summary: Troubleshoot Slots
      description: >-
        Returns time slots for an event on a given date with per-slot
        availability (for troubleshooting). Each slot includes a display time,
        optional tags/reason when unavailable (e.g. past), and lists of
        available and unavailable users. Query: linkPrefix (required), date
        (e.g. YYYY-MM-DD, required), timezone (IANA, required), selectedHost
        (optional).
      tags:
        - Events
      parameters:
        - name: linkPrefix
          in: query
          schema:
            type: string
            minLength: 1
            description: Public event link prefix
          required: true
          description: Public event link prefix
        - name: date
          in: query
          schema:
            type: string
            minLength: 1
            description: Date to troubleshoot
          required: true
          description: Date to troubleshoot
        - name: timezone
          in: query
          schema:
            type: string
            minLength: 1
            description: >-
              IANA timezone used for slot generation (must match app-supported
              timezones)
          required: true
          description: >-
            IANA timezone used for slot generation (must match app-supported
            timezones)
        - name: selectedHost
          in: query
          schema:
            description: Optional host user ID to pin results
            type: integer
            exclusiveMinimum: true
            maximum: 2147483647
            minimum: 0
          description: Optional host user ID to pin results
      responses:
        '200':
          description: >-
            Slots for the date with available/unavailable users and count of
            slots that have at least one available user
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      slots:
                        type: array
                        items:
                          type: object
                          properties:
                            slot:
                              type: string
                              description: Display time label (e.g. "12:00 AM", "03:45 PM")
                            tags:
                              type: array
                              items:
                                type: string
                              description: >-
                                Reasons the slot is unavailable (e.g. "Time
                                range is in past")
                            reason:
                              nullable: true
                              description: Human-readable reason when slot is unavailable
                              type: string
                            availableUsers:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: number
                                    description: User ID
                                  firstName:
                                    description: User first name
                                    nullable: true
                                    type: string
                                  lastName:
                                    description: User last name
                                    nullable: true
                                    type: string
                                  email:
                                    description: User email
                                    nullable: true
                                    type: string
                                  phoneNumber:
                                    description: User phone number
                                    nullable: true
                                    type: string
                                  profilePictureKey:
                                    description: Profile picture storage key
                                    nullable: true
                                    type: string
                                  signedUrl:
                                    description: Temporary signed URL for profile picture
                                    nullable: true
                                    type: string
                                  extraDetails:
                                    description: Additional host-specific metadata
                                    nullable: true
                                    type: object
                                required:
                                  - id
                                additionalProperties: false
                              description: Users available for this slot
                            unAvailableUsers:
                              type: array
                              items:
                                type: object
                                properties:
                                  id:
                                    type: number
                                    description: User ID
                                  firstName:
                                    description: User first name
                                    nullable: true
                                    type: string
                                  lastName:
                                    description: User last name
                                    nullable: true
                                    type: string
                                  profilePictureKey:
                                    description: Profile picture storage key
                                    nullable: true
                                    type: string
                                  inviteNotAccepted:
                                    description: >-
                                      Whether user invite is still pending
                                      acceptance
                                    type: boolean
                                  signedUrl:
                                    description: Temporary signed URL for profile picture
                                    nullable: true
                                    type: string
                                  reason:
                                    description: >-
                                      Why this user is unavailable for this slot
                                      (e.g. matches tags)
                                    type: string
                                  busyDetails:
                                    description: >-
                                      Underlying busy interval metadata when
                                      applicable
                                    type: object
                                    properties:
                                      userId:
                                        type: number
                                      accountId:
                                        type: number
                                      googleEventId:
                                        description: >-
                                          Google Calendar event id, or Microsoft
                                          Graph event id (same field for both
                                          integrations)
                                        type: string
                                      name:
                                        description: >-
                                          Calendar event title when from an
                                          external calendar
                                        type: string
                                      reason:
                                        type: string
                                      overBooked:
                                        type: boolean
                                      startDate:
                                        anyOf:
                                          - type: string
                                          - type: string
                                            format: date-time
                                      endDate:
                                        anyOf:
                                          - type: string
                                          - type: string
                                            format: date-time
                                      source:
                                        description: >-
                                          Present for busy intervals from a
                                          connected calendar (Google vs
                                          Outlook/Microsoft)
                                        type: string
                                        enum:
                                          - googleCalendar
                                          - microsoftCalendar
                                    additionalProperties: false
                                required:
                                  - id
                                additionalProperties: false
                              description: Users that are not available for this slot
                            datetime:
                              type: string
                              description: Slot start time as epoch milliseconds string
                          required:
                            - slot
                            - tags
                            - reason
                            - availableUsers
                            - unAvailableUsers
                            - datetime
                          additionalProperties: false
                        description: Generated slots with host availability details
                      noOfAvailableSlots:
                        type: number
                        description: Number of slots that have at least one available user
                    required:
                      - slots
                      - noOfAvailableSlots
                    additionalProperties: false
                    description: Troubleshoot-slots payload
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  slots:
                    - slot: 09:45 AM
                      tags:
                        - Time range is in past
                      reason: This time slot is in past.
                      availableUsers: []
                      unAvailableUsers:
                        - id: 3684
                          firstName: CustomerSupport5
                          lastName: 5-dfgdf
                          profilePictureKey: support5@iclosed.io/1771418602957
                          inviteNotAccepted: false
                          signedUrl: >-
                            https://resources.iclosed.io/assets/support5@iclosed.io/1771418602957
                      datetime: '1773135900000'
                    - slot: 03:45 PM
                      tags: []
                      reason: null
                      availableUsers:
                        - id: 3684
                          firstName: CustomerSupport5
                          lastName: 5-dfgdf
                          email: support5@iclosed.io
                          phoneNumber: '+923444381002'
                          profilePictureKey: support5@iclosed.io/1771418602957
                          signedUrl: >-
                            https://resources.iclosed.io/assets/support5@iclosed.io/1771418602957
                          extraDetails: null
                      unAvailableUsers: []
                      datetime: '1773157500000'
                  noOfAvailableSlots: 11
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/events/eventDates:
    post:
      operationId: getPublicEventDates
      summary: Get Event Date and Time
      description: Returns available dates for public event booking.
      tags:
        - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                linkPrefix:
                  type: string
                  minLength: 1
                  description: Public event link prefix
                timeZone:
                  description: Timezone used to generate available dates
                  type: string
                currentDate:
                  description: Current date anchor for date generation
                  type: string
                conditionalUsers:
                  description: >-
                    Optional comma-separated user IDs to constrain host
                    selection
                  type: string
              required:
                - linkPrefix
              additionalProperties: false
              example:
                linkPrefix: amunim/new-event
                timeZone: America/New_York
                currentDate: '2026-04-15'
            example:
              linkPrefix: amunim/new-event
              timeZone: America/New_York
              currentDate: '2026-04-15'
      responses:
        '201':
          description: Available event dates and times by date
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      isPreview:
                        description: Whether returned dates are preview-only
                        type: boolean
                      availabilities:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Date-keyed map of available slot times
                    required:
                      - availabilities
                    additionalProperties: false
                    description: Public event-date availability payload
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  isPreview: false
                  availabilities:
                    '2026-02-26':
                      - '09:00'
                      - '09:15'
                      - '10:00'
                    '2026-02-27':
                      - '09:00'
                      - '14:00'
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/products:
    get:
      operationId: listProducts
      summary: Get Products
      description: >-
        List products for the authenticated account. Query: search, limit, page,
        parentProductId, allProducts, packageLess, timeFrom, timeTo, orderBy,
        orderColumn.
      tags:
        - Products
      parameters:
        - name: search
          in: query
          schema:
            description: Case-insensitive product name search term.
            type: string
          description: Case-insensitive product name search term.
        - name: limit
          in: query
          schema:
            default: 20
            description: Maximum number of records returned per page (1-200).
            type: integer
            minimum: 1
            maximum: 200
          description: Maximum number of records returned per page (1-200).
        - name: page
          in: query
          schema:
            default: 0
            description: Zero-based page index used with limit for pagination.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index used with limit for pagination.
        - name: orderBy
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: >-
            Sort direction applied to orderColumn. Required together with
            orderColumn when sorting.
        - name: orderColumn
          in: query
          schema:
            type: string
            enum:
              - id
              - name
              - createdAt
              - updatedAt
              - deals
          description: >-
            Product field used for sorting; "deals" sorts by related deal count.
            Required together with orderBy when sorting.
      responses:
        '200':
          description: List of products with count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      count:
                        description: Total number of matching records for pagination.
                        type: number
                      products:
                        description: Product records returned for the current page.
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: Unique product identifier.
                            tagId:
                              description: Associated tag identifier for the product.
                              type: number
                            name:
                              description: Product name.
                              type: string
                            description:
                              description: Product description text.
                              type: string
                            price:
                              description: Product price value when available.
                              type: number
                            contractValue:
                              description: Contract value used by legacy product flows.
                              type: number
                            accountId:
                              description: >-
                                Owning account identifier for the product
                                record.
                              type: number
                            createdAt:
                              description: ISO timestamp when the product was created.
                              type: string
                            updatedAt:
                              description: ISO timestamp when the product was last updated.
                              type: string
                            tag:
                              description: Tag relation details when loaded.
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Unique tag identifier.
                                name:
                                  type: string
                                  description: >-
                                    Tag display name associated with the
                                    product.
                                createdAt:
                                  type: string
                                  description: ISO timestamp when the tag was created.
                              required:
                                - id
                                - name
                                - createdAt
                              additionalProperties: false
                            _count:
                              type: object
                              properties:
                                deals:
                                  type: number
                                  description: >-
                                    Number of non-deleted deals linked to this
                                    product.
                              required:
                                - deals
                              additionalProperties: false
                              description: >-
                                Aggregated relation counts included when count
                                data is requested.
                          required:
                            - id
                          additionalProperties: false
                    additionalProperties: false
                    description: Paginated products payload for list responses.
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  count: 3
                  products:
                    - id: 3
                      tagId: 9
                      name: Laptop2
                      description: ''
                      createdAt: '2026-03-04T21:28:18.027Z'
                      updatedAt: '2026-03-04T21:28:18.027Z'
                      tag:
                        id: 9
                        name: laptop2
                        createdAt: '2026-03-04T21:28:18.029Z'
                      _count:
                        deals: 0
                    - id: 4
                      tagId: 10
                      name: testset
                      description: ''
                      createdAt: '2026-03-05T10:37:28.306Z'
                      updatedAt: '2026-03-05T10:37:28.306Z'
                      tag:
                        id: 10
                        name: testset
                        createdAt: '2026-03-05T10:37:28.307Z'
                      _count:
                        deals: 0
                    - id: 5
                      tagId: 11
                      name: Phone
                      description: ''
                      createdAt: '2026-03-05T12:00:00.000Z'
                      updatedAt: '2026-03-05T12:00:00.000Z'
                      tag:
                        id: 11
                        name: phone
                        createdAt: '2026-03-05T12:00:00.010Z'
                      _count:
                        deals: 0
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    post:
      operationId: createProduct
      summary: Create a new product
      description: 'Create a new product. Required: name. Optional: description.'
      tags:
        - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 40
                  description: Name for the new product (max 40 chars).
                description:
                  description: Optional description for the new product.
                  type: string
              required:
                - name
              additionalProperties: false
              example:
                name: Premium Plan
                description: Annual subscription tier
            example:
              name: Premium Plan
              description: Annual subscription tier
      responses:
        '201':
          description: Successfully created product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      product:
                        description: >-
                          Product payload returned on successful create or
                          update.
                        type: object
                        properties:
                          id:
                            type: number
                            description: Unique product identifier.
                          tagId:
                            description: Associated tag identifier for the product.
                            type: number
                          name:
                            description: Product name.
                            type: string
                          description:
                            description: Product description text.
                            type: string
                          price:
                            description: Product price value when available.
                            type: number
                          contractValue:
                            description: Contract value used by legacy product flows.
                            type: number
                          accountId:
                            description: Owning account identifier for the product record.
                            type: number
                          createdAt:
                            description: ISO timestamp when the product was created.
                            type: string
                          updatedAt:
                            description: ISO timestamp when the product was last updated.
                            type: string
                          tag:
                            description: Tag relation details when loaded.
                            type: object
                            properties:
                              id:
                                type: number
                                description: Unique tag identifier.
                              name:
                                type: string
                                description: Tag display name associated with the product.
                              createdAt:
                                type: string
                                description: ISO timestamp when the tag was created.
                            required:
                              - id
                              - name
                              - createdAt
                            additionalProperties: false
                          _count:
                            type: object
                            properties:
                              deals:
                                type: number
                                description: >-
                                  Number of non-deleted deals linked to this
                                  product.
                            required:
                              - deals
                            additionalProperties: false
                            description: >-
                              Aggregated relation counts included when count
                              data is requested.
                        required:
                          - id
                        additionalProperties: false
                      error:
                        description: Service error payload returned when operation fails.
                    additionalProperties: false
                    description: >-
                      Create/update result payload containing either product or
                      error details.
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  product:
                    id: 4
                    tagId: 10
                    name: testset
                    createdAt: '2026-03-05T10:37:28.306Z'
                    updatedAt: '2026-03-05T10:37:28.306Z'
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    put:
      operationId: updateProduct
      summary: Update a product
      description: >-
        Update an existing product. Required: productId. Optional: name,
        description.
      tags:
        - Products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                productId:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Identifier of the product to update.
                name:
                  description: New product name (max 40 chars).
                  type: string
                  minLength: 1
                  maxLength: 40
                description:
                  description: Updated product description.
                  type: string
              required:
                - productId
              additionalProperties: false
              example:
                productId: 4
                name: Premium Plan
                description: Updated product description
            example:
              productId: 4
              name: Premium Plan
              description: Updated product description
      responses:
        '200':
          description: Successfully updated product
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      product:
                        description: >-
                          Product payload returned on successful create or
                          update.
                        type: object
                        properties:
                          id:
                            type: number
                            description: Unique product identifier.
                          tagId:
                            description: Associated tag identifier for the product.
                            type: number
                          name:
                            description: Product name.
                            type: string
                          description:
                            description: Product description text.
                            type: string
                          price:
                            description: Product price value when available.
                            type: number
                          contractValue:
                            description: Contract value used by legacy product flows.
                            type: number
                          accountId:
                            description: Owning account identifier for the product record.
                            type: number
                          createdAt:
                            description: ISO timestamp when the product was created.
                            type: string
                          updatedAt:
                            description: ISO timestamp when the product was last updated.
                            type: string
                          tag:
                            description: Tag relation details when loaded.
                            type: object
                            properties:
                              id:
                                type: number
                                description: Unique tag identifier.
                              name:
                                type: string
                                description: Tag display name associated with the product.
                              createdAt:
                                type: string
                                description: ISO timestamp when the tag was created.
                            required:
                              - id
                              - name
                              - createdAt
                            additionalProperties: false
                          _count:
                            type: object
                            properties:
                              deals:
                                type: number
                                description: >-
                                  Number of non-deleted deals linked to this
                                  product.
                            required:
                              - deals
                            additionalProperties: false
                            description: >-
                              Aggregated relation counts included when count
                              data is requested.
                        required:
                          - id
                        additionalProperties: false
                      error:
                        description: Service error payload returned when operation fails.
                    additionalProperties: false
                    description: >-
                      Create/update result payload containing either product or
                      error details.
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  product:
                    id: 4
                    tagId: 10
                    name: testset
                    createdAt: '2026-03-05T10:37:28.306Z'
                    updatedAt: '2026-03-05T10:37:28.306Z'
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/outcomes:
    post:
      operationId: updateTask
      summary: Upsert Call Outcome
      description: >-
        Updates the outcome of a call.


        Body: `eventCallId` (required) identifies the event call; `outcome` is
        required. Optional: `notes`, `newDeal` (deal payload when posting WON).


        Cross-cutting validation: `noSaleReason` is required when `outcome` is
        NO_SALE or REJECTED. `objection` is required when `outcome` is WON. When
        `outcome` is NO_SALE and `noSaleReason` is FOLLOW_UP_SCHEDULE or
        UNQUALIFIED, `objection` is also required.


        By event call type (server-enforced):

        - Discovery calls: `outcome` must be APPROVED or REJECTED. If REJECTED,
        `noSaleReason` is required and must be one of NO_SHOW, BAD_FIT, OTHER,
        NOT_INTERESTED, CONTACT_CANCELLED, ADMIN_CANCELLED.

        - Strategy calls: `outcome` must be WON or NO_SALE. If NO_SALE,
        `noSaleReason` is required and must be one of FOLLOW_UP_SCHEDULE,
        UNQUALIFIED, NO_SHOW, CONTACT_CANCELLED, ADMIN_CANCELLED,
        NOT_INTERESTED.
      tags:
        - Outcomes
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                outcome:
                  type: string
                  enum:
                    - WON
                    - NO_SALE
                    - APPROVED
                    - REJECTED
                  description: Task outcome for the selected event call.
                noSaleReason:
                  description: Required when outcome is NO_SALE.
                  type: string
                  enum:
                    - FOLLOW_UP_SCHEDULE
                    - UNQUALIFIED
                    - NO_SHOW
                    - CONTACT_CANCELLED
                    - ADMIN_CANCELLED
                    - NOT_INTERESTED
                    - BAD_FIT
                    - OTHER
                notes:
                  description: Free-text notes stored with the task outcome.
                  type: string
                objection:
                  description: Required for WON and certain NO_SALE reasons.
                  type: string
                  enum:
                    - MONEY
                    - LOGISTIC
                    - PARTNER
                    - FEAR
                    - SMOKE_SCREEN
                    - NO_OBJECTION
                newDeal:
                  description: Deal payload used when posting a WON outcome.
                  type: object
                  properties:
                    id:
                      description: >-
                        Existing deal id: updates that deal only; never creates
                        a new deal. Cannot be used together with
                        `transactionIds`.
                      type: integer
                      minimum: 0
                      maximum: 2147483647
                    value:
                      description: >-
                        Deal value for manual create or update; ignored for
                        creation when `transactionIds` is set (value comes from
                        transaction sum).
                      type: number
                    transactionType:
                      description: >-
                        Transaction type on the deal; required for manual
                        new-deal create (no `id`, no `transactionIds`).
                      type: string
                      enum:
                        - WON
                        - RECURRING
                        - DEPOSIT
                    productId:
                      description: >-
                        Product id for the deal; required when `newDeal` is
                        present; validated to exist for the account.
                      type: integer
                      minimum: 0
                      maximum: 2147483647
                    date:
                      description: >-
                        ISO datetime for deal time; required for manual new-deal
                        create; optional when updating by `id` or creating via
                        `transactionIds` (defaults apply in service).
                      type: string
                      format: date-time
                    transactionIds:
                      description: >-
                        Creates a new deal from these transactions (aggregated
                        value). Cannot be used together with `id`.
                      type: array
                      items:
                        type: integer
                        minimum: 0
                        maximum: 2147483647
                  additionalProperties: false
                eventCallId:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Event call id used to locate and update its linked task.
              required:
                - outcome
                - eventCallId
              additionalProperties: false
            examples:
              strategyWonNewDealManual:
                summary: Strategy call — WON with newDeal (manual value)
                description: >-
                  Use on STRATEGY_EVENT calls. `objection` required for WON.
                  `newDeal` must include productId, value, transactionType, and
                  date for a manual create.
                value:
                  eventCallId: 1001
                  outcome: WON
                  objection: NO_OBJECTION
                  notes: Closed on first strategy call.
                  newDeal:
                    value: 5000
                    transactionType: WON
                    productId: 42
                    date: '2026-04-10T15:30:00.000Z'
              strategyWonNewDealFromTransactions:
                summary: Strategy call — WON with newDeal.transactionIds
                description: >-
                  Creates/links a deal from existing transactions; server sums
                  values. `productId` is required; transaction ids must exist
                  for the account.
                value:
                  eventCallId: 1002
                  outcome: WON
                  objection: MONEY
                  newDeal:
                    productId: 42
                    transactionIds:
                      - 90001
                      - 90002
              strategyNoSaleWithReason:
                summary: Strategy call — NO_SALE with noSaleReason (no objection)
                description: >-
                  Example uses NO_SHOW. For FOLLOW_UP_SCHEDULE or UNQUALIFIED,
                  `objection` is also required.
                value:
                  eventCallId: 1004
                  outcome: NO_SALE
                  noSaleReason: NO_SHOW
                  notes: Contact did not join.
              strategyNoSaleFollowUpWithObjection:
                summary: Strategy call — NO_SALE FOLLOW_UP_SCHEDULE with objection
                description: >-
                  When noSaleReason is FOLLOW_UP_SCHEDULE or UNQUALIFIED,
                  objection is required.
                value:
                  eventCallId: 1005
                  outcome: NO_SALE
                  noSaleReason: FOLLOW_UP_SCHEDULE
                  objection: LOGISTIC
                  notes: Follow-up booked; logistics concern.
              discoveryApprovedWithObjection:
                summary: Discovery call — APPROVED (optional objection)
                description: >-
                  Use on DISCOVERY_EVENT calls. Outcome must be APPROVED or
                  REJECTED.
                value:
                  eventCallId: 2001
                  outcome: APPROVED
                  objection: NO_OBJECTION
                  notes: Qualified for strategy call.
              discoveryRejectedBadFit:
                summary: Discovery call — REJECTED with BAD_FIT
                description: >-
                  REJECTED requires noSaleReason from: NO_SHOW, BAD_FIT, OTHER,
                  NOT_INTERESTED, CONTACT_CANCELLED, ADMIN_CANCELLED.
                value:
                  eventCallId: 2002
                  outcome: REJECTED
                  noSaleReason: BAD_FIT
                  notes: Not a fit for the offer.
      responses:
        '200':
          description: Task updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    description: Updated task record returned by updateTask.
                    type: object
                    properties:
                      id:
                        description: Task id that was updated.
                        type: number
                      noSaleReason:
                        description: Persisted no-sale reason on the task.
                        nullable: true
                        type: string
                        enum:
                          - FOLLOW_UP_SCHEDULE
                          - UNQUALIFIED
                          - NO_SHOW
                          - CONTACT_CANCELLED
                          - ADMIN_CANCELLED
                          - NOT_INTERESTED
                          - BAD_FIT
                          - OTHER
                      objection:
                        description: Persisted objection category on the task.
                        nullable: true
                        type: string
                        enum:
                          - MONEY
                          - LOGISTIC
                          - PARTNER
                          - FEAR
                          - SMOKE_SCREEN
                          - NO_OBJECTION
                      updatedAt:
                        description: Last task update timestamp.
                        type: string
                    additionalProperties: false
                additionalProperties: false
              example:
                data:
                  id: 6
                  noSaleReason: null
                  objection: NO_OBJECTION
                  updatedAt: '2026-04-13T12:00:00.000Z'
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/transactions:
    get:
      operationId: getTransactions
      summary: Get transactions
      description: >-
        List transactions with optional filters (id, synced, search, source,
        time range, pagination, sort).
      tags:
        - Transactions
      parameters:
        - name: id
          in: query
          schema:
            description: Filter by transaction ID.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Filter by transaction ID.
        - name: synced
          in: query
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
          description: Filter by synced-to-deal status.
        - name: search
          in: query
          schema:
            description: Search in name, email, phoneNumber, or value.
            type: string
          description: Search in name, email, phoneNumber, or value.
        - name: source
          in: query
          schema:
            type: string
            enum:
              - Zapier
              - Stripe
              - Make
              - Other
          description: Filter by source (e.g. "Zapier"). Comma-separated for multiple.
        - name: timeFrom
          in: query
          schema:
            description: Filter transactions created on or after this time (ISO 8601).
            type: string
            format: date-time
          description: Filter transactions created on or after this time (ISO 8601).
        - name: timeTo
          in: query
          schema:
            description: Filter by createdAt on or before this time (ISO 8601).
            type: string
            format: date-time
          description: Filter by createdAt on or before this time (ISO 8601).
        - name: page
          in: query
          schema:
            description: Page index for pagination (0-based).
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Page index for pagination (0-based).
        - name: limit
          in: query
          schema:
            description: Number of items per page.
            type: integer
            minimum: 0
            maximum: 100
          description: Number of items per page.
        - name: sort
          in: query
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort order by createdAt.
        - name: sortByAmount
          in: query
          schema:
            type: string
            enum:
              - ascAmount
              - descAmount
          description: 'Sort by transaction value amount: ascending or descending.'
      responses:
        '200':
          description: Transaction list with count
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: number
                    description: >-
                      Total number of transactions matching the query (before
                      pagination).
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: Transaction ID.
                        accountId:
                          type: number
                          description: Account ID.
                        name:
                          description: Contact or transaction name.
                          nullable: true
                          type: string
                        email:
                          description: Contact or transaction email.
                          nullable: true
                          type: string
                        phoneNumber:
                          description: Contact or transaction phone number.
                          nullable: true
                          type: string
                        description:
                          description: Transaction description.
                          nullable: true
                          type: string
                        value:
                          type: number
                          description: Transaction value.
                        currency:
                          description: >-
                            ISO 4217 alpha code (e.g. USD, EUR, GBP, JPY); null
                            if not set.
                          nullable: true
                          type: string
                        source:
                          description: Source of the transaction (e.g. "Zapier").
                          nullable: true
                          type: string
                        updatedBy:
                          description: Identifier of who last updated.
                          nullable: true
                          type: string
                        createdAt:
                          anyOf:
                            - type: string
                              format: date-time
                            - type: string
                          description: Creation time (ISO 8601 when serialized).
                        updatedAt:
                          anyOf:
                            - type: string
                              format: date-time
                            - type: string
                          description: Last update time (ISO 8601 when serialized).
                        syncedDeal:
                          description: Deal ID when synced to a deal; null Otherwise.
                          nullable: true
                          type: number
                        deal:
                          nullable: true
                          description: >-
                            Present when transaction is synced to a deal; null
                            Otherwise. Includes contact when populated.
                          type: object
                          properties:
                            contact:
                              description: Deal contact when populated.
                              type: object
                              properties:
                                id:
                                  type: number
                                  description: Contact ID.
                                firstName:
                                  description: Contact first name.
                                  nullable: true
                                  type: string
                                lastName:
                                  description: Contact last name.
                                  nullable: true
                                  type: string
                                email:
                                  description: Contact email.
                                  nullable: true
                                  type: string
                                previewId:
                                  description: Contact preview identifier.
                              required:
                                - id
                              additionalProperties: false
                          additionalProperties: false
                      required:
                        - id
                        - accountId
                        - value
                        - createdAt
                        - updatedAt
                        - deal
                      additionalProperties: false
                    description: Page of transaction items.
                required:
                  - count
                  - data
                additionalProperties: false
              example:
                count: 2354
                data:
                  - id: 1
                    accountId: 1
                    name: Jane Doe
                    email: jane.doe@example.com
                    phoneNumber: '+15551234567'
                    description: 'Test zapier '
                    value: 300.56
                    currency: null
                    source: Zapier
                    updatedBy: Zapier
                    createdAt: '2026-03-10T08:11:15.963Z'
                    updatedAt: '2026-03-10T08:11:15.963Z'
                    syncedDeal: null
                    deal: null
                  - id: 1
                    accountId: 1
                    name: Jane Doe
                    email: jane23.doe@example.com
                    phoneNumber: '+15551234567'
                    description: 'Test zapier '
                    value: 300.56
                    currency: null
                    source: Zapier
                    updatedBy: Zapier
                    createdAt: '2026-03-09T14:30:53.751Z'
                    updatedAt: '2026-03-09T14:30:53.751Z'
                    syncedDeal: null
                    deal: null
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    post:
      operationId: createTransaction
      summary: Create a transaction
      description: Create a new transaction. Value is required.
      tags:
        - Transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Contact or transaction name.
                  type: string
                email:
                  type: string
                  maxLength: 255
                  format: email
                phoneNumber:
                  type: string
                  maxLength: 16
                  pattern: ^\+?[1-9]\d{1,14}$
                description:
                  description: Transaction description (max 1000 chars).
                  type: string
                  maxLength: 1000
                value:
                  type: number
                  description: Transaction value (required).
                source:
                  description: Source of the transaction (e.g. "Zapier").
                  type: string
                  enum:
                    - Zapier
                    - Stripe
                    - Make
                    - Other
                updatedBy:
                  description: Identifier of who is creating/updating.
                  type: string
              required:
                - value
              additionalProperties: false
              example:
                name: John Doe
                phoneNumber: '+1234567890'
                description: Test transaction
                email: user@example.com
                value: 0
                source: Zapier
            example:
              name: John Doe
              phoneNumber: '+1234567890'
              description: Test transaction
              email: user@example.com
              value: 0
              source: Zapier
      responses:
        '201':
          description: Successfully created transaction
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: >-
                      Top-level. Present on success. Localized success message
                      (e.g. "Transaction added successfully").
                    type: string
                  status:
                    description: >-
                      Top-level. Present on success. HTTP-style status code
                      (e.g. 200).
                    type: number
                  data:
                    description: >-
                      Top-level. Present on success. Contains the created
                      transaction.
                    type: object
                    properties:
                      transaction:
                        type: object
                        properties:
                          id:
                            type: number
                            description: Transaction ID.
                          accountId:
                            type: number
                            description: Account ID.
                          syncedDeal:
                            description: >-
                              Deal ID when transaction is synced to a deal; null
                              or omitted Other wise.
                            nullable: true
                            type: number
                          name:
                            description: Contact or transaction name.
                            nullable: true
                            type: string
                          email:
                            description: Contact or transaction email.
                            nullable: true
                            type: string
                          phoneNumber:
                            description: Contact or transaction phone number.
                            nullable: true
                            type: string
                          description:
                            description: Transaction description (max 1000 chars).
                            nullable: true
                            type: string
                          value:
                            anyOf:
                              - type: number
                              - type: string
                            description: >-
                              Transaction value. May be string as a number when
                              serialized.
                          currency:
                            description: >-
                              ISO 4217 alpha code (e.g. USD, EUR, GBP, JPY);
                              null if not set.
                            nullable: true
                            type: string
                          source:
                            description: Source of the transaction (e.g. "Zapier").
                            nullable: true
                            type: string
                            enum:
                              - Zapier
                              - Stripe
                              - Make
                              - Other
                          updatedBy:
                            description: Identifier of who last updated the transaction.
                            nullable: true
                            type: string
                          createdAt:
                            anyOf:
                              - type: string
                                format: date-time
                              - type: string
                            description: Creation time (ISO 8601 when serialized).
                          updatedAt:
                            anyOf:
                              - type: string
                                format: date-time
                              - type: string
                            description: Last update time (ISO 8601 when serialized).
                          deletedAt:
                            description: Soft-delete time; null when not deleted.
                            anyOf:
                              - type: string
                                format: date-time
                                nullable: true
                              - type: string
                                nullable: true
                        required:
                          - id
                          - accountId
                          - value
                          - createdAt
                          - updatedAt
                        additionalProperties: false
                    required:
                      - transaction
                    additionalProperties: false
                additionalProperties: false
                description: >-
                  Create response: top-level keys are message (string), status
                  (number), and data (object with transaction). Message and
                  status are present on success.
              example:
                message: Transaction added successfully
                status: 200
                data:
                  transaction:
                    id: 1
                    accountId: 1
                    syncedDeal: 0
                    name: Jane Doe
                    email: jane23.doe@example.com
                    phoneNumber: '+15551234567'
                    description: 'Test zapier '
                    value: '0'
                    currency: usd
                    source: Zapier
                    updatedBy: User
                    createdAt: '2026-03-10T13:30:07.851Z'
                    updatedAt: '2026-03-10T13:30:07.851Z'
                    deletedAt: null
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    put:
      operationId: updateTransaction
      summary: Update a transaction
      description: Update an existing transaction by id. Id is required in body.
      tags:
        - Transactions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  minimum: 0
                  maximum: 2147483647
                  description: Transaction ID to update (required).
                name:
                  description: Contact or transaction name.
                  type: string
                email:
                  type: string
                  maxLength: 255
                  format: email
                phoneNumber:
                  type: string
                  maxLength: 16
                  pattern: ^\+?[1-9]\d{1,14}$
                description:
                  description: Transaction description (max 1000 chars).
                  type: string
                  maxLength: 1000
                value:
                  description: Transaction value.
                  type: number
                source:
                  description: Source of the transaction (e.g. "Zapier").
                  type: string
                  enum:
                    - Zapier
                    - Stripe
                    - Make
                    - Other
              required:
                - id
              additionalProperties: false
              example:
                id: 1
                name: John Doe
                phoneNumber: '+1234567890'
                description: Test transaction
                email: user@example.com
                value: 0
                source: Zapier
            example:
              id: 1
              name: John Doe
              phoneNumber: '+1234567890'
              description: Test transaction
              email: user@example.com
              value: 0
              source: Zapier
      responses:
        '200':
          description: Successfully updated transaction
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: >-
                      Top-level. Present on success. Localized success message
                      (e.g. "Transaction updated successfully").
                    type: string
                  status:
                    description: >-
                      Top-level. Present on success. HTTP-style status code
                      (e.g. 200).
                    type: number
                  data:
                    description: >-
                      Top-level. Present on success. Contains the updated
                      transaction.
                    type: object
                    properties:
                      transaction:
                        type: object
                        properties:
                          id:
                            type: number
                            description: Transaction ID.
                          accountId:
                            type: number
                            description: Account ID.
                          syncedDeal:
                            description: >-
                              Deal ID when transaction is synced to a deal; null
                              or omitted Other wise.
                            nullable: true
                            type: number
                          name:
                            description: Contact or transaction name.
                            nullable: true
                            type: string
                          email:
                            description: Contact or transaction email.
                            nullable: true
                            type: string
                          phoneNumber:
                            description: Contact or transaction phone number.
                            nullable: true
                            type: string
                          description:
                            description: Transaction description (max 1000 chars).
                            nullable: true
                            type: string
                          value:
                            anyOf:
                              - type: number
                              - type: string
                            description: >-
                              Transaction value. May be string as a number when
                              serialized.
                          currency:
                            description: >-
                              ISO 4217 alpha code (e.g. USD, EUR, GBP, JPY);
                              null if not set.
                            nullable: true
                            type: string
                          source:
                            description: Source of the transaction (e.g. "Zapier").
                            nullable: true
                            type: string
                            enum:
                              - Zapier
                              - Stripe
                              - Make
                              - Other
                          updatedBy:
                            description: Identifier of who last updated the transaction.
                            nullable: true
                            type: string
                          createdAt:
                            anyOf:
                              - type: string
                                format: date-time
                              - type: string
                            description: Creation time (ISO 8601 when serialized).
                          updatedAt:
                            anyOf:
                              - type: string
                                format: date-time
                              - type: string
                            description: Last update time (ISO 8601 when serialized).
                          deletedAt:
                            description: Soft-delete time; null when not deleted.
                            anyOf:
                              - type: string
                                format: date-time
                                nullable: true
                              - type: string
                                nullable: true
                        required:
                          - id
                          - accountId
                          - value
                          - createdAt
                          - updatedAt
                        additionalProperties: false
                    required:
                      - transaction
                    additionalProperties: false
                additionalProperties: false
                description: >-
                  Update response: top-level keys are message (string), status
                  (number), and data (object with transaction). Message and
                  status are present on success.
              example:
                data:
                  transaction:
                    id: 1
                    accountId: 1
                    syncedDeal: 0
                    name: Example Name
                    email: user@example.com
                    phoneNumber: '+1234567890'
                    description: Test transaction
                    value: '0'
                    currency: usd
                    source: Zapier
                    updatedBy: User
                    createdAt: '2026-03-10T13:30:07.851Z'
                    updatedAt: '2026-03-10T13:34:11.812Z'
                    deletedAt: null
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
    delete:
      operationId: deleteTransaction
      summary: Delete a transaction
      description: Delete a transaction by id (query param).
      tags:
        - Transactions
      parameters:
        - name: id
          in: query
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successfully deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    description: >-
                      Present on success. Localized success message (e.g.
                      "Transaction deleted successfully").
                    type: string
                  status:
                    description: Present on success. HTTP-style status code (e.g. 200).
                    type: number
                additionalProperties: false
              example:
                message: Transaction deleted successfully
                status: 200
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/userAvailabilities:
    get:
      operationId: getUserAvailabilities
      summary: Get user availabilities
      description: >-
        List user availabilities or get one by id. Query: id (optional) – fetch
        single by id; selectedUserId (optional) – filter by user when listing.
        When id is provided returns a single availability; otherwise returns a
        list.
      tags:
        - User Availabilities
      parameters:
        - name: userId
          in: query
          schema:
            description: Target user id whose availabilities are being fetched.
            type: integer
            exclusiveMinimum: true
            maximum: 2147483647
            minimum: 0
          description: Target user id whose availabilities are being fetched.
      responses:
        '200':
          description: List of user availabilities (or single when id is provided)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                          description: User availability id.
                        userId:
                          nullable: true
                          description: >-
                            Owner user id (nullable in legacy/incomplete
                            records).
                          type: number
                        name:
                          nullable: true
                          description: >-
                            Availability name (nullable in legacy/incomplete
                            records).
                          type: string
                        timeZone:
                          type: string
                          description: IANA timezone for this availability.
                        isDefault:
                          type: boolean
                          description: Whether this is the user default availability.
                        createdAt:
                          description: Availability creation timestamp.
                          anyOf:
                            - type: string
                              format: date-time
                            - type: string
                        userAvailabilityDays:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: number
                                description: Availability day id.
                              name:
                                type: string
                                enum:
                                  - monday
                                  - tuesday
                                  - wednesday
                                  - thursday
                                  - friday
                                  - saturday
                                  - sunday
                                description: Weekday name for this row.
                              active:
                                type: boolean
                                description: >-
                                  True when at least one timing slot exists for
                                  this day.
                              timings:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    startTime:
                                      type: string
                                      description: >-
                                        Start time in HH:mm (formatted in
                                        availability timezone).
                                    endTime:
                                      type: string
                                      description: >-
                                        End time in HH:mm (formatted in
                                        availability timezone).
                                  required:
                                    - startTime
                                    - endTime
                                  additionalProperties: false
                                description: Timing slots for the day (may be empty).
                            required:
                              - id
                              - name
                              - active
                              - timings
                            additionalProperties: false
                          description: Expanded availability matrix for all weekdays.
                        eventId:
                          type: array
                          items:
                            type: number
                          description: >-
                            Event ids currently associated with this
                            availability.
                      required:
                        - id
                        - userId
                        - name
                        - timeZone
                        - isDefault
                        - userAvailabilityDays
                        - eventId
                      additionalProperties: false
                    description: List of availability records for the requested user.
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  - id: 22726
                    name: test
                    userId: 3684
                    timeZone: America/Los_Angeles
                    isDefault: false
                    userAvailabilityDays:
                      - id: 1
                        name: monday
                        active: true
                        timings:
                          - startTime: '09:00'
                            endTime: '17:30'
                          - startTime: '17:15'
                            endTime: '17:45'
                          - startTime: '18:00'
                            endTime: '18:30'
                          - startTime: '18:45'
                            endTime: '19:15'
                      - id: 2
                        name: tuesday
                        active: true
                        timings:
                          - startTime: '09:00'
                            endTime: '17:00'
                          - startTime: '17:15'
                            endTime: '17:45'
                          - startTime: '18:00'
                            endTime: '18:30'
                          - startTime: '18:45'
                            endTime: '19:15'
                          - startTime: '19:30'
                            endTime: '20:00'
                      - id: 3
                        name: wednesday
                        active: true
                        timings:
                          - startTime: '09:00'
                            endTime: '17:00'
                          - startTime: '17:15'
                            endTime: '17:45'
                          - startTime: '18:00'
                            endTime: '18:30'
                          - startTime: '18:45'
                            endTime: '19:15'
                          - startTime: '19:30'
                            endTime: '20:00'
                      - id: 4
                        name: thursday
                        active: true
                        timings:
                          - startTime: '09:00'
                            endTime: '17:00'
                          - startTime: '17:15'
                            endTime: '17:45'
                          - startTime: '18:00'
                            endTime: '18:30'
                          - startTime: '18:45'
                            endTime: '19:15'
                          - startTime: '19:30'
                            endTime: '20:00'
                          - startTime: '20:15'
                            endTime: '20:45'
                          - startTime: '21:00'
                            endTime: '21:30'
                          - startTime: '21:45'
                            endTime: '22:15'
                      - id: 5
                        name: friday
                        active: true
                        timings:
                          - startTime: '09:00'
                            endTime: '17:00'
                          - startTime: '17:15'
                            endTime: '17:45'
                          - startTime: '18:00'
                            endTime: '18:30'
                          - startTime: '18:45'
                            endTime: '19:15'
                          - startTime: '19:30'
                            endTime: '20:00'
                          - startTime: '20:15'
                            endTime: '20:45'
                      - id: 6
                        name: saturday
                        active: true
                        timings:
                          - startTime: '09:00'
                            endTime: '17:00'
                          - startTime: '17:15'
                            endTime: '17:45'
                          - startTime: '18:00'
                            endTime: '18:30'
                          - startTime: '18:45'
                            endTime: '19:15'
                          - startTime: '19:30'
                            endTime: '20:00'
                          - startTime: '20:15'
                            endTime: '20:45'
                          - startTime: '21:00'
                            endTime: '21:30'
                          - startTime: '21:45'
                            endTime: '22:15'
                          - startTime: '22:30'
                            endTime: '23:00'
                          - startTime: '23:15'
                            endTime: '23:45'
                      - id: 7
                        name: sunday
                        active: true
                        timings:
                          - startTime: '09:00'
                            endTime: '17:00'
                          - startTime: '17:15'
                            endTime: '17:45'
                          - startTime: '18:00'
                            endTime: '18:30'
                          - startTime: '18:45'
                            endTime: '19:15'
                    eventId:
                      - 3951
                      - 4272
                      - 4430
                      - 5875
                  - id: 7061
                    name: Working Hours
                    userId: 3684
                    timeZone: Asia/Karachi
                    isDefault: true
                    userAvailabilityDays:
                      - id: 1
                        name: monday
                        active: true
                        timings:
                          - startTime: '00:00'
                            endTime: '23:40'
                      - id: 2
                        name: tuesday
                        active: true
                        timings:
                          - startTime: '00:00'
                            endTime: '23:45'
                      - id: 3
                        name: wednesday
                        active: true
                        timings:
                          - startTime: '00:00'
                            endTime: '23:45'
                      - id: 4
                        name: thursday
                        active: true
                        timings:
                          - startTime: '00:00'
                            endTime: '23:45'
                      - id: 5
                        name: friday
                        active: true
                        timings:
                          - startTime: '00:00'
                            endTime: '23:45'
                      - id: 6
                        name: saturday
                        active: true
                        timings:
                          - startTime: '00:00'
                            endTime: '23:45'
                      - id: 7
                        name: sunday
                        active: true
                        timings:
                          - startTime: '00:00'
                            endTime: '23:45'
                    eventId:
                      - 9267
                      - 22709
                      - 31729
                      - 33094
                      - 32884
                      - 32883
                      - 32882
                      - 32881
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
  /v1/users:
    get:
      operationId: getUsers
      summary: List users
      description: >-
        List users for the account, including soft-deleted users and users whose
        account membership row may be deleted. Paginated; optional search
        (name/email) and filter by user ids. Each item includes `role` (account
        role name) and `deletedAt` on the user when soft-deleted. Query: limit
        (default 20, max 100), page (default 0), search (optional), ids
        (optional comma-separated ids).
      tags:
        - Users
      parameters:
        - name: limit
          in: query
          schema:
            default: 20
            description: Page size, min 1 and max 100.
            type: integer
            minimum: 1
            maximum: 100
          description: Page size, min 1 and max 100.
        - name: page
          in: query
          schema:
            default: 0
            description: Zero-based page index.
            type: integer
            minimum: 0
            maximum: 2147483647
          description: Zero-based page index.
        - name: search
          in: query
          schema:
            description: Optional search text matched against user name fields.
            type: string
          description: Optional search text matched against user name fields.
        - name: ids
          in: query
          schema:
            description: >-
              Optional comma-separated user ids; adapter parses this value into
              number[].
            type: string
          description: >-
            Optional comma-separated user ids; adapter parses this value into
            number[].
      responses:
        '200':
          description: List of users and total count
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      users:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: number
                              description: User id.
                            firstName:
                              type: string
                              description: User first name.
                            lastName:
                              nullable: true
                              description: User last name; null when not set.
                              type: string
                            email:
                              type: string
                              description: User email address.
                            phoneNumber:
                              nullable: true
                              description: User phone number; null when not set.
                              type: string
                            timeZone:
                              nullable: true
                              description: User IANA time zone; null when not set.
                              type: string
                            createdAt:
                              anyOf:
                                - type: string
                                  format: date-time
                                - type: string
                              description: >-
                                User creation timestamp returned as Date or ISO
                                string.
                            deletedAt:
                              description: >-
                                Soft-delete timestamp for the user; null when
                                the user is active.
                              anyOf:
                                - type: string
                                  format: date-time
                                  nullable: true
                                - type: string
                                  nullable: true
                            role:
                              nullable: true
                              description: >-
                                Role name for this user in the account (from
                                UserRoles; first by name when multiple). Null
                                when no role is assigned.
                              type: string
                            integrations:
                              type: array
                              items:
                                type: object
                                properties:
                                  name:
                                    type: string
                                    enum:
                                      - googleCalendar
                                      - zoom
                                    description: >-
                                      Integration key; currently limited to
                                      googleCalendar and zoom in service query
                                      filters.
                                  platform_id:
                                    type: string
                                    description: >-
                                      Provider identifier for the connected
                                      integration account.
                                required:
                                  - name
                                  - platform_id
                                additionalProperties: false
                              description: Connected calendar/meeting integrations.
                          required:
                            - id
                            - firstName
                            - lastName
                            - email
                            - phoneNumber
                            - timeZone
                            - createdAt
                            - deletedAt
                            - role
                            - integrations
                          additionalProperties: false
                        description: Paginated list of users.
                      count:
                        type: number
                        description: Total number of users matching the applied filters.
                    required:
                      - users
                      - count
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
              example:
                data:
                  users:
                    - id: 7936
                      firstName: ab
                      lastName: cd
                      email: tahirddr@ic.io
                      phoneNumber: '+923213442422'
                      timeZone: Asia/Karachi
                      createdAt: '2024-12-10T10:04:34.743Z'
                      deletedAt: null
                      role: user
                      integrations: []
                    - id: 11848
                      firstName: abdul
                      lastName: iclosed
                      email: abdul.rehman@iclosed.io
                      phoneNumber: '+923213422242'
                      timeZone: Asia/Karachi
                      createdAt: '2025-04-04T14:33:26.258Z'
                      deletedAt: '2025-06-01T12:00:00.000Z'
                      role: admin
                      integrations:
                        - name: googleCalendar
                          platform_id: abdul.rehman@iclosed.io
                  count: 132
        '400':
          description: Bad request or validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Human-readable summary (first field/form error for Zod
                      validation failures).
                  details:
                    description: >-
                      Present when the failure is from createZodBodyValidator /
                      createZodQueryValidator.
                    type: object
                    properties:
                      formErrors:
                        type: array
                        items:
                          type: string
                        description: Global form-level error messages
                      fieldErrors:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                        description: Field name to list of validation error messages
                    required:
                      - formErrors
                      - fieldErrors
                    additionalProperties: false
                  stack:
                    description: Present only in non-production environments.
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                validationZodDetails:
                  summary: Zod validation (body/query)
                  value:
                    message: 'Invalid input: expected number, received undefined'
                    details:
                      formErrors: []
                      fieldErrors:
                        eventCallId:
                          - 'Invalid input: expected number, received undefined'
        '401':
          description: Unauthorized – missing or invalid API key (Bearer token required)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "API key is required" or "Invalid API key"
                  code:
                    description: >-
                      Optional code e.g. MISSING_API_KEY when rate limiter runs
                      before valid auth
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                missing:
                  summary: Missing API key
                  value:
                    message: API key is required
                invalid:
                  summary: Invalid API key
                  value:
                    message: Invalid API key
                missingFromRateLimiter:
                  summary: Missing auth when rate limiter runs first
                  value:
                    code: MISSING_API_KEY
                    message: API key is required for this endpoint
        '403':
          description: Forbidden – insufficient permissions
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                required:
                  - message
                additionalProperties: false
              example:
                message: Forbidden access
        '404':
          description: >-
            Resource not found (e.g. NOT_FOUND, RECORD_NOT_FOUND,
            EVENT_NOT_FOUND)
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: e.g. "Resource not found!" or "Record not found!"
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic not found
                  value:
                    message: Resource not found!
                record:
                  summary: Record not found
                  value:
                    message: Record not found!
        '429':
          description: >-
            Rate limit exceeded. Per-account, per-action limits apply. Response
            may include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset,
            and Retry-After headers.
          headers:
            RateLimit-Limit:
              description: Maximum requests allowed in the current window
              schema:
                type: string
            RateLimit-Remaining:
              description: Requests remaining in the current window
              schema:
                type: string
            RateLimit-Reset:
              description: ISO 8601 timestamp when the rate limit window resets
              schema:
                type: string
                format: date-time
            Retry-After:
              description: Seconds until the client can retry (when applicable)
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - RATE_LIMIT_EXCEEDED
                    description: Fixed code for rate limit responses
                  message:
                    type: string
                    description: e.g. "Too many requests, please try again later."
                  retryAfter:
                    description: Seconds until the rate limit window resets
                    type: number
                  limit:
                    description: Configured limit (when using account-based rate limiter)
                    type: object
                    properties:
                      points:
                        type: number
                      windowSec:
                        type: number
                    required:
                      - points
                      - windowSec
                    additionalProperties: false
                required:
                  - code
                  - message
                additionalProperties: false
              example:
                code: RATE_LIMIT_EXCEEDED
                message: Too many requests, please try again later.
        '500':
          description: >-
            Internal server error. Prisma and unhandled errors return a generic
            message; stack is only included in non-production.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      Generic: "Something went wrong" for Prisma errors, or
                      error message
                  stack:
                    description: Present only in non-production
                    type: string
                required:
                  - message
                additionalProperties: false
              examples:
                generic:
                  summary: Generic (e.g. Prisma errors)
                  value:
                    message: Something went wrong
                withMessage:
                  summary: Error with message
                  value:
                    message: Database connection failed
