# Custom Events API

For more detailed understanding of how users interact with your application, you can track custom events across your application by sending us Custom Events via our API at <https://spindl.link/events/server>.

**To do this, you will need:**

* Spindl API Key
* Properly Formatted events (you can send individual event or an array)
  * for each event, you can define an object:

<pre class="language-json"><code class="lang-json"><strong>[
</strong><strong>  {
</strong>   "type": "CUSTOM", // required (use the default "CUSTOM")
   "data": {
     "name": "Your Event Name", // required.
     "properties": { ... } // optional data can be passed as JSON here
   },
   "identity": {
      // either address or customerUserId is required to help us identify a user
      "address": "0x...",
      "customerUserId": "test@gmail.com"
   }
  }
]
</code></pre>

Below are several examples for sending an **array** of events to our API:

## Send Custom Events

<mark style="color:green;">`POST`</mark> `https://spindl.link/events/server`

Sending Custom events via API

#### Headers

| Name                                        | Type   | Description   |
| ------------------------------------------- | ------ | ------------- |
| X-API-Key<mark style="color:red;">\*</mark> | String | The API token |

#### Request Body

| Name                               | Type  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| ---------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:red;">\*</mark> | Array | <p>array of events is required to be passed in. Please pass in a array of objects with the following keys:<br><br><strong>type (required): string</strong></p><p>use <strong>"CUSTOM"</strong> here<br><br><strong>name </strong><em><strong>(required)</strong></em>: <strong>string</strong></p><p> Min 3 & max 100 characters. Must be lower/uppercase alphanumeric. <code>\_:-</code> symbols & spaces are allowed</p><p></p><p><strong>properties </strong><em><strong>(optional)</strong></em><strong>: Object</strong></p><p>Must be a valid JSON object. Max size 16KB & object keys & values cannot exceed 1,000 characters</p><p></p><p><strong>identity: {</strong><br>   <strong>address: string </strong><em><strong>(required)</strong></em></p><p>   <strong>customerUserId: string </strong><em><strong>(required)</strong></em><br><strong>}</strong> : either <code>address</code> or <code>customerUserId</code> is required to help us identify a user. </p><p></p><p><code>address</code> must be a valid wallet address. </p><p><code>cusomerUserId</code> can be a unique db user id or a unique identifier like email address.</p><p></p><p>These identifiers are very important part of stitching identities and providing accurate attribution.<br><br></p> |

{% tabs %}
{% tab title="204: No Content OK" %}

{% endtab %}
{% endtabs %}

<details>

<summary>NodeJs Axios Example</summary>

```javascript
const axios = require('axios');
let data = JSON.stringify([
  {
    "type": "CUSTOM",
    "data": {
      "name": "ADD_TO_CART",
      "properties": {
        "optional_data": "here"
      }
    },
    "identity": {
      "address": "0x0000000000000000000000000000000000000000",
      "customerUserId": "test@gmail.com"
    }
  },
  {
    "type": "CUSTOM",
    "data": {
      "name": "TEST_EVENT_2",
      "properties": {
        "optional_data": "here"
      }
    },
    "identity": {
      "address": "0x0000000000000000000000000000000000000000"
    }
  }
]);

let config = {
  method: 'post',
  url: 'https://spindl.link/events/server',
  headers: { 
    'X-Api-Key': 'YOUR_API_KEY', 
    'Content-Type': 'application/json',
  },
  data : data
};

axios.request(config)
.then((response) => {
  console.log(JSON.stringify(response.data));
})
.catch((error) => {
  console.log(error);
});


```

</details>

<details>

<summary>Javascript Fetch Example</summary>

```javascript
var myHeaders = new Headers();
myHeaders.append("X-Api-Key", "YOUR_API_KEY");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify([
  {
    "type": "CUSTOM",
    "data": {
      "name": "ADD_TO_CART",
      "properties": {
        "optional_data": "here"
      }
    },
    "identity": {
      "address": "0x0000000000000000000000000000000000000000",
      "customerUserId": "test@gmail.com"
    }
  },
  {
    "type": "CUSTOM",
    "data": {
      "name": "TEST_EVENT_2",
      "properties": {
        "optional_data": "here"
      }
    },
    "identity": {
      "address": "0x0000000000000000000000000000000000000000",
      "customerUserId": "test@gmail.com"
    }
  }
]);

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://spindl.link/events/server", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

</details>

<details>

<summary>cURL Example</summary>

```powershell
curl --location 'https://spindl.link/events/server' \
--header 'X-Api-Key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '[
    {
        "type": "CUSTOM",
        "data": {
            "name": "ADD_TO_CART",
            "properties": {
                "optional_data": "here"
            }
        },
        "identity": {
            "address": "0x0000000000000000000000000000000000000000",
            "customerUserId": "test@gmail.com"
        }
    },
    {
        "type": "CUSTOM",
        "data": {
            "name": "TEST_EVENT_2",
            "properties": {
                "optional_data": "here"
            }
        },
        "identity": {
            "address": "0x0000000000000000000000000000000000000000"
        }
    }
]'
```

</details>


---

# 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.spindl.xyz/spindl/techncial/api/custom-events-api.md?ask=<question>
```

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.