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.
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:
Navigate to the Authorization URL, where you’ll find a list of permissions corresponding to those selected during the creation of the TikTok app.
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:
Field | Data Type | Description |
---|---|---|
|
| (Required)
|
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) The App ID applied by the developer. It can be found in the Basic Information section for you app under My Apps. |
|
| (Required) Authorization code provided once the callback is complete. It is valid for 1 hour and can only be used once. For more details see Authorization. |
|
| (Required) The private key of the developer's App. It can be found in the Basic Information section for your app under My Apps. |
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:
Field | Data Type | Description |
---|---|---|
|
| (Required) Authorized access token. For details, see Authentication. |
|
| (Required)
|
Parameters: The following parameters must be included in the request body in the form-data
format.
Field | Data Type | Description |
---|---|---|
|
| (Required) Advertiser ID. |
|
| (Required) Data files. Only supports CSV and TXT files. The file suffixes should be exactly |
|
| (Required) The file's MD5, which is used for server-side verification. |
|
| (Required) Encryption type. The value for this field must be consistent with the actual file data. For enum values, see Enumeration - Encryption Type. |
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:
Field | Data Type | Description |
---|---|---|
|
| (Required) Authorized access token. For details, see Authentication. |
|
| (Required)
|
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) Advertiser ID. |
|
| (Required) Audience name. Maximum of 128 characters. |
|
| Audience sub type, indicating the type of ads that the audience can be used. Enum values:
|
|
| (Required) List of file paths, not exceeding 500. |
|
| (Required) Encryption type. |
|
| Number of days to retain the audience.
|
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
, andREMOVE
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 unfinishedREPLACE
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
andexpired_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:
Field | Data Type | Description |
---|---|---|
|
| (Required) Authorized access token. For details, see Authentication. |
|
| (Required)
|
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) Advertiser ID. |
|
| (Required) Custom audience ID. |
|
| (Conditional) You must pass in either this field or New name for the audience. Length limit: 128 characters. |
|
| Audience sub type, indicating the type of ads that the audience can be used for.
|
|
| (Conditional) You must pass in either this field or The files you upload to update the Customer File audience. |
|
| Modification type. This field is valid when
Default value: The |
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:
Field | Data Type | Description |
---|---|---|
|
| (Required) Authorized access token. For details, see Authentication. |
|
| (Required)
|
Parameters:
Field | Data Type | Description |
---|---|---|
|
| (Required) Advertiser ID. |
|
| (Required) A list of Audience IDs. Length range is |
A successful POST
will return an OK
message and an empty data set.
HTTPS/1.1 200 OK
{
"message": "OK",
"code": 0,
"data": {}
}