Promotion API

Introduction

The Promotion API endpoints provide access to CDP promotion data within our system. These endpoints enable you to import your promotion code from a third-party promotion engine into CDP and more, allowing your application to interact with our event data.

Authentication

To access these endpoints, you will need to authenticate your requests using OAuth 2.0 and ensure that the access token is authenticated with the scope promotion. Please refer to our Authentication Guide for details on how to obtain an access token.

Create Promotion Pool

Creates a new promotion pool in the system.

Notes:

• All pool names and codes must be unique in the system.
• File import fields are optional and only required when importing promotions from a file.
• When restrictionType = 1, allocationTypes must contain at least one valid value.
• When restrictionType = 2, allocationTypes must be null.
• shareAccess configuration determines the access control of the pool.

post

/api/promotion/pool

Header parameters

Content-Typestring · default: application/jsonrequired

Authorizationstringrequired

Example: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY

Body

pool_namestringrequired

Name of the promotion pool.

Example: Untitled Pool#2025-02-05 16:26:07

pool_codestringrequired

Unique identifier for the pool.

Example: untitled_pool20250205_162607

restrictionTypeinteger · enumrequired

Pool restriction type.

• 2: Restricted allocation
• 3: Unrestricted allocation

Example: 1

Options: 1, 2

expirationobjectrequired

descriptionstring

Detailed description of the pool.

allocationTypesstring · enum[] | nullable

Types of allocation for the pool.

Required when restrictionType is 1.

Must be null when restrictionType is 2.

Allowed values:

• audience
• user
• customer
• email
• phone

Example: ["audience"]

pool_name_multilangobject

Multi-language support for pool name.

alertSettingobject

shareAccessobject

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.ants.tech/access/api/promotion/pool' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY' \
  --data '{
    "pool_name": "Untitled Pool#2025-02-05 16:26:07",
    "pool_code": "untitled_pool20250205_162607",
    "restrictionType": 1,
    "expiration": {
      "type": "none",
      "endTime": null
    },
    "allocationTypes": [
      "audience"
    ],
    "pool_name_multilang": {
      "en": "Pool Name",
      "vi": "Tên Pool"
    },
    "alertSetting": {
      "alertOnExpireDay": false,
      "dayThresholdNumber": 0,
      "alertOnCodeNumber": false,
      "codeThresholdNumber": 0,
      "alertAccountIds": []
    },
    "shareAccess": {
      "is_public": 0,
      "public_role": 3,
      "list_access": [
        {
          "role": 1,
          "user_id": 1600080515,
          "allow_view": 1,
          "allow_edit": 1,
          "allow_comment": 1,
          "network_id": 564891081
        }
      ]
    }
  }'

200

400

200

{
  "code": 200,
  "data": {
    "pool_id": 35886334
  },
  "message": "Success"
}

Success

Import Promotion Codes

Import promotion codes in batch to an existing pool.

Notes:

• Maximum 500 promotions can be imported in a single request.
• All promotions in the batch must belong to the same pool.
• Each promotion code must have a unique id within the pool.
• job_run_id should be unique for each import batch.

post

/api/promotion/import

Header parameters

Content-Typestring · default: application/jsonrequired

Authorizationstringrequired

Example: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY

Body

promotionsobject[]required

Array of promotion codes to import.

pool_idintegerrequired

ID of the target promotion pool.

Example: 223123

job_run_idstringrequired

Unique identifier for the import job.

Example: 728334d0-164a-11ee-be56-0242ac120002

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.ants.tech/access/api/promotion/import' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY' \
  --data '{
    "promotions": [
      {
        "id": "abc",
        "name": "a231"
      }
    ],
    "pool_id": 223123,
    "job_run_id": "728334d0-164a-11ee-be56-0242ac120002"
  }'

200

400

200

{
  "code": 200,
  "status": true,
  "message": "ok",
  "requestId": "95a28137-e914-4941-bbb2-94b41a5e7148"
}

Success

Search Promotion Code(s)

Search for a list of promotion code(s) in the CDP based on conditions.

post

/api/item/search

Header parameters

Content-Typestring · default: application/jsonrequired

Authorizationstringrequired

Example: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY

Body

itemTypeIdinteger · enum

Identifier for the item type. This is a constant and cannot be changed.

Example: -100

Options: -100

itemTypeNamestring · enum

Name of the item type. This is a constant and cannot be changed.

Example: promotion_code

Options: promotion_code

attrsstring[]

List of attributes to retrieve. Default attributes are:

• allocated_audience: Allocated to audience
• allocated_time: Allocated time
• audience_type: Audience type
• pool_id: Promotion pool ID
• redeem_visitor_id: Visitor used code
• story_id: Journey ID
• transaction_code: Transaction ID
• code_status: Code status
• date_created: Created date
• id: ID
• last_updated: Last updated
• last_used_source: Last used source
• last_used_time: Last used time
• name: Name
• campaign_id: Campaign ID
• variant_id: Variant ID

Example: ["id","name","pool_id","date_created","allocated_time","allocated_audience","audience_type","code_status","last_used_source","last_used_time"]

filtersobject

Filtering conditions for the search.

Filter Items Order Rules:

• The last item must always be allocated_time.
• The first three items must be audience_type, allocated_audience, and code_status, but they can appear in any order.
• The request can contain either all four filters or any subset as long as allocated_time is present.

Responses

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.ants.tech/access/api/item/search' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY' \
  --data '{
    "itemTypeId": -100,
    "itemTypeName": "promotion_code",
    "attrs": [
      "id",
      "name",
      "pool_id",
      "date_created",
      "allocated_time",
      "allocated_audience",
      "audience_type",
      "code_status",
      "last_used_source",
      "last_used_time"
    ],
    "filters": {
      "OR": [
        {
          "AND": [
            {
              "type": null,
              "column": null,
              "data_type": null,
              "operator": null,
              "value": -1003
            }
          ]
        }
      ]
    }
  }'

200

400

403

200

{
  "code": 200,
  "message": "Search Business Object success",
  "data": [
    {
      "allocated_audience": "00088d37411f4d90ea80de8d1bdb4175",
      "audience_type": -1003,
      "allocated_time": "2024-08-16 19:29:46",
      "date_created": "2024-08-16 14:14:44",
      "last_used_source": null,
      "name": "5020772646313",
      "last_used_time": null,
      "id": "5020772646313",
      "pool_id": 26507591,
      "code_status": 3
    },
    {
      "allocated_audience": "000a04dd2bd60fdd22209a296105519b",
      "audience_type": -1003,
      "allocated_time": "2024-08-16 19:29:47",
      "date_created": "2024-08-16 14:14:43",
      "last_used_source": null,
      "name": "5020808638087",
      "last_used_time": null,
      "id": "5020808638087",
      "pool_id": 26507591,
      "code_status": 3
    },
    {
      "allocated_audience": "000a1ad1eb9adc97483c1da44d969f3f",
      "audience_type": -1003,
      "allocated_time": "2024-08-16 19:30:07",
      "date_created": "2024-08-16 14:03:13",
      "last_used_source": null,
      "name": "2014788869435",
      "last_used_time": null,
      "id": "2014788869435",
      "pool_id": 26507454,
      "code_status": 3
    },
    {
      "allocated_audience": "0003da4bccf6cec103a97e7a5c8485af",
      "audience_type": -1003,
      "allocated_time": "2024-08-17 10:06:05",
      "date_created": "2024-07-27 05:50:10",
      "last_used_source": null,
      "name": "5018570978043",
      "last_used_time": null,
      "id": "5018570978043",
      "pool_id": 24993469,
      "code_status": 3
    },
    {
      "allocated_audience": "000cf2ef7fd2506a06942bb523917a22",
      "audience_type": -1003,
      "allocated_time": "2024-08-01 10:14:56",
      "date_created": "2024-07-27 05:50:09",
      "last_used_source": null,
      "name": "5018612669277",
      "last_used_time": null,
      "id": "5018612669277",
      "pool_id": 24993469,
      "code_status": 3
    }
  ]
}

Success