---
title: "Create Custom Events"
method: POST
path: "/apps/{app_id}/custom_events"
---

# Create Custom Events

`POST /apps/{app_id}/custom_events`

The Custom Events API allows you to record user events. Custom events can represent any action users take in your application, such as completing a purchase, viewing content, or achieving milestones.

## Path parameters

- `app_id` string, required

## Headers

- `Authorization` string

## Request body

- object
  - `events` object[], required — Array of event objects to be recorded. Maximum size for each event is `2024` bytes. Maximum size of request is `1` MB.
    - `name` string, required — The identifier or name of the event. Maximum 128 characters.
    - `external_id` string — The external ID of the user targeted for the event. Either the user's External ID or OneSignal ID is required.
    - `onesignal_id` string — The OneSignal ID of the user targeted for the event. Either the user's External ID or OneSignal ID is required.
    - `timestamp` string — Time the event occurred as an [ISO8601 formatted string](https://www.timestamp-converter.com/). Defaults to the current time if not provided. If the timestamp provided is in the future, it will be reset to the current time.
    - `idempotency_key` string — A unique UUID for avoiding duplicate custom event processing. Repeated events with the same idempotency_key will not be processed.
    - `properties` object — Properties or data related to the event, like {"geography": "USA"}

## Response `202`

Accepted with optional partial-success details. The response body lists any individual events that could not be processed (typically because the supplied `event_user_id` does not resolve to a OneSignal user); other events in the same payload were processed normally. An empty `errors` array (or absent body) means every event was accepted.

- object
  - `errors` object[] — Errors for specific events in the payload. If this is returned, only the specified events have failed -- other events in the same payload were successfully processed.
    - `event_user_id` string — The External ID in the event that failed.
    - `event_id` string — The value of the `event_id` property in the event, if it has one.
    - `error` object — Information about the error that caused the event to not be processed.
      - `code` string — A short error code describing the error.
      - `title` string — Human-readable information about what caused the error.

## Other responses

- `400` — Bad request. The payload was rejected (e.g., malformed JSON or missing required fields). The response body shape is currently an empty object placeholder. Treat any 400 as a fatal request error.
- `401` — Unauthorized. The `Authorization` header is missing or invalid. This response uses `text/plain` with an empty body (not the standard `BasicErrorResponse` envelope). Treat any 401 from this endpoint as an auth failure regardless of body.
- `429` — Rate limit exceeded. Wait the number of seconds in the `Retry-After` header before retrying.
- `503` — Service temporarily unavailable. Retry after a short backoff. The body may be empty or non-JSON in some failure modes.

---

[API](https://skmtc.net/onesignal/apis/api-onesignal-com.md) · [All operations](https://skmtc.net/onesignal/apis/api-onesignal-com/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/onesignal/api-onesignal-com/versions/0fc223f7e338/schema)