SKAN v4 mapping API

The mapping endpoint returns information about an advertiser's conversion value mapping. Network partners may fetch this information at any time by making a GET request to the endpoint.

Important:
If the target app isn't configured to use SKAdNetwork v4, this endpoint falls back to v3 mapping schema. See the SKAN v3 mapping endpoint documentation.

Endpoint

https://app.adjust.com/skadnetwork/v4/{sk_network_token}/mapping/{app_store_id}

GET request

Returns mapping information as an array of JSON objects. Each GET request must contain the following parameters.

ParameterData typeInDescription
sk_network_token*StringPathPartner-specific token assigned by Adjust.

Example: abcdefklmn
app_store_id*StringPathThe App Store ID of the app.

Example: 1125517808

Response

The mapping endpoint returns an array of three JSON objects corresponding with the three postbacks sent by SKAdNetwork v4. Each object is identified by its corresponding conversion_window.

The endpoint returns both fine and coarse mapping information for the first postback only. The second and third postback contain coarse mapping information.

[
   {
      "data": {
         "fine": [{}],
         "coarse": [{}],
         "settings": {},
      },
      "conversion_window": 1
   },
   {
      "data": {
         "coarse": [{}],
         "settings": {},
      },
      "conversion_window": 2
   }
   {
      "data": {
         "coarse": [{}],
         "settings": {},
      },
      "conversion_window": 3
   }
]

Fine conversion value fields

Note:
The mapping endpoint returns mapping information for conversion values which have at least one partner event after sharing settings and event linking are applied. See API behavior for more information.

The mapping endpoint returns a breakdown of each mapped conversion value and its associated details.

[
   {
      "data": {
         "fine": [
            {
               "conversion_value":12,
               "events":[
                  {
                     "event_name":"Purchase",
                     "count_min":3,
                     "count_max":10,
                     "revenue_min":3.00,
                     "revenue_max":10.00
                  },
                  {
                     "event_name":"Registration"
                  }
               ]
            }
         ],
      }
   }
]

Event count and revenue ranges are optional parameters that are returned depending on how the advertiser has configured partner access. The following details may be mapped:

  • Session
  • Session count
  • Event
  • Event count
  • Event revenue
  • IAP
  • Ad Revenue
  • Total Revenue
Note:
To see revenue information, advertisers must enable revenue sharing for the partner making the request.

Count and Revenue range parameters are all optional and are defined as follows:

ParameterData typeDefault valueDescription
count_minNumber1The event or session was recorded not less than the specified number of times.
count_maxNumberUnlimitedThe event or session was recorded not more than the specified number of times.
revenue_minNumber0The total revenue was at least the specified amount. Amounts are measured in the app's reporting_currency.
revenue_maxNumberUnlimitedThe total revenue did not exceed the specified amount. Amounts are measured in the app's reporting_currency.

Coarse conversion value fields

Coarse conversion values are used when the volume of conversions isn’t high enough to meet the privacy threshold for providing a fine conversion value. The coarse CV can be low, medium, or high, which act as aggregated buckets for predefined CV values.

[
   {
      "data": {
         "coarse": [
            {
               "coarse_conversion_value": "low",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0,
                     "revenue_max": 0.5
                  }
               ]
            },
            {
               "coarse_conversion_value": "medium",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0.5,
                     "revenue_max": 1.0
                  }
               ]
            },
            {
               "coarse_conversion_value": "high",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 1.0,
                     "revenue_max": 50
                  }
               ]
            }
         ]
      }
   }
]
ParameterData typeDefault valueDescription
coarse_conversion_valueStringUndefinedThe level of the coarse conversion value. Can be one of:
  • "low"
  • "medium"
  • "high"
event_nameStringnullThe name of the mapped event.
count_minNumber1The event was recorded not less than the specified number of times.
count_maxNumberUnlimitedThe event was recorded not more than the specified number of times.
revenue_minNumber0The total revenue recorded for an event was at least the specified amount. Amounts are measured in the app's reporting_currency.
revenue_maxNumberUnlimitedThe total revenue recorded for an event did not exceed the specified amount. Amounts are measured in the app's reporting_currency.

Response settings fields

[
   {
      "data": {
         "settings": {
            "lock_window": {
               "time_in_hours": 24
            },
            "app_store_id":"1125517808",
            "updated_at":1617234177,
            "reporting_currency":"USD",
         }
      }
   }
]
FieldData typeDescription
app_store_idStringThe App Store ID of the app. Matches the app_store_id parameter sent in the request.
updated_atNumberThe Unix timestamp of the latest mapping change visible to the partner making the request.
lock_windowObjectSettings related to the Lock window.
time_in_hoursNumberThe length of the lock window in hours.
reporting_currencyStringThe ISO 4217 currency code of the app's reporting currency. Applies to all revenue amounts defined in the mapping schema.

Full response example

[
   {
      "data": {
         "fine": [
            {
               "conversion_value":7,
               "events":[
                  {
                     "event_name":"Registration"
                  }
               ]
            },
            {
               "conversion_value":10,
               "events":[
                  {
                     "event_name":"TutorialComplete"
                  }
               ]
            },
            {
               "conversion_value":12,
               "events":[
                  {
                     "event_name":"Purchase",
                     "count_min":3,
                     "count_max":10,
                     "revenue_min":3.00,
                     "revenue_max":10.00
                  },
                  {
                     "event_name":"Registration"
                  }
               ]
            }
         ],
         "coarse": [
            {
               "coarse_conversion_value": "low",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0,
                     "revenue_max": 0.5
                  }
               ]
            },
            {
               "coarse_conversion_value": "medium",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0.5,
                     "revenue_max": 1.0
                  }
               ]
            },
            {
               "coarse_conversion_value": "high",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 1.0,
                     "revenue_max": 50
                  }
               ]
            }
         ],
         "settings": {
            "lock_window": {
               "time_in_hours": 24
            },
            "app_store_id":"1125517808",
            "updated_at":1617234177,
            "reporting_currency":"USD",
         }
      },
      "conversion_window": 1
   },
   {
      "data": {
         "coarse": [
            {
               "coarse_conversion_value": "low",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0,
                     "revenue_max": 0.5
                  }
               ]
            },
            {
               "coarse_conversion_value": "medium",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0.5,
                     "revenue_max": 1.0
                  }
               ]
            },
            {
               "coarse_conversion_value": "high",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 1.0,
                     "revenue_max": 50
                  }
               ]
            }
         ],
         "settings": {
            "app_store_id":"1125517808",
            "updated_at":1617234177,
            "reporting_currency":"USD",
         }
      },
      "conversion_window": 2
   },
   {
      "data": {
         "coarse": [
            {
               "coarse_conversion_value": "low",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0,
                     "revenue_max": 0.5
                  }
               ]
            },
            {
               "coarse_conversion_value": "medium",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 0.5,
                     "revenue_max": 1.0
                  }
               ]
            },
            {
               "coarse_conversion_value": "high",
               "events": [
                  {
                     "event_name": "PURCHASE",
                     "revenue_min": 1.0,
                     "revenue_max": 50
                  }
               ]
            }
         ],
         "settings": {
            "app_store_id":"1125517808",
            "updated_at":1617234177,
            "reporting_currency":"USD",
         }
      },
      "conversion_window": 3
   }
]

Response error codes

Error codeDescription
400 Bad RequestThe Store ID is missing or isn't formatted correctly.
401 UnauthorizedThe network token is missing or not recognized.
403 ForbiddenThe app is recognized, but the Partner sharing requirements weren't met for the requested app.
404 Not FoundThe requested app wasn't found or isn't verified for SKAdNetwork.
422 Unprocessable EntityThe requested app is recognized and verified by Adjust, but the Conversion Value management feature is not not activated for the app.
429 Too Many RequestsRequests are throttled on a per-partner/app basis. Adjust recommends fetching updates once per day.