openapi: 3.0.1
servers:
  - url: https://api.hubapi.com
info:
  description: HTTP API for triggering instances of custom behavioral events
  title: Events Send Event Completions
  version: v3
  x-hubspot-api-use-case: You want to track more complex interactions that visitors perform when they navigate to your website and engage with your content.
  x-hubspot-documentation-banner: NONE
  x-hubspot-introduction: Use the custom events API to define events that you can later create and associate with records in your HubSpot CRM.
  x-hubspot-product-tier-requirements:
    cms: ENTERPRISE
    marketing: ENTERPRISE
    sales: ENTERPRISE
    service: ENTERPRISE
  x-hubspot-related-documentation:
    - name: Custom events guide
      url: https://hubspot.dev/guides/api/analytics/events
  x-logo:
    url: https://www.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/send
      version: "3.0"
  x-providerName: hubapi.com
  x-serviceName: analytics
tags:
  - name: Custom event data
  - name: Behavioral_Events_Tracking
  - name: ""
paths:
  /events/v3/send:
    post:
      description: Endpoint to send an instance of a custom event.
      operationId: post-/events/v3/send_send
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BehavioralEventHttpCompletionRequest"
        required: true
      responses:
        "204":
          content: {}
          description: No content
        default:
          $ref: "#/components/responses/Error"
      security:
        - private_apps_legacy: []
        - oauth2_legacy:
            - analytics.behavioral_events.send
      summary: Send custom event completion
      tags:
        - Custom event data
components:
  responses:
    Error:
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/Error"
      description: An error occurred.
  schemas:
    BehavioralEventHttpCompletionRequest:
      properties:
        email:
          description: Email of visitor
          type: string
        eventName:
          description: Internal name of the event-type to trigger
          type: string
        objectId:
          description: The object id that this event occurred on. Could be a contact id or a visitor id.
          type: string
        occurredAt:
          description: The time when this event occurred (if any). If this isn't set, the current time will be used
          format: date-time
          type: string
        properties:
          additionalProperties:
            type: string
          description: Map of properties for the event in the format property internal name - property value
          type: object
        utk:
          description: User token
          type: string
        uuid:
          type: string
      required:
        - eventName
      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
  securitySchemes:
    oauth2_legacy:
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          scopes:
            analytics.behavioral_events.send: Send Behavioral Event Completions
            behavioral_events.event_definitions.read_write: Read from and write to custom behavioral events definitions
          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
