openapi: 3.0.1
servers:
  - url: https://api.hubapi.com/
info:
  description: API for accessing CRM object events.
  title: HubSpot Events API
  version: v3
  x-logo:
    url: https://api.apis.guru/v2/cache/logo/https_developers.hubspot.com_hubfs_assets_hubspot.com_buzz_HubSpotOpenGraph.png
  x-origin:
    - format: openapi
      url: https://api.hubspot.com/api-catalog-public/v1/apis/events/v3/events
      version: "3.0"
  x-providerName: hubapi.com
  x-serviceName: events
tags:
  - name: Events
paths:
  /events/v3/events:
    get:
      operationId: get-/events/v3/events_getPage
      parameters:
        - description: The starting time as an ISO 8601 timestamp.
          explode: true
          in: query
          name: occurredAfter
          required: false
          schema:
            format: date-time
            type: string
          style: form
        - description: The ending time as an ISO 8601 timestamp.
          explode: true
          in: query
          name: occurredBefore
          required: false
          schema:
            format: date-time
            type: string
          style: form
        - description: The type of object being selected. Valid values are hubspot named object types (e.g. `contact`).
          explode: true
          in: query
          name: objectType
          required: false
          schema:
            type: string
          style: form
        - description: The id of the selected object. If not present, then the `objectProperty` parameter is required.
          explode: true
          in: query
          name: objectId
          required: false
          schema:
            format: int64
            type: integer
          style: form
        - description: Limits the response to the specified event type.  For example `&eventType=e_visited_page` returns only `e_visited_page` events.  If not present all event types are returned.
          explode: true
          in: query
          name: eventType
          required: false
          schema:
            type: string
          style: form
        - description: An additional parameter that may be used to get the next `limit` set of results.
          explode: true
          in: query
          name: after
          required: false
          schema:
            type: string
          style: form
        - explode: true
          in: query
          name: before
          required: false
          schema:
            type: string
          style: form
        - description: The maximum number of events to return, defaults to 20.
          explode: true
          in: query
          name: limit
          required: false
          schema:
            format: int32
            type: integer
          style: form
        - description: Selects the sort field and order. Defaults to ascending, prefix with `-` for descending order. `occurredAt` is the only field supported for sorting.
          explode: true
          in: query
          name: sort
          required: false
          schema:
            items:
              type: string
            type: array
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CollectionResponseExternalUnifiedEvent"
          description: successful operation
        default:
          $ref: "#/components/responses/Error"
      security:
        - hapikey: []
        - oauth2_legacy:
            - business-intelligence
        - private_apps_legacy: []
      summary: Returns a collection of events matching a query.
      tags:
        - Events
components:
  responses:
    Error:
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/Error"
      description: An error occurred.
  schemas:
    CollectionResponseExternalUnifiedEvent:
      properties:
        paging:
          $ref: "#/components/schemas/Paging"
        results:
          items:
            $ref: "#/components/schemas/ExternalUnifiedEvent"
          type: array
      required:
        - results
      type: object
    Error:
      example:
        category: VALIDATION_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
        message: Invalid input (details will vary based on the error)
      properties:
        category:
          description: The error category
          type: string
        context:
          additionalProperties:
            items:
              type: string
            type: array
          description: Context about the error condition
          example:
            invalidPropertyName:
              - propertyValue
            missingScopes:
              - scope1
              - scope2
          type: object
        correlationId:
          description: A unique identifier for the request. Include this value with any error reports or support tickets
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
          format: uuid
          type: string
        errors:
          description: further information about the error
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type: array
        links:
          additionalProperties:
            type: string
          description: A map of link names to associated URIs containing documentation about the error or recommended remediation steps
          type: object
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          example: An error occurred
          type: string
        subCategory:
          description: A specific category that contains more specific detail about the error
          type: string
      required:
        - category
        - correlationId
        - message
      type: object
    ErrorDetail:
      properties:
        code:
          description: The status code associated with the error detail
          type: string
        context:
          additionalProperties:
            items:
              type: string
            type: array
          description: Context about the error condition
          example:
            missingScopes:
              - scope1
              - scope2
          type: object
        in:
          description: The name of the field or parameter in which the error was found.
          type: string
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          type: string
        subCategory:
          description: A specific category that contains more specific detail about the error
          type: string
      required:
        - message
      type: object
    ExternalUnifiedEvent:
      description: |-
        Used to represent any event. With this format, the `objectType` and `eventType` values are stringified CRM types. Example object:
        <br/>
        ```
         {
              "objectType": "CONTACT",
              "objectId": 208451632,
              "eventType": "e_visited_page",
              "occurredAt": 1567377501421,
              "id": "leviathan-be3335d3-46f1-3985-988e-ff38e6e7b9d8",
              "properties": {
                  "hs_url": "https://some-website.com/",
                  "hs_title": "Home",
                  "hs_referrer": "https://some-other-website.com/blog/why-we-love-big-data-and-you-should-too",
                  "hs_userAgent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/46.0.2490.80 Safari/537.36",
                  "hs_city": "lund",
                  "hs_region": "m",
                  "hs_country": "se",
                  "hs_session_id" : "leviathan-be3335d3-46f1-3985-988e-ff38e6e7b9d8",
                  "hs_session_source" : "DIRECT"
              }
          }      
        ```
      properties:
        eventType:
          description: The format of the `eventType` string is `ae{appId}_{eventTypeLabel}`, `pe{portalId}_{eventTypeLabel}`, or just `e_{eventTypeLabel}` for HubSpot events.
          type: string
        id:
          description: A unique identifier for the event.
          type: string
        objectId:
          description: The objectId of the object which did the event.
          type: string
        objectType:
          description: The objectType for the object which did the event.
          type: string
        occurredAt:
          description: An ISO 8601 timestamp when the event occurred.
          format: date-time
          type: string
        properties:
          additionalProperties:
            type: string
          type: object
      required:
        - eventType
        - id
        - objectId
        - objectType
        - occurredAt
        - properties
      type: object
    NextPage:
      properties:
        after:
          type: string
        link:
          type: string
      required:
        - after
      type: object
    Paging:
      properties:
        next:
          $ref: "#/components/schemas/NextPage"
      type: object
  securitySchemes:
    hapikey:
      in: query
      name: hapikey
      type: apiKey
    oauth2_legacy:
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          scopes:
            business-intelligence: Read from Business Intelligence API
          tokenUrl: https://api.hubapi.com/oauth/v1/token
      type: oauth2
    private_apps_legacy:
      in: header
      name: private-app-legacy
      type: apiKey
x-hubspot-available-client-libraries:
  - PHP
  - Node
  - Python
  - Ruby
