Publisher API Integration

Step 1: Account Creation and Configuration

Create an account with us at https://www.playfull.com. After you’ve created an account, please let us know the email used to signup so that we can configure your account as an offerwall publisher.

Step 2: Dashboard Access

Once your account is set up, you can visit your dashboard at https://www.playfull.com/offerwall/dashboard to manage your offerwall settings.

Step 3: API Endpoints

Get Offers

Our offers consists of missions and quests. Quests are a group of missions that need to be completed.

GET https://<api-url>/offerwall/offers

Headers

Parameters

Response

{
  "statusCode": 200,
  "total": 1,
  "offset": 0,
  "limit": 20,
  "data": {
    "missions": [
      {
        "id": "6f2e9aa0-7031-4cfa-83a2-21dbbcee4a26",
        "title": "Sample offerwall mission",
        "description": "Mission description",
        "thumbnail": "...",
        "expirationDate": "2026-01-09T09:28:23.011Z",
        "previewUrl": "...",
        "trackingLink": "https://www.playfull.com/missions/<mission_id>?owid=<offerwall_id>",
        "payout": 0.16,
        "cap": 1000,
        "isActive": true,
        "operatingSystem": ["Web"],
        "geotargeting": {
          "countriesInclude": ["CA", "US"],
          "countriesExclude": []
        },
        "tags": ["Action"],
        "instructions": "",
        "requirements": "",
        "allowMultipleConversions": false
      }
    ],
    "quests": [
      {
        "id": "051966ef-ab41-4eb9-96a9-7b26020b999a",
        "name": "Sample Quest",
        "description": "Quest description",
        "thumbnail": "...",
        "expirationDate": "2026-01-09T09:28:23.007Z",
        "trackingLink": "https://www.playfull.com/quests/<quest_id>?owid=<offerwall_id>",
        "previewUrl": "...",
        "startCap": 500,
        "isActive": true,
        "operatingSystem": ["Web"],
        "tags": ["RPG", "Turn-based strategy"],
        "geotargeting": {
          "countriesInclude": [],
          "countriesExclude": []
        },
        "instructions": "",
        "requirements": "",
        "missions": [
          {
            "id": "c56395cd-2ef9-4308-a154-c1c31c734e13",
            "title": "Sample quest mission",
            "description": null,
            "payout": 0.4,
            "cap": null,
            "instructions": "",
            "requirements": "",
            "allowMultipleConversions": false
          }
        ]
      }
    ]
  }
}

Step 4: Tracking Link

We use tracking links to track users usage of our offerwall and to connect users with their conversions on the advertisers side. Tracking links can be retrieved from the Get Offers API and varies for missions and quests:

Mission tracking link: https://www.playfull.com/missions/<mission_id>?owid=<offerwall_id>

Quest tracking link: https://www.playfull.com/quests/<quest_id>?owid=<offerwall_id>

where owid will be prefilled with your offerwall ID.

We support the following parameters for tracking links:

*At least one of uid or clickid is required.

Step 5: Postback Configuration

Next, we will configure your postback for successful conversions. You will need to provide a postback URL for us to send a GET request to every time a conversion occurs. Your postback URL might look like this:

https://www.my_url.com?user_id={uid}&payout={payout}&mission_id={mission_id}&transaction_id={transaction_id}

By default, we support the following postback macros:

We also support the following legacy postback macros for those migrating from our old offerwall system:

IP Whitelisting

The postback will be sent from one of a set of static IP addresses that should be whitelisted on your server. We will provide you with the list of IP addresses during onboarding.

Postback Hashing

For additional security, we will provide a postback hash key for you to verify the validity of the postback. Below are instructions on how to verify the postback hash key:

Instructions for Calculating the Hash Key

1. Include all provided parameters and their values in the hash key calculation, except for the hash_key itself.
2. Order these parameter-value pairs alphabetically by parameter name (key).
3. Concatenate all pairs using an equals sign (=) between each key and value, and an ampersand (&) to separate each pair.
4. Append this string with another ampersand (&) followed by your API key.
5. Hash the entire resulting string using the SHA-1 algorithm. The resulting hash_key should be the one included in our postback.

Hash Key Calculation Example

1. Include all provided parameters and their values in the hash key calculation, except for the hash_key itself.

uid = user1234
payout = 1234
transaction_id = 102b20c6fe823536281e7515add26c
timestamp = 1615057106

2. Order these parameter-value pairs alphabetically by parameter name (key).

payout = 1234
timestamp = 1615057106
transaction_id = 102b20c6fe823536281e7515add26c
uid = user1234

3. Concatenate all pairs using an equals sign (=) between each key and value, and an ampersand (&) to separate each pair.

payout=1234&timestamp=1615057106&transaction_id=102b20c6fe823536281e7515add26c&uid=user1234

4. Append this string with another ampersand (&) followed by your API key.

API Key Example: 0f52fbb3dca243538ce80e33fcf4ad61

payout=1234&timestamp=1615057106&transaction_id=102b20c6fe823536281e7515add26c&uid=user1234&0f52fbb3dca243538ce80e33fcf4ad61

5. Hash the entire resulting string using the SHA-1 algorithm.

0e8bd720d5761d0441dc7fa74700019216e8cd0e

6. The resulting hash_key will be included as a separate parameter in the postback request.

GET https://www.my_url.com?payout=1234&timestamp=1615057106&transaction_id=102b20c6fe823536281e7515add26c&uid=user1234&hash_key=0e8bd720d5761d0441dc7fa74700019216e8cd0e