List of Promotions

You can retrieve the list of Promotions associated with your account through the Aptoide Connect Developer Console or programmatically using this API endpoint.

Endpoint

Method	URL
GET	https://ws.catappult.io/api/promotions

Authentication

To access this API, you need to have an active account subscription on Aptoide Connect and authenticate with an API key (check here how to generate one).

Headers

Header	Type	Required	Description
Api-Key	string	Required	Used to authenticate your API requests. The value is your Aptoide Connect API key.

Query Parameters

Parameter	Type	Required	Description
type	string	Optional	Filters promotions by type (e.g. SEARCH).
applicationName	string	Optional	Filters promotions by the unique package name of the application (e.g. com.example.test).
partnerName	string	Optional	Filters promotions whose partner.name matches the given identifier (e.g. APTOIDE-GAMES). See List Available Partners for valid values.
startsAfter	string (date)	Optional	Returns only promotions whose startTimestamp is after the given date. Format: YYYY-MM-DD.
startsBefore	string (date)	Optional	Returns only promotions whose startTimestamp is before the given date. Format: YYYY-MM-DD.
endsAfter	string (date)	Optional	Returns only promotions whose endTimestamp is after the given date. Format: YYYY-MM-DD.
endsBefore	string (date)	Optional	Returns only promotions whose endTimestamp is before the given date. Format: YYYY-MM-DD.

Example Request

curl -X GET "https://ws.catappult.io/api/promotions" \
  -H "Api-Key: <YOUR_API_KEY>"

Response

Success

If the API call returns an HTTP 200 status code, the request was successful and it returns an array of promotion objects associated with the authenticated account.

When a promotion is linked to an Event (via eventUid), the event field contains an embedded representation of that event; otherwise it is null.

Example Response

[
  {
    "uid": "9dbf70ff-30a4-4d82-b062-42ab24126e59",
    "name": "Test Promotion 1",
    "type": "SEARCH",
    "status": "active",
    "startTimestamp": "2026-03-16 00:00:00",
    "endTimestamp": "2026-04-30 00:00:00",
    "createdAt": "2026-03-26 20:47:20",
    "updatedAt": "2026-04-01 14:23:34",
    "hasStatistics": false,
    "event": {
      "uid": "56fd535b-b071-402c-a4fa-29807eb050c9",
      "name": "Test Event",
      "type": "CUSTOM",
      "status": "active",
      "startTimestamp": "2026-02-04 00:30:00",
      "endTimestamp": "2026-04-30 00:00:00",
      "createdAt": "2026-02-05 16:06:33",
      "updatedAt": "2026-04-20 15:01:53",
      "allowedPartners": ["APTOIDE-GAMES"],
      "application": {
        "name": "com.aptoide.diceroll.sdk",
        "title": "Aptoide Diceroll SDK",
        "iconUrl": "https://ws.catappult.io/api/applications/com.aptoide.diceroll.sdk/icon",
        "featureGraphicUrl": "https://ws.catappult.io/api/applications/com.aptoide.diceroll.sdk/featureGraphic"
      },
      "data": {
        "allowedPartners": "APTOIDE-GAMES",
        "applySameFilesToAllLocales": "false"
      },
      "locales": [
        {
          "localeName": "en_GB",
          "description": "Test",
          "longDescription": "Test",
          "files": [
            {
              "id": 953,
              "name": "b737866e7065a09e02a8393dd4c83a42_com-aptoide-diceroll-sdk-none-promotion-asset.webp",
              "downloadUrl": "https://cdn-catappult.aptoide.com/promotion_asset/b737866e7065a09e02a8393dd4c83a42_com-aptoide-diceroll-sdk-none-promotion-asset.webp",
              "ratio": "256:125"
            }
          ]
        }
      ]
    },
    "partner": { "name": "APTOIDE-GAMES" },
    "application": {
      "name": "com.aptoide.diceroll.sdk",
      "title": "Aptoide Diceroll SDK",
      "operatingSystem": "android",
      "iconUrl": "https://ws.catappult.io/api/applications/com.aptoide.diceroll.sdk/icon",
      "featureGraphicUrl": "https://ws.catappult.io/api/applications/com.aptoide.diceroll.sdk/featureGraphic"
    },
    "data": {
      "name": "Test Promotion 1",
      "oemId": "562c8031d4a08ba95e682a800cd04448",
      "utmContent": "search"
    },
    "files": [
      {
        "id": 385,
        "name": "64c5826a724c1bb78332c0ed67b5f83b_com-aptoide-diceroll-sdk-none-promotion-asset.png",
        "downloadUrl": "https://cdn-catappult.aptoide.com/promotion_asset/64c5826a724c1bb78332c0ed67b5f83b_com-aptoide-diceroll-sdk-none-promotion-asset.png"
      }
    ]
  }
]

Errors

HTTP Status	Code	Description
404	PARTNER-NOT-FOUND	The account associated with the API key has no Partner record linked.