> 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 %}