FunnelFlux Pro API DocumentsFunnelFlux Pro API Documents
  • Changelog
  • Status
  • Dashboard
  • Documentation
  • Authentication
  • Domains
  • Assets
  • Reporting
Getting Started
    General InformationAPI Best PracticesAuthenticationGenerating Asset IDsCreating Funnels
Feature Information
    Data MappingLogic ScriptsMiddleware NodesMiddleware TemplatesWebhook Payloads
Other
    Changelog
Feature Information

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
https://api.funnelflux.pro/v1

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
{ "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.

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

Example request:

TerminalCode
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:

Code
{ "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.

TerminalCode
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:

TerminalCode
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:

Code
{ "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.

StatuscodeWhen
413body_too_largeThe request body is over 4 MiB when Ledger receives it.
400invalid_requestMalformed 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.
404not_foundThe traffic source is missing, deleted, or belongs to another account.
409dictionary_sync_enabledIntegration dictionary sync supplies names for the traffic source.
409field_not_declaredUpload only: the selected field is not declared in dataMapping.
400no_rowsUpload only: rows is empty.
400too_many_rowsUpload only: rows contains more than 10,000 entries.
400invalid_rowsUpload 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 and its Updates operations. For the endpoint schemas and generated examples, see the Assets API Data Mapping section.

Last modified on November 16, 2026
Creating FunnelsLogic Scripts
On this page
  • Declare the mapped fields
  • Upload names
    • Upload limits and row rules
  • Clear names
  • Errors
  • How reports show names
JSON
JSON
JSON
JSON