{"openapi":"3.1.0","info":{"version":"1.0.0","title":"Pipelines API - Mobile App Events","description":"# Mobile App Semantic Events\n\nThis document describes semantic events for mobile applications in the Customer.io Pipelines API.\n\nSemantic events are special track events that follow a standard structure across different integrations. When you send a mobile app event with a specific name (like `Application Installed` or `Application Opened`), Customer.io and downstream integrations recognize it and handle it appropriately.\n\nWith semantic events, you can set up your events and they'll work with any of our destinations that support mobile app events.\n\n# Server addresses: US and EU\nCustomer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.\n\n| Region | Server Address |\n| :-- | :-- |\n| US | https://cdp.customer.io |\n| EU | https://cdp-eu.customer.io |\n\nIf you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries.\n\n# Authentication\n\nThe Data Pipelines API uses basic authentication with your API key as the username and a blank password.\n"},"servers":[{"url":"https://cdp.customer.io/v1","description":"The base URL for all Data Pipelines calls in our United States (US) region."},{"url":"https://cdp-eu.customer.io/v1","description":"The base URL for all Data Pipelines calls in our European Union (EU) region."}],"paths":{"/track":{"post":{"operationId":"track_mobile_app_events","summary":"Track Mobile App Events","description":"Send mobile app lifecycle events such as Application Installed, Application Opened, Application Backgrounded, Application Foregrounded, Application Updated, Application Uninstalled, or Application Crashed.\n\nThese are semantic events that follow a standard structure for mobile app tracking across different analytics and optimization platforms.\n","security":[{"Basic-Auth":[]}],"parameters":[{"name":"X-Strict-Mode","in":"header","description":"When set to `1`, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200.\n","required":false,"schema":{"type":"string","enum":["1"]},"example":"1"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/application_installed_event"},{"$ref":"#/components/schemas/application_opened_event"},{"$ref":"#/components/schemas/application_backgrounded_event"},{"$ref":"#/components/schemas/application_foregrounded_event"},{"$ref":"#/components/schemas/application_updated_event"},{"$ref":"#/components/schemas/application_uninstalled_event"},{"$ref":"#/components/schemas/application_crashed_event"}]}}}},"responses":{"200":{"$ref":"#/components/responses/200"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"}}}}},"components":{"schemas":{"application_installed_event":{"title":"Application Installed Event","oneOf":[{"title":"Known User","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The unique identifier for the user.","example":"user_12345"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Installed"],"description":"A person installed your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"Properties that describe the app installation.","properties":{"version":{"type":"string","description":"The version of the app installed.","example":"2.1.0"},"build":{"type":"string","description":"The specific build of the app installed.","example":"421"}},"additionalProperties":{"description":"Additional custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},{"title":"Anonymous User","type":"object","required":["anonymousId","event","type"],"properties":{"anonymousId":{"type":"string","description":"The anonymous identifier for the user.","example":"anon_abc123xyz"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Installed"],"description":"A person installed your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"Properties that describe the app installation.","properties":{"version":{"type":"string","description":"The version of the app installed.","example":"2.1.0"},"build":{"type":"string","description":"The specific build of the app installed.","example":"421"}},"additionalProperties":{"description":"Additional custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}}]},"application_opened_event":{"title":"Application Opened Event","oneOf":[{"title":"Known User","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The unique identifier for the user.","example":"user_12345"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Opened"],"description":"A person opened your app. Our SDKs automatically send this event when a person opens your app fresh or when they return to the app after sending it to the background."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"Properties that describe the app opening.","properties":{"from_background":{"type":"boolean","description":"If true, the user opened the app from the background.","example":false},"url":{"type":"string","description":"The value of `UIApplicationLaunchOptionsURLKey` from launchOptions. Collected on iOS only.","example":"myapp://promo/summer-sale"},"version":{"type":"string","description":"The version of the app opened.","example":"2.1.0"},"build":{"type":"string","description":"The specific build of the app opened.","example":"421"}},"additionalProperties":{"description":"Additional custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},{"title":"Anonymous User","type":"object","required":["anonymousId","event","type"],"properties":{"anonymousId":{"type":"string","description":"The anonymous identifier for the user.","example":"anon_abc123xyz"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Opened"],"description":"A person opened your app. Our SDKs automatically send this event when a person opens your app fresh or when they return to the app after sending it to the background."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"Properties that describe the app opening.","properties":{"from_background":{"type":"boolean","description":"If true, the user opened the app from the background.","example":false},"url":{"type":"string","description":"The value of `UIApplicationLaunchOptionsURLKey` from launchOptions. Collected on iOS only.","example":"myapp://promo/summer-sale"},"version":{"type":"string","description":"The version of the app opened.","example":"2.1.0"},"build":{"type":"string","description":"The specific build of the app opened.","example":"421"}},"additionalProperties":{"description":"Additional custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}}]},"application_backgrounded_event":{"title":"Application Backgrounded Event","oneOf":[{"title":"Known User","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The unique identifier for the user.","example":"user_12345"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Backgrounded"],"description":"A person sent your app to the background. Our SDKs automatically send this event when a person backgrounds your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Backgrounded event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},{"title":"Anonymous User","type":"object","required":["anonymousId","event","type"],"properties":{"anonymousId":{"type":"string","description":"The anonymous identifier for the user.","example":"anon_abc123xyz"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Backgrounded"],"description":"A person sent your app to the background. Our SDKs automatically send this event when a person backgrounds your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Backgrounded event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}}]},"application_foregrounded_event":{"title":"Application Foregrounded Event","oneOf":[{"title":"Known User","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The unique identifier for the user.","example":"user_12345"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Foregrounded"],"description":"A person brought your app to the foreground after having backgrounded it, indicating that they're using it again. Our SDKs automatically send this event when a person brings your app back to the foreground."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Foregrounded event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},{"title":"Anonymous User","type":"object","required":["anonymousId","event","type"],"properties":{"anonymousId":{"type":"string","description":"The anonymous identifier for the user.","example":"anon_abc123xyz"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Foregrounded"],"description":"A person brought your app to the foreground after having backgrounded it, indicating that they're using it again. Our SDKs automatically send this event when a person brings your app back to the foreground."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Foregrounded event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}}]},"application_updated_event":{"title":"Application Updated Event","oneOf":[{"title":"Known User","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The unique identifier for the user.","example":"user_12345"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Updated"],"description":"A person updated your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"Properties that describe the app update.","properties":{"previous_version":{"type":"string","description":"The previous version of the app installed—the version a person is upgrading _from_.","example":"2.0.5"},"previous_build":{"type":"string","description":"The previous build of the app installed—the build a person is upgrading _from_.","example":"398"},"version":{"type":"string","description":"The version of the app a person upgraded to.","example":"2.1.0"},"build":{"type":"string","description":"The specific build of the app the person upgraded to.","example":"421"}},"additionalProperties":{"description":"Additional custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},{"title":"Anonymous User","type":"object","required":["anonymousId","event","type"],"properties":{"anonymousId":{"type":"string","description":"The anonymous identifier for the user.","example":"anon_abc123xyz"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Updated"],"description":"A person updated your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"Properties that describe the app update.","properties":{"previous_version":{"type":"string","description":"The previous version of the app installed—the version a person is upgrading _from_.","example":"2.0.5"},"previous_build":{"type":"string","description":"The previous build of the app installed—the build a person is upgrading _from_.","example":"398"},"version":{"type":"string","description":"The version of the app a person upgraded to.","example":"2.1.0"},"build":{"type":"string","description":"The specific build of the app the person upgraded to.","example":"421"}},"additionalProperties":{"description":"Additional custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}}]},"application_uninstalled_event":{"title":"Application Uninstalled Event","oneOf":[{"title":"Known User","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The unique identifier for the user.","example":"user_12345"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Uninstalled"],"description":"A person uninstalled your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Uninstalled event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},{"title":"Anonymous User","type":"object","required":["anonymousId","event","type"],"properties":{"anonymousId":{"type":"string","description":"The anonymous identifier for the user.","example":"anon_abc123xyz"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Uninstalled"],"description":"A person uninstalled your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Uninstalled event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}}]},"application_crashed_event":{"title":"Application Crashed Event","oneOf":[{"title":"Known User","type":"object","required":["userId","event","type"],"properties":{"userId":{"type":"string","description":"The unique identifier for the user.","example":"user_12345"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Crashed"],"description":"A person experienced a crash in your app. Our SDKs automatically send this event when a person experiences a crash in your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Crashed event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}},{"title":"Anonymous User","type":"object","required":["anonymousId","event","type"],"properties":{"anonymousId":{"type":"string","description":"The anonymous identifier for the user.","example":"anon_abc123xyz"},"type":{"type":"string","enum":["track"],"description":"The event type. Must be `track` for event calls."},"event":{"type":"string","enum":["Application Crashed"],"description":"A person experienced a crash in your app. Our SDKs automatically send this event when a person experiences a crash in your app."},"timestamp":{"type":"string","format":"date-time","description":"The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.","example":"2024-01-15T10:30:00.000Z"},"properties":{"type":"object","description":"There are no default properties for the Application Crashed event. You can add custom properties to the event payload.","additionalProperties":{"description":"Custom properties for the event."}},"context":{"$ref":"#/components/schemas/context"},"integrations":{"$ref":"#/components/schemas/integrations"}}}]},"context":{"x-scalar-ignore":true,"title":"Context","type":"object","description":"Additional context about the event, such as device information, IP address, user agent, etc. Most of our libraries collect this automatically.","additionalProperties":true},"integrations":{"x-scalar-ignore":true,"title":"Integrations","type":"object","description":"Control which integrations receive this event. By default, all enabled integrations receive events.","additionalProperties":true,"example":{"All":false,"Mixpanel":true,"Segment":true}}},"securitySchemes":{"Basic-Auth":{"type":"http","scheme":"basic","description":"The Data Pipelines API uses a basic authentication scheme with your API key. Use the API Key as the username and leave the password blank.\n"}},"responses":{"200":{"description":"A successful request returns an empty object response.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or malformed request.","content":{"application/json":{"schema":{"type":"object","properties":{"meta":{"type":"object","properties":{"errors":{"type":"array","description":"An array of errors.","items":{"type":"string","description":"Error descriptions."}}}}}}}}},"401":{"description":"Unauthorized request. Make sure that you provided the right credentials."}}}}