> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
---
id: f0715c4c-5065-41f8-bbbb-5a6033d6b981
---
# Create and manage event types
> Learn how to define app event types so that you can send event occurrence data into HubSpot.
export const RequiredIndicator = () => {
return
required
;
};
This feature is intended only for [technology partners](https://www.hubspot.com/partners/technology/join), and requires approval from HubSpot to use. To apply for app events access, or if you want to learn more about the functionality, please submit [this in-app form](https://app.hubspot.com/l/developer-overview/appObjectsEventsRequest).
To send app event data to HubSpot, you'll first create an event type using a developer project. The event type is a JSON schema that defines the structure, properties, and validation rules for the event occurrence data you'll be sending. This includes the event name, display label, target CRM object, and event properties. Event types also include definitions for display templates for CRM record timeline rendering.
The app events described in this documentation are intended for apps built for the [HubSpot Marketplace](https://ecosystem.hubspot.com/marketplace/apps) using developer projects. To build custom event reporting for other types of integrations, you can instead use [custom events](/api-reference/latest/events/define-events/guide).
## Prerequisites
To include an app event type definition in your project:
* You must be using HubSpot CLI version `7.6.0` or later. You can check which version of the CLI you have by running `hs --version`, and update by running `npm install -g @hubspot/cli@latest`.
* Your project must be deployed before you can update it to include an app event component.
## Set up your project files
If you previously created a public app with a timeline event, learn more about [migrating it to the developer platform](#migrate-an-existing-timeline-event-type).
To create a new app event type definition in your project, update your [app configuration](/apps/developer-platform/build-apps/app-configuration) `hsmeta.json` file to include the `timeline` scope in the `requiredScopes` field. This is required for app event data to appear on CRM record timelines. Installers must grant this scope for your event data to send successfully.
```json theme={null}
"requiredScopes": [
"timeline"
],
```
Note that you may need to add other [scopes](/apps/legacy-apps/authentication/scopes#list-of-available-scopes), depending on the features your app includes.
Then, in the `app/` directory of your project, add an `app-events` directory. In `app-events/`, add a JSON configuration file to define the app event type. This file can have any name, but must end in `*-hsmeta.json`. You can include up to 750 event types per app, with each having its own `*-hsmeta.json` file.
In the event type `*-hsmeta.json` file, set up your [event type schema](/apps/developer-platform/add-features/app-events/reference#event-type-schema). This schema will configure event type attributes such as name, CRM record timeline display template, and the CRM object type to associate event data with.
While some of these fields can be updated after creation, the `name` and `objectType` fields cannot be changed once the event type is created.
For example, the following event type schema could be used for tracking customer login events.
```json theme={null}
{
"uid": "customer_login_event",
"type": "app-event",
"config": {
"name": "Customer login",
"description": "Tracks when a customer logs into their account including the method of login.",
"headerTemplate": "{{customerName}} logged in",
"detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"objectType": "CONTACT",
"properties": [
{
"name": "customerName",
"label": "Customer Name",
"description": "The full name of the customer who logged in.",
"type": "string"
},
{
"name": "loginLocation",
"label": "Login location",
"description": "Where the customer logged in from.",
"type": "enumeration",
"options": [
{
"value": "mobileApp",
"label": "Mobile app"
},
{
"value": "website",
"label": "Website"
}
]
}
]
}
}
```
| Field | Type | Description |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid` | String | An internal unique identifier for the event type. |
| `type` | String | The type of component. Must be `app-event`. |
| `name` | String | The label displayed in HubSpot (up to 50 characters). This value cannot be updated after creation. |
| `description` | String | A description of the event type. Can be up to 1,000 characters in length. |
| `objectType` | String | The fully qualified name of the CRM object type that event occurrences can be associated with. This value cannot be changed after creation. Can be one of: `APP_OBJECT`, `APPOINTMENT`, `COMPANY`, `CONTACT`, `COURSE`, `DEAL`, `LEAD`, `LISTING`, `ORDER`, `PROJECT`, `SERVICE`, `TICKET`. To create an event type for custom objects, use the `supportsCustomObject` field instead. |
| `supportsCustomObject` | Boolean | Set to `true` to configure the app event type for custom objects. When set to `true`: - The event type will be enabled for all custom objects in the account.
- You cannot specify another `objectType` in addition to custom objects (i.e., the `objectType` cannot be set to `CONTACT` and support custom objects).
- You cannot copy event property values to object property values via [property stamping](/apps/developer-platform/add-features/app-events/reference#property-stamping).
|
| `headerTemplate` | String | The [rendering template](/apps/developer-platform/add-features/app-events/reference#rendering-templates) for the header of the CRM timeline activity card. Can be up to 1,000 characters in length. |
| `detailTemplate` | String | The [rendering template](/apps/developer-platform/add-features/app-events/reference#rendering-templates) for the body of the CRM timeline activity card. Can be up to 10,000 characters in length. |
| `properties` | Array | Properties defined for the event type that you'll store event occurrence data in. Each event type can have up to 500 properties. Learn more about properties, including requirements and limitations, in the [app events reference documentation](/apps/developer-platform/add-features/app-events/reference). |
Upload your project to HubSpot with the `hs project upload` command.
```shell theme={null}
hs project upload
```
During the build phase, HubSpot will validate the event type. If there are any schema validation errors, the CLI will return an error indicating what to fix.
By default, after a successful build, HubSpot will automatically deploy the project. If you've turned this off in your [project settings](/apps/developer-platform/build-apps/manage-apps-in-hubspot#view-your-app-on-the-project-details-page), you can manually deploy using `hs project deploy`.
After deploying, your app event type will now be available and can be used for receiving event occurrence data.
## Retrieve the fullyQualifiedName (optional)
To send event occurrence data for the event type, you can either use your app's `uid` that's [set in the top-level](/apps/developer-platform/build-apps/app-configuration#specifying-uids) `app-hsmeta.json` file, or you can use the `fullyQualifiedName`, which is retrievable via the app events API. This name identifies the event type, and will need to be included with all app event API operations.
If you want to use the `fullyQualifiedName` when sending occurrence data:
* To retrieve the `eventTypeName`, make a `POST` request to `https://api.hubapi.com/integrators/timeline/v4/types/projects`. In the request body, include:
* A `projectName` field, which should be set to the `name` value from the `hsproject.json` file of your project.
* A `developerSymbol` field, which should be set to the `uid` value from the event type `*-hsmeta.json` configuration file.
```json theme={null}
{
"projectName": "my-marketplace-app",
"developerSymbol": "customer_login_event"
}
```
The response will return the project name, event type name, and the `fullyQualifiedName`.
```json highlight={6} theme={null}
{
"developerQualifiedSymbol": {
"projectName": "marketplace",
"developerSymbol": "customer_login_event"
},
"fullyQualifiedName": "ae000000_integrators-timeline-event-type-id-0000000"
}
```
The `fullyQualifiedName` value will never change, so you can safely hard code it into your implementation. The API limits the number of times you can retrieve this value per day, and cannot be used programmatically.
## Managing event types
To update an event type after creation, you'll just need to update the event type schema in your project, then re-upload to build and deploy the app.
If you no longer wish to use an event type, you can delete it from your project. However, before deleting an event type, note the following:
* Deleting an event type is a permanent and irreversible action.
* Deleting an event type removes both the event type and all occurrences of that type from all accounts that have installed the app.
* Deleting an event type will break other HubSpot tools that rely on that event type, such as reports and workflows.
To delete the event type, delete the `*-hsmeta.json` event type configuration file from your project, then upload and deploy the project.
## Migrate an existing timeline event type
If you have an existing public app with a timeline event, you can migrate it to the developer platform using the CLI.
Before migrating your app:
* Check out the [public app migration guide](/apps/developer-platform/build-apps/migrate-an-app/migrate-an-existing-public-app) to review the current considerations and limitations of the developer platform beta.
* Once you've migrated an existing timeline event type (`v1`/`v3`) to the developer platform, you'll have 7 days to change existing `v1`/`v3` timeline event API requests to the new `v4` endpoints, including both event type event occurrence/instance API requests. After 7 days, any existing calls to `v1`/`v3` event occurrence endpoints will return `401` errors.
* For creating and updating event types and templates, you'll no longer need to use the API. Instead, you'll manage them directly in the project via the [event type configuration file](/apps/developer-platform/add-features/app-events/reference#event-type-schema).
* For sending event occurrence data, you'll need to use the `v4` endpoints, which offers both [single and batch send endpoints](/apps/developer-platform/add-features/app-events/send-event-occurrences).
To migrate your app:
* In the terminal, run `hs app migrate`, then follow the terminal prompts to migrate your app and timeline event.
* Once the migration process is done, your app will now live in a developer project, and a local project directory will be created for you.
* To open the project in HubSpot, navigate into the local project directory, then run `hs project open`.
Note that the generated configuration files (`*-hsmeta.json`) may contain fields with `null` values. These fields are an artifact from the migration, and it's safe to remove them.
## Next Steps
After creating an event type, learn how to [send event occurrence data via the API](/apps/developer-platform/add-features/app-events/send-event-occurrences).
You can also check out the [app events reference documentation](/apps/developer-platform/add-features/app-events/reference) to continue building and customizing your app events.