1. Help Center
  2. Attribution and deep linking
  3. Deep linking with OneLink

OneLink API

Avatar
Eran Dunsky
Last update:
  • Advertisers
  • Developers

Introduction

The OneLink REST API provides programmatic access to read and write shortened OneLink attribution links. The OneLink API not only allows for useful link shortening, but also enables creating and shortening thousands of OneLink URLs automatically. OneLink REST API is an AppsFlyer premium feature. Please contact your CSM or send at a request to hello@appsflyer.com

Using the OneLink API you can create thousands of OneLink attribution 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.

Authenticating OneLink API Requests 

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 limit

The rate limit of creating OneLink attribution 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 attribution link created by the API has a default Time to Live (TTL) of 31 days. After 31 days this attribution link record is removed from our systems. Clicking on such an attribution 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 Link management 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 attribution link: myapp.onelink.me/ab12/qwer987 - the Shortlink ID is the last element in the attribution link structure. In the example above the Shortlink ID would be qwer987

Create OneLink attribution link

Given a OneLink ID and a set of query params, this API returns a short OneLink attribution 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 attribution link.

data : JSON format of the query parameters following the AppsFlyer macros for attribution 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 attribution 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 attribution link

Given a OneLink ID, Shortlink ID and a set of query params, this API updates the given attribution 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 attribution link: myapp.onelink.me/abc123/qwer9876 , the shortlink-id is qwer9876

Data Params

TTL : Time to Live for the full attribution 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 attribution 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 attribution 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 attribution link

Given a OneLink ID, Shortlink and Shortlink ID, this API returns the query params defined for this attribution 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 attribution 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 attribution link

Given a OneLink ID, Shortlink ID and a set of query params, this API deletes and invalidates this attribution link. Any subsequent clicks on this attribution 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 attribution 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'

FAQ

See the following FAQ to learn more about using OneLink API.

Can I get a list of all OneLinks created using the API?

Currently, there is no API that lists all OneLinks created with the API.

How do I get the OneLink TTL?

The default is 31 days if TTL is not specified when creating a OneLink. It's not possible to get the TTL when calling get OneLink.  

Can I extend the TTL?

Yes, you can send an update request and specify the TTL. Any update request resets the TTL to the one specified in the request body.

Can I set the shortlink ID when creating a OneLink?

It's not possible to choose or set the shortlink ID when creating a OneLink.

Was this article helpful?
2 out of 3 found this helpful

Articles in this section

Related articles