Deep Links API

The deep links API lets SDKs resolve routes, claim deferred deep links after app install, and retrieve basic app information. These endpoints are domain-resolved (no API key required) and use the /api/ path prefix.

Resolve a route

Look up a route by its prefix and optionally construct the full deep link path.

POST /api/path

Auth: None (hostname-resolved)

Request body:

{
  "prefix": "merchant",
  "token": "abc123"
}

Field	Required	Description
`prefix`	Yes	The route prefix (e.g. `merchant`, `product`)
`token`	No	Optional token appended to the path

Response 200:

{
  "route": {
    "prefix": "merchant",
    "name": "Merchant Link",
    "template": "generic"
  },
  "deep_link_path": "/merchant/abc123",
  "appspace": {
    "name": "My App",
    "slug": "my-app"
  }
}

Errors:

Status	Error
`400`	`Missing prefix`
`404`	`No app configured for this domain`
`404`	`Route not found`

Claim deferred link by token

After a user installs your app via a deep link, the SDK calls this endpoint to retrieve the original link destination. On Android, the token comes from the Play Store install referrer string, where it is stored as the tolk_token parameter (e.g. tolk_token=abc123).

GET /api/deferred/claim?token=abc123

Auth: None (hostname-resolved)

Query parameters:

Param	Required	Description
`token`	Yes	The referrer token from the Play Store install
`user_id`	No	Optional user ID for analytics attribution

Response 200:

{
  "deep_link_path": "/merchant/abc123",
  "appspace_id": "xyz"
}

If the claimed path is a referral link (/ref/<code>), the response includes referral data:

{
  "deep_link_path": "/ref/ABC123",
  "appspace_id": "xyz",
  "referrer_id": "user_456",
  "referral_code": "ABC123"
}

Errors:

Status	Error
`400`	`Missing token parameter`
`404`	`No matching deferred link found`

Send device signals

Update an existing deferred link record with client-side device signals. This improves fingerprint matching accuracy for iOS, where the Play Store referrer token is not available.

POST /api/deferred/signals

Auth: None (hostname-resolved)

Request body:

{
  "token": "abc123",
  "timezone": "America/New_York",
  "language": "en-US",
  "screen_width": 390,
  "screen_height": 844
}

Field	Required	Description
`token`	Yes	The deferred link token
`timezone`	No	IANA timezone name
`language`	No	BCP 47 language tag
`screen_width`	No	Screen width in logical pixels
`screen_height`	No	Screen height in logical pixels

Response 200:

{ "updated": true }

Claim deferred link by signals

Claim a deferred deep link using multi-signal fingerprint matching. Used by the iOS SDK, which cannot read the Play Store referrer token.

POST /api/deferred/claim-by-signals

Auth: None (hostname-resolved)

Request body:

{
  "appspace_id": "your_appspace_id",
  "timezone": "America/New_York",
  "language": "en-US",
  "screen_width": 390,
  "screen_height": 844
}

Field	Required	Description
`appspace_id`	Yes	Your Appspace ID
`timezone`	No	IANA timezone name
`language`	No	BCP 47 language tag
`screen_width`	No	Screen width in logical pixels
`screen_height`	No	Screen height in logical pixels

Response 200:

{
  "deep_link_path": "/merchant/abc123",
  "appspace_id": "xyz"
}

Referral data is included when applicable (same as token-based claiming).

Errors:

Status	Error
`400`	`Missing appspace_id`
`403`	`appspace_id does not match this domain`
`404`	`No matching deferred link found`

Get app info

Retrieve basic information about the app associated with the current domain. Used by SDKs to get store URLs without requiring an API key.

GET /api/app/info

Auth: None (hostname-resolved)

Response 200:

{
  "name": "My App",
  "slug": "my-app",
  "ios_app_store_url": "https://apps.apple.com/...",
  "android_play_store_url": "https://play.google.com/...",
  "web_fallback_url": "https://myapp.com"
}

Errors:

Status	Error
`404`	`No app configured for this domain`

Retrieve smart banner configuration for the banner.js script. This is the endpoint that the website smart banner script calls automatically.

GET /api/banner/config

Auth: None (hostname-resolved)

Query parameters:

Param	Required	Description
`user_id`	No	Enables segment-targeted banner filtering

Response 200:

{
  "enabled": true,
  "app_name": "My App",
  "app_icon": "https://...",
  "install_url": "/install",
  "banners": [
    {
      "id": "banner_id",
      "label": "summer-promo",
      "title": "Download the app",
      "body": "Get 20% off your first order",
      "action_url": "https://example.com/download",
      "cta_text": "Get the App",
      "background_color": "#ffffff",
      "text_color": "#000000",
      "position": "top",
      "dismiss_days": 7,
      "priority": 10
    }
  ]
}

If the Appspace is not found or banners fail to load: { "enabled": false, "banners": [] }.

Deep Links API

Resolve a route

Claim deferred link by token

Send device signals

Claim deferred link by signals

Get app info

Get banner config