# Track events In this section, we’ll explain how to track both semantic events and custom events. To illustrate, let’s assume the following JSON represents the configuration obtained in the previous step, [Get Configuration](/api/contacts-api/tracking-contact-events/api-reference/get-configuration.md). ```json { "applicationId": "4640861f-f29b-48b6-8baa-a0f23249cf77", "workspaceId": "a1405560-c8d3-4b1a-877d-3f449ad95352", "apiEndpoint": "https://api.bird.com", "allowedDomains": [ "myapplication.com" ], "allowedAppBundles": [ "" ], "tracking": { "connectorId": "a1405560-c8d3-4b1a-877d-3f449ad95352", "enabled": true, "writeKey": "a1405560-c8d3-4b1a-877d-3f449ad95352", "endpoint": "https://capture.eu-west-1.api.bird.com/tracking/track", "trackPageViews": true, "anonymousTracking": "enqueue", "trackLifecycleEvents": true }, "pushNotifications": { "enabled": false, "connectorId": "00000000-0000-0000-0000-000000000000", "endpoint": "https://capture.eu-west-1.api.bird.com/push-notifications" }, "appInbox": { "enabled": false, "connectorId": "00000000-0000-0000-0000-000000000000", "channelId": "00000000-0000-0000-0000-000000000000", "endpoint": "https://capture.eu-west-1.api.bird.com/ app-inbox" } } ``` To inform our platform about the actions your users are performing, send the events to the `tracking.endpoint` endpoint retrieved in the response above. Whether you are sending semantic events or custom events to Bird CRM, the following properties must be included at the top level of the event object: ```json { "timestamp": "event-timestamp", "event": "event-name", "type": "track", "identity": { "resolutionStrategy": "lookup", "entityType": "contact", "identifiers": [{ "key": "identifier-key", "value": "identifier-value" }] }, "properties": {}, "context": {}, "messageId": "unique-message-ID" } ``` * **event**: For semantic events, the event names must match the predefined names listed in the appendix. Custom events can have any name, as long as it doesn't conflict with any semantic event names. * **messageId**: The message ID should be a unique string that helps identify the event within the workspace. A UUID is a good option for this. * **identity**: The identity object indicates which contact the event is associated with. You must provide one or more identifiers, which will be used to search for the contact in the order presented. The first matching identifier will determine the contact. Common identifiers include external user ID or email address. If using an email address, the identifier key must be "emailaddress", and the value should be the actual email address. Phone numbers are generally not ideal identifiers unless they uniquely identify a contact and are already used as identifiers. In that case, the identifier key should be "phonenumber". * **properties**: nested event properties are supported no more than five levels deep. It’s important to include the following headers when sending POST requests to Bird CRM: * **X-Bird-Event-Name**: This header specifies the event type. For more information on supported semantic event types, refer to [BirdTracker](/api/client-sdks/sdk-integration/web-sdk/api-reference/birdtracker.md). * **X-Bird-Sdk-Version**: Set this to `0.0.1`. * **X-Bird-Workspace-Id**: Use the **workspace ID** retrieved from your configuration. * **X-Bird-Write-Key**: Use the **write key** from the Get Configuration step. Once you start tracking events for identified users, you can verify that the events are being correctly recorded by checking the contact activity timeline on the contact detail page. ## Semantic events Our platform provides a predefined set of commonly used events, known as semantic events, tailored for various verticals such as e-commerce. These events follow a standard schema that seamlessly integrates across the platform without requiring additional setup. Below is an example of how to track a page view event for an identified user with the email address "": ```bash curl -X POST https://capture.eu-west-1.api.bird.com/tracking/track \ -H "Origin: https://example.com" \ -H "Content-Type: application/json" \ -H "X-Bird-Event-Name: web/page-viewed" \ -H "X-Bird-Sdk-Version: 0.0.1" \ -H "X-Bird-Workspace-Id: a1405560-c8d3-4b1a-877d-3f449ad95352" \ -H "X-Bird-Write-Key: a1405560-c8d3-4b1a-877d-3f449ad95352" \ -d '{ "timestamp": "2024-11-26T15:00:00.000Z", "event": "web/page-viewed", "type": "track", "identity": { "resolutionStrategy": "lookup", "entityType": "contact", "identifiers": [{ "key": "emailaddress", "value": "john@example.com" }] }, "properties": { "title": "My website", "url": "https://example.com/", "path": "/" }, "context": { "page": { "path": "/", "referrer": "", "search": "", "title": "Flight search page", "url": "https://example.com/" }, "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36", "userAgentData": { "brands": [ { "brand": "Not/A)Brand", "version": "8" }, { "brand": "Chromium", "version": "126" }, { "brand": "Google Chrome", "version": "126" } ], "mobile": false, "platform": "macOS" }, "locale": "en-US", "timezone": "Europe/Amsterdam" }, "messageId": "bird-tracker-1719169959440-263ca131-f903-45aa-84fe-fb0285af811c" }' ``` ## Custom events Custom events can include arbitrary properties and don’t require a predefined schema. Our platform automatically infers the schema from ingested events. These events can be used to trigger journeys and flows, personalize messages, and create segments. To track the custom event called “Book Read” for an identified user with the email "", you need to set the event name in the HTTP request header to "custom". Below is an example of the POST request with the necessary details: ```bash curl -X POST https://capture.eu-west-1.api.bird.com/tracking/track \ -H "Origin: https://example.com" \ -H "Content-Type: application/json" \ -H "X-Bird-Event-Name: custom" \ -H "X-Bird-Sdk-Version: 0.0.1" \ -H "X-Bird-Workspace-Id: a1405560-c8d3-4b1a-877d-3f449ad95352" \ -H "X-Bird-Write-Key: a1405560-c8d3-4b1a-877d-3f449ad95352" \ -d '{ "timestamp": "2024-11-26T15:00:00.000Z", "event": "Book Read", "type": "track", "identity": { "resolutionStrategy": "lookup", "entityType": "contact", "identifiers": [{ "key": "emailaddress", "value": "john@example.com" }] }, "properties": { "title": "The Art of Computer Programming", "author": "Donald E. Knuth", "startedAt": "2024-06-01T18:23:44Z", "metadata": { "volume": "1" } }, "context": {}, "messageId": "1719169959440-263ca131-f903-45aa-84fe-fb0285af811c" }' ``` ## Playground To help make it easier to test custom event tracking with your workspace, we have built a [playground](https://event-tester.tools.talkbird.com/) just for this. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/contacts-api/tracking-contact-events/api-reference/track-events.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.