> For the complete documentation index, see [llms.txt](https://docs.sharemint.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sharemint.xyz/fundamentals/referee-requirements/api-events.md).

# API Events

You can send custom events to ShareMint using our API.

These events are associated with referees and are used to reward affiliates.

For example, if you have a web3 game, and your game has a breeding event, you can reward an affiliate that invites a user to the game that breeds at least 5 times. To determine whether the conditions have been completed, you would send a breed event to our API each time the user breeds. One we recieve 5 breed events, the affiliate reward will be unlocked.

To add an API Event requirement, navigate to your project's settings page. In the *Affiliates* section, click on *Advanced Referee Requirements*, and choose *API Event* as the requirement type.

You will be asked to fill in the following fields:

* **Event Name** - the name of the event. This must match the event name sent via API.
* **What is the minimum value required to be considered a referral?** - This is a numeric value threshold above which an affiliate is considered to be valid. You can leave this blank or set it to 0 if you'd like to allow any value.

<figure><img src="/files/OcCcEcStJY5uq6V3XVNm" alt=""><figcaption><p>Example using API Event</p></figcaption></figure>

### API

Send events using our API:

## To save custom events.

<mark style="color:green;">`POST`</mark> `https://sharemint.xyz/api/external/save-event`

One of `address`, `email`, or `projectUserId` must be provided, otherwise, the request will not be processed.

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| Content-Type<mark style="color:red;">\*</mark> | String | application/json |

#### Request Body

| Name                                        | Type   | Description                                                                                    |
| ------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| slug<mark style="color:red;">\*</mark>      | String | Project slug                                                                                   |
| apiSecret<mark style="color:red;">\*</mark> | String | Find this on the admin tab of your project                                                     |
| name<mark style="color:red;">\*</mark>      | String | Event name that should match an event name used for requirements on the project Settings page. |
| value                                       | Number | A custom value for the event.                                                                  |
| referredByCode                              | String | The referral code of the referrer that invited the user. This will usually be blank.           |
| referredByAddress                           | String | The address of the referrer that invited the user. This will usually be blank.                 |
| address                                     | String | The address of the user that performed the event.                                              |
| email                                       | String | The email of the user that performed the event.                                                |
| projectUserId                               | String | The ShareMint id of the user that performed the event.                                         |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}

{% tab title="500: Internal Server Error " %}

{% endtab %}

{% tab title="400: Bad Request " %}

{% endtab %}

{% tab title="401: Unauthorized " %}

{% endtab %}

{% tab title="403: Forbidden " %}

{% endtab %}

{% tab title="404: Not Found " %}

{% endtab %}
{% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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.sharemint.xyz/fundamentals/referee-requirements/api-events.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.