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

post

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.

Authorizations

bearerAuth

Header parameters

Content-TypestringRequiredDefault: application/json

AuthorizationstringRequiredExample: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY

Body

application/json

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: 1Possible values:

descriptionstringOptional

Detailed description of the pool.

Responses

200

Success

application/json

400

Error

application/json

post

/api/promotion/pool

HTTPcURLJavaScriptPython

POST /access/api/promotion/pool HTTP/1.1
Host: api.ants.tech
Authorization: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY
Content-Type: application/json
Accept: */*
Content-Length: 546

{
  "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
      }
    ]
  }
}

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

Import Promotion Codes

post

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.

Authorizations

bearerAuth

Header parameters

Content-TypestringRequiredDefault: application/json

AuthorizationstringRequiredExample: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY

Body

application/json

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

200

Success

application/json

400

Error

application/json

post

/api/promotion/import

HTTPcURLJavaScriptPython

POST /access/api/promotion/import HTTP/1.1
Host: api.ants.tech
Authorization: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY
Content-Type: application/json
Accept: */*
Content-Length: 112

{
  "promotions": [
    {
      "id": "abc",
      "name": "a231"
    }
  ],
  "pool_id": 223123,
  "job_run_id": "728334d0-164a-11ee-be56-0242ac120002"
}

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

Search Promotion Code(s)

post

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

Authorizations

bearerAuth

Header parameters

Content-TypestringRequiredDefault: application/json

AuthorizationstringRequiredExample: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY

Body

application/json

itemTypeIdinteger · enumOptional

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

Example: -100Possible values:

itemTypeNamestring · enumOptional

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

Example: promotion_codePossible values:

attrsstring[]Optional

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"]

Responses

200

Success

application/json

400

Unauthorized

application/json

403

Forbidden

application/json

post

/api/item/search

HTTPcURLJavaScriptPython

POST /access/api/item/search HTTP/1.1
Host: api.ants.tech
Authorization: Bearer 5474r2x214z26484u2e4y4u5u42424n594o4XXXXYYYY
Content-Type: application/json
Accept: */*
Content-Length: 306

{
  "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
          }
        ]
      }
    ]
  }
}

{
  "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
    }
  ]
}