Campaign APIs

Base URL

https://api.linkrunner.io/api/v1

Authentication

All API requests require authentication using an API key. You must include this key in the header of every request.

API Key Header

Include the following header in all API requests:

linkrunner-key: YOUR_API_KEY

Replace YOUR_API_KEY with your actual API key.

Obtaining Your API Key

You can find your API key on the Linkrunner settings page:

Go to https://www.linkrunner.io/settings?s=data-apis
Locate your Server key on this page
Use this key in the linkrunner-key header for all API requests

Keep your API key confidential. Do not share it or expose it in client-side code. Always make API requests from a secure server-side environment.

Error Responses

401 Unauthorized
- "Server key missing!"
- "Server key invalid!"
429 Too Many Requests
Message: "Rate limit exceeded. Please try again later."
Cause: You’ve exceeded the rate limit of 10 requests per second.

Rate Limit Details

Rate: 10 requests per second
Status code on limit exceeded: 429 (Too Many Requests)

Endpoints

1. List Campaigns

For getting/listing existing campaigns, please refer to the List Campaigns API documentation.

2. Create Campaign

Create a new campaign. You can optionally create a short link by including the is_shortlink: true parameter.

Request

POST /create-campaign

Request Body Examples

Creating Campaign:

{
    "name": "Summer Sale 2023",
    "deeplink": "https://app.domain.com/promo/summer25",
    "link_for_desktop_users": "https://www.your-website.com",
    "custom_display_id": "summer-sale-2025",
    "is_shortlink": false //pass this as true to create a shortened campaign link
}

Request Parameters

Parameter	Type	Required	Description
`name`	string	Yes	The display name of your campaign. This helps you identify the campaign in your dashboard.
`deeplink`	string	No	The URL that mobile app users will be directed to when they click your campaign link. Should be a valid deep link URL for your mobile application.
`link_for_desktop_users`	string	No	The fallback URL for desktop users who click your campaign link. Typically points to your website or web application.
`android_web_redirect`	string	No	Provide this only if you want the user to be explicitly redirected to a specific web URL on Android.
`ios_web_redirect`	string	No	Provide this only if you want the user to be explicitly redirected to a specific web URL on iOS.
`custom_display_id`	string	No	A custom identifier for your campaign. Must be unique across your account. If not provided, a random ID will be generated.
`is_shortlink`	boolean	No	Set to `true` to create a shortened campaign link. When enabled, creates a compact URL format suitable for sharing.

Note: If `android_web_redirect` or `ios_web_redirect` is provided, it will override the default store listing link for that platform within the campaign and redirect users to the specified URL instead.

Response

Standard Campaign Response:

{
    "msg": "Campaign created successfully!",
    "status": 201,
    "data": {
        "id": 123,
        "name": "Summer Sale 2023",
        "link": "https://lr-dev.subbox.in/promo/summer25?c=summer-sale-2025",
        "website": "https://www.your-website.com",
        "display_id": "summer-sale-2025",
        "created_at": "2023-05-01T12:00:00Z"
    }
}

Short Link Campaign Response:

{
    "msg": "Campaign created successfully!",
    "status": 201,
    "data": {
        "id": 124,
        "name": "Spring Launch 2024",
        "link": "https://app.domain.com/?c=spring-launch-2024",
        "website": "https://www.your-website.com",
        "display_id": "spring-launch-2024",
        "created_at": "2023-05-01T12:00:00Z"
    }
}

Response Properties

Property	Type	Description
`id`	number	Unique numerical identifier for the campaign in the system.
`name`	string	The campaign name as provided in the request.
`link`	string	The generated shareable campaign URL. For short links, this will be in format `https://app.domain.com/?c={display_id}`.
`website`	string\|null	The desktop fallback URL. Will be `null` for short link campaigns.
`display_id`	string	The campaign’s display identifier (custom or auto-generated).
`created_at`	string	ISO 8601 timestamp of when the campaign was created.

3. Edit Campaign

Update an existing campaign.

Request

PATCH /api/v1/campaigns/:display_id

Request Body

{
    "name": "campaign name",
    "active": false
}

Parameter	Type	Description
name	string	Optional. Name of the campaign
active	boolean	Optional. Campaign status

Responses

200 Campaign updated successfully
400 Invalid request parameters
404 Campaign not found
500 Internal server error

Success Response

{
    "msg": "Campaign updated successfully!",
    "status": 200,
    "data": {
        "display_id": "TOhmGM",
        "name": "campaign name",
        "created_at": "2025-07-09T17:18:41.912Z",
        "update_at": "2025-07-17T08:58:26.740Z",
        "google": false,
        "meta": false,
        "meta_campaign_id": "",
        "meta_web_to_app": false,
        "active": false,
        "default_link": true,
        "attributed_users": 0
    }
}

Error Responses

HTTP Status	Message	When/Why
400	”Campaign display ID is required!”	If the display_id param is missing
400	”At least one field (name or active) is required for update!”	If both name and active are missing in the request body
400	”Campaign name cannot be empty!”	If name is provided but is empty or only whitespace
400	”Active field must be a boolean!”	If active is provided but is not a boolean
404	”Campaign not found!”	If the campaign with the given display_id does not exist
500	”Internal server error”

4. Delete Campaign

Delete an existing campaign.

Request

DELETE /api/v1/campaigns/:display_id

Responses

204 Campaign deleted successfully
400 Invalid request parameters
404 Campaign not found
500 Internal server error

Success Response

{
    "msg": "Campaign deleted successfully!",
    "status": 204
}

Error Responses

HTTP Status	Message	When/Why
400	”Campaign display ID is required!”	If the display_id param is missing
404	”Campaign not found!”	If the campaign with the given display_id does not exist
500	”Internal server error”

Best Practices

Campaign naming: Use descriptive names that identify the purpose of the campaign
Deep links: Ensure your deep links are properly formatted and lead to valid destinations
Custom IDs: Use meaningful custom display IDs that are easy to recognize and remember. Duplicate ids are not allowed!
Desktop links: Provide a link_for_desktop_users URL to ensure desktop visitors are redirected to a relevant webpage instead of app stores.

Examples

Creating a New Campaign

fetch("https://api.linkrunner.io/api/v1/create-campaign", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "linkrunner-key": "YOUR-SERVER-KEY",
    },
    body: JSON.stringify({
        name: "Product Launch 2023",
        deeplink: "https://app.domain.com/promo/summer25",
        link_for_desktop_users: "https://www.your-website.com",
        custom_display_id: "summer-sale-2025",
    }),
})
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));

Editing a Campaign

fetch("https://api.linkrunner.io/api/v1/campaigns/TOhmGM", {
    method: "PUT",
    headers: {
        "Content-Type": "application/json",
        "linkrunner-key": "YOUR-SERVER-KEY",
    },
    body: JSON.stringify({
        name: "Updated Campaign Name",
        active: true,
    }),
})
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));

Deleting a Campaign

fetch("https://api.linkrunner.io/api/v1/campaigns/TOhmGM", {
    method: "DELETE",
    headers: {
        "linkrunner-key": "YOUR-SERVER-KEY",
    },
})
    .then((response) => response.json())
    .then((data) => console.log(data))
    .catch((error) => console.error("Error:", error));

Error Handling

The API will return appropriate HTTP status codes along with error messages when issues occur. Common errors across all endpoints include:

400 Bad Request: Missing required parameters or invalid input
401 Unauthorized: API key is required or invalid
404 Not Found: Campaign not found
429 Too Many Requests: You’ve exceeded the rate limit, please try again later
500 Internal Server Error: Contact support if this persists

Specific error responses for each endpoint are detailed in their respective sections above. For any help please reach out to darshil@linkrunner.io

Getting Started

SDK Documentation

API Documentation

Ad Network Integration

Features

Base URL

Authentication

API Key Header

Obtaining Your API Key

Error Responses

Rate Limit Details

Endpoints

1. List Campaigns

2. Create Campaign

Request

Request Body Examples

Request Parameters

Note: If `android_web_redirect` or `ios_web_redirect` is provided, it will override the default store listing link for that platform within the campaign and redirect users to the specified URL instead.

Response

Response Properties

3. Edit Campaign

Request

Request Body

Responses

Success Response

Error Responses

4. Delete Campaign

Request

Responses

Success Response

Error Responses

Best Practices

Examples

Creating a New Campaign

Editing a Campaign

Deleting a Campaign

Error Handling

Getting Started

SDK Documentation

API Documentation

Ad Network Integration

Features

​Base URL

​Authentication

​API Key Header

​Obtaining Your API Key

​Error Responses

​Rate Limit Details

​Endpoints

​1. List Campaigns

​2. Create Campaign

​Request

​Request Body Examples

​Request Parameters

Note: If android_web_redirect or ios_web_redirect is provided, it will override the default store listing link for that platform within the campaign and redirect users to the specified URL instead.

​Response

​Response Properties

​3. Edit Campaign

​Request

​Request Body

​Responses

​Success Response

​Error Responses

​4. Delete Campaign

​Request

​Responses

​Success Response

​Error Responses

​Best Practices

​Examples

​Creating a New Campaign

​Editing a Campaign

​Deleting a Campaign

​Error Handling

Base URL

Authentication

API Key Header

Obtaining Your API Key

Error Responses

Rate Limit Details

Endpoints

1. List Campaigns

2. Create Campaign

Request

Request Body Examples

Request Parameters

Note: If `android_web_redirect` or `ios_web_redirect` is provided, it will override the default store listing link for that platform within the campaign and redirect users to the specified URL instead.

Response

Response Properties

3. Edit Campaign

Request

Request Body

Responses

Success Response

Error Responses

4. Delete Campaign

Request

Responses

Success Response

Error Responses

Best Practices

Examples

Creating a New Campaign

Editing a Campaign

Deleting a Campaign

Error Handling