Get SKAN Conversion Info API Reference (SKadNetwork API for Singular Partners)

If you are an ad network partnered with Singular, you can use the Conversion Model API to get the details of the current conversion model configured by an advertiser. NOTE: This is a limited feature. To access this API, contact your Singular partner manager or our Singular Support.

For more information, see Integrating with Singular SKAdNetwork: FAQ for Partners.

If you're a Singular customer, see the Model Configuration FAQ instead.

 

Get SKAN Conversion Info Endpoint

GET https://api.singular.net/api/skadnetwork/conversion_info

Usage

SKAdNetwork postbacks can contain a conversion value, which is a number between 0 and 63. Singular offers a choice of several different "conversion models" to map as much information as possible into the conversion value. Advertisers can adjust a conversion model's settings or switch to a different conversion model on the fly through the conversion model dashboard.

If you want to parse the conversion value, query the conversion model endpoint to get the full details of the conversion model currently enabled for an app.

This API will return the configured conversion model for a given app(s), provided the following requirements have been met:

Sample Query

https://api.singular.net/api/skadnetwork/conversion_info?api_key=[api_key]&app_id=14
41750662&org_type=partner

Query Parameters

Parameter Required?
Description Example
api_key Yes

The Singular SKAN API key provided by Singular for the SKAdNetwork integration. Can either be part of the URL, or the Authorization HTTP header.

6aed7434-737f-4cae-9fd4-ff
1a0f17b0d1
app_id Yes The Apple App ID. 1441750662
bundle_id Yes The app's bundle ID (required if the app is not live in the App Store yet). com.my.app
org_type org_type Enter "partner". partner
app_response_type No Default is "bundle_id". Identify if the API response should be keyed by an app's bundle ID or Apple App ID.  Note that app_response_type=app_id will only return apps live in the app store.  app_response_type=bundle_id includes apps not yet live in the app store. app_id
bundle_id

Sample Response

{
      "com.my.app": {
          "currency": ​"USD"​, 
          "keepalive_interval": ​24​, 
          "measurement_period": ​168​, 
          "start_ts": ​1601856000​, 
          "update_ts": ​1601856000​, 
          "version": ​5​, 
          "previous_version": ​4​, 
          "conversion_model": {
              "0": [ 
                  {
                      "conversion_name": ​"purchase",​ 
                      "conversion_type": ​"conversion_events"​, 
                      "partner_conversion_name": ​"Partner Purchase"​, 
                      "value": ​0
                  }, 
                  {
                      "conversion_name": ​"Add To Cart",​ 
                      "conversion_type": ​"conversion_events"​, 
                      "partner_conversion_name": ​"Partner Add to Cart"​, 
                      "value": ​0
                  }, 
                  {
                      "conversion_name": ​"retention"​, 
                      "conversion_type": ​"retention"​, 
                      "partner_conversion_name": ​"Partner App Open"​, 
                      "value": {"min": ​0​,"max": ​24}
                  } 
              ],
              "1": [ 
                  {
                      "conversion_name": ​"purchase",​ 
                      "conversion_type": ​"conversion_events"​, 
                      "partner_conversion_name": ​"Partner Purchase"​, 
                      "value": ​0
                  },
                  {
                      "conversion_name": ​"Add To Cart",​ 
                      "conversion_type": ​"conversion_events"​, 
                      "partner_conversion_name": ​"Partner Add to Cart"​, 
                      "value": ​1
                  }, 
                  {
                      "conversion_name": ​"retention"​, 
                      "conversion_type": ​"retention"​, 
                      "partner_conversion_name": ​"Partner App Open"​, 
                      "value": {"min": ​0​,"max": ​24 }
                  }
              ],
              "2": [ 
                  {
                      "conversion_name": ​"purchase",​ 
                      "conversion_type": ​"conversion_events"​, 
                      "partner_conversion_name": ​"Partner Purchase"​, 
                      "value": ​1
                  }, 
                  {
                      "conversion_name": ​"Add To Cart",​ 
                      "conversion_type": ​"conversion_events"​, 
                      "partner_conversion_name": ​"Partner Add to Cart"​, 
                      "value": ​1
                  }, 
                  {
                      "conversion_name": ​"retention"​, 
                      "conversion_type": ​"retention"​, 
                      "partner_conversion_name": ​"Partner App Open"​, 
                      "value": {"min": ​0​, "max": ​24 }
                  } 
              ]
          }
      }
  }

Response Fields

Field Description
bundle_id object One or more of these are returned if the request was successful. Each bundle ID contains the details of the conversion model configured for the respective app.
status

Integer returned if there is an error:

  • 1 - HTTP 400, Invalid app ID in request
  • 2 - HTTP 400, Partner is not configured for this app.  Advertiser needs to configure the Partner Configuration for partner in their Singular dashboard
  • 3 - HTTP 200, Singular SKAdNetwork is not enabled for this app.  Advertiser needs to enable SKAdNetwork measurement with Singular as well as enable .
message

Description message corresponding to the status

  • status=1 - "Invalid App ID"
  • status=2 - "[Partner] is not configured for this app"
  • status=3 - "Singular SKAN is not enabled for this app"

Bundle_id Object Fields

Field Description Example
start_ts Timestamp of when this model was activated (Unix format) 1601856000
update_ts Timestamp of when this model was last updated 1601856000
version The version number of the conversion model 2
previous_version The previous version number of the conversion model 1
measurement_period The maximum period, in hours, that the conversion model uses to track post-install events. Singular supports up to 7 days (168 hours). 168
keepalive_interval The time interval, in hours, that the conversion model uses to implement "keep-alives" for conversion value tracking. Singular currently supports 24-hour intervals. 24
currency The currency set for the advertiser's Singular account. Any revenue details appearing in the response are based on this currency. USD
conversion_model

An object containing a list of possible conversion values. Each value contains an array of detail objects that together describe the meaning of the conversion values. Note that the list does not necessarily contain every number from 0 to 63, as some values may be unused by the conversion model.

  • conversion_type: Either "revenue", "retention", "engagement", "conversion_events", or "funnel". Use this field along with the value field and the conversion_name to translate the given conversion value (0-63) into metrics/KPIs. See Conversion Types and Values below for more information.
  • value: A number/object that should be interpreted based on the conversion_type. See Conversion Types and Values below.
  • conversion_name: the event name given by the advertiser, e.g., "My IAP."
  • partner_conversion_name: The event name given by the advertiser (when supported), e.g., "IAP." If the advertiser hasn't mapped the event to a partner name, this field is null or contains an empty string.
 

Conversion Types and Values

conversion_type Sample value Description
revenue
{
  "min": 0,
  "max": 5
}
If you see this conversion type, it means the advertiser has chosen to focus on revenue gained from the end-user within the limits of the measurement period. Due to the limitations of the conversion value, revenue isn't given as an exact number but as a category or "bucket" of revenue. In this example, the revenue from the end-user is between 0-5 (in the currency defined for the account - see bundle_id.currency).
retention
{
  "min": 0,
  "max": 24
}
This conversion type means that the advertiser has chosen to track the approximate time after the install in which this conversion event occurred. The time is given as one of several "buckets" defined by the customer, with a lower bound ("min") and a higher bound ("max"), in hours.
engagement
{
  "min": 2,
  "max": 2
}
This conversion type means the advertiser chose to track how many instances of the event have occurred within the measurement period (the event is denoted by the conversion_name and the partner_conversion_name).
conversion_events 1 This conversion type means the advertiser has chosen to track if the event has occurred at least once within the measurement period. 0 means that the event hasn't occurred, and 1 means that it has occurred (the event is denoted by the conversion_name and the partner_conversion_name).
funnel 1 This conversion type means the advertiser chosen to track if the event has occurred at least once within the measurement period. 0 means that the event hasn't occurred, and 1 means that it has occurred (the event is denoted by the conversion_name and the partner_conversion_name).