openapi: 3.0.3
info:
  title: Mobly REST API
  version: v0
  description: |
    Mobly REST API (version v0).

    - JSON-based
    - Authenticated via API key
    - Versioned under `/v0`
servers:
  - url: https://core-api.getmobly.com/api/v0
security:
  - ApiKeyAuth: []

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

  schemas:
    # Generic / shared
    Location:
      type: object
      properties:
        streetAddress:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        zip:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        latitude:
          type: string
          nullable: true
        longitude:
          type: string
          nullable: true
        timeZone:
          type: string
          nullable: true

    Pagination:
      type: object
      properties:
        limit:
          type: integer
          format: int32
        offset:
          type: integer
          format: int32
      required:
        - limit
        - offset

    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
        error:
          type: string
      required:
        - status
        - error

    # Enums
    EventType:
      type: string
      description: Event type classification.
      enum:
        - CONFERENCE
        - TRADE_SHOW
        - EVENT
        - SIDECAR
        - DINNER_MEAL
        - HAPPY_HOUR
        - OTHER

    PhoneNumberTypeEnum:
      type: string
      description: Phone number type.
      enum:
        - MOBILE
        - LANDLINE
        - DIRECT
        - OFFICE
        - HQ
        - UNKNOWN

    LeadActivityEventType:
      type: string
      description: Lead activity event type.
      enum:
        - NOTE
        - FACEBOOK
        - LINKEDIN
        - TWITTER
        - CALENDAR
        - PHONE
        - EMAIL
        - SMS
        - CAMPAIGN_ASSOCIATION
        - CSV_UPLOAD
        - MOBLY_API
        - EMAIL_CONTENT
        - SMS_CONTENT
        - OTHER_CONTENT

    ActivationType:
      type: string
      description: Activation type.
      enum:
        - CONFERENCE
        - TRADE_SHOW
        - EVENT
        - SIDECAR
        - DINNER_MEAL
        - HAPPY_HOUR
        - BREAKFAST
        - LUNCH
        - COFFEE_CHAT
        - RECEPTION
        - SPEAKING_SESSION
        - PANEL_DISCUSSION
        - WORKSHOP
        - DEMO
        - SPORTS_GAME
        - PARTY
        - BOOTH
        - GIVEAWAY
        - NETWORKING_MIXER
        - ONSITE_OFFICE_VISIT
        - OTHER

    TagGroupStatus:
      type: string
      description: Tag group publication status.
      enum:
        - ARCHIVED
        - DRAFT
        - PUBLISHED

    # Events
    Event:
      type: object
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        type:
          $ref: "#/components/schemas/EventType"
        registrationEnabled:
          type: boolean
        createdAt:
          type: string
          format: date-time
        startDate:
          type: string
          format: date
          nullable: true
        endDate:
          type: string
          format: date
          nullable: true
        location:
          allOf:
            - $ref: "#/components/schemas/Location"
          nullable: true
        tagGroups:
          type: array
          items:
            type: string
            format: uuid
      required:
        - id
        - name
        - type
        - registrationEnabled
        - createdAt
        - tagGroups

    EventCreateV0Input:
      type: object
      properties:
        eventName:
          type: string
        eventType:
          $ref: "#/components/schemas/EventType"
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        createdByEmail:
          type: string
          format: email
        registrationEnabled:
          type: boolean
      required:
        - eventName
        - eventType
        - startDate
        - endDate
        - createdByEmail

    EventUpdateV0Input:
      type: object
      properties:
        eventName:
          type: string
        eventType:
          $ref: "#/components/schemas/EventType"
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        registrationEnabled:
          type: boolean
      required:
        - eventName
        - eventType
        - startDate
        - endDate

    EventLeadV0Response:
      type: object
      properties:
        leadId:
          type: string
          format: uuid
        registered:
          type: boolean
        checkedIn:
          type: boolean
      required:
        - leadId
        - registered
        - checkedIn

    UserV0Response:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          nullable: true
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
      required:
        - id
        - email
        - firstName
        - lastName

    EventAddLeadsV0Input:
      type: object
      properties:
        eventLeads:
          type: array
          items:
            type: object
            properties:
              leadId:
                type: string
                format: uuid
              registered:
                type: boolean
              checkedIn:
                type: boolean
            required:
              - leadId
      required:
        - eventLeads

    # Leads
    PhoneNumber:
      type: object
      properties:
        number:
          type: string
        type:
          $ref: "#/components/schemas/PhoneNumberTypeEnum"
        preferred:
          type: boolean
      required:
        - number
        - type
        - preferred

    LeadPhoneNumbers:
      type: object
      properties:
        leadProvided:
          type: array
          items:
            $ref: "#/components/schemas/PhoneNumber"
        moblyProvided:
          type: array
          items:
            $ref: "#/components/schemas/PhoneNumber"
      required:
        - leadProvided
        - moblyProvided

    LeadCompany:
      type: object
      properties:
        name:
          type: string
          nullable: true
        industry:
          type: string
          nullable: true
        linkedin:
          type: string
          nullable: true
        streetAddress:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        state:
          type: string
          nullable: true
        zip:
          type: string
          nullable: true
        country:
          type: string
          nullable: true

    LeadActivationSummary:
      type: object
      properties:
        activationId:
          type: string
          format: uuid
        checkedIn:
          type: boolean
        registered:
          type: boolean
      required:
        - activationId
        - checkedIn
        - registered

    LeadTag:
      type: object
      properties:
        tagOptionId:
          type: string
          format: uuid
        value:
          type: string
      required:
        - tagOptionId
        - value

    LeadV0Response:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        isEnriched:
          type: boolean
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
        description:
          type: string
          nullable: true
        linkedin:
          type: string
          nullable: true
        facebook:
          type: string
          nullable: true
        twitter:
          type: string
          nullable: true
        jobTitle:
          type: string
          nullable: true
        address:
          type: string
          nullable: true
        phoneNumbers:
          $ref: "#/components/schemas/LeadPhoneNumbers"
        company:
          $ref: "#/components/schemas/LeadCompany"
        numberOfScans:
          type: integer
        lastScannedBy:
          type: string
          format: email
          nullable: true
        activations:
          type: array
          items:
            $ref: "#/components/schemas/LeadActivationSummary"
        tags:
          type: array
          items:
            $ref: "#/components/schemas/LeadTag"
        leadActivityEvents:
          type: array
          items:
            type: string
            format: uuid
        remoteIds:
          type: array
          description: Remote IDs for this lead in external integrations.
          items:
            type: object
            properties:
              id:
                type: string
              integrationType:
                $ref: "#/components/schemas/IntegrationType"
            required:
              - id
              - integrationType
      required:
        - id
        - createdAt
        - isEnriched
        - phoneNumbers
        - company
        - numberOfScans
        - activations
        - tags
        - leadActivityEvents
        - remoteIds

    LeadCreateV0Input:
      type: object
      properties:
        createdByEmail:
          type: string
          format: email
        firstName:
          type: string
        lastName:
          type: string
        companyName:
          type: string
        email:
          type: string
          format: email
        phoneNumbers:
          type: array
          items:
            $ref: "#/components/schemas/PhoneNumber"
      required:
        - createdByEmail
        - firstName
        - lastName
        - companyName

    LeadPatchV0Input:
      type: object
      properties:
        firstName:
          type: string
          nullable: true
        lastName:
          type: string
          nullable: true
        email:
          type: string
          format: email
          nullable: true
        address:
          type: string
          nullable: true
        linkedin:
          type: string
          nullable: true
        facebook:
          type: string
          nullable: true
        twitter:
          type: string
          nullable: true
        profilePicture:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        jobTitle:
          type: string
          nullable: true
        phoneNumbers:
          type: array
          nullable: true
          items:
            $ref: "#/components/schemas/PhoneNumber"
        remoteId:
          type: object
          description: Remote ID to set/clear for a specific integration. If omitted, existing remote IDs remain unchanged.
          properties:
            id:
              type: string
              nullable: true
              description: Remote ID value. Set to null to clear.
            integrationType:
              $ref: "#/components/schemas/IntegrationType"
          required:
            - id
            - integrationType

    # Lead Activity Events
    LeadActivityEventV0Response:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        createdBy:
          type: string
          format: email
          nullable: true
        eventType:
          $ref: "#/components/schemas/LeadActivityEventType"
        eventNotes:
          type: string
          nullable: true
        associatedLead:
          type: string
          format: uuid
        associatedCampaign:
          type: string
          format: uuid
          nullable: true
        associatedEvent:
          type: integer
          format: int64
          nullable: true
        associatedActivation:
          type: string
          format: uuid
          nullable: true
        associatedTagOption:
          type: string
          format: uuid
          nullable: true
      required:
        - id
        - createdAt
        - eventType
        - associatedLead

    # Activations
    ActivationV0Response:
      type: object
      properties:
        id:
          type: string
          format: uuid
        eventId:
          type: integer
          format: int64
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        type:
          $ref: "#/components/schemas/ActivationType"
        startDate:
          type: string
          format: date
        endDate:
          type: string
          format: date
        startTime:
          type: string
          example: "09:00:00"
        endTime:
          type: string
          example: "12:00:00"
        createdBy:
          type: string
          format: email
          nullable: true
        location:
          allOf:
            - $ref: "#/components/schemas/Location"
          nullable: true
        users:
          type: array
          items:
            type: string
            format: email
        numberOfScans:
          type: integer
      required:
        - id
        - eventId
        - name
        - createdAt
        - type
        - startDate
        - endDate
        - startTime
        - endTime
        - users
        - numberOfScans

    # Tag Groups
    TagOption:
      type: object
      properties:
        id:
          type: string
          format: uuid
        displayOrder:
          type: integer
        value:
          type: string
      required:
        - id
        - displayOrder
        - value

    TagGroupV0Response:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        status:
          $ref: "#/components/schemas/TagGroupStatus"
        allowsMultipleSelection:
          type: boolean
        displayOrder:
          type: integer
        usageInstructions:
          type: string
          nullable: true
        required:
          type: boolean
        allEvents:
          type: boolean
        tagOptions:
          type: array
          items:
            $ref: "#/components/schemas/TagOption"
      required:
        - id
        - name
        - status
        - allowsMultipleSelection
        - displayOrder
        - required
        - allEvents
        - tagOptions

    # Industry Events
    IndustryEvent:
      type: object
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        name:
          type: string
        startDate:
          type: string
          format: date-time
          nullable: true
        endDate:
          type: string
          format: date-time
          nullable: true
        sourceType:
          type: string
          nullable: true
        sourceId:
          type: string
          nullable: true
        eventType:
          type: string
          nullable: true
        venueCity:
          type: string
          nullable: true
        venueState:
          type: string
          nullable: true
        venueCountry:
          type: string
          nullable: true
        venueName:
          type: string
          nullable: true
        venueFullAddress:
          type: string
          nullable: true
        venueCoordinates:
          type: string
          nullable: true
        numberOfAttendees:
          type: integer
          nullable: true
        numberOfExhibitors:
          type: integer
          nullable: true
        attendeeCost:
          type: string
          nullable: true
        boothCost:
          type: string
          nullable: true
        exhibitorIndustries:
          type: array
          nullable: true
          items:
            type: string
        attendeePersonas:
          type: array
          nullable: true
          items:
            type: string
        keywords:
          type: array
          nullable: true
          items:
            type: string
        website:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        eventUrl:
          type: string
          nullable: true
        isBookmarked:
          type: boolean
          description: Present only on single-resource endpoint.
      required:
        - id
        - createdAt
        - updatedAt
        - name

    IndustryEventCreateV0Input:
      type: object
      properties:
        name:
          type: string
        startDate:
          type: string
          format: date-time
          nullable: true
        endDate:
          type: string
          format: date-time
          nullable: true
        sourceType:
          type: string
          nullable: true
        sourceId:
          type: string
          nullable: true
        eventType:
          type: string
          nullable: true
        venueCity:
          type: string
          nullable: true
        venueState:
          type: string
          nullable: true
        venueCountry:
          type: string
          nullable: true
        venueName:
          type: string
          nullable: true
        venueFullAddress:
          type: string
          nullable: true
        venueCoordinates:
          type: string
          nullable: true
        numberOfAttendees:
          type: integer
          nullable: true
        numberOfExhibitors:
          type: integer
          nullable: true
        attendeeCost:
          type: string
          nullable: true
        boothCost:
          type: string
          nullable: true
        exhibitorIndustries:
          type: array
          nullable: true
          items:
            type: string
        attendeePersonas:
          type: array
          nullable: true
          items:
            type: string
        keywords:
          type: array
          nullable: true
          items:
            type: string
        website:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        eventUrl:
          type: string
          nullable: true
      required:
        - name

    IndustryEventUpdateV0Input:
      type: object
      properties:
        name:
          type: string
        startDate:
          type: string
          format: date-time
          nullable: true
        endDate:
          type: string
          format: date-time
          nullable: true
        sourceType:
          type: string
          nullable: true
        sourceId:
          type: string
          nullable: true
        eventType:
          type: string
          nullable: true
        venueCity:
          type: string
          nullable: true
        venueState:
          type: string
          nullable: true
        venueCountry:
          type: string
          nullable: true
        venueName:
          type: string
          nullable: true
        venueFullAddress:
          type: string
          nullable: true
        venueCoordinates:
          type: string
          nullable: true
        numberOfAttendees:
          type: integer
          nullable: true
        numberOfExhibitors:
          type: integer
          nullable: true
        attendeeCost:
          type: string
          nullable: true
        boothCost:
          type: string
          nullable: true
        exhibitorIndustries:
          type: array
          nullable: true
          items:
            type: string
        attendeePersonas:
          type: array
          nullable: true
          items:
            type: string
        keywords:
          type: array
          nullable: true
          items:
            type: string
        website:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
        eventUrl:
          type: string
          nullable: true

    IndustryEventListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            industryEvents:
              type: array
              items:
                $ref: "#/components/schemas/IndustryEvent"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    IndustryEventSingleResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          type: object
          properties:
            industryEvent:
              $ref: "#/components/schemas/IndustryEvent"
      required:
        - status
        - results

    IndustryEventCreateResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          type: object
          properties:
            industryEvent:
              $ref: "#/components/schemas/IndustryEvent"
            created:
              type: boolean
              description: Whether a new record was created (false if matched by eventUrl).
            potentialDuplicates:
              type: array
              description: Existing events with matching name + startDate.
              items:
                $ref: "#/components/schemas/IndustryEvent"
      required:
        - status
        - results

    # Response envelopes
    EventListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            events:
              type: array
              items:
                $ref: "#/components/schemas/Event"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    EventSingleResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          $ref: "#/components/schemas/Event"
      required:
        - status
        - results

    EventLeadsListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            eventLeads:
              type: array
              items:
                $ref: "#/components/schemas/EventLeadV0Response"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    EventUsersListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            users:
              type: array
              items:
                $ref: "#/components/schemas/UserV0Response"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    EventLeadsUpdateResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          type: object
          properties:
            eventLeads:
              type: array
              items:
                $ref: "#/components/schemas/EventLeadV0Response"
      required:
        - status
        - results

    LeadsListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            leads:
              type: array
              items:
                $ref: "#/components/schemas/LeadV0Response"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    LeadSingleResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          $ref: "#/components/schemas/LeadV0Response"
      required:
        - status
        - results

    LeadActivityEventsListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            leadActivityEvents:
              type: array
              items:
                $ref: "#/components/schemas/LeadActivityEventV0Response"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    LeadActivityEventSingleResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          $ref: "#/components/schemas/LeadActivityEventV0Response"
      required:
        - status
        - results

    ActivationsListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            activations:
              type: array
              items:
                $ref: "#/components/schemas/ActivationV0Response"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    ActivationSingleResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          $ref: "#/components/schemas/ActivationV0Response"
      required:
        - status
        - results

    TagGroupsListResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        pagination:
          $ref: "#/components/schemas/Pagination"
        results:
          type: object
          properties:
            tagGroups:
              type: array
              items:
                $ref: "#/components/schemas/TagGroupV0Response"
            total:
              type: integer
      required:
        - status
        - pagination
        - results

    TagGroupSingleResponse:
      type: object
      properties:
        status:
          type: integer
          example: 200
        results:
          $ref: "#/components/schemas/TagGroupV0Response"
      required:
        - status
        - results

paths:
  /events:
    get:
      summary: List events
      description: List events for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Events list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventListResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "403":
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "429":
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      summary: Create event
      description: Create an event for the authenticated organization.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventCreateV0Input"
      responses:
        "200":
          description: Created event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSingleResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /events/{eventId}:
    get:
      summary: Get event
      description: Fetch a single event by ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: eventId
          schema:
            type: integer
          required: true
          description: Event ID
      responses:
        "200":
          description: Event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSingleResponse"
        "404":
          description: Event not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    put:
      summary: Update event
      description: Update the full event record for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: eventId
          schema:
            type: integer
          required: true
          description: Event ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventUpdateV0Input"
      responses:
        "200":
          description: Updated event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventSingleResponse"
        "404":
          description: Event not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      summary: Delete event
      description: Delete an event for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: eventId
          schema:
            type: integer
          required: true
          description: Event ID
      responses:
        "200":
          description: Event deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  results:
                    type: object
                required:
                  - status
                  - results
        "404":
          description: Event not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /events/{eventId}/leads:
    get:
      summary: List event leads
      description: Retrieve the leads associated with a specific event, including registration and check-in status.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: eventId
          schema:
            type: integer
          required: true
          description: Event ID
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Event leads list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventLeadsListResponse"

    put:
      summary: Add or update event leads
      description: |
        Associate existing leads with an event and optionally update their `registered` and `checkedIn` status.

        - Creates association if missing.
        - Updates flags if association exists.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: eventId
          schema:
            type: integer
          required: true
          description: Event ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/EventAddLeadsV0Input"
      responses:
        "200":
          description: Updated event lead associations.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventLeadsUpdateResponse"

  /events/{eventId}/leads/{leadId}:
    delete:
      summary: Remove lead from event
      description: Delete a lead's association with an event for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: eventId
          schema:
            type: integer
          required: true
          description: Event ID
        - in: path
          name: leadId
          schema:
            type: string
          required: true
          description: Lead ID
      responses:
        "200":
          description: Association removed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  results:
                    type: object
                required:
                  - status
                  - results

  /events/{eventId}/users:
    get:
      summary: List event users
      description: Retrieve the users assigned to a specific event for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: eventId
          schema:
            type: integer
          required: true
          description: Event ID
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Event users list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventUsersListResponse"

  /leads:
    get:
      summary: List leads
      description: List leads for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Leads list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeadsListResponse"

    post:
      summary: Create lead
      description: Create a lead for the authenticated organization.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LeadCreateV0Input"
      responses:
        "200":
          description: Created lead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeadSingleResponse"

  /leads/{leadId}:
    get:
      summary: Get lead
      description: Fetch a single lead by ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: leadId
          schema:
            type: string
          required: true
          description: Lead ID
      responses:
        "200":
          description: Lead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeadSingleResponse"
        "404":
          description: Lead not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    patch:
      summary: Patch lead
      description: Partially update a lead and its associated persona record.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: leadId
          schema:
            type: string
          required: true
          description: Lead ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LeadPatchV0Input"
      responses:
        "200":
          description: Updated lead.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeadSingleResponse"

    delete:
      summary: Delete lead
      description: Delete a lead for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: leadId
          schema:
            type: string
          required: true
          description: Lead ID
      responses:
        "200":
          description: Lead deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  results:
                    type: object
                required:
                  - status
                  - results

  /leadActivityEvents:
    get:
      summary: List lead activity events
      description: List lead activity events for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
        - in: query
          name: leadId
          schema:
            type: string
            description: Filter by associated lead ID
        - in: query
          name: eventType
          schema:
            $ref: "#/components/schemas/LeadActivityEventType"
      responses:
        "200":
          description: Lead activity events list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeadActivityEventsListResponse"

  /leadActivityEvents/{leadActivityEventId}:
    get:
      summary: Get lead activity event
      description: Fetch a single lead activity event by ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: leadActivityEventId
          schema:
            type: string
          required: true
          description: Lead activity event ID
      responses:
        "200":
          description: Lead activity event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LeadActivityEventSingleResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /activations:
    get:
      summary: List activations
      description: List activations for the organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Activations list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivationsListResponse"

  /activations/{activationId}:
    get:
      summary: Get activation
      description: Fetch a single activation by ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: activationId
          schema:
            type: string
          required: true
          description: Activation ID
      responses:
        "200":
          description: Activation.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivationSingleResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /tagGroups:
    get:
      summary: List tag groups
      description: List tag groups defined for the organization, including tag options.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Tag groups list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagGroupsListResponse"

  /tagGroups/{tagGroupId}:
    get:
      summary: Get tag group
      description: Fetch a single tag group by ID.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: tagGroupId
          schema:
            type: string
          required: true
          description: Tag group ID
      responses:
        "200":
          description: Tag group.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TagGroupSingleResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /industryEvents:
    get:
      summary: List industry events
      description: |
        List industry events. Supports filtering by URL or full-text search.

        - `eventUrl` — return only the event matching this exact URL
        - `q` — full-text search across name, venueCity, venueState, venueCountry, description, keywords, industries, personas

        If `eventUrl` is provided, `q` is ignored. If neither is provided, all industry events are returned (paginated).
      security:
        - ApiKeyAuth: []
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            default: 20
            maximum: 50
        - in: query
          name: offset
          schema:
            type: integer
            default: 0
        - in: query
          name: eventUrl
          schema:
            type: string
          description: Filter by exact event URL
        - in: query
          name: q
          schema:
            type: string
          description: Full-text search query
      responses:
        "200":
          description: Industry events list.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndustryEventListResponse"
        "401":
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    post:
      summary: Create industry event
      description: |
        Create an industry event with automatic deduplication:

        1. If an event with the same `eventUrl` already exists, the existing record is returned (`created: false`).
        2. If no URL match but `name` and `startDate` match, the event is still created but `potentialDuplicates` are returned.
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IndustryEventCreateV0Input"
      responses:
        "200":
          description: Created or existing industry event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndustryEventCreateResponse"
        "400":
          description: Bad request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /industryEvents/bookmarks:
    get:
      summary: List bookmarked industry events
      description: List industry events bookmarked by the authenticated organization.
      security:
        - ApiKeyAuth: []
      responses:
        "200":
          description: Bookmarked industry events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  results:
                    type: object
                    properties:
                      industryEvents:
                        type: array
                        items:
                          $ref: "#/components/schemas/IndustryEvent"

  /industryEvents/{industryEventId}:
    get:
      summary: Get industry event
      description: Fetch a single industry event by ID. Includes `isBookmarked` for the authenticated organization.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: industryEventId
          schema:
            type: string
            format: uuid
          required: true
          description: Industry event ID
      responses:
        "200":
          description: Industry event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndustryEventSingleResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    put:
      summary: Update industry event
      description: Partially update an industry event. Only fields included in the body are modified.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: industryEventId
          schema:
            type: string
            format: uuid
          required: true
          description: Industry event ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IndustryEventUpdateV0Input"
      responses:
        "200":
          description: Updated industry event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IndustryEventSingleResponse"
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

  /industryEvents/{industryEventId}/bookmark:
    post:
      summary: Bookmark industry event
      description: Add an industry event to the authenticated organization's bookmarks.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: industryEventId
          schema:
            type: string
            format: uuid
          required: true
          description: Industry event ID
      responses:
        "200":
          description: Bookmarked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  results:
                    type: object
                    properties:
                      success:
                        type: boolean
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"

    delete:
      summary: Unbookmark industry event
      description: Remove an industry event from the authenticated organization's bookmarks.
      security:
        - ApiKeyAuth: []
      parameters:
        - in: path
          name: industryEventId
          schema:
            type: string
            format: uuid
          required: true
          description: Industry event ID
      responses:
        "200":
          description: Unbookmarked.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: integer
                    example: 200
                  results:
                    type: object
                    properties:
                      success:
                        type: boolean
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
