OneLink API

Premium
For:
Last update:

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.

The amount of OneLink API queries you can make is limited depending on your account type. You can see how many queries you made and how many you have left, in the OneLink API dashboard. 

You can contact your CSM to increase the API query limit.  

Setup

To set up OneLink API:

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

  3. Copy the OneLink API token. For security, an "Admin" user needs to retrieve the token; account users do not have access. 
  4. Give the OneLink ID and the OneLink API token to the developer.
  5. Tell the developer to follow the instructions in the dev hub.

Dashboard

The OneLink API dashboard displays your daily, monthly, and three-month API usage. 

To view the OneLink API dashboard: 

In AppsFlyer, from the side menu, select Engage > OneLink API.

Traits and limitations

Trait

Remarks

API quota limit
  • The limit for using the OneLink API to create, edit, or delete OneLink links is 7.5 million per month (UTC timezone), per account.
  • All requests that are made after exceeding this quota are not served, and the links are not created; the API call receives error status code 429 with the message "Monthly quota exceeded".
  • Information regarding how much of the rate quota is used/remains is displayed in the OneLink API dashboard. 

Rate limit
  • The API rate limit per account is 500 requests per second (30000 per minute).
  • All requests that are made exceeding 500 requests per second (30000 per minute) are not served, and the links are not created; the API call receives error status code 429 with the message "Rate limit exceeded".

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

TTL 
  • The default time to live (TTL) for OneLink short URLs created via OneLink API is 31 days. It's extended by 31 days each time the link is clicked. Clicking on a link once the TTL expires still defaults to the behavior defined in the OneLink base configuration, but the attribution will not work.
    • It can take up to 48 hours for a OneLink short URL to be deleted after the TTL expires.
  • Maximum TTL is 31 days. Any TTL value larger than 31 is overridden with the default TTL of 31.
  • You can change the default TTL by adding the parameter ttl={value} and specifying how many days, hours, or minutes. For example ttl=7d, ttl=12h, or ttl=10m.
  • 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.
  • If you don't want link TTLs to automatically extend, add the parameter renew_ttl=false to your links. The value for this parameter is boolean, either true (default) or false.
  • The parameter renew_ttl doesn't display on the actual URL.

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, and the link and its functionality could potentially break.


Note: The following 3 parameters will not be decoded when the link is clicked and will remain encoded:

  • af_dp
  • deep_link_value
  • deep_link_sub1

Payload

Query string from the payload can't exceed 2,048 characters. 

URL ID

The URL ID (or shortlink ID) can be edited to highlight your campaign offering. For example: https://myapp.onelink.me/abc123/apples. The URL ID must not exceed 50 characters and can be a combination of letters and numbers. By default, it is 8 characters.

Note:

  • You can only edit the URL ID if the current ID isn't already in use.
  • If the URL ID is already in use, link creation fails and returns an error response (400). You and your developer need to decide and configure what happens in such an event.
  • The failed call still counts toward your monthly API quota.