Mobly REST API v0

The Mobly REST API (v0) gives programmatic access to events, leads, lead activity events, activations, qualifier/tag groups and industry events for the authenticated organization. All endpoints are JSON, versioned under /v0, authenticated with an `x-api-key` header, paginated with limit/offset, and rate limited per API key with a token bucket that returns X-RateLimit-* headers on every response.

OpenAPI Specification

mobly-rest-api-v0-openapi.yml Raw ↑
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
           

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mobly/refs/heads/main/openapi/mobly-rest-api-v0-openapi.yml