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

OneLink API

Avatar
Eran Dunsky
Last update:
  • Advertisers
  • Developers

At a glance: OneLink REST API enables creating, updating, retrieving, and deleting OneLink attribution links.

Use OneLink API to: 

  • Create, update, get, and delete OneLink URLs automatically.  
  • To generate a large number of OneLink attribution links. 
  • Customize OneLink URLs with your brand. When you generate the URL it is generated with your brand domain, instead of the OneLink subdomain.

 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.

OneLink API

Authentication key 

OneLink API requests must be authenticated using a OneLink API Key. 

Prerequisite:

  • The account admin needs to retrieve the API key. Team members do not have access to the API Key. 

To retrieve the OneLink API key:

  • Go to Integration > API Access, scroll down to the OneLink API section. 
  • API calls must be made over https.
  • API rate limit: The rate limit of creating OneLink attribution links via API is 250K per day, per account.
  • Requirements: Retargeting attribution data via onAppOpenAttribution is available using Appslfyer SDKs, iOS and Android, version 4.8.0 and later. 

Limitations

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: “&”

 Note

  • Use the OneLink API only with links created by it.
  • Don't use OneLink API to update or delete shortened OneLink URLs created using the Link management page. It may break 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
  • brand_domain (optional): You can specify a branded link in the request payload but there are two requirements:
    • The branded links feature is enabled in your account.
    • The branded link is configured in your account.
      Click here to learn how to enable the feature and to configure a branded link.
  • TTL (optional): Time to Live for the full attribution link.
  • data : JSON format of the query parameters following the AppsFlyer macros for attribution links.

 

Example: 
{
 "brand_domain": "click.example.com", #optional, requires a configured branded link
 "ttl" : "25", #optional, default is 31d
 "data" :
   {
   "pid" : "SMS-Offer",
   "c" : "April-Coupon",
   "Custom_param" : "value"
   }
}

Success Response

A successful response contains the shortened OneLink attribution link URL (shortlink), or the branded link with the OneLink and shortlink ID. If you specify a branded link and it is not configured, the response contains a shortlink.

Example:

Code: 200

  • Shortlink: https://myapp.onelink.me/abc123/qwer9876
  • Branded link: https://click.example.com/abc123/qwer9876

Error Response
Error code Content Remarks
401 UNAUTHORIZED { error : "Authentication Failed" }  
400 API limit reached { error : "Data sent exceeds limit" }  

Sample Call

 
curl -X POST \
 https://onelink.appsflyer.com/shortlink/v1/abc123 \
 -H 'authorization: [Your OneLink API Key]'\
 -H 'content-type: application/json' \
 -d '{"brand_domain": "click.example.com"
 "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
  • brand_domain (optional): You can specify a branded link in the request payload but there are two requirements:
    • The branded links feature is enabled in your account.
    • The branded link is configured in your account.
      Click here to learn how to enable the feature and to configure a branded link.
  • TTL (optional): 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:

{
 "brand_domain": "click.example.com", #optional, requires a configured branded link
 "ttl" : "25", #optional, default is 31d
 "data" :
   {
   "pid" : "SMS-Offer",
   "c" : "April-Coupon",
   "custom_param" : "value"
   }
}

Success Response

A successful response contains the shortened OneLink attribution link URL (shortlink), or the branded link with the OneLink and shortlink ID. If you specify a branded link and it is not configured, the response contains a shortlink.

Example:

Code: 200

  • Shortlink: https://myapp.onelink.me/abc123/qwer9876
  • Branded link: https://click.example.com/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 PUT\
https://onelink.appsflyer.com/shortlink/v1/abc123?id=qwer9876 \
 -H 'authorization: [Your OneLink API Key]'\
 -H 'content-type: application/json' \
 -d '{"brand_domain": "click.example.com"
   "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 OneLink API Key]'\
-H 'content-type: application/json'

Delete OneLink attribution link

Given a OneLink ID and a Shortlink ID, 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 OneLink API Key]'\
-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?

Articles in this section

Related articles