TikTok API

Overview

This document outlines how you can integrate between between Redpoint Data Management (DM) and TikTok APIs for CRUD tasks involving TikTok custom audiences. This document contains instructions for each CRUD task, as well as their configuration options.

Basic requirements

Each task contained in this documentation has the following requirements:

• A TikTok app with the Audience Management scope enabled.

• A corresponding App ID and Secret.

• An Advertiser ID.

• OAuth2 Authentication.

• An audience file for upload. Refer to Cloud storage providers and Define file exports for details.

Create a long lived access token

All requests to the TikTok API must include an access token for authentication. The creation of a long lived access token is a two-step process where the user must first generate an authentication code, and then use that code to generate an access token. Once created, access tokens do not expire unless invalidated, /oauth2/revoke_token/.

Generate an authentication code

Each TikTok application has a corresponding Advertiser Authorization URL, for example:

https://business-api.tiktok.com/portal/auth?app_id=7237383493024481281&state=your_custom_params&redirect_uri=https%3A%2F%2Fwww.redpointglobal.com

To generate an authentication code:

1. Navigate to the Authorization URL, where you’ll find a list of permissions corresponding to those selected during the creation of the TikTok app.

2. Once you review and verify the permissions, you’ll be redirected to the Redirect URL specified during app creation. The authentication code is appended to the Redirect URL as a query string parameter named auth_code.

https://www.redpointglobal.com?state=your_custom_params&code=3c6dc21d2db289199737bcb8c006c23aaf000a1e&auth_code=1234c21d2db289199737bcb8c006c23aaf000a1e&id=1701890905779201

Generate access token

The auth_code is then used to post to the following endpoint:

Endpoint: https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/

Method: POST

Header:

Parameters:

A successful post will return an access_token that can be stored and used for future TikTok API requests.

Response:

{
  "message": "OK",
  "code": 0,
  "data": {
    "access_token": "xxxxxxxxxxxxx",
    "scope": [
      4
    ],
    "advertiser_ids": [
      "123456789",
      "123456781"
    ]
  },
  "request_id": "2020042715295501023125104093250"
}

Create a custom audience

The creation of the TikTok custom audience is broken down into two stages: uploading a customer file and creating a custom audience using customer file paths.

Upload a customer file

The customer file contains a set of Apple Identifiers for Advertisers (IDFA) and/or Google Advertising IDs (GAID). These IDs will be the basis for the TikTok custom audience. The customer file must adhere to the guidelines listed at https://ads.tiktok.com/help/article/customer-file?redirected=2.

• Supported file formats: .csv or .txt format (zip file is not supported).

• Size: Up to 250MB (this is the size limit for the endpoint, the TikTok admin GUI allows for 1GB).

• Accepted IDs:

  • Apple IDFA (Identifier for Advertisers)

  • GAID (Google Advertising ID)

• Accepted hash:

  • MD5 Hashed

  • SHA256 Hashed

  • Original (unhashed or raw) value

    • If you provide unhashed or raw values (which will be hashed automatically), the contents of the file before hashing need to contain consistent capitalization – either all uppercase or all lowercase.

• IDFA and GAID data can be combined in the same file, with each entry on a separate line. Only matched data will process, all other data will not be processed – including column headings/names, or other unmatched data.

Once the customer file is created, it must be posted to the following endpoint:

Endpoint: https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/file/upload/

Method: POST

Header:

Parameters: The following parameters must be included in the request body in the form-data format.

DM caveat

The requirement for multipart/form-data and a file upload presents a difficulty for DM. The request must be created manually using a Calculate function after consuming the customer file. We must define a form-data boundary, the request content type, including the boundary, and the request itself.

Examples:

• Field: boundary
  Expression: "0ebd3"

• Field: contentType
  Expression: "multipart/form-data; boundary=" + boundary

• Field: request
  Expression:

"--" + boundary + "
Content-Disposition: form-data; name=\"advertiser_id\"

7275812891423653890
--" + boundary + "
Content-Disposition: form-data; name=\"file_signature\"

eeb3aee488d9c7fde3a57a4ede3ffd3b
--" + boundary + "
Content-Disposition: form-data; name=\"calculate_type\"

FIRST_SHA256
--" + boundary + "
Content-Disposition: form-data; name=\"file\"; filename=\"file:///C:/path_to_ids/tiktok ids text.txt\"
Content-Type: text/plain

"+ DecodeTextBytes(contents,"UTF8") +"
--" + boundary + "--"

When run through a DM web service with the request field assigned to the Body field, this will produce a payload that contains contents of the file located at filename.

A successful POST request will return a file_path within TikTok that can then be referenced when creating a custom audience.

Response:

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "file_path": "f19fa450136c460f"
    },
    "request_id":"11111111111"
}

Create an audience by file

Once we have one-to-many customer files in TikTok, we can use their contents to assign them to a custom audience. The request must adhere to the following guidelines: https://business-api.tiktok.com/portal/docs?id=1739940570793985.

• An advertiser can have a maximum of 400 audiences. Existing audiences must be deleted prior to the creation of new ones if the limit is reached.

• Newly created audiences require at most 48 hours to be analyzed and processed before they become active.

Endpoint: https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/create/

Method: POST

Header:

Parameters:

Field	Data Type	Description
advertiser_id	string	(Required) Advertiser ID.
custom_audience_name	string	(Required) Audience name. Maximum of 128 characters.
audience_sub_type	string	Audience sub type, indicating the type of ads that the audience can be used. Enum values: NORMAL Normal audience. It can be used in non-R&F ads. (Default) REACH_FREQUENCY: Audience for Reach & Frequency. It can only be used in R&F ads.
file_paths	string[]	(Required) List of file paths, not exceeding 500.
calculate_type	string	(Required) Encryption type. calculate_type should be the same as all the files in the file_path, or you will not get a audience id or get an invalid audience id. For enum values, see Enumeration - Encryption Type.
retention_in_days	integer	Number of days to retain the audience. Value range: 1-365. If this field is passed, the expiration date will be the specified number of retention days from the date when the audience was created. Any operations to the audience CANNOT reset the expiration date. If this field is not passed, the expiration date will be 365 days from the last time the audience was applied to an active ad group or modified. Applying the audience to an active ad group or modifying the audience will reset the expiration date. To learn about the actions that will reset the expiration date, refer to the Help Center article Audience Expiration Policy.

A successful POST request will return a custom_audience_id within TikTok.

Response:

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {
        "custom_audience_id": "123"
    }
}

Update a custom audience

An existing custom audience can be updated to change its name or to update its associated file paths. The request must adhere to the guidelines listed at https://business-api.tiktok.com/portal/docs?id=1739940572667906.

• There is a daily quota of 24 Audience update operations (APPEND, REMOVE, REPLACE). This limit is at audience level.

• Wait until the current operation completes on an audience before re-trying. This limit is at audience level.

• The REPLACE, APPEND, and REMOVE operations will fail if the audience size is less than 1,000 after the operation.

• Only one file-based audience REPLACE operation is allowed per day. This limit is at audience level.

• REPLACE operations will be rejected if there is an existing unfinished REPLACE operation.

• For REMOVE, you cannot remove all data files.

• An expiring or expired audience cannot be modified. It can only be deleted. You can use is_expiring and expired_time to find out whether an audience is expiring or expired.

Endpoint: https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/update/

Method: POST

Header:

Parameters:

Field	Data Type	Description
advertiser_id	string	(Required) Advertiser ID.
custom_audience_id	string	(Required) Custom audience ID.
custom_audience_name	string	(Conditional) You must pass in either this field or file_paths. New name for the audience. Length limit: 128 characters.
audience_sub_type	string	Audience sub type, indicating the type of ads that the audience can be used for. The allowed enum value: REACH_FREQUENCY (To enable the audience to be used in Reach & Frequency campaigns). It means you can only convert audience sub type from NORMAL to REACH_FREQUENCY, but not the other way around. If you update this field, changes to other data fields will be ignored. If you want to update a Lookalike audience, you cannot change the audience_sub_type to REACH_FREQUENCY. Otherwise, an error will occur.
file_paths	string[]	(Conditional) You must pass in either this field or custom_audience_name. The files you upload to update the Customer File audience. Once you pass in this field, you can specify the modification type (APPEND, REMOVE or REPLACE) via action. The files must be encrypted with the same encryption method/type with the audience that you want to update.
action	string	Modification type. This field is valid when file_paths is passed. Enum values: APPEND: Upload files to expand the Customer File audience. Only data not included in the original file will be added. REMOVE: Upload files to remove the Customer File audience. Only the data that coincide with the original file will be removed. REPLACE: Upload files to replace the Customer File audience. All the data in the original file will be replaced. Default value: REPLACE. The APPEND, REMOVE and REPLACE operations will fail if the audience size is less than 1,000 after the operation.

A successful POST will return an OK message and an empty data set.

Response:

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {}
}

Delete an existing audience

An existing custom audience can be deleted by passing its ID to the appropriate endpoint.

Endpoint: https://business-api.tiktok.com/open_api/v1.3/dmp/custom_audience/delete/

Method: POST

Header:

Parameters:

A successful POST will return an OK message and an empty data set.

HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {}
}