1. Help Center
  2. Attribution & Deep Linking
  3. Deep Linking with OneLink

OneLink API

Print / PDF
  • Advertisers
  • Developers
Avatar
Eran Dunsky
Last update:

Introduction

The OneLink REST API provides programmatic access to read and write shortened OneLink tracking links. The OneLink API not only allows for useful link shortening, but also enables creating and shortening thousands of OneLink URLs automatically.

Using the OneLink API you can create thousands of OneLink tracking links per day. You can also update, delete or query them once created. 

 Example

BigTravel wants to convert its website visitors to mobile app users with personalized content. For each country web page users visit, BigTravel, using the OneLink REST API, builds a OneLink URL containing specific details for the country, user identity (if logged in) and a free admission to an attraction in that country. 

 Note

OneLink REST API is an AppsFlyer premium feature. Please contact your CSM or AppsFlyer's support to enable it. 

Authentication

To prevent misuse, applications must authenticate all API requests using their OneLink API Key. Authenticate the API calls using the OneLink API Key exposed in the API access screen in the AppsFlyer platform, under the OneLink API Key section. 

Note that all API calls must be made over https.

API Rate Limiting

The rate limit of creating OneLink tracking links via API is 50K per day, per account.

Requirements

  • Retargeting attribution data via onAppOpenAttribution is available only from iOS and Android SDK version 4.8.0.

Known Limitations

The OneLink API has the following limitations:

  • Each OneLink tracking link created by the API has a default Time to Live (TTL) of 31 days. After 31 days this tracking link record is removed from our systems. Clicking on such a tracking link once the TTL expires still defaults to the behavior defined in OneLink base Configuration. Maximum TTL is 31 days.
  • Any TTL value larger than 31 is overridden with the default TTL of 31. 
  • TTL value can be specified in days (default), minutes or hours (e.g., 10m, 20h, 14d).
  • It is not possible to use the following special characters in the OneLink API data payload: “&”

 Warning

Use the OneLink API ONLY with links created by it!
Do not use the OneLink API to update or delete shortened OneLink URLs created with the Custom Tracking Link page, as it may break these live URLs. 

Glossary

Onelink ID
The OneLink ID is the unique identifier for the OneLink configured in the OneLink configuration screen:
Shortlink ID
Given a OneLink API generated tracking link: myapp.onelink.me/ab12/qwer987 - the Shortlink ID is the last element in the tracking link structure. In the example above the Shortlink ID would be qwer987

Create OneLink Tracking Link

Given a OneLink ID, Shortlink ID and a set of query params, this API returns a short OneLink tracking link.

Parameter Description

URL

 
https://onelink.appsflyer.com/shortlink/v1/:onelink-id

Method

POST

URL Params

Required:

onelink-id=[alphaNumeric]

Taken from the OneLink configuration screen

Data Params

TTL:  Time to Live for the full tracking link. 

data :  JSON format of the query parameters following the AppsFlyer macros for tracking links.

Example: 
{
 "ttl" : "25", #optional, default is 31d
 "data" :
     {
     "pid" : "SMS-Offer",
     "c" : "April-Coupon",
     "Custom_param" : "value"
     }
}

Success Response

Successful response contains the shortened OneLink tracking link URL

Example:

Code: 200

Content: { https://myapp.onelink.me/abc123/qwer9876}

Error Response

Code: 401 UNAUTHORIZED

Content: { error : "Authentication Failed" }

 

OR

Code: 400 API limit reached

Content: { error : "Data sent exceeds limit" }

Sample Call

 
curl -X POST \
  https://onelink.appsflyer.com/shortlink/v1/abc123 \
  -H 'authorization: your_token_here'\
  -H 'content-type: application/json' \
  -d '{"ttl" : "25",

      "data" : {

      "pid": "your PID here",

      "c": "your campaign here"

      }

  }'

Notes

 AppsFlyer recommends to include the pid parameter (media source name) when creating any link. If the pid parameter is not provided in the API call all installs are attributed to the “None” media source in AppsFlyer dashboards and reports.

Update OneLink Tracking Link

Given a OneLink ID, Shortlink ID and a set of query params, this API updates the given tracking link to the provided query params.

Parameter Description

URL

 
https://onelink.appsflyer.com/shortlink/v1/:onelink-id?id=:shortlink-id

Method

PUT

URL Params

Required:

onelink-id=[alphaNumeric]

Taken from the OneLink configuration screen

shortlink-id=[alphaNumeric]

The id of the short OneLink query params. E.g. For the following OneLink tracking link: myapp.onelink.me/abc123/qwer9876 , the shortlink-id is qwer9876

Data Params

TTL :  Time to Live for the full tracking link. Maximum and default TTL is 31 days. Any TTL value larger than 31 is overridden with 31 . This time frame can be specified in minutes, hours or days (10m/10h/10d) with no distinction defaulting to days.

data :  JSON format of the query parameters following the AppsFlyer macros for tracking links.

Example:

{
 "ttl" : "25", #optional, default is 31d
 "data" :
     {
     "pid" : "SMS-Offer",
     "c" : "April-Coupon",
     "custom_param" : "value"
     }
}

Success Response

Successful response contains the shortened OneLink tracking link URL

Example:

Code: 200

Content: { myapp.onelink.me/abc123/qwer9876 }

Error Response

Code: 401 UNAUTHORIZED

Content: { error : "Authentication Failed" }

OR

Code: 400 Data Error

Content: { error : "Invalid/no data in request" }

OR

Code: 400 API limit reached

Content: { error : "Data sent exceeds limit" }

Sample Call

 
curl -X POST \
https://onelink.appsflyer.com/shortlink/v1/abc123?id=qwer9876 \
  -H 'authorization: your_token_here'\
  -H 'content-type: application/json' \
  -d '{"ttl" : "25",

      "data" : {

      "pid" : "your PID here",

      "c" : "your campaign here"

           }

      }'

Get OneLink Tracking Link

Given a OneLink ID, Shortlink and Shortlink ID, this API returns the query params defined for this tracking link.

Parameter Description

URL

 
https://onelink.appsflyer.com/shortlink/v1/:onelink-id?id=:shortlink-id

Method

GET

URL Params

Required:

onelink-id=[alphaNumeric]

Taken from the OneLink configuration screen

shortlink-id=[alphaNumeric]

The id of the short OneLink query params. E.g. For the following OneLink tracking link: myapp.onelink.me/abc123/qwer9876 , the shortlink-id is qwer9876

Data Params

NONE

Success Response

Successful response contains a JSON of the query params used to define this short link

Example:

Code: 200

Content:

{
  "pid": "sms-offer"
  "c": "april-coupon"
}

Error Response

Code: 401 UNAUTHORIZED

Content: { error : "Authentication Failed" }

OR

Code: 404 Shortlink record not found

Content: { error : "Record Not Found" }

Sample Call

 
curl -X GET \
"https://onelink.appsflyer.com/shortlink/v1/abc123?id=qwer9876 \
-H 'authorization: your_token_here'\
-H 'content-type: application/json'

Delete OneLink Tracking Link

Given a OneLink ID, Shortlink ID and a set of query params, this API deletes and invalidates this tracking link. Any subsequent clicks on this tracking link default to the base definitions in the OneLink’s configuration.

Parameter Description

URL

 
https://onelink.appsflyer.com/shortlink/v1/:onelink-id?id=:shortlink-id

Method

DELETE

URL Params

Required:

onelink-id=[alphaNumeric]

Taken from the OneLink configuration screen

shortlink-id=[alphaNumeric]

The id of the short OneLink query params. E.g. For the following OneLink tracking link: myapp.onelink.me/abc123/qwer9876 , the shortlink-id is qwer9876

Data Params

NONE

Success Response

Example:

Code: 200

Content: { ok }

Error Response

Code: 401 UNAUTHORIZED

Content: { error : "Authentication Failed" }

OR

Code: 404 Shortlink record not found

Content: { error : "Record Not Found" }

Sample Call

 
curl -X DELETE \
"onelink.appsflyer.com/shortlink/v1/abc123?id=qwer9876 \
-H 'authorization: your_token_here'\
-H 'content-type: application/json'

 

Was this article helpful?
1 out of 1 found this helpful

Articles in this section

Related articles