For example, you want to better segment your contacts based on their interactions with your company and content. To do this, you need more information about them. Your app can create custom events (contacts who registered but did not attend a recent webinar, which variant of a sign-up flow a contact completed, etc.) that give you more context about the interactions contacts have with your company.
## Create an event template
Before you can start creating events, you must create an event template. Event templates describe actions your app will add to the timeline of a contact, company, deal, or ticket record in HubSpot. Examples of these actions include viewing a video, registering for a webinar, or filling out a survey. A single app can create up to 750 event templates.
Event templates are created for contacts by default, but they can be created for companies, deals, or tickets using the `objectType` field. See creating a timeline event template for more details.
Each event template has its own set of tokens and templates. You can use events created for contacts as criteria when creating new contact lists or workflows, such as: 'Create a list of all contacts with a Video Like where the video name contains XYZ,' where your event template is named "Video Like" and has an event token named "video name."
### Create event templates through the API
For this example, we'll create a new 'Example Webinar Registration' event template. For authentication, use the developer API key found in your app developer account.
```shell theme={null}
curl -X POST
-H "Content-Type: application/json" -d '
{
"name": "Example Webinar Registration",
"objectType": "contacts"
}' \
'https://api.hubapi.com/crm/v3/timeline/<
You'll start with a draft of your new event template. Once you've set the object type and the detail and header templates for the event, click **Create**.
When creating or editing your event template, set any tokens you want to use with it in the *Data* tab.
Clicking on "Show details" renders the details template:
To set the icon that is displayed next to the events, see "[Setting up a custom icon"](/api-reference/legacy/crm/extensions/timeline/guide#customicon) below.
The 'Example App Name' text above is the name of the app. In the CRM timeline, events can be filtered by app.
### Define all aspects of an event template in a single call
Now that you’ve seen each aspect of an event template is progressively defined, you can define it all in one `POST` call.
```shell theme={null}
curl -X POST -H "Content-Type: application/json" -d '
{
"name": "Another Webinar Registration",
"objectType": "contacts",
"headerTemplate": "Registered for [{{webinarName}}](https://mywebinarsystem/webinar/{{webinarId}})",
"detailTemplate": "Registration occurred at {{#formatDate timestamp}}{{/formatDate}}",
"tokens": [
{
"name": "webinarName",
"label": "Webinar Name",
"type": "string"
},
{
"name": "webinarId",
"label": "Webinar Id",
"type": "string"
},
{
"name": "webinarType",
"label": "Webinar Type",
"type": "enumeration",
"options": [
{
"value": "regular",
"label": "Regular"
},
{
"value": "ama",
"label": "Ask me anything"
}
]
}
]
}' \
'https://api.hubapi.com/crm/v3/timeline/<
### Set the event timestamp
The timestamp of the event determines where the event will appear in the record's timeline. By default, the event timestamp is when the POST command is sent. You can customize the event time by providing it in the request body in a timestamp property:
```shell theme={null}
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <
Clicking that link would open a modal window displaying the page set in the `url`:
### Stamp event data onto CRM object properties
In many cases, you'll want to modify the properties for the contacts, companies, deals, or tickets to which you're adding events. This often happens in cases where adding the event will actually create a contact—you'll likely want to update the first and last name properties on the contact so that you don't just create a contact with only an email address and an event.
You can stamp data onto the associated record from an event by mapping your custom event tokens to contact, company, deal, or ticket properties.
Consider this `PUT` command for updating a custom event template, note the `objectPropertyName` field:
```shell theme={null}
curl -X PUT -H "Content-Type: application/json" -d '
{
"label" : "Updated Webinar Name",
"objectPropertyName": "zz_webinar_name"
}' \
'https://api.hubapi.com/crm/v3/timeline/<
Note: If an event token is stamped to a custom property, and that custom property is not present for a HubSpot account, then the value will still be set for the event, but it will be ignored for the corresponding record.
### Understand `extraData`
You may need to add detailed data to an event that doesn't fit the simple token-value structure used by the event template tokens. You may need to add a list or some hierarchical breakdown to an integration event. This is where `extraData` comes in.
You can add an `extraData` attribute to an event’s JSON body. The value of this `extraData` can be any valid JSON. For example:
```shell theme={null}
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer <
Note: The `extraData` attribute can only be referenced in the details template for an event. It can't be used in either the header template or in list segmentation.
### Set up a custom icon
To add visual appeal to your timeline items, you'll want to add a custom icon.
This image file for this icon should:
* Have roughly square dimensions
* Have a transparent background
* Have the content in the center of the icon
* Be able to size down to 30x30 pixels
* Have a file size of 5MB or less
To set the icon used for timeline events, navigate to Timeline events. Click on the placeholder image or the existing icon to set or update it.
Once you set the icon(s), they will be shown next to all of the timeline events associated with this application:
## Limits
The following limits apply for the timeline events API.
### Event instance limits
When creating an event, each serialized event instance is subject to the following size limits of:
* 500 bytes for the event instance ID
* 510 KB per property/token
* 1 MB in total size for the event instance
### Limits for events in legacy public apps
Timeline events in a legacy public app are subject to the following limits:
* You can create up to 750 timeline event types per public app.
* You can create up to 500 properties per timeline event type.
* Event instance size limits are the same as described in the [Event instance limits](#event-instance-limits) section above.