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. The Reporting API reads those names when it renders reports; reporting update endpoints are not where names are written. The API base URL is:
Code
All examples below use a bearer access token in the Authorization header. See 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:
Code
campaign: truedeclares manual names for thecampaignURL parameter.field1Slotdeclares the tracking field (c1throughc20) that reads field 1 names.field2Slotdeclares the tracking field (c1throughc20) that reads field 2 names.suffixIds: truedisplays 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.
Code
Example request:
Code
A successful upload returns 200 with counts for the merge:
Code
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
400before Ledger can return its JSON error. idandnameare 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 (
ABCandabcare the same ID). Non-BMP characters are replaced withU+FFFDbefore 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 asid_empty,name_empty,id_too_long,name_too_long,id_invalid_character,name_invalid_character, orduplicate_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.
Code
To clear every field of the traffic source, omit field:
Code
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:
Code
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:
campaignvalues use campaign names whendataMapping.campaignistrue.- A tracking field such as
c1uses field 1 names whenfield1Slotisc1, or field 2 names whenfield2Slotisc1. - 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 and its Updates operations. For the endpoint schemas and generated examples, see the Assets API Data Mapping section.