openapi: 3.0.1
servers:
  - url: https://api.hubapi.com
info:
  description: API for accessing CRM object events.
  title: Events
  version: v3
  x-hubspot-api-use-case: You want to view a timeline of the interactions that a contact has had with your content. You can then use this timeline to build a dataset for custom analytics or present a contact timeline in an external application.
  x-hubspot-documentation-banner: NONE
  x-hubspot-introduction: Use the web analytics API to fetch events associated with CRM records of any type. This includes standard events, such as website page views and email opens, as well as custom events.
  x-hubspot-product-tier-requirements:
    cms: ENTERPRISE
    marketing: ENTERPRISE
    sales: ENTERPRISE
    service: ENTERPRISE
  x-hubspot-related-documentation:
    - name: Web Analytics Guide
      url: https://hubspot.dev/guides/api/events/web-analytics
  x-logo:
    url: 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:
  - description: ""
    name: Events
    x-hubspot-tag-name-english-source: Events
paths:
  /events/v3/events/:
    get:
      operationId: get-/events/v3/events/_getPage
      parameters:
        - explode: true
          in: query
          name: objectType
          required: false
          schema:
            type: string
          style: form
        - explode: true
          in: query
          name: eventType
          required: false
          schema:
            type: string
          style: form
        - explode: true
          in: query
          name: occurredAfter
          required: false
          schema:
            format: date-time
            type: string
          style: form
        - explode: true
          in: query
          name: occurredBefore
          required: false
          schema:
            format: date-time
            type: string
          style: form
        - explode: true
          in: query
          name: objectId
          required: false
          schema:
            format: int64
            type: integer
          style: form
        - explode: true
          in: query
          name: indexTableName
          required: false
          schema:
            type: string
          style: form
        - explode: true
          in: query
          name: indexSpecificMetadata
          required: false
          schema:
            type: string
          style: form
        - description: The paging cursor token of the last successfully read resource will be returned as the `paging.next.after` JSON property of a paged response containing more 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 results to display per page.
          explode: true
          in: query
          name: limit
          required: false
          schema:
            format: int32
            type: integer
          style: form
        - explode: true
          in: query
          name: sort
          required: false
          schema:
            items:
              type: string
            type: array
          style: form
        - explode: true
          in: query
          name: objectProperty.{propname}
          required: false
          schema:
            type: object
          style: form
        - explode: true
          in: query
          name: property.{propname}
          required: false
          schema:
            type: object
          style: form
        - explode: true
          in: query
          name: id
          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:
        - private_apps_legacy: []
        - oauth2_legacy:
            - oauth
      tags:
        - Events
components:
  responses:
    Error:
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/Error"
      description: An error occurred.
  schemas:
    CollectionResponseExternalUnifiedEvent:
      properties:
        paging:
          $ref: "#/components/schemas/Paging"
        results:
          description: ""
          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
          example: VALIDATION_ERROR
          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
          example:
            knowledge-base: https://www.hubspot.com/products/service/knowledge-base
          type: object
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          example: Invalid input (details will vary based on the error)
          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
      type: object
    NextPage:
      properties:
        after:
          description: ""
          type: string
        link:
          description: ""
          type: string
      required:
        - after
      type: object
    Paging:
      properties:
        next:
          $ref: "#/components/schemas/NextPage"
        prev:
          $ref: "#/components/schemas/PreviousPage"
      type: object
    PreviousPage:
      properties:
        before:
          type: string
        link:
          type: string
      required:
        - before
      type: object
  securitySchemes:
    oauth2_legacy:
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          scopes:
            oauth: User and Account Information
          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
  - Ruby
  - Python
x-hubspot-documentation-banner: NONE
x-hubspot-product-tier-requirements:
  cms: ENTERPRISE
  marketing: ENTERPRISE
  sales: ENTERPRISE
  service: ENTERPRISE
