API

The API provides publishers with access to a list of available offers tailored to their app.

By integrating this API, publishers can seamlessly fetch and display these offers within their own user interface. This allows for the creation of fully native and personalised in-app experiences that align with the app’s design and user flow, enhancing user engagement and improving conversion rates.

Pre-approval from PubScale team is required for the offerwall integration. Please contact your account manager or reach out to support before starting this integration. Learn More

1. Authentication

In order to access offers API. Following Keys need to be generated.

1. Pub Key (Generated once per publisher)

2. App ID

App-ID

In order to generate an App ID follow this guide for instructions on how to set up your app. Once completed, you will receive a unique 8-digit App ID. This will be used as App ID to access the API.

Pub-Key

In order the generate a Pub-Key a pre-approval is required. This is a one time approval for a publisher. Please contact account manager for the same.

Go to the Settings > API Key section to get your Offerwall Pub-Key.

You can regenerate the Pub-Key by contacting your Account Manager. Once the Offerwall Pub-Key is regenerated, the existing Pub-Key will no longer be valid.

---

2. Offers API:

Description:

The API provides a list of offers available for your app, which can be used to display and run offers on your platform.

Offers are cached on our server and refreshed every 5 minutes. We recommend updating your inventory accordingly.

Endpoint:

POST https://api-ow.pubscale.com/v1/offer/api

Auth:

The keys generated in the previous steps must be included in the following headers when making API requests.

These are Mandatory for accessing the API.

• App-Id – The unique App ID generated for your app during the setup process.

• Pub-Key – The unique key generated for your publisher account during setup. This key is shared across all apps within the same account.

Example:

curl 'https://api-ow.pubscale.com/v1/offer/api' \
--header 'App-Id: <Your App ID>' \
--header 'Pub-Key: <Your Pub Key>' \
--header 'Content-Type: application/json' \
--data '{
    "page": 1,
    "size": 1000,
    "filt": [
        {
            "dim": "offer_type",
            "match": {
                "type": "any",
                "value": [
                    "CPI"
                ]
            }
        }
    ]
}'

Payload:

Body	Required	Type	Description
page	Required	Integer	The page field in the Offers API response indicates the current page number and should always be a positive integer.
size	Required	Integer	The size field in the Offers API response represents the number of offers returned in that response and should always be a positive integer.
filt	Optional	Array	Contains an array of filters to be applied to the Offers API request to refine the results based on specified criteria.
dim	Optional	String	Specifies the dimension on which the filter is applied. Supported values are offer_type, platform, and country.
match	Optional	Model	Contains details about the filter to be applied, including the values to filter by and the match type used for filtering.
type	Optional	String	Specifies the match type to be used for the filter. Supported values are any (matches any of the provided values) and exact (requires a single, exact value match).
values	Optional	Array	Contains the values to apply the filter on. Allowed values depend on the specified filter dimension.

Filter Values

Offer Type:

• CPR – Cost Per Registration

• CPI - Cost Per Install

• CPL – Cost Per Lead

• CPC – Cost Per Click

• CPE – Cost Per Engagement

• CPA – Cost Per Action

• APK_INSTALL – APK-based Install

• APK_REGISTER – APK-based Registration

Example Curl:

curl --location 'https://api-dev.sikkaapp.in/v1/offer/api' \
    --header 'App-Id: 77754913' \
    --header 'Pub-Key: 09DAE7FB5D9AA83582DE7703348D8087' \
    --header 'Content-Type: application/json' \
    --data '{
            "page": 1,
            "size": 1000,
            "filt": [
            {
                "dim": "offer_type",
                "match": {
                        "type": "any",
                        "value": [
                            "CPI","CPA"
                        ]
                }
            }
            ]
        }' -v

Platforms

• ios – Apple iOS platform

• android – Android platform

• web – Web-based platform

Example Curl:

curl --location 'https://api-dev.sikkaapp.in/v1/offer/api' \
    --header 'App-Id: 77754913' \
    --header 'Pub-Key: 09DAE7FB5D9AA83582DE7703348D8087' \
    --header 'Content-Type: application/json' \
    --data '{
            "page": 1,
            "size": 1000,
            "filt": [
            {
                "dim": "platform",
                "match": {
                        "type": "any",
                        "value": [
                            "web","ios","android"
                        ]
                }
            }
            ]
        }' -v

Country

• Countries must be specified using the standard ISO Alpha-2 country codes (e.g., US for United States, IN for India, FR for France).

Example Curl:

curl --location 'https://api-dev.sikkaapp.in/v1/offer/api' \
    --header 'App-Id: 77754913' \
    --header 'Pub-Key: 09DAE7FB5D9AA83582DE7703348D8087' \
    --header 'Content-Type: application/json' \
    --data '{
            "page": 1,
            "size": 1000,
            "filt": [
            {
                "dim": "country",
                "match": {
                        "type": "any",
                        "value": [
                            "IN","US"
                        ]
                }
            }
            ]
        }' -v

---

Example Response:

{
    "offers": [
        {
            "id": "973839",
            "upd_ts": 1745834294,
            "off_type": "CPI",
            "s_id": "nova.solitaire.patience.card.games.klondike.free",
            "name": "Classic Solitaire : Card Game",
            "lp_url": "https://play.google.com/store/apps/details?id=nova.solitaire.patience.card.games.klondike.free",
            "pyt": {
                "cur": "USD",
                "amt": 0.0325
            },
            "inapp_pyt": {
                "cur": "Bullets",
                "amt": 4.875
            }
            "crtvs": {
                "ic_url": "https://play-lh.googleusercontent.com/TIogtAtBq22AAHUK8q0nkXVi3KPPssCqIjp2J5JmLLuw8sdStdpeiRsPg1STEIo2ng"
            },
            "desc": {
                "raw": "Classic Solitaire : Card Game"
            },
            "ctg": [
                "SINGLE_STEP"
            ],
            "gls": [
                {
                    "id": "2710875",
                    "gl_val": null,
                    "ttl": "Complete Install and Use The App",
                    "instr": "1.Click on redeem now.\n2.Install the app.\n3.Use the app.\n4.Explore the app and enjoy.",
                    "pyt": {
                        "cur": "USD",
                        "amt": 0.0325
                    },
                    "inapp_pyt": {
                        "cur": "Bullets",
                        "amt": 4.875
                    },
                    "ord": 1
                }
            ],
            "trk_url": "https://api-ow.pubscale.com/v2/tracking/click?rid=2710875&app=77754913&user_id={your_user_id}&gaid={gaid_for_android}&idfa={idfa_for_ios}",
            "geo_tgt": {
                "include": [
                    "AT"
                ],
                "exclude": []
            },
            "os": "android",
            "metrics": [
                {
                    "m_type": "GLOBAL",
                    "cr": 80,
                    "epc": 23.87
                }
            ]
        }
    ],
    "total": 1931
}

Response Details

Field	Description
offers	An array containing the offer details. Each element represents an individual offer.
id	A unique identifier for the offer.
upd_ts	The timestamp when the offer was last updated (in UNIX timestamp format).
off_type	The type of offer (e.g., CPI for Cost Per Install, CPC for Cost Per Click, etc.).
s_id	The unique identifier for the app associated with the offer.
name	The name of the app or offer.
lp_url	The link to the landing page for the app (usually a store link).
pyt	Payment details for the offer. Contains cur (currency) and amt (amount).
inapp_pyt	Displays payout details in the application's currency, with cur representing the currency name and amt the amount, based on app settings.
crtvs	Creatives related to the offer. Contains ic_url (URL to the icon image).
desc	Description of the offer. Contains raw (raw description text).
ctg	Categories associated with the offer (e.g., SINGLE_STEP). Possible values: SINGLE_STEP, MULTI_REWARD, DEPOSIT, GAMING, FINANCE, SURVEY, NEW
gls	A list of goals for the offer. Each goal has id, gl_val (value), ttl (title), instr (instructions), and pyt (payment details) and inapp_yt(payment in apps currency).
trk_url	Tracking URL for tracking user actions like clicks or installs, with placeholders for dynamic user data.
geo_tgt	Geographical targeting information. Contains include (countries to include) and exclude (countries to exclude).
os	The operating system platform for the app (e.g., android, ios).
total	The total number of offers available (in this case, 1931 offers).
metrics	Contains performance metrics related to the offer, including CR (Conversion Rate) and EPC (Earnings Per Click). Currently, only global values are supported.

---

3. Click Parameters:

You can use the tracking link provided in the trk_url field of each offer in the API response to start sending click events to Pubscale. This tracking link is essential for monitoring user interactions and attributing tasks correctly.

Purpose

The trk_url is used to track clicks from users on a particular offer. When a user interacts with an offer, your app or system should trigger this URL with the appropriate parameters.

---

Supported Click Parameters

The following query parameters are supported for integration with the tracking URL:

Parameter	Required	Description
user_id	Manadatory	The unique identifier of the user who clicks on the offer. This will be included in the callback. Special characters aren't allowed except "_","@","-" and ".".
gaid	Recomended	Google Advertising ID (required for Android users).
idfa	Recomended	Identifier for Advertisers (required for iOS users).
c1-c5	Optional	Custom parameters can be appended to the tracking URL by the publisher and will be included in the callback for reference. Special characters aren't allowed except "_","@","-" and "."

4. Setup Server-to-Server(S2S) callbacks

This step is manadatory for rewarding users.

Set up the Server-to-Server (S2S) callbacks to receive instant updates whenever a user completes an offer and earns a reward. When an offer is completed, our server will send a notification to the configured callback URL. This callback provides the necessary information to process and verify the reward for the user in your application. Learn more.