Tracking Link Management API Reference

Use the Tracking Link Management API endpoints to create and view Singular tracking links.

 

List of Tracking Link Management Endpoints

Click on any endpoint name to learn more.

Discover Apps GET https://api.singular.net/api/v1/links/discover_apps Returns a list of your apps (name + app ID). Use the app ID when querying Discover Available Partners and Create Link.
Discover Available Partners GET https://api.singular.net/api/v1/links/discover_available_partners Returns a list of partners available for a specific app ID. Use the partner ID when querying Create Link.
Create Link POST https://api.singular.net/api/v1/links/create Create a new tracking link.
View Links GET https://api.singular.net/api/v1/links/view View existing tracking links and their details.
Create Custom Link POST https://api.singular.net/api/v1/links/create_custom Create a new custom link (a tracking link for a custom source).
View Custom Links GET https://api.singular.net/api/v1/links/view_custom View existing custom links and their details.

Discover Apps Endpoint

GET https://api.singular.net/api/v1/links/discover_apps

Usage

Query this endpoint to retrieve your applications.

Query Parameters

Parameter Type Description
include_admon_fields Boolean (Optional) Set to true to receive the app's ad monetization information.

Query Headers

Header Format Description
Authorization String Your Singular API key.

Sample Output (CURL)

"available_apps": [
  {
    "singular_app_id": 34762423,
    "app_name": "Jewel Run",
    "app_longname": "com.acme.jewelrun",
    "app_platform": "ios",
    "app_public_id": "52534563456",
    "admon_revenue_sources": [
      "ironsource_user_level_publisher"
    ]
  },
  {
    "singular_app_id": 25634565,
    "app_name": "Brick Smash",
    "app_longname": "com.acme.bricksmash",
    "app_platform": "android",
    "app_public_id": "com.acme.bricksmash",
    "admon_revenue_sources": [
      "ironsource_user_level_publisher"
    ]
  }
]

Output Details

Attribute Description
singular_app_id The ID of the app (to use when querying endpoints such as Create Link).
app_public_id The ID of the app in the app store.
app_name The name of the app.
app_longname The app package name, e.g., "com.my.app".
app_platform The platform for which the app is distributed, e.g., "ios" or "android".
admon_revenue_sources This field is returned if you set include_admon_fields to true. It lists the source(s) used to calculate device- or impression-level ad revenue data for this app. A source can be a mediation platform, a third-party tool, or a generic way of calculating ad revenue.

Discover Available Partners Endpoint

GET https://api.singular.net/api/v1/links/discover_available_partners

Usage

Query this endpoint to retrieve the available partners for whom you can create a tracking link for a specific application.

Note: Partners only appear here if you've configured them in the Partner Configuration page.

Sample Query (CURL)

--request GET \
--url 'https://api.singular.net/api/v1/links/discover_available_partners?singular_app_id=singular_app_id' \
--header 'authorization: Authorization'

Query Parameters

Parameter Format Description
singular_app_id Integer The ID of the app for which you want to create a tracking link, as retrieved from the Discover Apps endpoint.

Query Headers

Header Format Description
Authorization String Your Singular API key.

Sample Output

{
  "available_partners": [
    {
      "singular_partner_id":1234,
      "singular_partner_display_name":"AdColony"
    },
    {
      "singular_partner_id":1235,
      "singular_partner_display_name":"Inmobi"
    }
  }
  ]
}

Create Link Endpoint

POST https://api.singular.net/api/v1/links/create

Usage

Use this endpoint to create tracking links, for a provided application and partner.

Note: You won't be able to create a new tracking link if there's an existing tracking link with the same app, partner, and tracker_campaign_name.

Sample Query (CURL)

curl --request POST \
  --url https://api.singular.net/api/v1/links/create \
  --header 'authorization: Authorization' \
  --header 'content-type: application/json' \
  --data '{"tracker_campaign_name":"My First Campaign","destination_fallback_url":"https://play.google.com/store/apps/details?id=com.my.app","destination_deeplink_url":"myapp://path/to/somewhere?macros_supported={NETWORK}","destination_universal_link_url":"https://www.myuniversallink.com/","deferred_deeplink_enabled":false,"reengagement_enabled":false}'

Query Parameters

Parameter Format Description
singular_app_id Integer The ID of the app for which you want to create a tracking link, as retrieved from the Discover Apps endpoint.
singular_partner_id Integer Singular Partner ID, returned from the discover_available_partners endpoint.
tracker_campaign_name String Tracker (Singular) campaign name.
destination_fallback_url String The URL the tracking link will redirect the user too. If deeplinks are used, the URL the tracking link will redirect the user to, when the app is not installed.
destination_deeplink_url String Optional deeplink URL to enable smart linking. This is the destination the tracking link will redirect the user to, if the application is installed. This is required if "deferred_deeplink_enabled" is True.
destination_universal_link_url String iOS only. Optional universal link URL for iOS apps. Please note that using this field will issue a 302 redirect to the configured Universal Link. Redirects to Universal Links have mixed support in iOS, so this is not commonly used.
deferred_deeplink_enabled Boolean Set to true to enable deferred deep linking for this tracking link. The deferred deep link destination will be destination_deeplink_url. Default: False.
reengagement_enabled Boolean Enable re-engagement for the tracking link. Default False if not provided. Re-engagement is only supported with partners who are able to provide advertising IDs in tracking links.

Query Headers

Header Format Description
Authorization String Your Singular API key.

Sample Output

{
  "singular_app_id":12345,
  "app_longname":"com.my.app",
  "app_platform":"android",
  "singular_partner_id":1234,
  "singular_partner_display_name":"AdColony",
  "tracker_campaign_name":"My First Campaign",
  "destination_fallback_url":"https://play.google.com/store/apps/details?id=com.my.app",
  "destination_deeplink_url":"myapp://path/to/somewhere?macros_supported={NETWORK}",
  "deferred_deeplink_enabled":false,
  "reengagement_enabled":true,
  "click_tracking_link":"https://c.singular.net/api/v1/ad?st=1221039&h=192837192837192387&re=1",
  "impression_tracking_link":"https://i.singular.net/api/v1/imp?st=1221039&h=192837192837192387&re=1",
  "tracking_link_id":1221039,
  "created_utc":"2018-06-01T10:12:18+00:00:00",
  "updated_utc":"2018-06-01T10:12:18+00:00:00"
}

View Links Endpoint

GET https://api.singular.net/api/v1/links/view

Usage

Retrieve existing tracking links and their details. You can query this endpoint without any parameters to retrieve all existing links in your account, or filter the search by app(s), partner(s), or tracking link ID(s).

Sample Query (CURL)

curl --request GET \
  --url https://api.singular.net/api/v1/links/view \
  --header 'authorization: Authorization'

Query Parameters

Parameter Format Description
singular_app_ids String An app ID to filter by or multiple app IDs separated by commas.
singular_partner_ids String A partner ID to filter by, or multiple partner IDs separated by commas.
tracking_link_ids String A tracking link ID to filter by, or multiple tracking link IDs separated by commas.
include_archived_links Boolean Set to True to include links that have been archived. Default: False.

Query Headers

Header Format Description
Authorization String Your Singular API key.

Sample Output

{
  "results": [
    {
      "app_longname": "com.my.app",
      "app_platform": "android",
      "click_tracking_link": "https://c.singular.net/api/v1/ad?st=1221039&h=192837192837192387&re=1",
      "created_utc": "2018-06-01T10:12:18+00:00:00",
      "deferred_deeplink_enabled": false,
      "destination_deeplink_url": "myapp://test?value={somemacro}",
      "destination_fallback_url": "https://play.google.com/store/apps/details?id=com.my.app",
      "impression_tracking_link": "https://i.singular.net/api/v1/imp?st=1221039&h=192837192837192387&re=1",
      "reengagement_enabled": true,
      "singular_app_id": 1234,
      "singular_partner_display_name": "AdColony",
      "singular_partner_id": 1234,
      "tracker_campaign_name": "My First Campaign",
      "tracking_link_id": 1221039,
      "updated_utc": "2018-06-01T10:12:18",
      "status":"Active"
    },
    {
      "app_longname": "com.my.app",
      "app_platform": "ios",
      "click_tracking_link": "https://c.singular.net/api/v1/ad?st=1221040&h=192837192837192387&re=1",
      "created_utc": "2018-06-01T10:12:18+00:00:00",
      "deferred_deeplink_enabled": false,
      "destination_deeplink_url": "myapp://test?value={somemacro}",
      "destination_fallback_url": "https://itunes.apple.com/us/app/favorite-wallpapers/id1234567890?mt=8",
      "impression_tracking_link": "https://i.singular.net/api/v1/imp?st=1221040&h=192837192837192387&re=1",
      "reengagement_enabled": true,
      "singular_app_id": 1235,
      "singular_partner_display_name": "AdColony",
      "singular_partner_id": 1234,
      "tracker_campaign_name": "My First Campaign",
      "tracking_link_id": 1221040,
      "updated_utc": "2018-06-01T10:12:18",
      "status":"Archived"
    }
  ]
}

Create Custom Link Endpoint

POST https://api.singular.net/api/v1/links/create_custom

Usage

Use this endpoint to create a tracking link for a custom source - for example, a link to be used in an SMS or email campaign.

Notes:

  • You can give a custom source any name you want as long as it's not a name used by Singular for a partner.
  • You can configure the tracking link to have both an iOS destination (the Apple App Store) and an Android destination (the Google Play Store).

Sample Query (CURL)

curl --request POST \
  --url https://api.singular.net/api/v1/links/create_custom \
  --header 'authorization: Authorization' \
  --header 'content-type: application/json' \
  --data '{"custom_source_name":"My Custom Source","tracker_campaign_name":"My First Campaign","ios_destination_fallback_url":"https://itunes.apple.com/us/app/id1234567890?mt=8","ios_destination_deeplink_url":"myapp://path/to/somewhere?macros_supported={NETWORK}","ios_destination_universal_link_url":"https://www.myuniversallink.com/","android_destination_fallback_url":"https://play.google.com/store/apps/details?id=com.my.app","android_destination_deeplink_url":"myapp://path/to/somewhere?macros_supported={NETWORK}","other_destination_fallback_url":"https://www.mywebsite.com/"}'

Query Parameters

Parameter Format Description
ios_singular_app_id Integer Singular App ID of an iOS application, returned from the discover_apps endpoint. You have to specify either ios_singular_app_id,  android_singular_app_id, or both.
android_singular_app_id Integer Singular App ID of an Android application, returned from the discover_apps endpoint. You have to specify either ios_singular_app_id,  android_singular_app_id, or both.
custom_source_name String Name of custom source.
tracker_campaign_name String Tracker (Singular) campaign name.
ios_destination_fallback_url String Required if ios_singular_app_id is provided. The URL the tracking link will redirect the user to. If deep linking is enabled, this is the URL that the tracking link redirects the user to when the app is not installed.
ios_destination_deeplink_url String Optional if ios_singular_app_id is provided. Required if ios_deferred_deeplink_enabled is True. The deep linking destination that will be opened if the app is installed on the user's device.
ios_destination_universal_link_url String Optional if ios_singular_app_id is provided. Universal link URL for iOS apps. Note: Using this parameter will issue a 302 redirect to the configured Universal Link. Redirects to Universal Links have mixed support in iOS, so this is not commonly used.
ios_deferred_deeplink_enabled Boolean Optional if ios_singular_app_id is provided. Set to True to enable deferred deep linking in iOS. The deep linking destination will be the value of ios_destination_deeplink_url. Default: False.
android_destination_fallback_url String Required if android_singular_app_id is provided. The URL the tracking link will redirect the user to. If deep linking is enabled, this is the URL that the tracking link redirects the user to when the app is not installed.
android_destination_deeplink_url String Optional if android_singular_app_id is provided. Required if android_deferred_deeplink_enabled is True. The deep linking destination that will be opened if the app is installed on the user's device.
android_deferred_deeplink_enabled Boolean Optional if android_singular_app_id is provided. Set to True to enable deferred deep linking in Android. The deep linking destination will be the value of android_destination_deeplink_url. Default: False.
reengagement_enabled Boolean Set to True to mark this tracking link as belonging to a re-engagement (retargeting) campaign. Default: False. Note: Re-engagement is only supported with partners that are able to append advertising IDs in tracking links.
other_destination_fallback_url String The URL the tracking link will redirect the user to if it is not served on an iOS or Android device.

Query Headers

Header Format Description
Authorization String Your Singular API key.

Sample Output

{
  "custom_source_name":"My Custom Source",
  "tracker_campaign_name":"My First Campaign",
  "ios_singular_app_id":1234,
  "ios_app_longname":"com.my.app",
"ios_destination_fallback_url":"https://itunes.apple.com/us/app/id1234567890?mt=8",
  "ios_destination_deeplink_url":"myapp://path/to/somewhere?macros_supported={NETWORK}",
  "ios_deferred_deeplink_enabled":true,
  "android_singular_app_id":1235,
  "android_app_longname":"com.my.app",  "android_destination_fallback_url":"https://play.google.com/store/apps/details?id=com.my.app",
  "android_deferred_deeplink_enabled":false,
  "reengagement_enabled":false,
  "other_destination_fallback_url":"https://www.mywebsite.com/",
  "click_tracking_link":"https://c.singular.net/api/v1/ad?st=1221039&h=192837192837192387",  "impression_tracking_link":"https://i.singular.net/api/v1/imp?st=1221039&h=192837192837192387",
  "tracking_link_id":1221039,
  "created_utc":"2018-06-01T10:12:18+00:00:00",
  "updated_utc":"2018-06-01T10:12:18+00:00:00"
}

View Custom Links Endpoint

GET https://api.singular.net/api/v1/links/view_custom

Usage

Retrieve existing custom links and their details. You can query this endpoint without any parameters to retrieve all existing custom links in your account, or filter the search by app(s), partner(s), or tracking link ID(s).

Sample Query (CURL)

curl --request GET \
  --url https://api.singular.net/api/v1/links/view_custom \
  --header 'authorization: Authorization'

Query Parameters

Parameter Format Description
singular_app_ids String An app ID to filter by or multiple app IDs separated by commas.
custom_source_name String Custom source name to filter by.
tracking_link_ids String A tracking link ID to filter by, or multiple tracking link IDs separated by commas.
include_archived_links Boolean Set to True to include links that have been archived. Default: False.

Query Headers

Header Format Description
Authorization String Your Singular API key.

Sample Output

{
  "results": [
    {
      "android_app_longname": "com.my.app",
      "android_deferred_deeplink_enabled": false,
      "android_destination_fallback_url": "https://play.google.com/store/apps/details?id=com.my.app",
      "android_singular_app_id": 1235,
      "click_tracking_link": "https://c.singular.net/api/v1/ad?st=1221039&h=192837192837192387",
      "created_utc": "2018-06-01T10:12:18+00:00:00",
      "custom_source_name": "My Custom Source",
      "impression_tracking_link": "https://i.singular.net/api/v1/imp?st=1221039&h=192837192837192387",
      "ios_app_longname": "com.my.app",
      "ios_deferred_deeplink_enabled": true,
      "ios_destination_deeplink_url": "myapp://path/to/somewhere?macros_supported={NETWORK}",
      "ios_destination_fallback_url": "https://itunes.apple.com/us/app/id1234567890?mt=8",
      "ios_singular_app_id": 1234,
      "other_destination_fallback_url": "https://www.mywebsite.com/",
      "reengagement_enabled": false,
      "tracker_campaign_name": "My First Campaign",
      "tracking_link_id": 1221039,
      "updated_utc": "2018-06-01T10:12:18+00:00:00",
      "status":"Active"
    }
  ]
}
Was this article helpful?