---
title: "Add custom events"
method: POST
path: "/api/custom-events"
tags: ["Custom Events"]
---

# Add custom events

`POST /api/custom-events`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/custom-events`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `http://oauth2.{domain}.com/token` scopes: `evt`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/custom-events/post.ts> (a function with typed inputs; its response is checked against the schema)

Submit an externally-generated custom event, associated with a channel ID or named user, to Airship. You can use these events as custom event triggers for Automation or Sequences and can use handlebars to personalize messages using custom event properties (information in the `body.properties` object).

## Request body

- CustomEventObject[]
  - `body` object, required: Contains information about your custom event. While only the event `name` is required, it is recommended that you provide as much information in this object as possible, so that your event is relevant and informative.
    - `external_campaigns` object: An object specifying custom campaign categories related to the event.
      - `categories` string[], required: An array of strings representing the campaigns you wish to associate with the event. Must have between 1 to 10 items in the array with a 64 character/byte maximum per item.
    - `interaction_id` string: The identifier defining where the event occurred. In a traditional website, this would be the path and query string from the URL. In a single page app that uses hash routing, it would be the path, query string, and fragment identifier.
    - `interaction_type` string: Describes the type of interaction that triggered the event, e.g., `url`, `social`, `email`. This should almost always be 'url' for web events. Airship can separate events with the same `name` by `interaction_type`, providing greater insight into custom events.
    - `name` string, required: A plain-text name for the event. Airship’s analytics systems will roll up events with the same `name`, providing counts and total value associated with the event. This value cannot contain upper-case characters. If the `name` contains upper-case characters, you will receive a 400 response.
    - `properties` object: An object containing custom event properties. You can use handlebars to access custom event properties in templates or messages triggered by the custom event. Items in the `properties` object are limited to a 255 character maximum string length.
    - `session_id` string: The user session during which the event occurred. You must supply and maintain session identifiers.
    - `transaction` string: If the event is one in a series representing a single transaction, use the transaction field to tie events together.
    - `unique_id` string: If properties for the custom event are being used for triggering and personalizing a Sequence, use a unique ID to introduce uniqueness in order to differentiate messages and prevent dropping sends as duplicates.
    - `value` number: If the event is associated with a count or amount, the 'value' field carries that information. Airship will treats this field as a representation of money; mathematical operations will use fixed precision representations of this field. The `value` field respects six digits of precision to the right of the decimal point. This field is optional; if empty, its value will default to zero.
  - `occurred` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the event occurred. Events must have occurred within the past 90 days. You cannot provide a future date-time. If omitted, the current date-time is used.
  - `user` union, required: Contains the Airship channel identifier for the user who triggered the event.
    - object
      - `named_user_id` string: The named user associated with the event.
    - object
      - `amazon_channel` string, uuid: The unique channel identifier for a Fire OS device.
    - object
      - `android_channel` string, uuid: The unique channel identifier for an Android device.
    - object
      - `ios_channel` string, uuid: The unique channel identifier for an iOS device.
    - object
      - `web_channel` string, uuid: The unique channel identifier for a web device.
    - object
      - `channel` string, uuid: Airship canonical identifier for a user. Airship will determine the device.

## Response `200`

Returned on success.

- object
  - `ok` boolean: Success.
  - `operation_id` string, uuid: A unique string identifying the API interaction. You can use the `operation_id` in support requests if something goes wrong.

## Other responses

- `400`: There was a parsing or validation error in the request. Bad Request errors typically include `path` and `location` in the response to help you find the cause of the error.
- `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing.

## Changes

- **2026-06-24** `38241778b0c1`: 1 breaking, 2 info
  - removed `subschema #1: Named User` from the `items/user` request property `oneOf` list
  - added the new optional request property `items/body/external_campaigns`
  - added `subschema #1: Named user` to the `items/user` request property `oneOf` list
  - …this revision’s changelog is incomplete
- **2025-08-28** `3304568aaadc`: 2 breaking
  - removed `subschema #2: Amazon Channel` from the `items/user` request property `oneOf` list
  - the `items/occurred` request property format changed from no format to `date-time`
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/custom-events/post.md)

---

[API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)