Advertiser¶

An advertiser is a TikTok Ads account. Nova Play operates 10 advertiser accounts, one per game; the account name is the game name followed by the OS in parentheses, for example Dragon Merge Saga (Android) or Puzzle Blast Mania (iOS). Every other endpoint in this API is scoped to one advertiser through the advertiser_id parameter, so listing advertisers is always your first call.

Get authorized advertisers¶

GET /open_api/v1.3/oauth2/advertiser/get/

Returns every advertiser account the access token is authorized to read. This endpoint has no parameters and no paging.

Parameters¶

Name	Type	Required	Description
—			No parameters. The token in the `Access-Token` header determines the result.

Request¶

curl -s "https://business-api.huydata.com/open_api/v1.3/oauth2/advertiser/get/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN"

Response¶

{
  "code": 0,
  "message": "OK",
  "request_id": "6e596d719a0141599ce7",
  "data": {
    "list": [
      {"advertiser_id": "7643153585721644371", "advertiser_name": "Dragon Merge Saga (Android)"},
      {"advertiser_id": "7548458757843580535", "advertiser_name": "Idle Mining Empire (Android)"},
      {"advertiser_id": "7990946724050865085", "advertiser_name": "Zombie Siege Defense (Android)"},
      {"advertiser_id": "7561433009497335594", "advertiser_name": "Puzzle Blast Mania (iOS)"},
      ...
    ]
  }
}

Field	Type	Description
`advertiser_id`	string	Numeric account id (19 digits, starts with `7`). Pass it as `advertiser_id` to every other endpoint.
`advertiser_name`	string	`"<Game name> (<Android\|iOS>)"`.

The list currently contains 10 accounts: Dragon Merge Saga, Idle Mining Empire, Zombie Siege Defense, Car Park Master 3D, Hero Tower Defense and Pixel Survivors on Android; Puzzle Blast Mania, Castle Match Legends, Sushi Shop Tycoon and Word Garden Story on iOS.

Get advertiser info¶

GET /open_api/v1.3/advertiser/info/

Returns account details (currency, time zone, status) for one or more advertisers.

Parameters¶

Name	Type	Required	Description
`advertiser_ids`	JSON array of strings	Yes	Advertiser ids to describe, for example `["7643153585721644371","7561433009497335594"]`. Every id must be authorized for the token, otherwise the whole call fails with `40002`.
`fields`	JSON array of strings	No	Subset of response fields to return. Any name from the response table below. Unknown names fail with `40001`.

Request¶

curl -s -G "https://business-api.huydata.com/open_api/v1.3/advertiser/info/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode 'advertiser_ids=["7643153585721644371","7561433009497335594"]'

Response¶

{
  "code": 0,
  "message": "OK",
  "request_id": "e7836bfa0cb442cd9faa",
  "data": {
    "list": [
      {
        "advertiser_id": "7643153585721644371",
        "name": "Dragon Merge Saga (Android)",
        "company": "Nova Play",
        "currency": "USD",
        "timezone": "UTC",
        "display_timezone": "Etc/UTC",
        "status": "STATUS_ENABLE",
        "role": "ROLE_ADVERTISER",
        "create_time": 1760950800
      },
      {
        "advertiser_id": "7561433009497335594",
        "name": "Puzzle Blast Mania (iOS)",
        "company": "Nova Play",
        "currency": "USD",
        "timezone": "UTC",
        "display_timezone": "Etc/UTC",
        "status": "STATUS_ENABLE",
        "role": "ROLE_ADVERTISER",
        "create_time": 1762938000
      }
    ]
  }
}

Field	Type	Description
`advertiser_id`	string	Account id.
`name`	string	Account name (same value as `advertiser_name` in the list endpoint).
`company`	string	Legal entity that owns the account: always `Nova Play`.
`currency`	string	Currency of `spend`, `budget` and all cost metrics. `USD` for every account.
`timezone`	string	Reporting time zone. `UTC` for every account, so `stat_time_day` is a UTC day.
`display_timezone`	string	IANA name of the time zone (`Etc/UTC`).
`status`	string	`STATUS_ENABLE`.
`role`	string	`ROLE_ADVERTISER`.
`create_time`	integer	Account creation time as a Unix timestamp in seconds. Note that this is an integer, unlike the `create_time` strings returned by campaign, ad group and ad endpoints.

With fields:

curl -s -G "https://business-api.huydata.com/open_api/v1.3/advertiser/info/" \
  -H "Access-Token: $TIKTOK_ACCESS_TOKEN" \
  --data-urlencode 'advertiser_ids=["7643153585721644371"]' \
  --data-urlencode 'fields=["advertiser_id","name","currency","timezone"]'

{
  "code": 0,
  "message": "OK",
  "request_id": "a9090ce85b244b6e9289",
  "data": {
    "list": [
      {"advertiser_id": "7643153585721644371", "name": "Dragon Merge Saga (Android)", "currency": "USD", "timezone": "UTC"}
    ]
  }
}

Errors¶

advertiser_ids sent as a plain value instead of a JSON array (advertiser_ids=7643153585721644371) → 40001 Parameter 'advertiser_ids' must be a JSON-encoded list.
An id that is not in your authorized list → 40002 Advertiser 1234567890 is not authorized for this access token.