# Data Mapping

Data mapping replaces raw tracking values with readable names in FunnelFlux Pro reports. A mapping belongs to your account, one traffic source, and one mapping field: `campaign`, `field1`, or `field2`.

Write mappings through the [Assets API Data Mapping operations](/api/assets/data-mapping). The [Reporting API](/api/reporting/updates) reads those names when it renders reports; reporting update endpoints are not where names are written. The API base URL is:

```text
https://api.funnelflux.pro/v1
```

All examples below use a bearer access token in the `Authorization` header. See [Authentication](/authentication) for token setup.

## Declare the mapped fields

Before uploading names, declare which fields a traffic source maps in its `dataMapping` setting. You can set this while creating or updating the traffic source through the [Assets API traffic-source operations](/api/assets/traffic-sources):

```json
{
  "dataMapping": {
    "campaign": true,
    "field1Slot": "c1",
    "field2Slot": "c2",
    "suffixIds": false
  }
}
```

- `campaign: true` declares manual names for the `campaign` URL parameter.
- `field1Slot` declares the tracking field (`c1` through `c20`) that reads field 1 names.
- `field2Slot` declares the tracking field (`c1` through `c20`) that reads field 2 names.
- `suffixIds: true` displays the raw ID after the mapped name.

`field1Slot` and `field2Slot` cannot use the same tracking field. An upload is accepted only for a declared field. A clear can remove a selected field even if its declaration has since been removed.

Manual mappings and integration dictionary sync are mutually exclusive. A traffic source with dictionary sync enabled refuses both mapping operations with `409 dictionary_sync_enabled`; its synced names are never changed by manual mapping calls. The traffic-source declaration also cannot be saved alongside dictionary sync.

## Upload names

`PUT /v1/trafficsource/data-mapping/upload/` merges rows into one traffic source and one field. Existing manual names for IDs in the request are replaced; new IDs are added; IDs omitted from the request remain stored.

```json
{
  "idTrafficSource": "TRAFFIC_SOURCE_ID",
  "field": "campaign",
  "rows": [
    { "id": "cmp-9", "name": "Spring sale" },
    { "id": "cmp-10", "name": "Retargeting" }
  ]
}
```

Example request:

```shell
curl --location 'https://api.funnelflux.pro/v1/trafficsource/data-mapping/upload/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ACCESS_TOKEN_HERE' \
  --data '{
    "idTrafficSource": "TRAFFIC_SOURCE_ID",
    "field": "campaign",
    "rows": [
      { "id": "cmp-9", "name": "Spring sale" },
      { "id": "cmp-10", "name": "Retargeting" }
    ]
  }'
```

A successful upload returns `200` with counts for the merge:

```json
{
  "idTrafficSource": "TRAFFIC_SOURCE_ID",
  "field": "campaign",
  "added": 2,
  "updated": 0
}
```

### Upload limits and row rules

- Each request can contain at most **10,000 rows**.
- The complete request body can be at most **4 MiB (4,194,304 bytes)**. Split larger uploads. A body over that limit may be rejected by the API gateway with a plain-text `400` before Ledger can return its JSON error.
- `id` and `name` are trimmed, must be non-empty, and can be at most 512 characters each.
- Control and invisible-formatting characters are rejected. A tab inside a value is invalid; tabs around a value are removed by trimming.
- IDs are compared after trimming and without case differences (`ABC` and `abc` are the same ID). Non-BMP characters are replaced with `U+FFFD` before duplicate comparison.
- Repeating an ID with the same name collapses to one mapping. Repeating an ID with different names rejects all conflicting rows.
- If any row is invalid, the upload is all-or-nothing. The response includes every refused row in `rowErrors`, using its 1-based row number and a reason such as `id_empty`, `name_empty`, `id_too_long`, `name_too_long`, `id_invalid_character`, `name_invalid_character`, or `duplicate_id_conflict`.

## Clear names

`POST /v1/trafficsource/data-mapping/clear/` removes manual names of exactly one traffic source. With `field`, only that field's manual names are removed. Without `field`, or with `field` empty, every manual name of that traffic source is removed, across `campaign`, `field1` and `field2`, declared or not.

```shell
curl --location 'https://api.funnelflux.pro/v1/trafficsource/data-mapping/clear/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ACCESS_TOKEN_HERE' \
  --data '{
    "idTrafficSource": "TRAFFIC_SOURCE_ID",
    "field": "field1"
  }'
```

To clear every field of the traffic source, omit `field`:

```shell
curl --location 'https://api.funnelflux.pro/v1/trafficsource/data-mapping/clear/' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ACCESS_TOKEN_HERE' \
  --data '{
    "idTrafficSource": "TRAFFIC_SOURCE_ID"
  }'
```

Because an omitted `field` clears all fields, the body is read strictly: it may contain only `idTrafficSource` and `field`, each spelled exactly that way and at most once. An unknown or differently-cased key, a repeated key, and an explicit `null` `field` are refused with `400 invalid_request` and nothing is cleared — omit `field` rather than sending `null`. A non-empty `field` must be `campaign`, `field1`, or `field2`.

A successful clear returns `200` with the number of manual names removed. Clearing a field, or a whole traffic source, with no stored names succeeds with `removed: 0`:

```json
{
  "idTrafficSource": "TRAFFIC_SOURCE_ID",
  "removed": 1
}
```

Synced rows (`origin: "synced"`) are never touched, and a clear never reaches another traffic source or another account. A clear with `field` does not change names in any other field.

## Errors

Both operations are scoped to the authenticated account. The first failed check answers, and a failed request writes nothing.

| Status | `code` | When |
| --- | --- | --- |
| `413` | `body_too_large` | The request body is over 4 MiB when Ledger receives it. |
| `400` | `invalid_request` | Malformed JSON, extra JSON after the first object, a missing `idTrafficSource`, or a `field` outside `campaign`/`field1`/`field2`; for clear, also an unknown or repeated body key, or an explicit `null` `field`. |
| `404` | `not_found` | The traffic source is missing, deleted, or belongs to another account. |
| `409` | `dictionary_sync_enabled` | Integration dictionary sync supplies names for the traffic source. |
| `409` | `field_not_declared` | Upload only: the selected field is not declared in `dataMapping`. |
| `400` | `no_rows` | Upload only: `rows` is empty. |
| `400` | `too_many_rows` | Upload only: `rows` contains more than 10,000 entries. |
| `400` | `invalid_rows` | Upload only: one or more rows violates the row rules; inspect `rowErrors`. |

Authentication failures return `401`. Requests can also be rate limited with `429`; follow the documented `Retry-After` behavior.

## How reports show names

After an upload or clear returns successfully, subsequent reports use the current mappings immediately. The underlying tracking data is not rewritten: a mapping changes the displayed label, not row counts or metrics.

Report name resolution applies only when a URL tracking field is broken down by traffic source or filtered to exactly one traffic source:

- `campaign` values use campaign names when `dataMapping.campaign` is `true`.
- A tracking field such as `c1` uses field 1 names when `field1Slot` is `c1`, or field 2 names when `field2Slot` is `c1`.
- An undeclared field, a value without a stored name, or a report without the required traffic-source context shows the raw ID.
- Changing a field slot changes which tracking field reads the existing names; it does not rewrite stored rows.

For report query and update details, see the [Reporting API](/api/reporting) and its [Updates operations](/api/reporting/updates). For the endpoint schemas and generated examples, see the [Assets API Data Mapping section](/api/assets/data-mapping).
