---
title: "Retrieve event definitions"
method: GET
path: "/events/v3/event-definitions"
tags: ["Basic"]
---

# Retrieve event definitions

`GET /events/v3/event-definitions`

## Request

- Base URL: `https://api.hubapi.com`
- URL: `https://api.hubapi.com/events/v3/event-definitions`
- Auth: OAuth 2
  - Authorization code: `https://app.hubspot.com/oauth/authorize`
  - Token URL: `https://api.hubapi.com/oauth/v1/token` scopes: `behavioral_events.event_definitions.read_write`

Retrieve existing custom event definitions.

## Query parameters

- `after` string
- `includeProperties` boolean
- `limit` integer
- `searchString` string
- `sortOrder` string

## Response `200`

successful operation

- CollectionResponseWithTotalExternalBehavioralEventTypeDefinition
  - `paging` Paging: Represents the pagination information for navigating through a list of results in the API. It provides details on how to access the previous or next set of results.
    - `next` NextPage: Specifies the paging information needed to retrieve the next set of results in a paginated API response
      - `after` string, required: A paging cursor token for retrieving subsequent pages.
      - `link` string: A URL that can be used to retrieve the next page results.
    - `prev` PreviousPage: specifies the paging information needed to retrieve the previous set of results in a paginated API response
      - `before` string, required: A paging cursor token for retrieving previous pages.
      - `link` string: A URL that can be used to retrieve the previous pages' results.
  - `results` ExternalBehavioralEventTypeDefinition[], required
    - `archived` boolean, required
    - `associations` AssociationDefinition[], required
      - `allowsCustomLabels` boolean, required: Whether custom labels can be used in the association.
      - `cardinality` 'ONE_TO_MANY' | 'ONE_TO_ONE', required: The cardinality from the source object's perspective, either "ONE_TO_ONE" or "ONE_TO_MANY".
      - `category` 'HUBSPOT_DEFINED' | 'INTEGRATOR_DEFINED' | 'USER_DEFINED' | 'WORK', required: The error category
      - `fromObjectType` 'ABANDONED_CART' | 'ACCEPTANCE_TEST' | 'AD' | 'AD_ACCOUNT' | 'AD_CAMPAIGN' | 'AD_GROUP' | 'AI_FORECAST' | 'ALL_PAGES' | 'APPROVAL' | 'APPROVAL_STEP' | 'ATTRIBUTION' | 'AUDIENCE' | 'AUTOMATION_JOURNEY' | 'AUTOMATION_PLATFORM_FLOW' | 'AUTOMATION_PLATFORM_FLOW_ACTION' | 'BET_ALERT' | 'BET_DELIVERABLE_SERVICE' | 'BLOG_LISTING_PAGE' | 'BLOG_POST' | 'CALL' | 'CAMPAIGN' | 'CAMPAIGN_BUDGET_ITEM' | 'CAMPAIGN_SPEND_ITEM' | 'CAMPAIGN_STEP' | 'CAMPAIGN_TEMPLATE' | 'CAMPAIGN_TEMPLATE_STEP' | 'CART' | 'CASE_STUDY' | 'CHATFLOW' | 'CLIP' | 'CMS_URL' | 'COMBO_EVENT_CONFIGURATION' | 'COMMERCE_PAYMENT' | 'COMMUNICATION' | 'COMPANY' | 'CONTACT' | 'CONTACT_CREATE_ATTRIBUTION' | 'CONTENT' | 'CONTENT_AUDIT' | 'CONTENT_AUDIT_PAGE' | 'CONVERSATION' | 'CONVERSATION_INBOX' | 'CONVERSATION_SESSION' | 'CRM_OBJECTS_DUMMY_TYPE' | 'CRM_PIPELINES_DUMMY_TYPE' | 'CTA' | 'CTA_VARIANT' | 'DATA_PRIVACY_CONSENT' | 'DATA_SYNC_STATE' | 'DEAL' | 'DEAL_CREATE_ATTRIBUTION' | 'DEAL_REGISTRATION' | 'DEAL_SPLIT' | 'DISCOUNT' | 'DISCOUNT_CODE' | 'DISCOUNT_TEMPLATE' | 'EMAIL' | 'ENGAGEMENT' | 'EXPORT' | 'EXTERNAL_WEB_URL' | 'FEE' | 'FEEDBACK_SUBMISSION' | 'FEEDBACK_SURVEY' | 'FILE_MANAGER_FILE' | 'FILE_MANAGER_FOLDER' | 'FOLDER' | 'FORECAST' | 'FORM' | 'FORM_SUBMISSION_INBOUNDDB' | 'GOAL_TARGET' | 'GOAL_TARGET_GROUP' | 'GOAL_TEMPLATE' | 'GSC_PROPERTY' | 'HUB' | 'IMPORT' | 'INVOICE' | 'KEYWORD' | 'KNOWLEDGE_ARTICLE' | 'LANDING_PAGE' | 'LEAD' | 'LINE_ITEM' | 'MARKETING_CALENDAR' | 'MARKETING_CAMPAIGN_UTM' | 'MARKETING_EMAIL' | 'MARKETING_EVENT' | 'MARKETING_EVENT_ATTENDANCE' | 'MARKETING_SMS' | 'MEDIA_BRIDGE' | 'MEETING_EVENT' | 'MIC' | 'NOTE' | 'OBJECT_LIST' | 'ORDER' | 'OWNER' | 'PARTNER_ACCOUNT' | 'PARTNER_CLIENT' | 'PARTNER_CLIENT_REVENUE' | 'PARTNER_SERVICE' | 'PAYMENT_LINK' | 'PAYMENT_SCHEDULE' | 'PAYMENT_SCHEDULE_INSTALLMENT' | 'PERMISSIONS_TESTING' | 'PLAYBOOK' | 'PLAYBOOK_QUESTION' | 'PLAYBOOK_SUBMISSION' | 'PLAYBOOK_SUBMISSION_ANSWER' | 'PLAYLIST' | 'PLAYLIST_FOLDER' | 'PODCAST_EPISODE' | 'PORTAL' | 'PORTAL_OBJECT_SYNC_MESSAGE' | 'POSTAL_MAIL' | 'PRIVACY_SCANNER_COOKIE' | 'PRODUCT' | 'PRODUCT_OR_FOLDER' | 'PROPERTY_INFO' | 'PROSPECTING_AGENT_CONTACT_ASSIGNMENT' | 'PUBLISHING_TASK' | 'QUARANTINED_SUBMISSION' | 'QUOTA' | 'QUOTE' | 'QUOTE_FIELD' | 'QUOTE_MODULE' | 'QUOTE_MODULE_FIELD' | 'QUOTE_TEMPLATE' | 'RESTORABLE_CRM_OBJECT' | 'ROSTER' | 'ROSTER_MEMBER' | 'SALES_DOCUMENT' | 'SALES_TASK' | 'SALES_WORKLOAD' | 'SALESFORCE_SYNC_ERROR' | 'SCHEDULING_PAGE' | 'SCHEMAS_BACKEND_TEST' | 'SCORE_CONFIGURATION' | 'SEQUENCE' | 'SEQUENCE_ENROLLMENT' | 'SEQUENCE_STEP' | 'SEQUENCE_STEP_ENROLLMENT' | 'SERVICE' | 'SITE_PAGE' | 'SNIPPET' | 'SOCIAL_BROADCAST' | 'SOCIAL_CHANNEL' | 'SOCIAL_POST' | 'SOCIAL_PROFILE' | 'SOX_PROTECTED_DUMMY_TYPE' | 'SOX_PROTECTED_TEST_TYPE' | 'SUBMISSION_TAG' | 'SUBSCRIPTION' | 'TASK' | 'TASK_TEMPLATE' | 'TAX' | 'TEMPLATE' | 'TICKET' | 'UNKNOWN' | 'UNSUBSCRIBE' | 'USER' | 'VIEW' | 'VIEW_BLOCK' | 'WEB_INTERACTIVE': The name of the source object type (e.g,. "DEAL" or "QUOTE").
      - `fromObjectTypeId` string, required: The ID of the source object type (e.g., 0-1 for contacts).
      - `hasAllAssociatedObjects` boolean, required: Whether all potential linked objects are included in the association
      - `hasCascadingDeletes` boolean, required: Whether deletions in the association should cause cascading deletes to linked objects.
      - `hasUserEnforcedMaxFromObjectIds` boolean, required: Whether a user has set a limit for the number of source objects.
      - `hasUserEnforcedMaxToObjectIds` boolean, required: Whether a user has set a limit for the number of destination objects.
      - `hidden` boolean, required: Whether the association is hidden or not.
      - `hiddenReason` 'DEFAULT' | 'INTERNAL' | 'USER_CONFIGURED'
      - `id` integer, required: The unique ID of the associated object (e.g., a contact ID).
      - `inverseAllowsCustomLabels` boolean, required: Whether the reverse association can also support custom labels.
      - `inverseCardinality` 'ONE_TO_MANY' | 'ONE_TO_ONE', required: The cardinality from the destination object's perspective, either "ONE_TO_ONE" or "ONE_TO_MANY".
      - `inverseHasAllAssociatedObjects` boolean, required: Whether all potential reverse linked objects are included in the association.
      - `inverseId` integer, required: The unique ID for the inverse side of the association.
      - `inverseLabel` string: The label used to describe the reverse relationship in an association.
      - `inverseName` string, required: The name used to describe the inverse relationship in this association
      - `isDefault` boolean, required
      - `isInversePrimary` boolean, required: Whether the inverse association is considered primary.
      - `isPrimary` boolean, required: Whether the association is the primary link between the entities involved.
      - `label` string: The label given to an association.
      - `maxFromObjectIds` integer, required: The maximum number of source object IDs allowed in the association.
      - `maxToObjectIds` integer, required: The maximum number of destination object IDs allowed in the association.
      - `name` string, required: For labeled association types, the internal name of the association.
      - `portalUniqueIdentifier` string, required: A unique across-portal ID applied to the association.
      - `readOnly` boolean, required
      - `toObjectType` 'ABANDONED_CART' | 'ACCEPTANCE_TEST' | 'AD' | 'AD_ACCOUNT' | 'AD_CAMPAIGN' | 'AD_GROUP' | 'AI_FORECAST' | 'ALL_PAGES' | 'APPROVAL' | 'APPROVAL_STEP' | 'ATTRIBUTION' | 'AUDIENCE' | 'AUTOMATION_JOURNEY' | 'AUTOMATION_PLATFORM_FLOW' | 'AUTOMATION_PLATFORM_FLOW_ACTION' | 'BET_ALERT' | 'BET_DELIVERABLE_SERVICE' | 'BLOG_LISTING_PAGE' | 'BLOG_POST' | 'CALL' | 'CAMPAIGN' | 'CAMPAIGN_BUDGET_ITEM' | 'CAMPAIGN_SPEND_ITEM' | 'CAMPAIGN_STEP' | 'CAMPAIGN_TEMPLATE' | 'CAMPAIGN_TEMPLATE_STEP' | 'CART' | 'CASE_STUDY' | 'CHATFLOW' | 'CLIP' | 'CMS_URL' | 'COMBO_EVENT_CONFIGURATION' | 'COMMERCE_PAYMENT' | 'COMMUNICATION' | 'COMPANY' | 'CONTACT' | 'CONTACT_CREATE_ATTRIBUTION' | 'CONTENT' | 'CONTENT_AUDIT' | 'CONTENT_AUDIT_PAGE' | 'CONVERSATION' | 'CONVERSATION_INBOX' | 'CONVERSATION_SESSION' | 'CRM_OBJECTS_DUMMY_TYPE' | 'CRM_PIPELINES_DUMMY_TYPE' | 'CTA' | 'CTA_VARIANT' | 'DATA_PRIVACY_CONSENT' | 'DATA_SYNC_STATE' | 'DEAL' | 'DEAL_CREATE_ATTRIBUTION' | 'DEAL_REGISTRATION' | 'DEAL_SPLIT' | 'DISCOUNT' | 'DISCOUNT_CODE' | 'DISCOUNT_TEMPLATE' | 'EMAIL' | 'ENGAGEMENT' | 'EXPORT' | 'EXTERNAL_WEB_URL' | 'FEE' | 'FEEDBACK_SUBMISSION' | 'FEEDBACK_SURVEY' | 'FILE_MANAGER_FILE' | 'FILE_MANAGER_FOLDER' | 'FOLDER' | 'FORECAST' | 'FORM' | 'FORM_SUBMISSION_INBOUNDDB' | 'GOAL_TARGET' | 'GOAL_TARGET_GROUP' | 'GOAL_TEMPLATE' | 'GSC_PROPERTY' | 'HUB' | 'IMPORT' | 'INVOICE' | 'KEYWORD' | 'KNOWLEDGE_ARTICLE' | 'LANDING_PAGE' | 'LEAD' | 'LINE_ITEM' | 'MARKETING_CALENDAR' | 'MARKETING_CAMPAIGN_UTM' | 'MARKETING_EMAIL' | 'MARKETING_EVENT' | 'MARKETING_EVENT_ATTENDANCE' | 'MARKETING_SMS' | 'MEDIA_BRIDGE' | 'MEETING_EVENT' | 'MIC' | 'NOTE' | 'OBJECT_LIST' | 'ORDER' | 'OWNER' | 'PARTNER_ACCOUNT' | 'PARTNER_CLIENT' | 'PARTNER_CLIENT_REVENUE' | 'PARTNER_SERVICE' | 'PAYMENT_LINK' | 'PAYMENT_SCHEDULE' | 'PAYMENT_SCHEDULE_INSTALLMENT' | 'PERMISSIONS_TESTING' | 'PLAYBOOK' | 'PLAYBOOK_QUESTION' | 'PLAYBOOK_SUBMISSION' | 'PLAYBOOK_SUBMISSION_ANSWER' | 'PLAYLIST' | 'PLAYLIST_FOLDER' | 'PODCAST_EPISODE' | 'PORTAL' | 'PORTAL_OBJECT_SYNC_MESSAGE' | 'POSTAL_MAIL' | 'PRIVACY_SCANNER_COOKIE' | 'PRODUCT' | 'PRODUCT_OR_FOLDER' | 'PROPERTY_INFO' | 'PROSPECTING_AGENT_CONTACT_ASSIGNMENT' | 'PUBLISHING_TASK' | 'QUARANTINED_SUBMISSION' | 'QUOTA' | 'QUOTE' | 'QUOTE_FIELD' | 'QUOTE_MODULE' | 'QUOTE_MODULE_FIELD' | 'QUOTE_TEMPLATE' | 'RESTORABLE_CRM_OBJECT' | 'ROSTER' | 'ROSTER_MEMBER' | 'SALES_DOCUMENT' | 'SALES_TASK' | 'SALES_WORKLOAD' | 'SALESFORCE_SYNC_ERROR' | 'SCHEDULING_PAGE' | 'SCHEMAS_BACKEND_TEST' | 'SCORE_CONFIGURATION' | 'SEQUENCE' | 'SEQUENCE_ENROLLMENT' | 'SEQUENCE_STEP' | 'SEQUENCE_STEP_ENROLLMENT' | 'SERVICE' | 'SITE_PAGE' | 'SNIPPET' | 'SOCIAL_BROADCAST' | 'SOCIAL_CHANNEL' | 'SOCIAL_POST' | 'SOCIAL_PROFILE' | 'SOX_PROTECTED_DUMMY_TYPE' | 'SOX_PROTECTED_TEST_TYPE' | 'SUBMISSION_TAG' | 'SUBSCRIPTION' | 'TASK' | 'TASK_TEMPLATE' | 'TAX' | 'TEMPLATE' | 'TICKET' | 'UNKNOWN' | 'UNSUBSCRIBE' | 'USER' | 'VIEW' | 'VIEW_BLOCK' | 'WEB_INTERACTIVE': The name of the destination object type (e.g,. "DEAL" or "QUOTE").
      - `toObjectTypeId` string, required: The ID of the destination object type (e.g., 0-3 for deals).
    - `comboEventRules` ComboEventRuleBranch
      - `composingRules` ComboEventRule[], required
        - `count` integer, required
        - `eventTypeId` string, required
        - `lookbackWindowDays` integer
        - `propertyFilters` PropertyFilter[], required
          - `context` PropertyFilterContext
            - `objectTypeId` string, required
          - `filterInsightsId` integer
          - `filterType` 'PROPERTY', required
          - `frameworkFilterId` integer
          - `operation` union, required
            - BoolPropertyOperation
              - …
            - NumberPropertyOperation
              - …
            - StringPropertyOperation
              - …
            - DateTimePropertyOperation
              - …
            - RangedDatePropertyOperation
              - …
            - ComparativeDatePropertyOperation
              - …
            - ComparativeBoolPropertyOperation
              - …
            - ComparativeNumberPropertyOperation
              - …
            - ComparativeStringPropertyOperation
              - …
            - ComparativePropertyUpdatedOperation
              - …
            - RollingDateRangePropertyOperation
              - …
            - RollingPropertyUpdatedOperation
              - …
            - EnumerationPropertyOperation
              - …
            - AllPropertyTypesOperation
              - …
            - RangedNumberPropertyOperation
              - …
            - MultiStringPropertyOperation
              - …
            - DatePropertyOperation
              - …
            - CalendarDatePropertyOperation
              - …
            - TimePointOperation
              - …
            - RangedTimeOperation
              - …
            - RegexPropertyOperation
              - …
          - `property` string, required
      - `operationType` 'AND' | 'OR', required
      - `ruleBranches` ComboEventRuleBranch[], required
    - `createdAt` string, date-time
    - `createdUserId` integer
    - `customMatchingId` ExternalObjectResolutionMappingResponse
      - `primaryObjectRule` ExternalPrimaryObjectResolutionRule, required
        - `eventPropertyName` string, required
        - `targetObjectPropertyName` string, required
    - `description` string
    - `detailTemplate` string
    - `fullyQualifiedName` string, required
    - `headerTemplate` string
    - `id` string, required
    - `labels` BehavioralEventTypeDefinitionLabels, required
      - `plural` string
      - `singular` string, required
    - `name` string, required
    - `objectTypeId` string, required
    - `primaryObject` string
    - `primaryObjectId` string
    - `properties` Property[], required
      - `archived` boolean: Whether the property is archived.
      - `archivedAt` string, date-time: The timestamp when the property was archived, in ISO 8601 format.
      - `calculated` boolean: Whether the property is a calculated field.
      - `calculationFormula` string: The formula used for calculated properties.
      - `createdAt` string, date-time: The timestamp when the property was created, in ISO 8601 format.
      - `createdUserId` string: The ID of the user who created the property.
      - `currencyPropertyName` string: The name of the related currency property.
      - `dataSensitivity` 'highly_sensitive' | 'non_sensitive' | 'sensitive': Indicates the sensitivity level of the property, such as "non_sensitive", "sensitive", or "highly_sensitive".
      - `dateDisplayHint` 'absolute' | 'absolute_with_relative' | 'time_since' | 'time_until'
      - `description` string, required: A summary of the property's purpose.
      - `displayOrder` integer: The position of the item relative to others in the list.
      - `externalOptions` boolean: Applicable only for enumeration type properties. Should be set to true with a 'referencedObjectType' of 'OWNER'. Otherwise false.
      - `fieldType` string, required: Determines how the property will appear in HubSpot's UI or on a form. Learn more in the properties API guide.
      - `formField` boolean: Whether the property can appear on forms.
      - `groupName` string, required: The name of the group to which the property is assigned.
      - `hasUniqueValue` boolean: Whether the property is a unique identifier property.
      - `hidden` boolean: Whether or not the property will be hidden from the HubSpot UI. It's recommended that this be set to false for custom properties.
      - `hubspotDefined` boolean: A boolean value set to true for HubSpot default properties.
      - `label` string, required: The display label for the property.
      - `modificationMetadata` PropertyModificationMetadata
        - `archivable` boolean, required
        - `readOnlyDefinition` boolean, required
        - `readOnlyOptions` boolean
        - `readOnlyValue` boolean, required
      - `name` string, required: The internal name for the property.
      - `numberDisplayHint` 'currency' | 'duration' | 'formatted' | 'percentage' | 'probability' | 'unformatted': Hint for how a number property is displayed and validated in HubSpot's UI. Can be: "unformatted", "formatted", "currency", "percentage", "duration", or "probability".
      - `options` Option[], required: A list of valid options for the property. This field is required for enumerated properties.
        - `description` string: A description of the option.
        - `displayOrder` integer: The position of the item relative to others in the list.
        - `hidden` boolean, required: Whether the option is displayed in HubSpot's UI.
        - `label` string, required: A user-friendly label that identifies the option.
        - `value` string, required: The actual value of the option.
      - `referencedObjectType` string: Deprecated. Use externalOptionsReferenceType instead.
      - `sensitiveDataCategories` string[]: When sensitiveData is true, lists the type of sensitive data contained in the property (e.g., "HIPAA").
      - `showCurrencySymbol` boolean: Whether to show the currency symbol in HubSpot's UI.
      - `textDisplayHint` 'domain_name' | 'email' | 'ip_address' | 'multi_line' | 'phone_number' | 'physical_address' | 'postal_code' | 'unformatted_single_line': Hint for how the text is displayed and validated in HubSpot's UI. Can be: "unformatted_single_line", "multi_line", "email", "phone_number", "domain_name", "ip_address", "physical_address", or "postal_code".
      - `type` string, required: The data type of the property, such as string or number.
      - `updatedAt` string, date-time: The timestamp when the property was last updated, in ISO 8601 format.
      - `updatedUserId` string
    - `trackingType` 'APP_EVENT' | 'AUTOCAPTURE_EVENT' | 'CLICKED_ELEMENT' | 'COMBO_EVENT' | 'CUSTOM_SCRIPT' | 'CUSTOM_SIGNAL' | 'IMPORT' | 'MANUAL' | 'POLLING' | 'PROPERTY_CHANGE' | 'VISITED_URL' | 'WEBHOOK'
    - `updatedAt` string, date-time
    - `updatedUserId` integer
  - `total` integer, required

## Other responses

- `default`: An error occurred.

## Changes

- **2026-10-16** (v3) `ed9a1391fdff`: 25 info
  - added the optional property `results/items/comboEventRules/composingRules/items/propertyFilters/items/operation/oneOf[subschema #10: property-updated-comparative]/propertyAspect` to the response with the `200` status
  - added the optional property `results/items/comboEventRules/composingRules/items/propertyFilters/items/operation/oneOf[subschema #11: datetime-rolling]/propertyAspect` to the response with the `200` status
  - added the optional property `results/items/comboEventRules/composingRules/items/propertyFilters/items/operation/oneOf[subschema #12: rolling-property-updated]/propertyAspect` to the response with the `200` status
  - added the optional property `results/items/comboEventRules/composingRules/items/propertyFilters/items/operation/oneOf[subschema #13: enumeration]/propertyAspect` to the response with the `200` status
  - …21 more
- **2026-08-14** (v3) `b12482347df4`: 1 info
  - endpoint added
- **2026-07-13** (v3) `8d341c0a911c`: 1 breaking
  - api path removed without deprecation
- **2026-07-13** (v3) `7afd5ac6fbf1`: 1 info
  - endpoint added
- **2026-07-13** (v3) `ae745d244e14`: 1 breaking
  - api path removed without deprecation

[Operation history](https://skmtc.dev/hubspot/apis/events-manage-event-definitions/changes/events/v3/event-definitions/get.md)

---

[API](https://skmtc.dev/hubspot/apis/events-manage-event-definitions.md) - [All operations](https://skmtc.dev/hubspot/apis/events-manage-event-definitions/llms.txt) - [OpenAPI document](https://skmtc.dev/hubspot/apis/events-manage-event-definitions/revisions/49b86c29a335?raw)
