# Custom Events

User events that occur outside of your app can be submitted to Airship for inclusion in analytics reporting, as triggers for Automation, or for export via Connect. These events can take place on the web, e.g., your website, social media, or in your back office systems such as CRM or POS software. Any event that can be associated with a mobile app user can be submitted as an Airship Custom Event. The events that you submit are associated with channels and are available to use as Custom Event triggers.


## Add Custom Events {#addcustomevents}

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).


[Jump to examples ↓](#addcustomevents-examples)

### `POST /api/custom-events`

{{< note >}}
* Requests complete validation before returning a response.
* Requests are authenticated with a bearer token, which can provide access to this resource alone or to this resource and others.
* The `name` value inside `body` must not contain any uppercase characters, or the event will be rejected with a 400 status code.

{{< /note >}}

**Security:**

- [bearerAuth]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-bearerAuth)
- [oauth2Token]({{< ref "/developer/rest-api/ua/introduction/" >}}#security-oauth2Token): evt

**Request headers:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `X-UA-Appkey` | `string` | Required | The application key for your project. |

**Request body**

An array of Custom Event objects.

**Content-Type:** `application/json`

Type: `array`

**Responses**

**`200`** Returned on success.

Response body:

**Content-Type:** `application/vnd.urbanairship+json; version=3`

- **`ok`** `boolean`

  Success.

- **`operation_id`** `string`

  A unique string identifying the API interaction. You can use the `operation_id` in support requests if something goes wrong.

  Format: `uuid`

  Example: `ef625038-70a3-41f1-826f-57bc11dd625a`

**`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.

Response body:

**Content-Type:** `application/json`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**`401`** Authentication information (the app key and secret or bearer token) was either incorrect or missing.

Response body:

**Content-Type:** `text/plain`

[Error response]({{< ref "/developer/rest-api/ua/schemas/responses/" >}}#error)

**Examples**

*Example*

```http
POST /api/custom-events HTTP/1.1
Authorization: Bearer <authorization token>
X-UA-Appkey: <application key>
Accept: application/vnd.urbanairship+json; version=3
Content-Type: application/json

[
   {
      "occurred": "2020-05-02T02:31:22",
      "user": {
         "named_user_id": "hugh.manbeing"
      },
      "body": {
         "name": "purchased",
         "value": 239.85,
         "transaction": "886f53d4-3e0f-46d7-930e-c2792dac6e0a",
         "interaction_id": "your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234",
         "interaction_type": "url",
         "properties": {
            "description": "Sneaker purchase",
            "brand": "Victory Sneakers",
            "colors": [
             "red",
             "blue"
            ],
            "items": [
               {
                  "text": "New Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Old Line Sneakers",
                  "price": "$ 79.95"
               },
               {
                  "text": "Blue Line Sneakers",
                  "price": "$ 79.95"
               }
            ],
            "name": "Hugh Manbeing",
            "userLocation": {
               "state": "CO",
               "zip": "80202"
            }
         },
         "session_id": "22404b07-3f8f-4e42-a4ff-a996c18fa9f1"
      }
   }
]

```

```http
HTTP/1.1 200 OK
Content-Type: application/vnd.urbanairship+json; version=3

{
   "ok": true,
   "operation_id": "8c61c0c4-95b0-45a6-bc38-733f7fcb8979"
}

```

```python
from datetime import datetime
from urbanairship import (
    BearerTokenClient, CustomEvent
)

client = BearerTokenClient(
    app_key='<app_key>',
    token='<bearer_token>'
)

event = CustomEvent(
   client=client,
   name='purchased',
   user={'named_user_id': 'hugh.manbeing'},
   interaction_type='url',
   interaction_id='your.store/us/en_us/pd/shoe/pid-11046546/pgid-10978234',
   value=239.85,
   transaction='886f53d4-3e0f-46d7-930e-c2792dac6e0a',
   session_id='22404b07-3f8f-4e42-a4ff-a996c18fa9f1',
   properties={
      'description': 'Sneaker purchase',
      'brand': 'Victory Sneakers',
      'colors': ['red', 'blue'],
      'items': [
         {'text': 'New Line Sneakers', 'price': '$ 79.95'},
         {'text': 'Old Line Sneakers', 'price': '$ 79.95'},
         {'text': 'Blue Line Sneakers', 'price': '$ 79.95'}
      ],
      'name': 'Hugh Manbeing',
      'userLocation': {
         'state': 'CO',
         'zip': '80202'
      }
   },
   occurred=datetime(2020, 5, 2, 2, 31, 22)
)

response = event.send()

```

```java
UrbanAirshipClient client = UrbanAirshipClient.newBuilder()
        .setKey("<app key>")
        .setSecret("<master secret>")
        .setBearerToken("<bearer token>")
        .build();

CustomEventUser customEventUser = CustomEventUser.newBuilder()
        .setNamedUserId("hugh.manbeing")
        .build();

CustomEventPropertyValue customEventProperty = CustomEventPropertyValue.of("Victory Sneakers");

List<CustomEventPropertyValue> items = new ArrayList<>();
items.add(CustomEventPropertyValue.of("New Line Sneakers"));
items.add(CustomEventPropertyValue.of("Old Line Sneakers"));

DateTime occurred = new DateTime(2020, 05, 02, 02, 31, 22, DateTimeZone.UTC);

CustomEventBody customEventBody = CustomEventBody.newBuilder()
        .setName("purchased")
        .addPropertiesEntry("brand", customEventProperty)
        .addPropertiesEntry("items", CustomEventPropertyValue.of(items))
        .build();

CustomEventPayload customEventPayload = CustomEventPayload.newBuilder()
        .setCustomEventBody(customEventBody)
        .setCustomEventUser(customEventUser)
        .setOccurred(occurred)
        .build();

CustomEventRequest customEventRequest = CustomEventRequest.newRequest(customEventPayload);
Response<CustomEventResponse> response = client.execute(customEventRequest);

```

```ruby
require 'urbanairship'

UA = Urbanairship
airship = UA::Client.new(key: '<app key>', token: '<token>')

example_events = [
  UA.custom_events(
    body: UA.custom_events_body(
      interaction_id: "api/ua/#schemas-customeventobject",
      interaction_type: "url",
      name: "example",
      properties: {
        "who" => "Alf",
        "where" => "In the garage!",
        "from" => "Melmac"
      },
      session_id: "8d168d40-bc9b-4359-800c-a546918354ac",
      transaction: "d768f61f-73ba-495f-9e16-b3b9c3b598b7",
      value: 1
    ),
    occurred: "2021-10-01T00:00:00",
    user: UA.custom_events_user(named_user_id: "Gordon Shumway")
  )
]
event = Urbanairship::CustomEvents::CustomEvent.new(client: airship)
event.events = example_events
event.create

```

---