Skip to main content
Skip table of contents

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:

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:

CODE
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.

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

Content-Type

string

(Required)

"application/json".

Parameters:

Field

Data Type

Description

app_id

string

(Required)

The App ID applied by the developer. It can be found in the Basic Information section for you app under My Apps.

auth_code

string

(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.

secret

string

(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:

JSON
{
  "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

Access-Token

string

(Required)

Authorized access token. For details, see Authentication.

Content-Type

string

(Required)

multipart/form-data

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

Field

Data Type

Description

advertiser_id

string

(Required)

Advertiser ID.

file

file

(Required)

Data files. Only supports CSV and TXT files. The file suffixes should be exactly .csv or .txt.

file_signature

string

(Required)

The file's MD5, which is used for server-side verification.

calculate_type

string

(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:

CODE
"--" + 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:

JSON
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

Access-Token

string

(Required)

Authorized access token. For details, see Authentication.

Content-Type

string

(Required)

"application/json".

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:

JSON
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:

Field

Data Type

Description

Access-Token

string

(Required)

Authorized access token. For details, see Authentication.

Content-Type

string

(Required)

"application/json".

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:

JSON
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

Access-Token

string

(Required)

Authorized access token. For details, see Authentication.

Content-Type

string

(Required)

"application/json".

Parameters:

Field

Data Type

Description

advertiser_id

string

(Required)

Advertiser ID.

custom_audience_ids

string[]

(Required)

A list of Audience IDs. Length range is [1, 100].

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

JSON
HTTPS/1.1 200 OK
{
    "message": "OK",
    "code": 0,
    "data": {}
}
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.