Resolve a mobile open

curl --request POST \
  --url https://biq.li/api/v1/track/open \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Biq-Request-Id: <x-biq-request-id>' \
  --header 'X-Biq-SDK: <x-biq-sdk>' \
  --header 'X-Biq-SDK-Version: <x-biq-sdk-version>' \
  --data '
{
  "eventId": "<string>",
  "appId": "<string>",
  "appInstanceId": "<string>",
  "firstOpen": true,
  "probabilisticAllowed": true,
  "sdkVersion": "<string>",
  "handoffToken": "<string>",
  "deepLink": "<string>",
  "domain": "<string>",
  "appVersion": "<string>",
  "osVersion": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "attestation": {}
}
'

import requests

url = "https://biq.li/api/v1/track/open"

payload = {
    "eventId": "<string>",
    "appId": "<string>",
    "appInstanceId": "<string>",
    "firstOpen": True,
    "probabilisticAllowed": True,
    "sdkVersion": "<string>",
    "handoffToken": "<string>",
    "deepLink": "<string>",
    "domain": "<string>",
    "appVersion": "<string>",
    "osVersion": "<string>",
    "occurredAt": "2023-11-07T05:31:56Z",
    "attestation": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-Biq-SDK": "<x-biq-sdk>",
    "X-Biq-SDK-Version": "<x-biq-sdk-version>",
    "X-Biq-Request-Id": "<x-biq-request-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-Biq-SDK': '<x-biq-sdk>',
    'X-Biq-SDK-Version': '<x-biq-sdk-version>',
    'X-Biq-Request-Id': '<x-biq-request-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    eventId: '<string>',
    appId: '<string>',
    appInstanceId: '<string>',
    firstOpen: true,
    probabilisticAllowed: true,
    sdkVersion: '<string>',
    handoffToken: '<string>',
    deepLink: '<string>',
    domain: '<string>',
    appVersion: '<string>',
    osVersion: '<string>',
    occurredAt: '2023-11-07T05:31:56Z',
    attestation: {}
  })
};

fetch('https://biq.li/api/v1/track/open', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/track/open",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventId' => '<string>',
    'appId' => '<string>',
    'appInstanceId' => '<string>',
    'firstOpen' => true,
    'probabilisticAllowed' => true,
    'sdkVersion' => '<string>',
    'handoffToken' => '<string>',
    'deepLink' => '<string>',
    'domain' => '<string>',
    'appVersion' => '<string>',
    'osVersion' => '<string>',
    'occurredAt' => '2023-11-07T05:31:56Z',
    'attestation' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-Biq-Request-Id: <x-biq-request-id>",
    "X-Biq-SDK: <x-biq-sdk>",
    "X-Biq-SDK-Version: <x-biq-sdk-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://biq.li/api/v1/track/open"

	payload := strings.NewReader("{\n  \"eventId\": \"<string>\",\n  \"appId\": \"<string>\",\n  \"appInstanceId\": \"<string>\",\n  \"firstOpen\": true,\n  \"probabilisticAllowed\": true,\n  \"sdkVersion\": \"<string>\",\n  \"handoffToken\": \"<string>\",\n  \"deepLink\": \"<string>\",\n  \"domain\": \"<string>\",\n  \"appVersion\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"attestation\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-Biq-SDK", "<x-biq-sdk>")
	req.Header.Add("X-Biq-SDK-Version", "<x-biq-sdk-version>")
	req.Header.Add("X-Biq-Request-Id", "<x-biq-request-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/track/open")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-Biq-SDK", "<x-biq-sdk>")
  .header("X-Biq-SDK-Version", "<x-biq-sdk-version>")
  .header("X-Biq-Request-Id", "<x-biq-request-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventId\": \"<string>\",\n  \"appId\": \"<string>\",\n  \"appInstanceId\": \"<string>\",\n  \"firstOpen\": true,\n  \"probabilisticAllowed\": true,\n  \"sdkVersion\": \"<string>\",\n  \"handoffToken\": \"<string>\",\n  \"deepLink\": \"<string>\",\n  \"domain\": \"<string>\",\n  \"appVersion\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"attestation\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/track/open")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-Biq-SDK"] = '<x-biq-sdk>'
request["X-Biq-SDK-Version"] = '<x-biq-sdk-version>'
request["X-Biq-Request-Id"] = '<x-biq-request-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventId\": \"<string>\",\n  \"appId\": \"<string>\",\n  \"appInstanceId\": \"<string>\",\n  \"firstOpen\": true,\n  \"probabilisticAllowed\": true,\n  \"sdkVersion\": \"<string>\",\n  \"handoffToken\": \"<string>\",\n  \"deepLink\": \"<string>\",\n  \"domain\": \"<string>\",\n  \"appVersion\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"attestation\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "open": {
    "id": "<string>",
    "firstOpen": true,
    "matchedBy": "exact_app_link",
    "confidence": "exact"
  },
  "click": {
    "id": "<string>"
  },
  "link": {
    "id": "<string>",
    "shortUrl": "<string>",
    "route": "<string>"
  },
  "attribution": {
    "referralCode": "<string>",
    "metadata": {},
    "dynamic": {}
  },
  "attributionReceipt": "<string>",
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

POST

track

open

Resolve a mobile open

curl --request POST \
  --url https://biq.li/api/v1/track/open \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'X-Biq-Request-Id: <x-biq-request-id>' \
  --header 'X-Biq-SDK: <x-biq-sdk>' \
  --header 'X-Biq-SDK-Version: <x-biq-sdk-version>' \
  --data '
{
  "eventId": "<string>",
  "appId": "<string>",
  "appInstanceId": "<string>",
  "firstOpen": true,
  "probabilisticAllowed": true,
  "sdkVersion": "<string>",
  "handoffToken": "<string>",
  "deepLink": "<string>",
  "domain": "<string>",
  "appVersion": "<string>",
  "osVersion": "<string>",
  "occurredAt": "2023-11-07T05:31:56Z",
  "attestation": {}
}
'

import requests

url = "https://biq.li/api/v1/track/open"

payload = {
    "eventId": "<string>",
    "appId": "<string>",
    "appInstanceId": "<string>",
    "firstOpen": True,
    "probabilisticAllowed": True,
    "sdkVersion": "<string>",
    "handoffToken": "<string>",
    "deepLink": "<string>",
    "domain": "<string>",
    "appVersion": "<string>",
    "osVersion": "<string>",
    "occurredAt": "2023-11-07T05:31:56Z",
    "attestation": {}
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "X-Biq-SDK": "<x-biq-sdk>",
    "X-Biq-SDK-Version": "<x-biq-sdk-version>",
    "X-Biq-Request-Id": "<x-biq-request-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'X-Biq-SDK': '<x-biq-sdk>',
    'X-Biq-SDK-Version': '<x-biq-sdk-version>',
    'X-Biq-Request-Id': '<x-biq-request-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    eventId: '<string>',
    appId: '<string>',
    appInstanceId: '<string>',
    firstOpen: true,
    probabilisticAllowed: true,
    sdkVersion: '<string>',
    handoffToken: '<string>',
    deepLink: '<string>',
    domain: '<string>',
    appVersion: '<string>',
    osVersion: '<string>',
    occurredAt: '2023-11-07T05:31:56Z',
    attestation: {}
  })
};

fetch('https://biq.li/api/v1/track/open', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://biq.li/api/v1/track/open",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventId' => '<string>',
    'appId' => '<string>',
    'appInstanceId' => '<string>',
    'firstOpen' => true,
    'probabilisticAllowed' => true,
    'sdkVersion' => '<string>',
    'handoffToken' => '<string>',
    'deepLink' => '<string>',
    'domain' => '<string>',
    'appVersion' => '<string>',
    'osVersion' => '<string>',
    'occurredAt' => '2023-11-07T05:31:56Z',
    'attestation' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "X-Biq-Request-Id: <x-biq-request-id>",
    "X-Biq-SDK: <x-biq-sdk>",
    "X-Biq-SDK-Version: <x-biq-sdk-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://biq.li/api/v1/track/open"

	payload := strings.NewReader("{\n  \"eventId\": \"<string>\",\n  \"appId\": \"<string>\",\n  \"appInstanceId\": \"<string>\",\n  \"firstOpen\": true,\n  \"probabilisticAllowed\": true,\n  \"sdkVersion\": \"<string>\",\n  \"handoffToken\": \"<string>\",\n  \"deepLink\": \"<string>\",\n  \"domain\": \"<string>\",\n  \"appVersion\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"attestation\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("X-Biq-SDK", "<x-biq-sdk>")
	req.Header.Add("X-Biq-SDK-Version", "<x-biq-sdk-version>")
	req.Header.Add("X-Biq-Request-Id", "<x-biq-request-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://biq.li/api/v1/track/open")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("X-Biq-SDK", "<x-biq-sdk>")
  .header("X-Biq-SDK-Version", "<x-biq-sdk-version>")
  .header("X-Biq-Request-Id", "<x-biq-request-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventId\": \"<string>\",\n  \"appId\": \"<string>\",\n  \"appInstanceId\": \"<string>\",\n  \"firstOpen\": true,\n  \"probabilisticAllowed\": true,\n  \"sdkVersion\": \"<string>\",\n  \"handoffToken\": \"<string>\",\n  \"deepLink\": \"<string>\",\n  \"domain\": \"<string>\",\n  \"appVersion\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"attestation\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://biq.li/api/v1/track/open")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["X-Biq-SDK"] = '<x-biq-sdk>'
request["X-Biq-SDK-Version"] = '<x-biq-sdk-version>'
request["X-Biq-Request-Id"] = '<x-biq-request-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventId\": \"<string>\",\n  \"appId\": \"<string>\",\n  \"appInstanceId\": \"<string>\",\n  \"firstOpen\": true,\n  \"probabilisticAllowed\": true,\n  \"sdkVersion\": \"<string>\",\n  \"handoffToken\": \"<string>\",\n  \"deepLink\": \"<string>\",\n  \"domain\": \"<string>\",\n  \"appVersion\": \"<string>\",\n  \"osVersion\": \"<string>\",\n  \"occurredAt\": \"2023-11-07T05:31:56Z\",\n  \"attestation\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "open": {
    "id": "<string>",
    "firstOpen": true,
    "matchedBy": "exact_app_link",
    "confidence": "exact"
  },
  "click": {
    "id": "<string>"
  },
  "link": {
    "id": "<string>",
    "shortUrl": "<string>",
    "route": "<string>"
  },
  "attribution": {
    "referralCode": "<string>",
    "metadata": {},
    "dynamic": {}
  },
  "attributionReceipt": "<string>",
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "<string>",
    "message": "<string>"
  },
  "requestId": "<string>"
}

{
  "error": {
    "code": "invalid_token",
    "message": "<string>",
    "details": {}
  },
  "request_id": "<string>"
}

Mobile-open resolution is in Public Beta. Use an official Biqli mobile SDK unless you need to implement the wire contract directly.

POST https://biq.li/api/v1/track/open resolves an iOS or Android open for one registered Mobile App. A successful response can contain an exact match, a probabilistic iOS match, or no match.

Authentication

Send the Mobile App’s public, app-scoped key:

Authorization: Bearer biqli_mobile_pk_your_public_mobile_key

Do not use a biqli_pk_... browser key or a biqli_... secret workspace API key. The key must belong to the appId in the body.

Required headers

Header	Constraint
`Authorization`	`Bearer` plus an active `biqli_mobile_pk_...` key.
`Content-Type`	`application/json`.
`Idempotency-Key`	From 8 to 100 letters, digits, `.`, `_`, `~`, or `-`. Reuse only with the identical canonical request.
`X-Biq-SDK`	Exactly `ios` or `android`; must match body `platform`.
`X-Biq-SDK-Version`	Non-empty string up to 32 characters; must match body `sdkVersion`.
`X-Biq-Request-Id`	From 8 to 100 letters, digits, `.`, `_`, `~`, or `-`. Returned in the response header and body.

The JSON body must be an object no larger than 16 KB and no deeper than 32 levels. Unknown fields are rejected.

Request body

Field	Type	Required	Constraint and meaning
`eventId`	string	Yes	Stable event ID, 8–100 safe identifier characters.
`appId`	string	Yes	Mobile App ID, up to 40 characters, belonging to the mobile key.
`appInstanceId`	string	Yes	Stable random ID for this installation, 16–128 safe identifier characters. Do not use a user or advertising ID.
`platform`	string	Yes	`ios` or `android`; that platform must be configured on the Mobile App.
`firstOpen`	boolean	Yes	Whether this is an eligible first-install resolution attempt.
`probabilisticAllowed`	boolean	Yes	Explicitly allow probabilistic evaluation. Valid only for an iOS request with an eligible verified `domain`.
`handoffToken`	string or null	No	Opaque `bqmh_...` handoff, up to 128 characters. Do not log it.
`deepLink`	string or null	No	HTTPS Biqli short URL, up to 2,048 characters. It must use an attached verified domain and one-segment link path to match. Credentials and fragments are not eligible.
`domain`	string or null	Conditional	Hostname up to 255 characters. Required for probabilistic matching; it must be verified, HTTPS-active, and attached to the iOS app.
`appVersion`	string or null	No	Application version, up to 32 characters.
`osVersion`	string or null	No	Operating-system version, up to 32 characters. Used as part of eligible probabilistic comparison.
`sdkVersion`	string	Yes	SDK version, up to 32 characters; must equal `X-Biq-SDK-Version`.
`occurredAt`	ISO 8601 date-time or null	No	Client-observed event time for diagnostics. Server receipt time controls matching.
`attestation`	object or array or null	No	Reserved for future use. It is not currently enforced and does not enable App Attest or Play Integrity validation.

The current official SDKs send no attestation value. Do not advertise device-attestation enforcement until Biqli documents an active contract.

Example request

curl --request POST \
  --url https://biq.li/api/v1/track/open \
  --header "Authorization: Bearer $BIQLI_MOBILE_PUBLISHABLE_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: open_0e7cb12b4ecb4bc4a192de5578ec0139' \
  --header 'X-Biq-SDK: android' \
  --header 'X-Biq-SDK-Version: 1.0.0' \
  --header 'X-Biq-Request-Id: req_8d2cc6242a224f7aaf2c0c172f849f87' \
  --data '{
    "eventId": "open_0e7cb12b4ecb4bc4a192de5578ec0139",
    "appId": "biq_mapp_01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "appInstanceId": "install_98261e74ceca42bc830282c8f6cfd02f",
    "platform": "android",
    "firstOpen": true,
    "probabilisticAllowed": false,
    "handoffToken": "bqmh_example_opaque_value_not_a_real_token",
    "deepLink": null,
    "domain": null,
    "appVersion": "2.4.0",
    "osVersion": "15",
    "sdkVersion": "1.0.0",
    "occurredAt": "2026-09-27T12:30:00Z"
  }'

Matched response

{
  "open": {
    "id": "biq_open_01ARZ3NDEKTSV4RRFFQ69G5FAW",
    "firstOpen": true,
    "matchedBy": "exact_install_referrer",
    "confidence": "exact"
  },
  "click": {
    "id": "AbCdEf123456"
  },
  "link": {
    "id": "biq_lnk_01ARZ3NDEKTSV4RRFFQ69G5FAX",
    "shortUrl": "https://go.example.com/invite",
    "route": "/invite/accepted"
  },
  "attribution": {
    "referralCode": "PARTNER_42",
    "metadata": {
      "campaign": "spring_launch"
    },
    "dynamic": {
      "ref": "BOB"
    }
  },
  "attributionReceipt": "eyJhbGciOiJFZERTQSIsImtpZCI6ImV4YW1wbGUiLCJ0eXAiOiJKV1QifQ.example.signature",
  "requestId": "req_8d2cc6242a224f7aaf2c0c172f849f87"
}

No-match response

No match is a successful 200 response:

{
  "open": {
    "id": "biq_open_01ARZ3NDEKTSV4RRFFQ69G5FAY",
    "firstOpen": false,
    "matchedBy": "none",
    "confidence": "none"
  },
  "click": null,
  "link": null,
  "attribution": null,
  "attributionReceipt": null,
  "requestId": "req_5f36c66b57eb42e4a5f644235e59e6bd"
}

Matching behavior

`matchedBy`	Confidence	Source
`exact_app_link`	`exact`	Eligible installed-app HTTPS link.
`exact_install_referrer`	`exact`	Valid Android handoff supplied through Google Play.
`exact_handoff`	`exact`	Valid iOS Deep View handoff supplied by explicit paste.
`probabilistic`	`probabilistic`	One unambiguous eligible iOS first-open candidate.
`none`	`none`	No eligible match.

Exact handoff or App Link matching runs before probabilistic evaluation. If handoffToken and deepLink identify different links, the API returns 422 handoff_mismatch. For a matched first open, the first accepted install attribution is immutable. A later firstOpen: true request for the same app instance returns the original accepted result.

Idempotency

The endpoint de-duplicates within the Mobile App by either eventId or the hashed Idempotency-Key. Repeating either identifier with the identical validated request returns the stored result and creates no second open event. Reusing either identifier with different request data returns 409 idempotency_conflict. Persist the event ID, request ID, idempotency key, and complete body together before sending. A retry must not regenerate only part of that set.

Rate limits

Default one-minute limits are 3,000 requests per Mobile App, 120 per source address, 30 per app instance, and 20 per handoff token. Additional abuse protection applies to repeated invalid-token attempts. A 429 response includes Retry-After; wait at least that many seconds and retry with the same idempotent request.

Errors

Errors produced after the mobile resolver accepts the endpoint contain error.code, error.message, and requestId; the same safe request ID is returned in X-Biq-Request-Id. The method guard and unexpected-failure handler use the standard API envelope with request_id instead. Read either request-ID spelling when implementing a direct client.

Status	Code	Meaning
`400`	`invalid_request`	Body is not JSON, not an object, exceeds 16 KB, or exceeds supported JSON depth.
`400`	`invalid_headers`	An idempotency, SDK, SDK-version, or request-ID header is missing or invalid.
`401`	`invalid_mobile_key`	Mobile key is missing, invalid, revoked, or unavailable.
`403`	`mobile_linking_unavailable`	Mobile resolution is not currently available.
`403`	`mobile_sdk_unavailable`	The requested platform SDK is not currently available.
`404`	`resource_not_found`	The app ID does not belong to the mobile key or an exact resource is unavailable.
`409`	`idempotency_conflict`	An event or idempotency identity was reused with different data.
`422`	`validation_error`	A field is missing, malformed, out of bounds, or unknown.
`422`	`platform_not_configured`	The Mobile App does not contain this platform.
`422`	`header_mismatch`	Platform or SDK version differs between headers and body.
`422`	`invalid_probabilistic_domain`	Probabilistic matching lacks an eligible attached iOS domain.
`422`	`platform_mismatch`	The existing app instance is already registered to another platform.
`422`	`handoff_mismatch`	Handoff and deep link identify different links.
`429`	`rate_limited`	A mobile-open or abuse-protection bucket was exceeded. Honor `Retry-After`.
`405`	`method_not_allowed`	Use `POST`; other methods return `Allow: POST` rather than the application shell.
`500`	`internal_server_error`	An unexpected failure prevented resolution. Retry the identical idempotent request with bounded backoff.

Retry transport failures, 429, and 5xx with bounded backoff and the identical idempotent request. Correct other errors before retrying.

Receipts and caching

Matched live responses can include a short-lived signed receipt. Cached SDK results intentionally omit it. Verify a live receipt on a trusted backend by following Attribution receipts. Responses include Cache-Control: no-store and must not be stored by shared HTTP caches.

Authorizations

Authorization

string

header

required

A public app-scoped key beginning with biqli_mobile_pk_. It resolves mobile opens for one registered Mobile App and grants no workspace-management access.

Headers

Idempotency-Key

string

required

Stable identity for this exact request. Reuse only with the identical canonical body.

Required string length: 8 - 100

Pattern: ^[A-Za-z0-9._~-]+$

X-Biq-SDK

enum<string>

required

Native platform. Must equal the body platform.

Available options:

ios,

android

X-Biq-SDK-Version

string

required

SDK version. Must equal the body sdkVersion.

Required string length: 1 - 32

X-Biq-Request-Id

string

required

Caller-generated request identifier returned in the response.

Required string length: 8 - 100

Pattern: ^[A-Za-z0-9._~-]+$

Body

application/json

JSON object no larger than 16 KB and no deeper than 32 levels. Unknown fields are rejected.

eventId

string

required

Required string length: 8 - 100

Pattern: ^[A-Za-z0-9._~-]+$

appId

string

required

Mobile App ID belonging to the bearer key.

Maximum string length: 40

appInstanceId

string

required

Random stable identifier for this app installation.

Required string length: 16 - 128

Pattern: ^[A-Za-z0-9._~-]+$

platform

enum<string>

required

Available options:

ios,

android

firstOpen

boolean

required

probabilisticAllowed

boolean

required

Valid only for an eligible iOS first-open request with a verified attached domain.

sdkVersion

string

required

Required string length: 1 - 32

handoffToken

string | null

Opaque handoff token. Treat as sensitive and do not log.

Maximum string length: 128

deepLink

string<uri> | null

Eligible installed-app HTTPS short URL.

Maximum string length: 2048

domain

string | null

Required verified attached hostname for probabilistic matching.

Maximum string length: 255

appVersion

string | null

Maximum string length: 32

osVersion

string | null

Maximum string length: 32

occurredAt

string<date-time> | null

attestation

Reserved and not currently enforced.

Response

Resolution completed. A no-match result is also a successful response.

open

object

required

Show child attributes

click

object | null

required

Show child attributes

link

object | null

required

Show child attributes

attribution

object | null

required

Show child attributes

attributionReceipt

string | null

required

Short-lived Ed25519 JWT on eligible live matched responses. Cached SDK results omit it.

requestId

string

required

Required string length: 1 - 100

GETTING STARTED

SDKs

MOBILE ATTRIBUTION

BIQLI LINKS API

Resolve a mobile open

Authentication

Required headers

Request body

Example request

Matched response

No-match response

Matching behavior

Idempotency

Rate limits

Errors

Receipts and caching

Authorizations

Headers

Body

Response

​Authentication

​Required headers

​Request body

​Example request

​Matched response

​No-match response

​Matching behavior

​Idempotency

​Rate limits

​Errors

​Receipts and caching

Authorizations

Headers

Body

Response

Authentication

Required headers

Request body

Example request

Matched response

No-match response

Matching behavior

Idempotency

Rate limits

Errors

Receipts and caching