VI | EN
Message us on Messenger
Developer resources

Get a portfolio by ID — TikTok Business API

Get a portfolio by ID · call it through Quantri360 with one API key for your own accounts / assets that you connected and authorized — 360 handles request signing and refreshing the authorization you granted.

Get a portfolio by ID

GET/creative/portfolio/get/Via 360: GET https://partner.quantri360.com/v1/tiktok_business/creative/portfolio/get/
Description

Use this endpoint to get an existing creative portfolio by its ID. You can get portfolios that are created with the /creative/portfolio/create/ endpoint.

Request

Endpoint

GET https://partner.quantri360.com/v1/tiktok_business/creative/portfolio/get/

Authentication & shop

NameInTypeSampleDescription
AuthorizationheaderheaderBearer q360_live_ab12cd34_…Khóa API của brand (tạo ở mục API key). Bắt buộc với mọi request. Brand suy từ key — không truyền mã brand.
platform_shop_idquerystring7000000000000000001Tài sản TikTok Business đã kết nối — "Mã tài sản" ở trang Nền tảng hoặc GET /v1/platforms (tài khoản quảng cáo cho Marketing API, tài khoản TikTok cho Organic / Messaging). Có thể bỏ khi chỉ kết nối một tài sản.

Request parameters

NameInTypeRequiredSampleDescription
creative_portfolio_idquerystringYesID of the creative portfolio that you want to get. You can find the portfolio id (creative_portfolio_id) in the response of /creative/portfolio/create/.

Request examples

curl -s "https://partner.quantri360.com/v1/tiktok_business/creative/portfolio/get/?creative_portfolio_id=" \
  -H "Authorization: Bearer $KEY"
Python
import requests

KEY = "q360_live_..."  # khóa API của brand
r = requests.get(
    "https://partner.quantri360.com/v1/tiktok_business/creative/portfolio/get/",
    params={
        "creative_portfolio_id": ""
    },
    headers={"Authorization": f"Bearer {KEY}"},
    timeout=60,
)
print(r.status_code)
print(r.json())
Node.js
const KEY = 'q360_live_...'; // khóa API của brand
const url = new URL('https://partner.quantri360.com/v1/tiktok_business/creative/portfolio/get/');
for (const [k, v] of Object.entries({"creative_portfolio_id":""})) url.searchParams.set(k, typeof v === 'object' ? JSON.stringify(v) : String(v));
const r = await fetch(url, {
  method: 'GET',
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(r.status, await r.json());
PHP
<?php
$key = 'q360_live_...'; // khóa API của brand
$url = 'https://partner.quantri360.com/v1/tiktok_business/creative/portfolio/get/' . '?' . http_build_query(['creative_portfolio_id' => '']);
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Bearer ' . $key]);
$res = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, "\n", $res;

Response

Response fields (as returned by TikTok Business)

NameTypeSampleDescription
messagestringThe return message. For example, see Appendix-Return information.
codenumberThe return code. For details, see Appendix-Return Code.
dataobjectThe returned data.
creative_portfolio_idstringCreative portfolio ID.
creative_portfolio_typestringCreative portfolio type. Enum values: - `CTA`: call-to-action text. - `CARD`: card (Display Card). - `HOTEL_CARD` : Hotel Card. - `FLIGHT_CARD` : Flight Card. - `DESTINATION_CARD`: Destination Card. - `WEB_INFO_CARD`: Website info card. - `DOWNLOAD_CARD`: Download Card. - `INVENTORY_CARD`: Inventory Card. - `PRODUCT_CARD`: Product Card. - `PRODUCT_TILE`: Product Tiles. - `STICKER`: Countdown Sticker or Gift Code Sticker. - `PREMIUM_BADGE`: Pop-up Showcase. - `GESTURE`: Gesture. - `SUPER_LIKE`: Superlike. A Superlike engages the audience with a surprise visual element after they like a video ad. With Superlke, heart-shaped and customized icons float across the screen when the audience likes or double-taps on the ads. Note: - Website info cards can only be used for auction ads with the `objective_type` as `WEB_CONVERSIONS` or `TRAFFIC` (with `promotion_type` set to `WEBSITE`). - You can only use the Inventory Card portfolio in Automotive Ads. - Product Cards can only be used in Video Shopping Ads. - Product Tiles can only be used in Video Shopping Ads with product source as catalog. - Using a Product Tiles portfolio to create ads is currently an allowlist-only feature. If you would like to access it, please contact your TikTok representative. - Countdown Sticker can only be used for auction ads with the advertising objective (`objective_type`) as Reach (`REACH`), Traffic (`TRAFFIC`), Video views(`VIDEO_VIEW`), App promotion (`APP_PROMOTION`), Lead generation(`LEAD_GENERATION`), Website conversions (`WEB_CONVERSIONS`), or Product sales (`PRODUCT_SALES`), as well as for R&F (`RF_REACH`) ads. - Reminder Countdown Sticker (`sticker_type` as `REMINDER_COUNTDOWN` or `LIVE_REMINDER_COUNTDOWN`) is an allowlist-only feature for Traffic (`TRAFFIC`), App promotion (`APP_PROMOTION`), Website conversions (`WEB_CONVERSIONS`) ads. If you would like to access it for ads with these objectives, please contact your TikTok representative. - Gift Code Sticker can only be used for auction ads with the advertising objective (`objective_type`) as Reach (`REACH`), Traffic (`TRAFFIC`), Video views(`VIDEO_VIEW`), App promotion (`APP_PROMOTION`), Lead generation(`LEAD_GENERATION`), Website conversions (`WEB_CONVERSIONS`), or Product sales (`PRODUCT_SALES`), as well as for R&F ads with the advertising objective(`objective_type`) as Reach (`RF_REACH`). - Gestures can only be used for auction ads with the `objective_type` (advertising objective) as `REACH`, `TRAFFIC`, `VIDEO_VIEWS` (with `optimization_goal` as `ENGAGED_VIEW`), `APP_PROMOTION`, `WEB_CONVERSIONS`, as well as for R&F ads with the advertising objective (`objective_type`) as Reach (`RF_REACH`). - Using Gesture portfolios in campaigns with the advertising objective `APP_PROMOTION`, `TRAFFIC`, or `WEB_CONVERSIONS` are currently separate allowlist-only features. If you would like to access them, please contact your TikTok representative. - Superlikes can only be used for auction ads with the `objective_type` (advertising objective) as `REACH`, `TRAFFIC`, `VIDEO_VIEWS` (with `optimization_goal` as `ENGAGED_VIEW`), `ENGAGEMENT` (with `optimization_goal` as `PAGE_VISIT`), `APP_PROMOTION`, `WEB_CONVERSIONS`, as well as for R&F ads with the advertising objective (`objective_type`) as Reach (`RF_REACH`). - Using Superlike portfolios in campaigns with the advertising objective `APP_PROMOTION` or `TRAFFIC` are currently separate allowlist-only features. If you would like to access them, please contact your TikTok representative.
portfolio_contentobject[]The content of the creative portfolio.
asset_contentstringA call-to-action text. For example, `"Learn More"`.
asset_idsstring[]A list of CTAs. For example, `[201781, 201535]`.
card_typestringCard type. Enum value: `IMAGE`(Display Card).
primary_textstringReturned when `creative_portfolio_type` is `HOTEL_CARD`, `FLIGHT_CARD`, or `DESTINATION_CARD`. Primary text. When `creative_portfolio_type` is `HOTEL_CARD` or `FLIGHT_CARD`, the allowed values are: - `NONE`: None. - `DEALS`: The label "Deals". - `CUSTOM_LABEL`: The first custom label specified for the hotel or flight product. When `creative_portfolio_type` is `DESTINATION_CARD`, the allowed values are: - `CUSTOM_LABEL`: Custom label. - `DEALS`: Discounts. Discounts will be displayed as a percentage based on the original price and sale price in your catalog. However, if you didn't upload any sales price info, the deals tag will be shown instead. - `NONE`: None.
secondary_textstringReturned when `creative_portfolio_type` is `HOTEL_CARD`, `FLIGHT_CARD`, or `DESTINATION_CARD`. Secondary text. When `creative_portfolio_type` is `HOTEL_CARD` , the allowed values are: - `NONE`: None. - `RATING`: The rating information, including max score, actual score, and number of reviewers, specified for the hotel product. - `CUSTOM_LABEL`: The second custom label specified for the hotel product. When `creative_portfolio_type` is `FLIGHT_CARD` , the allowed values are: - `NONE`: None. - `CUSTOM_LABEL`: The second custom label specified for the flight product. When `creative_portfolio_type` is `DESTINATION_CARD` , the allowed values are: - `CUSTOM_LABEL`: Custom label. - `NONE`: None.
card_show_pricebooleanReturned when `creative_portfolio_type` is `PRODUCT_CARD`, `HOTEL_CARD` or `FLIGHT_CARD`. Whether to show the price of the catalog product in the card. Enum values: `true`, `false`.
image_optimization_enabledbooleanReturned only when `creative_portfolio_type` is `HOTEL_CARD`, `FLIGHT_CARD`, or `DESTINATION_CARD`. Whether to use AI to optimize the hero image (converting a non-square image to a square image). Supported values: `true`, `false`.
display_price_enabledbooleanReturned only when `creative_portfolio_type` is `DESTINATION_CARD`. Whether to display price info. Supported values: `true`, `false`.
gesture_typestringReturned when `creative_portfolio_type` is `GESTURE`. Gesture type. Enum values: - `CLICK`: Click Gesture. - `STRAIGHT_SLIDE`: Straight Slide Gesture. - `CURVED_SLIDE`: Curved Slide Gesture.
image_idstringReturned only when `creative_portfolio_type` is `CARD`, `WEB_INFO_CARD`, `INVENTORY_CARD`, or `SUPER_LIKE`. Image ID.
pop_up_window_image_idstringReturned in any of the following scenarios: - `creative_portfolio_type` is `GESTURE`. - `creative_portfolio_type` is `SUPER_LIKE` and a `pop_up_window_image_id` is specified during portfolio creation.. The gesture pop-up card in the Gesture or the ID of the pop-up window image in the Superlike. - When `creative_portfolio_type` is `GESTURE`, this field represents the gesture pop-up card that will appear after the viewer follows the gesture. - When `creative_portfolio_type` is `SUPER_LIKE`, this field represents the pop-up window that will appear after the Superlike finishes floating across the screen and will take the audience to the ad landing page when they click on it.
titlestringReturned only when `creative_portfolio_type` is `WEB_INFO_CARD`. The title of the card.
selling_pointsstring[]Returned only when `creative_portfolio_type` is `WEB_INFO_CARD`. The reasons why your products are worth buying.
content_urlstringReturned only when `creative_portfolio_type` is `WEB_INFO_CARD`. The website URL of your landing page. Note: - Specifying the `content_url` in a website info card via API is currently not supported. You can only retrieve the `content_url` of website info cards created via the TikTok Ads Manager. - For website info cards created via API, the value of this field will be an empty string (`""`).
thumbnail_idstringReturned only when `creative_portfolio_type` is `DOWNLOAD_CARD`, `PRODUCT_CARD`, `PRODUCT_TILE`, or `PREMIUM_BADGE`. Thumbnail ID.
call_to_action_textstringReturned when `creative_portfolio_type` is `GESTURE` or `PREMIUM_BADGE`. Interactive guide text for the Gesture or Pop-out Showcase.
badge_show_timeintegerReturned when `creative_portfolio_type` is `GESTURE` or `PREMIUM_BADGE`. The time when the Gesture icon within the Gesture or the Premium Badge within the Pop-out Showcase will appear in your video, in seconds.
badge_positionobjectReturned when `creative_portfolio_type` is `GESTURE` or `PREMIUM_BADGE`. Information about the position of the Gesture icon within a Gesture or the Premium Badge within a Pop-out Showcase.
position_xfloatRelative X-axis value of the top-left corner of the Gesture icon within a Gesture or the Premium Badge within a Pop-out Showcase.
position_yfloatRelative Y-axis value of the top-left corner of the Gesture icon within a Gesture or the Premium Badge within a Pop-out Showcase.
anglenumberReturned when `badge_position` is specified and any of the following conditions is met: - `creative_portfolio_type` is `GESTURE` and `gesture_type` is `STRAIGHT_SLIDE` or `CURVED_SLIDE`. - `creative_portfolio_type` is `PREMIUM_BADGE`. The angle of the Straight Slide Gesture or Curved Slide Gesture icon within a Gesture or the Premium Badge within a Pop-out Showcase.
badge_image_infoobjectReturned when `creative_portfolio_type` is `PREMIUM_BADGE`. Information about the badge image in the Pop-out Showcase.
image_idstringID of the badge image in the Pop-out Showcase.
slide_lengthnumberReturned when `creative_portfolio_type` is `GESTURE` and `gesture_type` is `STRAIGHT_SLIDE`. The length of the Straight Slide Gesture.
slide_dimensionobjectReturned when `creative_portfolio_type` is `GESTURE` and `gesture_type` is `CURVED_SLIDE`. The dimensions of the Curved Slide Gesture.
dimension_widthnumberThe width of the Curved Slide Gesture.
dimension_heightnumberThe height of the Curved Slide Gesture.
interactive_music_idstringReturned when `creative_portfolio_type` is `GESTURE`. The URL of the background music for the Gesture.
layoutsstring[]Returned when `creative_portfolio_type`= `DOWNLOAD_CARD`. The layout type of the Download Card. Enum values: - `TYPE_1`: Type 1, showing app description in the Download Card. - `TYPE_2` : Type 2, not showing app description in the Download Card. When both `TYPE_1` and `TYPE_2` have been passed in this field, one Type 1 Download card and one Type 2 Download card will be created .
descriptionstringReturned in any of the following scenarios: - `creative_portfolio_type` is `DOWNLOAD_CARD` and the value of `layouts` includes `TYPE_1`. - `creative_portfolio_type` is `INVENTORY_CARD`. Description of the app that you want to promote in the Download Card or text of the Inventory Card.
tagsstring[]Returned when `creative_portfolio_type`= `DOWNLOAD_CARD`. Tags for the Download Card. Enum values: - `CATEGORIES`:Showing the category of the app you want to promote in the Download Card. - `FILESIZE`:Showing the file size of the app you want to promote in the Download Card. - `RATING`:Showing the rating of the app you want to promote in the Download Card. - `RANKING`:Showing the ranking of the app you want to promote in the Download Card. - `COMMENT_VOLUME`:Showing the number of comments for the app you want to promote in the Download Card.
category_labelstringReturned when `creative_portfolio_type`= `DOWNLOAD_CARD` and `category_label` is specified during card creation. Category name of the app you want to promote in the Download Card.
app_idstringReturned when `creative_portfolio_type`= `DOWNLOAD_CARD`. ID of the app that you want to promote in the Download Card. It's the App ID from Events Manager.
sticker_paramobjectDetails of the Countdown Sticker or Gift Code Sticker you want to create. You can see an example of Countdown Sticker in Countdown Sticker and an example of Gift Code Sticker in Gift Code Sticker. Returned only when `creative_portfolio_type`=`STICKER`. Note: You can only create one Countdown Sticker or Gift Code Sticker at a time.
sticker_typestringSticker type. Enum values: - `COUNTDOWN`: A Countdown Sticker with no reminder. - `REMINDER_COUNTDOWN`: A Countdown Sticker with reminder for a non-LIVE event. - `LIVE_REMINDER_COUNTDOWN`: A Countdown Sticker with reminder for a LIVE event. - `GIFTCODE`: A Gift Code Sticker that aims to gain new customers and engage existing customers by providing virtual gifts or coupon redemption codes.
titlestringSticker title. - For a Countdown Sticker, the maximum length is 54, in UTF-8 bytes, and the hashtag symbol (#) is not supported. - For a Gift Code Sticker, the maximum length is 20 in UTF-8 bytes.
giftcodestringGift code. This field is only applicable for Gift Code Stickers. The maximum length is 10 in UTF-8 bytes (10 letters and numbers).
cutoff_timestringCountdown deadline (when `sticker_type`= `COUNTDOWN` or `REMINDER_COUNTDOWN`) or LIVE start time (when `sticker_type`=`LIVE_REMINDER_COUNTDOWN`) for the Countdown Sticker, in the format of "2022-10-30 00:00:00" (UTC+0 Time). Note: The time your pass in via this field is regarded as UTC+0 time by default and you cannot modify the default time zone.
colorstringBackground color of the sticker. - For a Countdown Sticker, the supported enum values are `ORANGE`(orange), `BLACK`(black), `RED`(red), and`BLUE`(blue). - For a Giftcode Sticker created through the API, only `BLACK` and `BLUE` will be returned. However, `ORANGE` and `RED` may be returned for a Gift Code Sticker created on TTAM when orange and red were supported for Gift Code Stickers.
display_angleintegerSticker display angle. Value range: `[-180, +180]`. `+90` means to rotate the sticker clockwise by 90 degrees. Note: This field is not returned for a Gift Code Sticker created through the API. However, it may be returned for a Gift Code Sticker created on TTAM when the `display_angle` setting was supported for Gift Code Stickers.
predefined_placementstring- If the portfolio is a Gift Code Sticker and the predefined placement of the sticker corresponds to an enum value in Predefined placements, this field returns x-axis and y-axis coordinates. - If the portfolio is a Countdown Sticker and the predefined placement of the sticker corresponds to an enum value in Predefined placements, this field returns x-axis and y-axis coordinates, and size. For example: If the x-axis coordinate, y-axis coordinate and size of the Countdown Sticker are 196, 148, and 0.8, respectively, which corresponds to the enum value `196x148x0.8` in Predefined placements, this field will be returned as `196x148x0.8`. Note: If the sticker does not correspond to any enum value in Predefined placements, this field returns `null`.
position_xintegerThe x-axis coordinate relative to the top-left corner of the screen.
position_yintegerThe y-axis coordinate relative to the top-left corner of the screen.
sizestringSticker size by percentage. Enum values: `0.6`(60%), `0.7`(70%), `0.8`(80%), `0.9`(90%), `1`(100%), `1.1`(110%). Note: This field is not returned for a Gift Code Sticker created through the API. However, it may be returned for a Gift Code Sticker created on TTAM when the `size` setting was supported for Gift Code Stickers.
opacitystringSticker opacity. Enum values: `0.7`, `0.8`, `0.9`, `1`. The lower the value, the more transparent the sticker will be. Note: This field is not returned for a Gift Code Sticker created through the API. However, it may be returned for a Gift Code Sticker created on TTAM when the `opacity` setting was supported for Gift Code Stickers.
reminder_timestringThe time set for the reminder. Returns value when `sticker_type`= `REMINDER_COUNTDOWN` or `LIVE_REMINDER_COUNTDOWN`. For non-LIVE stickers (when `sticker_type`= `REMINDER_COUNTDOWN`), the enum values are: - `ONE_MINUTE_EARLIER`: send the reminder one minute before the non-LIVE event. - `ONE_HOUR_EARLIER `: send the reminder one hour before the non-LIVE event. - `ONE_DAY_EARLIER`: send the reminder one day before the non-LIVE event. For LIVE stickers (when `sticker_type`= `LIVE_REMINDER_COUNTDOWN`), the enum values are: - `ONE_MINUTE_AFTER`: send the reminder one minute after the LIVE event starts. - `FIVE_MINUTES_AFTER`: send the reminder five minutes after the LIVE event starts. - `TEN_MINUTES_AFTER`: send the reminder ten minutes after the LIVE event starts.
landing_page_urlstringThe landing page URL you will be redirected to when you click the reminder after the countdown for an non-LIVE event ends. Returns value when `sticker_type` is `REMINDER_COUNTDOWN`.
live_tiktok_user_idstringTikTok user ID of the LIVE event host. After specifying this field, you will be redirected to the host's LIVE room when you click the reminder for a LIVE event. Returns value when `sticker_type` is `LIVE_REMINDER_COUNTDOWN`.
card_tagsstring[]The product tags that are shown on the Product Card. Enum values: `BRAND` (Brand Name), `DESC` (Description).
card_image_indexintegerUsed to specify the image used in the Product Card or Product Tiles. The number set via this field is used as index to query the Image URLs you have passed through `additional_image_urls` in /catalog/product/upload/. For instance, `card_image_index` = 1 means that you will use the image via the second image URL in `additional_image_urls`.
request_idstringRequest log ID

Response sample

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "portfolio_content": [
            {
                "asset_ids": [
                    "201781",
                    "201535"
                ],
                "asset_content": "learn_more"
            },
            {
                "asset_ids": [
                    "201902",
                    "201404"
                ],
                "asset_content": "download_now"
            }
        ]
    },
    "request_id": "2020123008315601023125104010685"
}

Get started

  1. Sign up for Partner
  2. Enable a data type of the Ads (Marketing API) group on the platform page
  3. Create an API key (tick the TikTok Business channel)
  4. Call it as in the examples above