1. Help Center
  2. Attribution & deep linking
  3. Deep linking using OneLink

OneLink API

Avatar
Eli Wrightman
Last update:
  • Advertisers
  • Developers

At a glance: OneLink API helps you engage end-users and leverage owned media by generating personalized links in large-scale campaigns, via SMS, and more. Requires both advertiser and developer to implement.

OneLink API

OneLink API is used to:

  • Create, get, update, and delete OneLink short URLs with customized parameters automatically.
    Parameters can be either:
    • Attribution-related parameters, used for measuring and monitoring marketing efforts, like media source, campaign, and asset. Note: The media source (pid) parameter is mandatory. 
    • Personalization parameters, that let you configure a customized user experience when opening the app from the relevant link. These params let you send users to customized in-app content, for example, a specific product page, coupon code, or promotion.
  • Allow the sharing of website and app content directly to mobile users (thereby increasing mobile engagement and installs).
  • Generate a large number of OneLink custom attribution links instantly.
    Note: For referral links, see the User invite attribution article.

 Example

Feed Me, a grocery delivery service, wants to send a personalized link via SMS to existing customers to encourage them to download the Feed Me app and buy bananas. Based on the country of the customer, Feed Me uses the OneLink REST API to build a custom OneLink URL that contains specific details for the country, user identity, and a special offer for bananas that are on sale.

Procedures

To set up OneLink API:

  1. Create a OneLink template.
  2. Record the OneLink ID. 

  3. Record the OneLink API key. The account admin needs to retrieve the API key. Team members do not have access to the API Key. 
    • In the AppsFlyer dashboard, go to Integration > API Access, and scroll down to the OneLink API section.
    • If the OneLink API key is not there for the admin, it means you don't have the requisite package, and you need to contact your CSM.   

      OL_API_key.png

  4. Give the OneLink ID and the OneLink API key to the developer.
  5. Tell the developer to follow the instructions in the dev hub.
    The OneLink API reference in the dev hub provides a controlled environment for the developer to experiment with the API. Once the developer understands the API, they can take the code generated in the API reference and move it to their own code to generate many custom links.
  6. [Best practice] Tell the developer to keep a log of all the API-created links, and save them to a local table, so you can access the links for any future purpose.

Limitations

Limitation

Remarks

API rate
  • The rate limit of creating OneLink attribution links via API is 7.5 million per month (UTC timezone), per account.
  • All requests that are made after exceeding 7.5 million aren't served, and the links aren't created; the API call receives error status code 429 with the message "throttling limit exceeded".
  • Information regarding how much of the rate limit is used/remains is not currently available. 

Custom links visibility
  • Links created via the API do not appear in the list of OneLink custom links in the AppsFlyer dashboard.
  • There is no API that lists all OneLink custom links created with the API.
  • Best practice: Save API-created links to a local table, so you can access the links for any future purpose. 

TTL 
  • 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 a link once the TTL expires still defaults to the behavior defined in the OneLink base configuration, but the attribution will not work.
  • 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 (for example, 10m, 20h, 14d).
  • You can send an update request to specify the TTL. Any update request resets the TTL (for existing links) to the one specified in the request body.
    • This means the TTL is replaced. For example, if you make an update call with TTL 2d for a link that currently has TTL 29d, it will change to TTL=2d (not 31d).
    • An update call can potentially extend the life of the attribution link. For example, if you make an update call with TTL 31d for a link that currently has TTL 20d but 5 days have passed, the TTL will be 31d from the time of the update.

Special characters

 The following characters must be encoded if used for API created links: ;, , !, @, #, ?, $, ^, :, &, ~, `, =, +, ’, >, <, /
If you don't encode these characters, they are replaced with a blank space.

 

Was this article helpful?

Articles in this section

Related articles