---
title: Event mappings
description: Map your app's raw event names to Retidal's 17 standard events, so ad platforms and decisioning can act on them.
---

An event mapping links one of your project's own event names (e.g. `user_paid`) to one
of Retidal's 17 standard events (e.g. `PURCHASE`). This mapping is what lets
[Ad platforms](/docs/attribution/ad-platforms) translate your business events into each
platform's native conversion event — without a mapping, an event has no standard-event
identity and cannot be reported as a conversion to any platform.

## Prerequisites

- The target standard event's global definition id — list definitions with `GET
  /api/event-definitions` and note the `id` of the one you want to map to (e.g.
  `PURCHASE`). `appEventName` itself does not need to have been sent by the project
  before; the mapping is what gives that name meaning going forward.

## Authentication

Every endpoint on this page is a **Management API** call — host `https://retidal.com`,
authenticated with the `trackly_session` cookie from a logged-in console user, not a
project API key. See [Authentication](/docs/authentication) for the full model.

## Listing mappings

```
GET https://retidal.com/api/projects/{projectId}/event-mappings
```

Returns every mapping currently configured for the project — each entry names the app
event name, the standard event it maps to, and its active/inactive status.

Console → Projects → Event Mappings shows the same list, with a search box and a
create-mapping dialog.

## Creating a mapping

```
GET https://retidal.com/api/event-definitions
POST https://retidal.com/api/projects/{projectId}/event-mappings
```

First find the target standard event's definition id:

```json title="GET /api/event-definitions response (excerpt)"
{
  "events": [
    { "id": "evtdef_9f2a1c", "code": "PURCHASE", "name": "Purchase", "category": "Monetization", "hasAmount": true }
  ]
}
```

Then create the mapping using that `id` as `eventDefinitionId`:

<CodeGroup>
```json title="Request body"
{
  "appEventName": "user_paid",
  "eventDefinitionId": "evtdef_9f2a1c",
  "isActive": true
}
```
```json title="201 Created"
{ "mapping": { "id": "map_7c1b3e", "appEventName": "user_paid", "eventDefinitionId": "evtdef_9f2a1c", "isActive": true } }
```
</CodeGroup>

`POST /api/projects/{projectId}/event-mappings` returns `404` if `eventDefinitionId`
doesn't match an existing event definition, and `409` if a mapping already exists for the
same `appEventName`.

## Deleting a mapping (optional)

```
DELETE https://retidal.com/api/projects/{projectId}/event-mappings/{mappingId}
```

Removes a mapping outright. Once deleted, events carrying that app event name stop
translating to any standard event — [Ad platforms](/docs/attribution/ad-platforms)
postback for that event name stops until a new mapping replaces it.

## What this unlocks

A configured mapping is the single dependency [Ad platforms](/docs/attribution/ad-platforms)
needs to translate your business event into a platform-native conversion — nothing else
on that page works until the mapping exists.

## Verify it worked

Console → Projects → Event Mappings shows the mapping you just created, with the app
event name and the standard event it points to. Equivalently, from a browser session
already logged into the console (so the `trackly_session` cookie is sent automatically):

```bash
curl -s https://retidal.com/api/projects/{projectId}/event-mappings \
  -H "Cookie: trackly_session=$SESSION_COOKIE"
# expect: 200 { "mappings": [...] } containing the mapping you just created, with
# your appEventName and eventDefinitionId
```

## If it doesn't work

If a raw event name maps to the wrong (or no) canonical event — breaking the same
postback-crediting chain [Ad platforms](/docs/attribution/ad-platforms) depends on —
work through [Conversions failing](/docs/troubleshooting/conversions-failing).