API Documentation | LinksTest

Create Test (Async)

URL: https://linkstest.com/api/tests
Method: POST
Auth: Api-Key header

⚠️ API Access Required: Your account must be on an API-enabled plan to use this endpoint.

Queue processing: Tests are accepted immediately and completed asynchronously by the LinksTest background worker.

Request Parameters

Parameter	Type	Description	Required
url	string	URL to test	Required
country	string	2-letter ISO country code	Required
device	string	Preferred OS/device field. Examples: "Android", "iOS", "Mac", "Windows"	Required*
os	string	Optional alias for `device`. If provided, it overrides `device`.	Optional
version	string	Optional OS version hint	Optional
city	string	Optional city override	Optional
referrer	string	Optional referrer URL sent with the test request	Optional

* The request must include either device or os.

Request Body

{
  "test": {
    "url": "http://example.com/test",
    "country": "us",
    "device": "Android"
  }
}

Response — Queued

{
  "status": "pending",
  "test_id": "uuid",
  "credits_remaining": 987
}

Check Test Status

URL: https://linkstest.com/api/tests/{test_id}
Method: GET
Auth: Api-Key header

Status Response — Success

{
  "status": "success",
  "test_id": "uuid",
  "result": {
    "result": "success",
        "testId": "uuid",
    "test_id": "uuid",
    "data": {
      "init": {
        "url": "http://example.com/test",
        "os": "Android",
        "country": "us",
        "version": "",
        "city": ""
      },
      "hops": [
        {
          "from": "https://example.com/initial",
                    "to": "https://tracker.example.com/redirect1",
                    "status": 302,
                    "domain": "example.com",
                    "hidden_domain": "store.example.com",
                    "hidden_url": "https://store.example.com/app?id=123",
                    "masking_via": "params/path decode",
                    "is_masking": true
        }
            ],
            "parallel_events": [],
            "final_destination_candidates": [
                {
                    "to": "https://play.google.com/store/apps/details?id=com.example.app"
                }
            ],
            "primary_destination": {
                "to": "https://play.google.com/store/apps/details?id=com.example.app"
            },
            "summary": {
                "total_events": 1,
                "events_by_type": {
                    "http_redirect": 1,
                    "javascript_redirect": 0,
                    "parallel_request": 0,
                    "decoded_deeplink": 0
                }
            },
            "final_url": "https://play.google.com/store/apps/details?id=com.example.app"
    }
  },
  "credits_remaining": 987
}

Status Response — Pending

{
    "status": "pending",
    "test_id": "uuid",
    "credits_remaining": 987
}

Status Response — Failure

{
    "status": "failure",
    "test_id": "uuid",
    "error": "Test failed",
    "credits_remaining": 987
}

Code Examples

PHP

$url = 'https://linkstest.com/api/tests';
$apiKey = 'your_api_key_here';

$data = [
    'test' => [
        'url' => 'http://example.com/test',
        'country' => 'us',
        'device' => 'Android',
        'referrer' => 'https://example.com/'
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'Api-Key: ' . $apiKey
]);

$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
echo $response;

// Poll for result
if (!empty($result['test_id'])) {
    $statusUrl = 'https://linkstest.com/api/tests/' . $result['test_id'];
    for ($i = 0; $i < 20; $i++) {
        sleep(2);
        $ch = curl_init($statusUrl);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, ['Api-Key: ' . $apiKey]);
        $statusResponse = curl_exec($ch);
        curl_close($ch);

        echo $statusResponse;
        $status = json_decode($statusResponse, true);
        if (in_array($status['status'] ?? '', ['success', 'failure'], true)) {
            break;
        }
    }
}

Python

import requests, json, time

url = 'https://linkstest.com/api/tests'
api_key = 'your_api_key_here'
headers = {'Content-Type': 'application/json', 'Api-Key': api_key}
data = {'test': {'url': 'http://example.com/test', 'country': 'us', 'device': 'Android', 'referrer': 'https://example.com/'}}

try:
    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    result = response.json()
    print(json.dumps(result, indent=2))

    test_id = result.get('test_id')
    if test_id:
        status_url = f'https://linkstest.com/api/tests/{test_id}'
        for _ in range(20):
            time.sleep(2)
            status_resp = requests.get(status_url, headers={'Api-Key': api_key})
            print(status_resp.text)
            status_data = status_resp.json()
            if status_data.get('status') in ('success', 'failure'):
                break
except requests.exceptions.RequestException as e:
    print(f'Error: {e}')

Node.js

const fetch = require('node-fetch');

const url = 'https://linkstest.com/api/tests';
const apiKey = 'your_api_key_here';
const data = { test: { url: 'http://example.com/test', country: 'us', device: 'Android', referrer: 'https://example.com/' } };

fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', 'Api-Key': apiKey },
    body: JSON.stringify(data)
})
.then(r => r.json())
.then(async result => {
    console.log(JSON.stringify(result, null, 2));
    if (result.test_id) {
        const statusUrl = `https://linkstest.com/api/tests/${result.test_id}`;
        for (let i = 0; i < 20; i++) {
            await new Promise(r => setTimeout(r, 2000));
            const s = await fetch(statusUrl, { headers: { 'Api-Key': apiKey } });
            const payload = await s.json();
            console.log(JSON.stringify(payload, null, 2));
            if (payload.status === 'success' || payload.status === 'failure') {
                break;
            }
        }
    }
})
.catch(err => console.error('Error:', err));

💡 Tip: Replace 'your_api_key_here' with your actual API key found in your LinksTest account settings.

Common Errors

Error	Status	Description
Invalid or missing API Key	401	Authentication failed
Insufficient credits	401	Not enough credits for this request
API access not enabled	403	Current plan does not include API access
Missing required fields	400	Every test must include `url`, `country`, and either `device` or `os`
Missing test_id	400	Status endpoint was called without a test ID
Test not found	404	Invalid test_id when checking status
Method not allowed	405	HTTP method not supported for this endpoint
Endpoint not found	404	The requested endpoint does not exist