Deferred Deep Linking

Kumulos has a RESTful API that allows you to create deferred deep links from any other backend system.

Headers

Please ensure that you set the following headers in your request:

Content-Type: application/json
Accept: application/json

Authentication

The Kumulos Messaging API authenticates other back-end services via HTTP Basic Auth using your app's API Key as the username and your Server Key as the password (in the Authorization header). Both of these are available from the App Dashboard in your Agency Console.

Creating Deferred Deep Links

POST https://links.kumulos.com/v1/deep-links

You can create upto 500 deferred deep links per API request.

Payload

[{
  linkData: {
    Required, an object of arbitrary data about this deep link that will be returned to your app when the deep link is matched.
  }
  desktopWebFallbackUrl: Required, a fallback url for the landing page when consuming a deferred deep link, allowing the user to view the content without installing the app.
  mobileWebFallbackUrl: Required, a mobile friendly fallback url for the landing page when consuming a deferred deep link, allowing the user to view the content without installing the app.
  slug: Optional, the url path to use for the deeplink, if provided this must be globally unique for your app, if not provided Kumulos will generate one.
  content: { Optional
    title: Optional, used as the title used on the jump page.
    description: Optional, used to provide context on the jump page
    imageUrl: Optional, used to provide a card image if the deep link is distributed via social media
  }
  reportingMeta: {
    Optional object of arbitrary meta-data about this deep link
  }
  expiresAt: Optional, datetime that the link will expire at, this should be provided in UTC time or with its UTC offset in the ISO 8601 format, for example 2020-10-27T07:00:00+00:00
  lookupLimit: Optional, number of times the link can be matched before being reported as having exceeded its limit.
  forceWebFallback: Optional, skip the landing page and redirect to the desktop or mobile fallback URL instead.
}]

imageUrl for social media cards should be at least 600px wide, however the exact dimensions vary by platform. e.g. Facebook require a minimum of 200x200px

Expiry and limits will both still allow users to follow the link and download your app, but will be reported to the SDK as either expired or limit exceeded so that your app can handle this.

Sample cURL

curl -X POST
    -H "Content-Type: application/json"
    -H "Accept: application/json"
    -u API_KEY:SERVER_KEY
    -d '[{
  "slug": "my-deep-link",
  "linkData": {"my":"data"},
  "desktopWebFallbackUrl": "https://www.kumulos.com/my-deep-link",
  "mobileWebFallbackUrl": "https://m.kumulos.com/my-deep-link"
},{
  "linkData": {"key":"value"},
  "desktopWebFallbackUrl": "https://www.kumulos.com/deep-link-2",
  "mobileWebFallbackUrl": "https://m.kumulos.com/deep-link-2"
}]' "http://links.kumulos.com/v1/deep-links"

Responses

401 Unauthorized

Your request was rejected because the authorization header was not provided or poorly formed. Check your API Key, Server Key and that you have followed the HTTP Basic authentication strategy.

422 Unprocessable Entity

Your request was either unparsable / invalid JSON, was missing required fields, or had provided invalid values for a given key.

The response body will return a JSON object describing what keys were not present or had invalid values.

200 OK

Your request was accepted and processed.

The response body will contain a JSON array reflecting each deep link that was created as a result.

[
  {
    "id": 1,
    "url": "https://deeplinks.lnk.click/my-deep-link"
  },
  {
    "id": 2,
    "url": "https://deeplinks.lnk.click/6b06b0153d291512fdc5bbc8f6e64e86"
  }
]

Reporting Meta-Data

When creating a deep link, you may wish to associate meaningful meta-data with it. This meta-data will be reflected in the data field of any events generated as a result a user's interaction with the link.

For example, if you wanted to send a campaign identifier, you could add the following to the request:

{
  ...
  "reportingMeta": {
    "campaign": "Summer Promotion"
  }
}