openapi: 3.2.0 info: title: TikTok API for Business — Marketing Audience API description: TikTok API for Business (Marketing API) v1.3. This document is a mechanical union of the 202 per-operation OpenAPI 3.0.1 documents TikTok publishes in yml_files/ of its own SDK repository (https://github.com/tiktok/tiktok-business-api-sdk), which are the swagger-codegen inputs for TikTok's first-party Java/Python/JavaScript SDKs. Operation content (paths, parameters, responses, tags and the x-open-* extensions) is preserved verbatim; only info, servers and components.securitySchemes were written by API Evangelist, because the per-operation fragments carry placeholder info blocks and no servers block. The servers values are the production and sandbox base URLs TikTok documents at https://business-api.tiktok.com/portal/docs?id=1738855331457026 . version: v1.3 contact: name: TikTok API for Business support url: https://business-api.tiktok.com/portal/docs?id=1795190020378625 termsOfService: https://business-api.tiktok.com/portal/docs?id=1737191804348417 x-source: https://github.com/tiktok/tiktok-business-api-sdk/tree/main/yml_files x-harvested-by: API Evangelist enrichment pipeline x-harvested: '2026-08-13' servers: - url: https://business-api.tiktok.com/open_api/v1.3 description: Production - url: https://sandbox-ads.tiktok.com/open_api/v1.3 description: Sandbox security: - AccessToken: [] tags: - name: Audience paths: /audience/insight/overlap/: get: operationId: Audience Insight Overlap parameters: - description: '' in: query name: advertiser_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.advertiser_id x-open-field-id: 1 - description: '' in: query name: benchmark_custom_audience_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.benchmark_custom_audience_id x-open-field-id: 2 - description: '' in: query name: comparison_custom_audience_ids required: false schema: items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) maxItems: 4 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-source: $.http.query.comparison_custom_audience_ids x-open-field-id: 3 - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Get details of audience overlap. [Audience Insight Overlap](https://business-api.tiktok.com/portal/docs?id=1797023590780930) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.query.advertiser_id type: number - name: benchmark_custom_audience_id required: true source: $.http.query.benchmark_custom_audience_id type: number - children: - type: number is_expand: true name: comparison_custom_audience_ids required: false source: $.http.query.comparison_custom_audience_ids sub_type: number type: array - children: - name: core_user_id required: false source: $.http.query.context_info.core_user_id type: number is_expand: true name: context_info required: false source: $.http.query.context_info type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.query.advertiser_id benchmark_custom_audience_id: $.http.query.benchmark_custom_audience_id comparison_custom_audience_ids: $.http.query.comparison_custom_audience_ids context_info: $.http.query.context_info response_cookie: [] response_header: [] response_rule: benchmark_audience: $.rpc.output.benchmark_audience comparison_audiences: $.rpc.output.comparison_audiences x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: true /dmp/custom_audience/apply/: post: operationId: Dmp Custom_audience Apply parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: action_mode: description: 'Specific operation to be performed on the audience. Enum values: Apply, Disconnect.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: null enum_package_name: null enums: - description: '' is_valid: true key: Apply value: Apply - description: '' is_valid: true key: Disconnect value: Disconnect key_format: string strict: true use_part: false validate_only: false value_format: string x-open-field-id: 4 x-open-source: $.http.body.action_mode adgroup_ids: description: 'A list of ad group IDs. Note: adgroup_ids and custom_audience_id should be under the same advertiser account. Otherwise, an error will occur. Lookalike Audience cannot be used in Reach & Frequency ads. Otherwise, an error will occur. See below for more details. 1. If the custom_audience_id is a Lookalike Audience and the adgroup_ids are Reach & Frequency ad groups, an error will occur. 2. If the custom_audience_id is a Lookalike Audience with the REACH_FREQUENCY audience subtype, an error will occur.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.adgroup_ids advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id custom_audience_id: description: Custom audience ID. You can only pass one custom audience ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 2 x-open-source: $.http.body.custom_audience_id usage_mode: description: 'Whether to include this audience in or exclude it from your ad groups. Required when action_mode is Apply. Enum values: Include, Exclude.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: null enum_package_name: null enums: - description: '' is_valid: true key: Include value: Include - description: '' is_valid: true key: Exclude value: Exclude key_format: string strict: true use_part: false validate_only: false value_format: string x-open-field-id: 5 x-open-source: $.http.body.usage_mode required: - advertiser_id - custom_audience_id - adgroup_ids - action_mode type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Apply a shared custom audience [Dmp Custom_audience Apply](https://ads.tiktok.com/marketing_api/docs?id=1740245827044354) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: custom_audience_id required: true source: $.http.body.custom_audience_id type: number - children: - type: number is_expand: true name: adgroup_ids required: true source: $.http.body.adgroup_ids sub_type: number type: array - name: action_mode required: true source: $.http.body.action_mode type: string - name: usage_mode required: false source: $.http.body.usage_mode type: string - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: action_mode: $.http.body.action_mode adgroup_ids: $.http.body.adgroup_ids advertiser_id: $.http.body.advertiser_id context_info: core_user_id: $.context.core_user_id custom_audience_id: $.http.body.custom_audience_id usage_mode: $.http.body.usage_mode response_cookie: [] response_header: [] response_rule: null x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/apply/log/: get: operationId: Dmp Custom_audience Apply Log parameters: - description: Advertiser ID. in: query name: advertiser_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.advertiser_id x-open-field-id: 1 - content: application/json: schema: items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-source: $.http.query.custom_audience_ids description: A list of custom audience IDs. Note The advertiser must be the owner of the custom_audience_ids. Otherwise, an error will occur. You can use the is_creator field returned in /dmp/custom_audience/list/ and /dmp/custom_audience/get/ to check whether this advertiser is the owner of this audience. in: query name: custom_audience_ids required: true x-open-field-id: 2 - description: 'Current page number. Default value: 1.' in: query name: page required: false schema: default: 1 format: int32 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.page x-open-field-id: 3 - description: 'Page size. Default value: 10.' in: query name: page_size required: false schema: default: 10 format: int32 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.page_size x-open-field-id: 4 - description: The timezone of returned value. For enum values, see Appendix - Time Zone. If not specified, UTC will be used. in: query name: timezone required: false schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-source: $.http.query.timezone x-open-field-id: 5 - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Get the latest application log of custom audiences [Dmp Custom_audience Apply Log](https://ads.tiktok.com/marketing_api/docs?id=1758615737388033) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.query.advertiser_id type: number - children: - type: number is_expand: true name: custom_audience_ids required: true source: $.http.query.custom_audience_ids sub_type: number type: array - name: page required: false source: $.http.query.page type: number - name: page_size required: false source: $.http.query.page_size type: number - name: timezone required: false source: $.http.query.timezone type: string - children: - name: app_id required: false source: $.context.app_id type: number - name: core_user_id required: false source: $.context.core_user_id type: number - name: developer_id required: false source: $.context.developer_id type: number - name: x_forwarded_for required: false source: $.context.is_same_identity type: string - name: x_real_ip required: false source: $.context.source_ip type: string is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.query.advertiser_id context_info: app_id: $.context.app_id core_user_id: $.context.core_user_id developer_id: $.context.developer_id x_forwarded_for: $.context.is_same_identity x_real_ip: $.context.source_ip custom_audience_ids: $.http.query.custom_audience_ids page: $.http.query.page page_size: $.http.query.page_size timezone: $.http.query.timezone response_cookie: [] response_header: [] response_rule: advertiser_id: $.rpc.output.advertiser_id list[][]: - action_timestamp: $.rpc.output.data[].action_timestamp adgroup_id: $.rpc.output.data[].adgroup_id adgroup_name: $.rpc.output.data[].adgroup_name audience_id: $.rpc.output.data[].audience_id editor: $.rpc.output.data[].editor usage_mode: $.rpc.output.data[].usage_mode page_info: $.rpc.output.page_info x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/create/: post: operationId: Dmp Custom_audience Create parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id audience_enhancement: default: 'False' description: '' type: boolean x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 7 x-open-source: $.http.body.audience_enhancement audience_sub_type: default: NORMAL description: '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. REACH_FREQUENCY: Audience for Reach & Frequency. It can only be used in R&F ads. Default: NORMAL.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1804315821131778 enum_package_name: AudienceSubType enums: - description: '' is_valid: true key: NORMAL value: '0' - description: '' is_valid: true key: REACH_FREQUENCY value: '1' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 5 x-open-source: $.http.body.audience_sub_type calculate_type: description: 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. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1804315795490817 enum_package_name: CalculateType enums: - description: '' is_valid: true key: EMAIL_SHA256 value: '8' - description: '' is_valid: true key: FIRST_MD5 value: '7' - description: '' is_valid: true key: FIRST_SHA256 value: '6' - description: '' is_valid: true key: GAID_MD5 value: '13' - description: '' is_valid: true key: GAID_SHA256 value: '16' - description: '' is_valid: true key: IDFA_MD5 value: '12' - description: '' is_valid: true key: IDFA_SHA256 value: '15' - description: '' is_valid: true key: MULTIPLE_TYPES value: '100' - description: '' is_valid: true key: PHONE_SHA256 value: '9' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 3 x-open-source: $.http.body.calculate_type custom_audience_name: description: Audience name. Maximum of 128 characters. maxLength: 128 minLength: 1 type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.custom_audience_name file_paths: description: List of file paths. The recommended size is <50 to ensure a stable request. You can use /dmp/custom_audience/update/ to append more data files to the audience. You get the file_path in response after you upload your file calling Upload audience files endpoint. items: default: '' maxLength: 16 minLength: 16 type: string x-open-allow-strlist: false x-open-allow-strnum: false maxItems: 500 minItems: 1 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.file_paths retention_in_days: description: 'Number of days to retain the audience. Value range: [1, 365]. Note: 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.' format: int32 maximum: 365 minimum: 1 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 6 x-open-source: $.http.body.retention_in_days required: - advertiser_id - custom_audience_name - calculate_type - file_paths type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Create an audience by file [Dmp Custom_audience Create](https://ads.tiktok.com/marketing_api/docs?id=1739940570793985) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: custom_audience_name required: true source: $.http.body.custom_audience_name type: string - name: calculate_type required: true source: $.http.body.calculate_type type: number - children: - type: string is_expand: true name: file_paths required: true source: $.http.body.file_paths[] sub_type: string type: array - name: audience_sub_type required: false source: $.http.body.audience_sub_type type: number - name: retention_in_days required: false source: $.http.body.retention_in_days type: number - name: audience_enhancement required: false source: $.http.body.audience_enhancement type: boolean plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id audience_enhancement: $.http.body.audience_enhancement audience_sub_type: $.http.body.audience_sub_type calculate_type: $.http.body.calculate_type custom_audience_name: $.http.body.custom_audience_name file_paths: $.http.body.file_paths[] retention_in_days: $.http.body.retention_in_days response_cookie: [] response_header: [] response_rule: custom_audience_id: $.rpc.output.custom_audience_id x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/delete/: post: operationId: Dmp Custom_audience Delete parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id custom_audience_ids: description: A list of Audience IDs. Length range is [1, 100]. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) maxItems: 100 minItems: 1 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.custom_audience_ids required: - advertiser_id - custom_audience_ids type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Delete audiences [Dmp Custom_audience Delete](https://business-api.tiktok.com/portal/docs?id=1739940539757569) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - children: - type: number is_expand: true name: custom_audience_ids required: true source: $.http.body.custom_audience_ids[] sub_type: number type: array plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id custom_audience_ids: $.http.body.custom_audience_ids[] response_cookie: [] response_header: [] response_rule: null x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/file/upload/: post: operationId: Dmp Custom_audience File Upload parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: multipart/form-data: schema: properties: advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id calculate_type: description: Encryption type. The value for this field must be consistent with the actual file data. Otherwise, your upload will fail or you will not be able to create a valid audience. For enum values, see Enumeration - Encryption Type. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1812020346560514 enum_package_name: DmpCalculateType enums: - description: '' is_valid: true key: EMAIL_SHA256 value: '8' - description: '' is_valid: true key: FIRST_MD5 value: '7' - description: '' is_valid: true key: FIRST_SHA256 value: '6' - description: '' is_valid: true key: GAID_MD5 value: '13' - description: '' is_valid: true key: GAID_SHA256 value: '16' - description: '' is_valid: true key: IDFA_MD5 value: '12' - description: '' is_valid: true key: IDFA_SHA256 value: '15' - description: '' is_valid: true key: MAID_MD5 value: '7' - description: '' is_valid: true key: MAID_SHA256 value: '6' - description: '' is_valid: true key: MULTIPLE_TYPES value: '100' - description: '' is_valid: true key: PHONE_SHA256 value: '9' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 4 x-open-source: $.http.body.calculate_type file: description: Data files. Only supports CSV and TXT files. The file suffixes should exactly be .csv or .txt. format: binary type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.file file_signature: description: The file's MD5, which is used for server-side verification. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.file_signature name: description: '' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 5 required: - advertiser_id - file - file_signature - calculate_type type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Upload a data file [Dmp Custom_audience File Upload](https://business-api.tiktok.com/portal/docs?id=1739940567842818) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: file required: true source: $.http.body.file type: string - name: file_signature required: true source: $.http.body.file_signature type: string - name: calculate_type required: true source: $.http.body.calculate_type type: number - children: - name: app_id required: false source: $.context.app_id type: number - name: core_user_id required: false source: $.context.core_user_id type: number - name: developer_id required: false source: $.context.developer_id type: number is_expand: true name: context_info required: false type: object - name: name required: false source: $.http.body.name type: string plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id calculate_type: $.http.body.calculate_type context_info: app_id: $.context.app_id core_user_id: $.context.core_user_id developer_id: $.context.developer_id file: $.http.body.file file_signature: $.http.body.file_signature name: $.http.body.name response_cookie: [] response_header: [] response_rule: file_path: $.rpc.output.file_path x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/get/: get: operationId: Dmp Custom_audience Get parameters: - description: Advertiser ID. in: query name: advertiser_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.advertiser_id x-open-field-id: 1 - content: application/json: schema: items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) maxItems: 100 minItems: 1 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-source: $.http.query.custom_audience_ids description: A list of Audience IDs. Length range is [1, 100] . in: query name: custom_audience_ids required: true x-open-field-id: 2 - description: The size of the history data which the user requests. in: query name: history_size required: false schema: default: 100 format: int32 maximum: 100 minimum: 1 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.history_size x-open-field-id: 3 - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Obtain the details of specified audiences [Dmp Custom_audience Get](https://business-api.tiktok.com/portal/docs?id=1739940507792385) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.query.advertiser_id type: number - children: - type: number is_expand: true name: custom_audience_ids required: true source: $.http.query.custom_audience_ids[] sub_type: number type: array - name: history_size required: false source: $.http.query.history_size type: number plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.query.advertiser_id custom_audience_ids: $.http.query.custom_audience_ids[] history_size: $.http.query.history_size response_cookie: [] response_header: [] response_rule: list[][]: - audience_details[]: - audience_enhancement: $.rpc.output.data[].audience_details.audience_enhancement audience_id: $.rpc.output.data[].audience_details.audience_id audience_sub_type: $.rpc.output.data[].audience_details.audience_sub_type calculate_type: $.rpc.output.data[].audience_details.calculate_type cover_num: $.rpc.output.data[].audience_details.cover_num create_time: $.rpc.output.data[].audience_details.create_time enhancement_status: $.rpc.output.data[].audience_details.enhancement_status error_msg: $.rpc.output.data[].audience_details.err_msg expired_time: $.rpc.output.data[].audience_details.expired_time is_auto_refresh: $.rpc.output.data[].audience_details.is_auto_refresh is_creator: $.rpc.output.data[].audience_details.is_creator is_expiring: $.rpc.output.data[].audience_details.is_expiring is_valid: $.rpc.output.data[].audience_details.is_valid lookalike_spec[]: - audience_size: $.rpc.output.data[].audience_details.lookalike_spec.lookalike_num include_source: $.rpc.output.data[].audience_details.lookalike_spec.is_contain_seed location_ids: $.rpc.output.data[].audience_details.lookalike_spec.country_ids mobile_os: $.rpc.output.data[].audience_details.lookalike_spec.platform placements: $.rpc.output.data[].audience_details.lookalike_spec.app_names source_audience_id: $.rpc.output.data[].audience_details.lookalike_spec.seed_id msg: $.rpc.output.data[].audience_details.msg name: $.rpc.output.data[].audience_details.name owner_id: $.rpc.output.data[].audience_details.owner_id rule: $.rpc.output.data[].audience_details.rule shared: $.rpc.output.data[].audience_details.shared type: $.rpc.output.data[].audience_details.type audience_history[][]: - action: $.rpc.output.data[].audience_history[].action action_detail: $.rpc.output.data[].audience_history[].action_detail editor: $.rpc.output.data[].audience_history[].editor msg: $.rpc.output.data[].audience_history[].msg opt_time: $.rpc.output.data[].audience_history[].opt_time x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/list/: get: operationId: Dmp Custom_audience List parameters: - description: Advertiser ID. in: query name: advertiser_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.advertiser_id x-open-field-id: 1 - content: application/json: schema: items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) maxItems: 100 minItems: 1 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-source: $.http.query.custom_audience_ids description: A list of Audience IDs. Length range is [1, 100]. in: query name: custom_audience_ids required: false x-open-field-id: 2 - description: 'Current page number. Default value: 1. Value range: ≥ 1.' in: query name: page required: false schema: default: 1 format: int32 minimum: 1 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.page x-open-field-id: 3 - description: 'Page size. Defaults is 10. Value range: 1-100.' in: query name: page_size required: false schema: default: 10 format: int32 maximum: 100 minimum: 1 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.page_size x-open-field-id: 4 - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Get all audiences [Dmp Custom_audience List](https://business-api.tiktok.com/portal/docs?id=1739940506015746) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.query.advertiser_id type: number - children: - type: number is_expand: true name: custom_audience_ids required: false source: $.http.query.custom_audience_ids[] sub_type: number type: array - name: page required: false source: $.http.query.page type: number - name: page_size required: false source: $.http.query.page_size type: number plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.query.advertiser_id custom_audience_ids: $.http.query.custom_audience_ids[] page: $.http.query.page page_size: $.http.query.page_size response_cookie: [] response_header: [] response_rule: list: $.rpc.output.data page_info: $.rpc.output.page_info x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/lookalike/create/: post: operationId: Dmp Custom_audience Lookalike Create parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id custom_audience_name: description: Audience name. Maximum of 128 characters. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.custom_audience_name lookalike_spec: description: '' properties: audience_size: description: 'Size of lookalike audience. Enum values: NARROW, BALANCED and BROAD.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1808692160894978 enum_package_name: DmpLookalikeAudienceSizeType enums: - description: '' is_valid: true key: BALANCED value: '20' - description: '' is_valid: true key: BROAD value: '30' - description: '' is_valid: true key: NARROW value: '10' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 6 x-open-source: $.http.body.lookalike_spec.lookalike_num include_source: description: Whether to include the source audience in the new lookalike audience. type: boolean x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.lookalike_spec.is_contain_seed location_ids: description: IDs of the locations that you want to target. For enum values, see Enumeration-Lookalike Locations. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false minItems: 1 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 5 x-open-source: $.http.body.lookalike_spec.country_ids mobile_os: description: Device operating systems. Enum values support ALL for both ANDROID and IOS. See Enumeration-Audience Management-Lookalike System for details. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1828094114965570 enum_package_name: DmpLookalikePlatform enums: - description: '' is_valid: true key: ALL value: ALL - description: '' is_valid: true key: ANDROID value: ANDROID - description: '' is_valid: true key: IOS value: IOS key_format: string strict: true use_part: false validate_only: false value_format: string x-open-field-id: 3 x-open-source: $.http.body.lookalike_spec.platform placements: description: 'The apps where you want to deliver your ads. Enum values: TikTok, TopBuzz & BuzzVideo, Pangle. See Enumeration - Audience Management-Lookalike Placement for details.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.lookalike_spec.app_names source_audience_id: description: 'Source (seed) audience ID. Source audience cannot be an existing lookalike audience. Note: The size of source audience should be no less than 100.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.lookalike_spec.seed_id required: - source_audience_id - include_source - mobile_os - placements - location_ids - audience_size type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.lookalike_spec required: - advertiser_id - custom_audience_name - lookalike_spec type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Create a lookalike audience [Dmp Custom_audience Lookalike Create](https://business-api.tiktok.com/portal/docs?id=1739940511844353) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: custom_audience_name required: true source: $.http.body.custom_audience_name type: string - children: - name: seed_id required: false source: $.http.body.lookalike_spec.source_audience_id type: number - name: is_contain_seed required: false source: $.http.body.lookalike_spec.include_source type: boolean - name: platform required: false source: $.http.body.lookalike_spec.mobile_os type: string - children: - type: string is_expand: true name: app_names required: false source: $.http.body.lookalike_spec.placements[] sub_type: string type: array - children: - type: string is_expand: true name: country_ids required: false source: $.http.body.lookalike_spec.location_ids[] sub_type: string type: array - name: lookalike_num required: false source: $.http.body.lookalike_spec.audience_size type: number is_expand: true name: lookalike_spec required: true type: object - children: - name: app_id required: false source: $.context.app_id type: number - name: core_user_id required: false source: $.context.core_user_id type: number - name: developer_id required: false source: $.context.developer_id type: number is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id context_info: app_id: $.context.app_id core_user_id: $.context.core_user_id developer_id: $.context.developer_id custom_audience_name: $.http.body.custom_audience_name lookalike_spec: app_names: $.http.body.lookalike_spec.placements[] country_ids: $.http.body.lookalike_spec.location_ids[] is_contain_seed: $.http.body.lookalike_spec.include_source lookalike_num: $.http.body.lookalike_spec.audience_size platform: $.http.body.lookalike_spec.mobile_os seed_id: $.http.body.lookalike_spec.source_audience_id response_cookie: [] response_header: [] response_rule: custom_audience_id: $.rpc.output.custom_audience_id x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/lookalike/update/: post: operationId: Dmp Custom_audience Lookalike Update parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id custom_audience_ids: description: A list of custom audience IDs. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.custom_audience_ids required: - advertiser_id - custom_audience_ids type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Manually refresh a Lookalike Audience [Dmp Custom_audience Lookalike Update](https://ads.tiktok.com/marketing_api/docs?id=1758616888158209) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - children: - type: number is_expand: true name: custom_audience_ids required: true source: $.http.body.custom_audience_ids sub_type: number type: array - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id context_info: core_user_id: $.context.core_user_id custom_audience_ids: $.http.body.custom_audience_ids response_cookie: [] response_header: [] response_rule: null x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/rule/create/: post: operationId: Dmp Custom_audience Rule Create parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id audience_enhancement: default: false description: '' type: boolean x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 11 audience_sub_type: description: 'Audience sub type, indicating the type of ads that the audience can be used. Enum values: NORMAL: Audience for non-Reach & Frequency ads. REACH_FREQUENCY: Audience for Reach & Frequency ads. It can only be used in Reach & Frequency ads. Default value: NORMAL.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1804315821131778 enum_package_name: AudienceSubType enums: - description: '' is_valid: true key: NORMAL value: '0' - description: '' is_valid: true key: REACH_FREQUENCY value: '1' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 4 x-open-source: $.http.body.audience_sub_type audience_type: description: 'Audience type. Enum values: ENGAGEMENT: Engagement Audience (with asset type as ad groups). ENGAGEMENT_ORGANIC_VIDEO: Organic Engagement Audience (with asset type as public video). ENGAGEMENT_LIVE_VIDEO: Live Engagement Audience (with asset type as live video). APP: App Activity Audience. PIXEL: Website Traffic Audience. LEAD_GENERATION: Lead Generation Audience. BUSINESS_ACCOUNT: Business Account Audience. TIKTOK_SHOP: Shop Activity Audience. OFFLINE: Offline Activity Audience.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1805510940313602 enum_package_name: SecondPartyAudienceType enums: - description: '' is_valid: true key: APP value: '3' - description: '' is_valid: true key: BUSINESS_ACCOUNT value: '16' - description: '' is_valid: true key: ENGAGEMENT value: '2' - description: '' is_valid: true key: ENGAGEMENT_LIVE_VIDEO value: '200' - description: '' is_valid: true key: ENGAGEMENT_ORGANIC_VIDEO value: '100' - description: '' is_valid: true key: LEAD_GENERATION value: '15' - description: '' is_valid: true key: OFFLINE value: '25' - description: '' is_valid: true key: PIXEL value: '4' - description: '' is_valid: true key: TIKTOK_SHOP value: '21' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 3 x-open-source: $.http.body.audience_type custom_audience_name: description: 'Audience name. Length limit: 128 characters.' maxLength: 128 type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.custom_audience_name identity_authorized_bc_id: description: Required when identity_type is BC_AUTH_TT. ID of the Business Center that a TikTok Account User in Business Center identity is associated with. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 9 x-open-source: $.http.body.identity_authorized_bc_id identity_id: description: Required when audience_type is ENGAGEMENT_LIVE_VIDEO or ENGAGEMENT_ORGANIC_VIDEO. Identity ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 7 x-open-source: $.http.body.identity_id identity_type: description: 'Required when audience_type is ENGAGEMENT_LIVE_VIDEO or ENGAGEMENT_ORGANIC_VIDEO. Identity type. Enum values: TT_USER, BC_AUTH_TT' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1800331041544193 enum_package_name: IdentityType enums: - description: '' is_valid: true key: AUTH_CODE value: '2' - description: '' is_valid: true key: BC_AUTH_TT value: '5' - description: '' is_valid: true key: BC_SELF_TT value: '4' - description: '' is_valid: true key: CUSTOMIZED_USER value: '1' - description: '' is_valid: true key: TT_USER value: '3' - description: '' is_valid: true key: UNSET value: '0' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 8 x-open-source: $.http.body.identity_type is_auto_refresh: description: 'Whether to turn on the audience auto-refresh function. Supported values: true, false. Default value: true. If you enable this feature, your audience will automatically refresh to include the latest user data according to the lookback window you set. If you disable this feature, your audience will not automatically refresh.' type: boolean x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 6 x-open-source: $.http.body.is_auto_refresh retention_in_days: description: 'Number of days to retain the audience. Value range: 1-365. Note: 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.' format: int32 maximum: 365 minimum: 1 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 5 x-open-source: $.http.body.retention_in_days rule_spec: description: Rule of the audience. properties: exclusion_rule_set: description: '' properties: operator: description: 'Required when exclusion_rule_set is passed. Operator between the exclusion rules within the exclusion rule set. Enum value: OR.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1805510775614465 enum_package_name: RuleSetOperatorType enums: - description: '' is_valid: true key: OR value: '2' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 1 x-open-source: $.http.body.rule_spec.exclusion_rule_set.operator rules: description: Required when exclusion_rule_set is passed. A list of exclusion rules within the exclusion rule set. items: properties: event_source_ids: description: List of event source IDs of the rule. For an Engagement Audience, use ad group IDs as event source IDs. If not specified, all available event source IDs will be used. For an Organic Engagement Audience, use TikTok post IDs as event source IDs. You can use /identity/video/get/ to get TikTok post IDs. The maximum allowed number of TikTok post IDs is 10. For a Live Engagement Audience, use live video ID as event source IDs. You can use /identity/live/get/ to get live video IDs. The maximum allowed number of live video IDs is 10. For an App Activity Audience, use App IDs as event source IDs. For a Website Traffic Audience, use pixel IDs as event source IDs. For a Lead Generation Audience, do not pass in this field. Otherwise, an error will occur. If not specified, all available event source IDs will be used. For a Business Account Audience, use core user IDs of the advertisers. You can use /user/info/ to get a core user ID. For a Shop Activity Audience, use TikTok Shop IDs as event source IDs. You can use /store/list/ to get TikTok Shop IDs. For an Offline Activity Audience, use Offline Event set IDs as event source IDs. You can use /offline/get/ to get Offline Event set IDs. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].event_source_ids filter_set: description: Required when exclusion_rule_set is passed. The set of filters for the exclusion rule. properties: filters: description: 'Required when exclusion_rule_set is passed. An array of filters on previous audience actions and optionally also on URL keywords or parameters. Max size: 1.' items: properties: field: description: 'Required when exclusion_rule_set is passed. Filter field. Enum value: EVENT: To exclude the people who''ve carried out a certain action in the past few days as indicated by retention_days.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].field operator: description: 'Required when exclusion_rule_set is passed. Filter operator between filter field and filter value. Enum value: EQ: equals.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1805510758672386 enum_package_name: FilterFieldOperatorType enums: - description: '' is_valid: true key: EQ value: '1' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 2 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].operator parameter_filters: description: 'List of filters on URL keywords or parameters. Within parameter_filters, you can add a maximum of one URL keyword filter (with field set to URL) and 10 parameter filters (with field not set to URL) . If specified, these filters (parameter_filters) are combined with the action filter (as specified by field, operator and value) using default AND logic to form the exclusion rule. For example, if retention_days is 30 and filter_set is set to {"operator": "OR", "filters":[{"field":"EVENT","operator":"EQ", "value":"PIXEL COMPLETE PAYMENT"},"parameter_filters":[{"field":"URL","operator":"CONTAINS","value":"us"}]]}, the exclusion rule will create an audience that excludes people who carried out the "Complete Payment" action on a webpage with "us" included in the page URL within the past 30 days on the website where the Pixel is installed.' items: properties: field: description: 'Required when parameter_filters within exclusion_rule_set is passed. Filter condition. Use this field to specify whether to filter URL keywords, or Web Event parameters reported via the Pixel. Enum value: URL: URL keywords. CONTENT_TYPE: the parameter content_type. PRICE: the parameter price. VALUE: the parameter value. CONTENT_ID: the parameter content_id. CONTENT_CATEGORY: the parameter content_category.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].field operator: description: 'Required when parameter_filters within exclusion_rule_set is passed. Filter operator between filter condition and filter value. Enum value: CONTAINS: contains. DOES_NOT_CONTAIN: doesn''t contain. EQ: equals. IS_LESS_THAN: is less than. IS_GREATER_THAN: is greater than. IS_LESS_THAN_OR_EQUAL_TO: is less than or equal to. IS_GRETER_THAN_OR_EQUAL_TO: is greater than or equal to. The allowed values vary based on the field value: If field is set to URL, operator can only be set to CONTAINS, DOES_NOT_CONTAIN, or EQ. If field is not set to URL, operator can be set to CONTAINS, DOES_NOT_CONTAINS, EQ, IS_LESS_THAN, IS_GREATER_THAN, IS_LESS_THAN_OR_EQUAL_TO, or IS_GREATER_THAN_OR_EQUAL_TO.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1813841099262977 enum_package_name: ParameterFilterOperatorType enums: - description: '' is_valid: true key: CONTAINS value: '3' - description: '' is_valid: true key: DOES_NOT_CONTAIN value: '4' - description: '' is_valid: true key: EQ value: '1' - description: '' is_valid: true key: IS_GREATER_THAN value: '5' - description: '' is_valid: true key: IS_GREATER_THAN_OR_EQUAL_TO value: '6' - description: '' is_valid: true key: IS_LESS_THAN value: '7' - description: '' is_valid: true key: IS_LESS_THAN_OR_EQUAL_TO value: '8' - description: '' is_valid: true key: NOT_EQUAL value: '2' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 2 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].operator values: description: 'Required when parameter_filters within exclusion_rule_set is passed. A list of filter values. Max size: 10. Length limit for each value: 100 characters. If you specify multiple values, the values will be combined using OR logic.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].values required: - field - operator - values type: object x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters value: description: Required when exclusion_rule_set is passed. Filter value. For enum values, see Enumeration - Filter Value. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].value required: - field - operator - value type: object x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters operator: description: 'Required when exclusion_rule_set is passed. Operator between filters in the filters object array. Enum value: OR. Within each exclusion rule, you can only specify one object in filters.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1805510742984706 enum_package_name: FilterSetOperatorType enums: - description: '' is_valid: true key: AND value: '1' - description: '' is_valid: true key: OR value: '2' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 2 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.operator required: - filters - operator type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set retention_days: description: 'Required when exclusion_rule_set is passed. Audience lookback window. For enum values, see Enumerations - Lookback window. Note: If audience_type = BUSINESS_ACCOUNT, and the value in the filters object is not BUSINESS ACCOUNT PROFILE FOLLOW, then retention_days must be 7, 14, or 30. If audience_type = ENGAGEMENT_LIVE_VIDEO or ENGAGEMENT_ORGANIC_VIDEO, then retention_days must be 7, 14, or 30. To avoid confusion between retention_days and retention_in_days, we''ll rename retention_days in the next API version.' format: int32 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules[].retention_days required: - retention_days type: object x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.rule_spec.exclusion_rule_set.rules required: - operator - rules type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.rule_spec.exclusion_rule_set inclusion_rule_set: description: Details of the inclusion rule set. properties: operator: description: 'Operator between the inclusion rules within the inclusion rule set. Enum value: OR. If you provide more than one inclusion rule, the inclusion rules will be combined using OR logic to broaden the audience.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1805510775614465 enum_package_name: RuleSetOperatorType enums: - description: '' is_valid: true key: OR value: '2' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 1 x-open-source: $.http.body.rule_spec.inclusion_rule_set.operator rules: description: A list of inclusion rules within the inclusion rule set. items: properties: event_source_ids: description: Required when audience_type is not ENGAGEMENT or LEAD_GENERATION. List of event source IDs of the rule. For an Engagement Audience, use ad group IDs as event source IDs. If not specified, all available event source IDs will be used. For an Organic Engagement Audience, use TikTok post IDs as event source IDs. You can use /identity/video/get/ to get TikTok post IDs. The maximum allowed number of TikTok post IDs is 10. For a Live Engagement Audience, use live video ID as event source IDs. You can use /identity/live/get/ to get live video IDs. The maximum allowed number of live video IDs is 10. For an App Activity Audience, use App IDs as event source IDs. For a Website Traffic Audience, use pixel IDs as event source IDs. For a Lead Generation Audience, do not pass in this field. Otherwise, an error will occur. If not specified, all available event source IDs will be used. For a Business Account Audience, use core user IDs of the advertisers. You can use /user/info/ to get a core user ID. For a Shop Activity Audience, use TikTok Shop IDs as event source IDs. You can use /store/list/ to get TikTok Shop IDs. For an Offline Activity Audience, use Offline Event set IDs as event source IDs. You can use /offline/get/ to get Offline Event set IDs. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].event_source_ids filter_set: description: The set of filters for each inclusion rule. properties: filters: description: 'An array of filters on previous audience actions and optionally also on URL keywords or parameters. Max size: 1.' items: properties: field: description: 'Filter field. Enum value: EVENT: To include the people who''ve carried out a certain action in the past few days as indicated by retention_days.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].field operator: description: 'Filter operator between filter field and filter value. Enum value: EQ: equals.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1805510758672386 enum_package_name: FilterFieldOperatorType enums: - description: '' is_valid: true key: EQ value: '1' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 2 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].operator parameter_filters: description: 'List of filters on URL keywords or parameters. Within parameter_filters, you can add a maximum of one URL keyword filter (with field set to URL) and 10 parameter filters (with field not set to URL) . If specified, these filters (parameter_filters) are combined with the action filter (as specified by field, operator and value) using default AND logic to form the inclusion rule. For example, if retention_days is 30 and filter_set is set to {"operator": "OR", "filters":[{"field":"EVENT","operator":"EQ", "value":"PIXEL COMPLETE PAYMENT"},"parameter_filters":[{"field":"URL","operator":"CONTAINS","value":"us"}]]}, the inclusion rule will create an audience that includes people who carried out the "Complete Payment" action on a webpage with "us" included in the page URL within the past 30 days on the website where the Pixel is installed.' items: properties: field: description: 'Required when parameter_filters within inclusion_rule_set is passed. Filter condition. Use this field to specify whether to filter URL keywords, or Web Event parameters reported via the Pixel. Enum value: URL: URL keywords. CONTENT_TYPE: the parameter content_type. PRICE: the parameter price. VALUE: the parameter value. CONTENT_ID: the parameter content_id. CONTENT_CATEGORY: the parameter content_category.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].field x-open-validate: - error_msg: '' expr: '%s in ["URL", "CONTENT_TYPE", "PRICE", "VALUE", "CONTENT_ID", "CONTENT_CATEGORY"]' operator: description: 'Required when parameter_filters within inclusion_rule_set is passed. Filter operator between filter condition and filter value. Enum value: CONTAINS: contains. DOES_NOT_CONTAIN: doesn''t contain. EQ: equals. IS_LESS_THAN: is less than. IS_GREATER_THAN: is greater than. IS_LESS_THAN_OR_EQUAL_TO: is less than or equal to. IS_GRETER_THAN_OR_EQUAL_TO: is greater than or equal to. The allowed values vary based on the field value: If field is set to URL, operator can only be set to CONTAINS, DOES_NOT_CONTAIN, or EQ. If field is not set to URL, operator can be set to CONTAINS, DOES_NOT_CONTAINS, EQ, IS_LESS_THAN, IS_GREATER_THAN, IS_LESS_THAN_OR_EQUAL_TO, or IS_GREATER_THAN_OR_EQUAL_TO.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1813841099262977 enum_package_name: ParameterFilterOperatorType enums: - description: '' is_valid: true key: CONTAINS value: '3' - description: '' is_valid: true key: DOES_NOT_CONTAIN value: '4' - description: '' is_valid: true key: EQ value: '1' - description: '' is_valid: true key: IS_GREATER_THAN value: '5' - description: '' is_valid: true key: IS_GREATER_THAN_OR_EQUAL_TO value: '6' - description: '' is_valid: true key: IS_LESS_THAN value: '7' - description: '' is_valid: true key: IS_LESS_THAN_OR_EQUAL_TO value: '8' - description: '' is_valid: true key: NOT_EQUAL value: '2' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 2 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].operator values: description: 'Required when parameter_filters within inclusion_rule_set is passed. A list of filter values. Max size: 10. Length limit for each value: 100 characters. If you specify multiple values, the values will be combined using OR logic.' items: maxLength: 100 type: string x-open-allow-strlist: false x-open-allow-strnum: false maxItems: 10 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].values required: - field - operator - values type: object x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters value: description: Filter value. For enum values, see Enumeration - Filter Value. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].value required: - field - operator - value type: object x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters operator: description: 'Operator between filters in the filters object array. Enum value: OR. Within each inclusion rule, you can only specify one object in filters.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1805510742984706 enum_package_name: FilterSetOperatorType enums: - description: '' is_valid: true key: AND value: '1' - description: '' is_valid: true key: OR value: '2' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 2 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.operator required: - filters - operator type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set retention_days: description: 'Audience lookback window. For enum values, see Enumerations - Lookback window. Note: If audience_type = BUSINESS_ACCOUNT, and the value in the filters object is not BUSINESS ACCOUNT PROFILE FOLLOW, then retention_days must be 7, 14, or 30. If audience_type = ENGAGEMENT_LIVE_VIDEO or ENGAGEMENT_ORGANIC_VIDEO, then retention_days must be 7, 14, or 30. To avoid confusion between retention_days and retention_in_days, we''ll rename retention_days in the next API version.' format: int32 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules[].retention_days required: - retention_days type: object x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.rule_spec.inclusion_rule_set.rules required: - operator - rules type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.rule_spec.inclusion_rule_set required: - inclusion_rule_set type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 10 x-open-source: $.http.body.rule_spec required: - advertiser_id - custom_audience_name - audience_type - rule_spec type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Create an audience by rules [Dmp Custom_audience Rule Create](https://business-api.tiktok.com/portal/docs?id=1739940509849601) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: custom_audience_name required: true source: $.http.body.custom_audience_name type: string - name: audience_type required: true source: $.http.body.audience_type type: number - name: audience_sub_type required: false source: $.http.body.audience_sub_type type: number - name: retention_in_days required: false source: $.http.body.retention_in_days type: number - name: is_auto_refresh required: false source: $.http.body.is_auto_refresh type: boolean - name: identity_id required: false source: $.http.body.identity_id type: string - name: identity_type required: false source: $.http.body.identity_type type: number - name: identity_authorized_bc_id required: false source: $.http.body.identity_authorized_bc_id type: number - children: - children: - name: operator required: true source: $.http.body.rule_spec.inclusion_rule_set.operator type: number - children: - children: - name: retention_days required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].retention_days type: number - children: - type: string is_expand: true name: event_source_ids required: false source: $.http.body.rule_spec.inclusion_rule_set.rules[].event_source_ids sub_type: string type: array - children: - children: - children: - name: field required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].field type: string - name: operator required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].operator type: number - name: value required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].value type: string - children: - children: - name: field required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].field type: string - name: operator required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].operator type: number - children: - type: string is_expand: true name: values required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].values sub_type: string type: array is_expand: true type: object is_expand: true name: parameter_filters required: false sub_type: object type: array is_expand: true type: object is_expand: true name: filters required: true sub_type: object type: array - name: operator required: true source: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.operator type: number is_expand: true name: filter_set required: false type: object is_expand: true type: object is_expand: true name: rules required: true sub_type: object type: array is_expand: true name: inclusion_rule_set required: true type: object - children: - name: operator required: true source: $.http.body.rule_spec.exclusion_rule_set.operator type: number - children: - children: - name: retention_days required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].retention_days type: number - children: - type: string is_expand: true name: event_source_ids required: false source: $.http.body.rule_spec.exclusion_rule_set.rules[].event_source_ids sub_type: string type: array - children: - children: - children: - name: field required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].field type: string - name: operator required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].operator type: number - name: value required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].value type: string - children: - children: - name: field required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].field type: string - name: operator required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].operator type: number - children: - type: string is_expand: true name: values required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].values sub_type: string type: array is_expand: true type: object is_expand: true name: parameter_filters required: false sub_type: object type: array is_expand: true type: object is_expand: true name: filters required: true sub_type: object type: array - name: operator required: true source: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.operator type: number is_expand: true name: filter_set required: false type: object is_expand: true type: object is_expand: true name: rules required: true sub_type: object type: array is_expand: true name: exclusion_rule_set required: false type: object is_expand: false name: rule_spec required: true type: object - children: - name: core_user_id required: false source: $.http.body.context_info.core_user_id type: number is_expand: true name: context_info required: false type: object - name: audience_enhancement required: false source: $.http.body.audience_enhancement type: boolean plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id audience_enhancement: $.http.body.audience_enhancement audience_sub_type: $.http.body.audience_sub_type audience_type: $.http.body.audience_type context_info: core_user_id: $.http.body.context_info.core_user_id custom_audience_name: $.http.body.custom_audience_name identity_authorized_bc_id: $.http.body.identity_authorized_bc_id identity_id: $.http.body.identity_id identity_type: $.http.body.identity_type is_auto_refresh: $.http.body.is_auto_refresh retention_in_days: $.http.body.retention_in_days rule_spec: exclusion_rule_set: operator: $.http.body.rule_spec.exclusion_rule_set.operator rules[][]: - event_source_ids: $.http.body.rule_spec.exclusion_rule_set.rules[].event_source_ids filter_set[]: - filters[][]: - field: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].field operator: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].operator parameter_filters[][]: - field: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].field operator: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].operator values: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].values value: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.filters[].value operator: $.http.body.rule_spec.exclusion_rule_set.rules[].filter_set.operator retention_days: $.http.body.rule_spec.exclusion_rule_set.rules[].retention_days inclusion_rule_set: operator: $.http.body.rule_spec.inclusion_rule_set.operator rules[][]: - event_source_ids: $.http.body.rule_spec.inclusion_rule_set.rules[].event_source_ids filter_set[]: - filters[][]: - field: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].field operator: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].operator parameter_filters[][]: - field: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].field operator: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].operator values: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].parameter_filters[].values value: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.filters[].value operator: $.http.body.rule_spec.inclusion_rule_set.rules[].filter_set.operator retention_days: $.http.body.rule_spec.inclusion_rule_set.rules[].retention_days response_cookie: [] response_header: [] response_rule: custom_audience_id: $.rpc.output.custom_audience_id x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/share/: post: operationId: Dmp Custom_audience Share parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: Operator advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id context_info: description: '' properties: app_id: description: '' format: int64 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.context_info.app_id core_user_id: description: '' format: int64 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.context_info.core_user_id developer_id: description: '' format: int64 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.context_info.developer_id x_forwarded_for: description: '' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.context_info.x_forwarded_for x_real_ip: description: '' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 5 x-open-source: $.http.body.context_info.x_real_ip type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.context_info custom_audience_ids: description: 'Custom audiences that you want to share. Size: 1-10.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.custom_audience_ids shared_advertiser_ids: description: 'Advertisers that you want to share audiences with. They must be in the same Business Center as you. Size: 1-10.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.shared_advertiser_ids required: - advertiser_id - custom_audience_ids - shared_advertiser_ids type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Share custom audiences with other advertisers [Dmp Custom_audience Share](https://business-api.tiktok.com/portal/docs?id=1740245803888706) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: false source: $.http.body.advertiser_id type: number - children: - type: number is_expand: true name: custom_audience_ids required: true source: $.http.body.custom_audience_ids sub_type: number type: array - children: - type: number is_expand: true name: shared_advertiser_ids required: true source: $.http.body.shared_advertiser_ids sub_type: number type: array - children: - name: app_id required: false source: $.context.app_id type: number - name: core_user_id required: false source: $.context.core_user_id type: number - name: developer_id required: false source: $.context.developer_id type: number is_expand: true name: context_info required: false source: '' type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id context_info: app_id: $.context.app_id core_user_id: $.context.core_user_id developer_id: $.context.developer_id custom_audience_ids: $.http.body.custom_audience_ids shared_advertiser_ids: $.http.body.shared_advertiser_ids response_cookie: [] response_header: [] response_rule: null x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/share/cancel/: post: operationId: Dmp Custom_audience Share Cancel parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: The advertiser ID that performed the operation. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id custom_audience_id: description: The audience ID that you want to stop sharing. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 2 x-open-source: $.http.body.custom_audience_id shared_advertiser_id: description: The advertiser ID you want to stop sharing with. You only need to pass this field if you want to stop sharing audiences with an advertiser. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 3 x-open-source: $.http.body.shared_advertiser_id required: - advertiser_id - custom_audience_id - shared_advertiser_id type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Stop sharing custom audiences with other advertisers [Dmp Custom_audience Share Cancel](https://business-api.tiktok.com/portal/docs?id=1740245829978113) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: custom_audience_id required: true source: $.http.body.custom_audience_id type: number - name: shared_advertiser_id required: true source: $.http.body.shared_advertiser_id type: number - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id context_info: core_user_id: $.context.core_user_id custom_audience_id: $.http.body.custom_audience_id shared_advertiser_id: $.http.body.shared_advertiser_id response_cookie: [] response_header: [] response_rule: null x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/share/log/: get: operationId: Dmp Custom_audience Share Log parameters: - description: Advertiser ID. in: query name: advertiser_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.advertiser_id x-open-field-id: 1 - description: Custom audiences that you want to get sharing log for. in: query name: custom_audience_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-source: $.http.query.custom_audience_id x-open-field-id: 2 - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Get the sharing log of a custom audience [Dmp Custom_audience Share Log](https://ads.tiktok.com/marketing_api/docs?id=1740245827044354) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.query.advertiser_id type: number - name: custom_audience_id required: true source: $.http.query.custom_audience_id type: number - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false source: '' type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.query.advertiser_id context_info: core_user_id: $.context.core_user_id custom_audience_id: $.http.query.custom_audience_id response_cookie: [] response_header: [] response_rule: list[][]: - custom_audience_id: $.rpc.output.data[].custom_audience_id shared_advertiser_id: $.rpc.output.data[].shared_advertiser_id shared_advertiser_name: $.rpc.output.data[].shared_advertiser_name status: $.rpc.output.data[].status x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/custom_audience/update/: post: operationId: Dmp Custom_audience Update parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: action: default: REPLACE description: '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. Note: The APPEND, REMOVE and REPLACE operations will fail if the audience size is less than 1,000 after the operation.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: null enum_package_name: null enums: - description: '' is_valid: true key: REPLACE value: REPLACE - description: '' is_valid: true key: APPEND value: APPEND - description: '' is_valid: true key: REMOVE value: REMOVE key_format: string strict: true use_part: false validate_only: false value_format: string x-open-field-id: 6 x-open-source: $.http.body.action advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id audience_enhancement: description: '' type: boolean x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 7 x-open-source: $.http.body.audience_enhancement audience_sub_type: description: '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 round. Note: 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.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.audience_sub_type context_info: description: '' properties: core_user_id: description: '' format: int64 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 1 x-open-source: $.http.body.context_info.core_user_id type: object x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 8 x-open-source: $.http.body.context_info custom_audience_id: description: Custom audience ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 2 x-open-source: $.http.body.custom_audience_id custom_audience_name: description: 'New name for the audience. Length limit: 128 characters. You must pass in either this field or file_paths.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.custom_audience_name file_paths: description: The files you upload to update the Customer File audience. You must pass in either this field or custom_audience_name. The recommended size is <50 per request to ensure stability. 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. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 5 x-open-source: $.http.body.file_paths required: - advertiser_id - custom_audience_id type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Update the details of an audience [Dmp Custom_audience Update](https://business-api.tiktok.com/portal/docs?id=1739940572667906) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: custom_audience_id required: true source: $.http.body.custom_audience_id type: number - name: custom_audience_name required: false source: $.http.body.custom_audience_name type: string - name: audience_sub_type required: false source: $.http.body.audience_sub_type type: string - children: - type: string is_expand: true name: file_paths required: false source: $.http.body.file_paths sub_type: string type: array - name: action required: false source: $.http.body.action type: string - name: audience_enhancement required: false source: $.http.body.audience_enhancement type: boolean - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false source: '' type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: action: $.http.body.action advertiser_id: $.http.body.advertiser_id audience_enhancement: $.http.body.audience_enhancement audience_sub_type: $.http.body.audience_sub_type context_info: core_user_id: $.context.core_user_id custom_audience_id: $.http.body.custom_audience_id custom_audience_name: $.http.body.custom_audience_name file_paths: $.http.body.file_paths response_cookie: [] response_header: [] response_rule: null x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/saved_audience/create/: post: operationId: Dmp Saved_audience Create parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: actions: description: A list of action category objects. items: properties: action_category_ids: description: Required when actions has been specified and valid only when TikTok placement is the only placement selected in your ad group. IDs of the action categories (behaviors) or hashtags that you want to target. You can get action category IDs via /tool/action_category/. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 4 x-open-source: $.http.body.actions[].action_category_ids action_period: description: 'Required when actions has been specified. The time period to include actions from. Enum values: 0, 7, 15. If action_scene is CREATOR_RELATED or HASHTAG_RELATED, 0 will be used regardless of the value you pass in. 0 means that there is no definite timeframe to select actions from.' format: int32 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 2 x-open-source: $.http.body.actions[].action_period action_scene: description: 'Required when actions has been specified. Where you can collect information about user actions. Enum values: VIDEO_RELATED, CREATOR_RELATED, HASHTAG_RELATED.' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1800966577028098 enum_package_name: ActionScene enums: - description: '' is_valid: true key: CREATOR_RELATED value: '11' - description: '' is_valid: true key: HASHTAG_RELATED value: '13' - description: '' is_valid: true key: VIDEO_RELATED value: '2' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 1 x-open-source: $.http.body.actions[].action_scene video_user_actions: description: 'Required when actions has been specified. Video-related Actions. If action_scene is VIDEO_RELATED, the allowed values are: WATCHED_TO_END,LIKED,COMMENTED,SHARED. If action_scene is CREATOR_RELATED, the allowed values are: FOLLOWING, VIEW_HOMEPAGE. If action_scene is HASHTAG_RELATED, the allowed value is VIEW_HASHTAG.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1804237663605761 enum_package_name: VideoAction enums: - description: '' is_valid: true key: COMMENTED value: '2' - description: '' is_valid: true key: FOLLOWING value: '4' - description: '' is_valid: true key: LIKED value: '1' - description: '' is_valid: true key: SHARED value: '3' - description: '' is_valid: true key: VIEW_HASHTAG value: '6' - description: '' is_valid: true key: VIEW_HOMEPAGE value: '5' - description: '' is_valid: true key: WATCHED_TO_END value: '0' key_format: string strict: true use_part: false validate_only: false value_format: int32 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.actions[].video_user_actions type: object x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 11 x-open-source: $.http.body.actions advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id age_groups: description: Age groups you want to target. For enum values, see Enumeration - Targeting Age Group. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 5 x-open-source: $.http.body.age_groups audience_ids: description: List of audience IDs. You can get audience IDs via the /dmp/custom_audience/list/ endpoint. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 7 x-open-source: $.http.body.audience_ids carrier_ids: description: Carriers that you want to target. Use /tool/carrier/ endpoint to get a list of carriers. A carrier is valid only when the in_use field for the carrier is true. The carriers must be consistent with the location(s) that you want to target. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 17 x-open-source: $.http.body.carrier_ids device_model_ids: description: 'IDs of the device models that you want to target. Use /tool/device_model/ to get the complete list of device model IDs and their statuses, and only active devices (is_active = true in the response of /tool/device_model/) can be used to create ads. Note: Device model (device_model_ids) and device price (device_price_ranges) cannot be set at the same time.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 15 x-open-source: $.http.body.device_model_ids device_price_ranges: description: '' items: format: int32 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 18 x-open-source: $.http.body.device_price_ranges excluded_audience_ids: description: List of audience IDs to be excluded. You can get audience IDs via the /dmp/custom_audience/list/ endpoint. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 8 x-open-source: $.http.body.excluded_audience_ids gender: description: 'Gender that you want to target. Enum values: GENDER_FEMALE,GENDER_MALE,GENDER_UNLIMITED' type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1804229882527745 enum_package_name: AudienceGenderType enums: - description: '' is_valid: true key: GENDER_FEMALE value: '2' - description: '' is_valid: true key: GENDER_MALE value: '1' - description: '' is_valid: true key: GENDER_UNLIMITED value: '0' key_format: string strict: true use_part: false validate_only: false value_format: int32 x-open-field-id: 4 x-open-source: $.http.body.gender interest_category_ids: description: Interest classification. You can use /tool/target_recommend_tags/ to get a list of recommended interest categories based on your targeting regions and your industries, or use /tool/interest_category/ endpoint to get the complete list of interest categories. If the interest is specified, users who do not meet the interest target will be excluded during delivery. Do not specify if you wish to target everyone. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 9 x-open-source: $.http.body.interest_category_ids interest_keyword_ids: description: IDs of interest keywords that you want to use to target audience. You can use /tool/interest_keyword/recommend/ to get recommended interest keywords. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 10 x-open-source: $.http.body.interest_keyword_ids languages: description: Codes of the languages that you want to target. You can get language codes via /tool/language/, and if you don't want to limit the languages you target, assign an empty value to this field or do not pass in this field. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 6 x-open-source: $.http.body.languages location_ids: description: 'IDs of the locations that you want to target. To get the available locations and corresponding IDs, use the /tool/region/ or /tool/targeting/search/ endpoint. Note: Overlapping targeted locations are not supported. For instance, you cannot target the U.S. and the state of California at the same time. DMA-level and city-level (or lower) targeting is only available in certain countries, and the access is managed by allowlist. If you would like to access it, please contact your TikTok representative for allowlisting.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 3 x-open-source: $.http.body.location_ids min_android_version: description: Minimum device Android version. For enum values, see Enumeration - Minimum Android Version. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 13 x-open-source: $.http.body.min_android_version min_ios_version: description: Minimum iOS version. For enum values, see Enumeration - Minimum iOS Version. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 14 x-open-source: $.http.body.min_ios_version network_types: description: 'Device connection types that you want to target. Default: unlimited. For enum values, see Enumeration - Connection Type.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1803592836258818 enum_package_name: ReportAccessType enums: - description: '' is_valid: true key: 2G value: '2' - description: '' is_valid: true key: 3G value: '3' - description: '' is_valid: true key: 4G value: '4' - description: '' is_valid: true key: 5G value: '5' - description: '' is_valid: true key: UNKNOWN value: '0' - description: '' is_valid: true key: WIFI value: '1' key_format: string strict: true use_part: false validate_only: false value_format: int32 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 16 x-open-source: $.http.body.network_types operating_systems: description: 'Device operating systems that you want to target. Enum values: ANDROID, IOS. Only one value is allowed.' items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-enum: enum_package_expired: false enum_package_id: 1804229743233025 enum_package_name: 'AudiencePlatformType ' enums: - description: '' is_valid: true key: ANDROID value: '1' - description: '' is_valid: true key: IOS value: '2' - description: '' is_valid: true key: PC value: '16' - description: '' is_valid: true key: UNKNOWN value: '0' key_format: string strict: true use_part: false validate_only: false value_format: int32 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 12 x-open-source: $.http.body.operating_systems saved_audience_name: description: Saved Audience name. Character limit is 512 and cannot contain emoji. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.saved_audience_name required: - advertiser_id - saved_audience_name - location_ids type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Create a Saved Audience [Dmp Saved_audience Create](https://business-api.tiktok.com/portal/docs?id=1780154541898754) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - name: saved_audience_name required: true source: $.http.body.saved_audience_name type: string - children: - type: number is_expand: true name: location_ids required: true source: $.http.body.location_ids sub_type: number type: array - name: gender required: false source: $.http.body.gender type: number - children: - type: string is_expand: true name: age_groups required: false source: $.http.body.age_groups sub_type: string type: array - children: - type: string is_expand: true name: languages required: false source: $.http.body.languages sub_type: string type: array - children: - type: number is_expand: true name: audience_ids required: false source: $.http.body.audience_ids sub_type: number type: array - children: - type: number is_expand: true name: excluded_audience_ids required: false source: $.http.body.excluded_audience_ids sub_type: number type: array - children: - type: number is_expand: true name: interest_category_ids required: false source: $.http.body.interest_category_ids sub_type: number type: array - children: - type: number is_expand: true name: interest_keyword_ids required: false source: $.http.body.interest_keyword_ids sub_type: number type: array - children: - children: - name: action_scene required: false source: $.http.body.actions[].action_scene type: number - name: action_period required: false source: $.http.body.actions[].action_period type: number - children: - type: number is_expand: true name: video_user_actions required: false source: $.http.body.actions[].video_user_actions sub_type: number type: array - children: - type: number is_expand: true name: action_category_ids required: false source: $.http.body.actions[].action_category_ids sub_type: number type: array is_expand: true type: object is_expand: true name: actions required: false sub_type: object type: array - children: - type: number is_expand: true name: operating_systems required: false source: $.http.body.operating_systems sub_type: number type: array - name: min_android_version required: false source: $.http.body.min_android_version type: string - name: min_ios_version required: false source: $.http.body.min_ios_version type: string - children: - type: number is_expand: true name: device_model_ids required: false source: $.http.body.device_model_ids sub_type: number type: array - children: - type: number is_expand: true name: network_types required: false source: $.http.body.network_types sub_type: number type: array - children: - type: number is_expand: true name: carrier_ids required: false source: $.http.body.carrier_ids sub_type: number type: array - children: - type: number is_expand: true name: device_price_ranges required: false source: $.http.body.device_price_ranges sub_type: number type: array - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: actions[][]: - action_category_ids: $.http.body.actions[].action_category_ids action_period: $.http.body.actions[].action_period action_scene: $.http.body.actions[].action_scene video_user_actions: $.http.body.actions[].video_user_actions advertiser_id: $.http.body.advertiser_id age_groups: $.http.body.age_groups audience_ids: $.http.body.audience_ids carrier_ids: $.http.body.carrier_ids context_info: core_user_id: $.context.core_user_id device_model_ids: $.http.body.device_model_ids device_price_ranges: $.http.body.device_price_ranges excluded_audience_ids: $.http.body.excluded_audience_ids gender: $.http.body.gender interest_category_ids: $.http.body.interest_category_ids interest_keyword_ids: $.http.body.interest_keyword_ids languages: $.http.body.languages location_ids: $.http.body.location_ids min_android_version: $.http.body.min_android_version min_ios_version: $.http.body.min_ios_version network_types: $.http.body.network_types operating_systems: $.http.body.operating_systems saved_audience_name: $.http.body.saved_audience_name response_cookie: [] response_header: [] response_rule: saved_audience_id: $.rpc.output.saved_audience_id x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/saved_audience/delete/: post: operationId: Dmp Saved_audience Delete parameters: - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string requestBody: content: application/json: schema: properties: advertiser_id: description: Advertiser ID. type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 x-open-source: $.http.body.advertiser_id saved_audience_ids: description: IDs of Saved Audiences that you want to delete. Max size = 100. items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) maxItems: 100 minItems: 1 type: array x-open-allow-strlist: false x-open-allow-strnum: false x-open-field-id: 2 x-open-source: $.http.body.saved_audience_ids required: - advertiser_id - saved_audience_ids type: object x-open-allow-strlist: false x-open-allow-strnum: false responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Delete Saved Audiences [Dmp Saved_audience Delete](https://business-api.tiktok.com/portal/docs?id=1780154666312706) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.body.advertiser_id type: number - children: - type: number is_expand: true name: saved_audience_ids required: true source: $.http.body.saved_audience_ids sub_type: number type: array - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.body.advertiser_id context_info: core_user_id: $.context.core_user_id saved_audience_ids: $.http.body.saved_audience_ids response_cookie: [] response_header: [] response_rule: null x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false /dmp/saved_audience/list/: get: operationId: Dmp Saved_audience List parameters: - description: Advertiser ID. in: query name: advertiser_id required: true schema: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 1 - content: application/json: schema: items: type: string x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) maxItems: 100 type: array x-open-allow-strlist: false x-open-allow-strnum: false description: 'IDs of Saved Audiences. Max size: 100. To create Saved Audiences and obtain the Saved Audience IDs, use /dmp/saved_audience/create/.' in: query name: saved_audience_ids required: false x-open-field-id: 2 - description: '' in: query name: page required: false schema: default: 1 format: int32 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 3 - description: '' in: query name: page_size required: false schema: default: 10 format: int32 maximum: 100 minimum: 1 type: integer x-open-allow-strlist: false x-open-allow-strnum: false x-open-convert: - int64(%s) x-open-field-id: 4 - description: Authorized access token. For details, see [Authentication](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162). in: query name: Access-Token required: true schema: type: string responses: '200': content: application/json: schema: properties: code: description: Response code. For the complete list of response codes and descriptions, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). Will be shown only if it is an error request. format: int64 type: - integer - 'null' x-open-allow-strlist: false x-open-field-id: 4 data: description: Returned data. The response for the SDK can be checked in the document for the API given in the description. properties: {} type: - object - 'null' x-open-allow-strlist: false x-open-field-id: 1 x-open-source: $.rpc.output.data message: description: Response message. For details, see [Appendix - Return Codes](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097). type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 3 request_id: description: The log ID of a request, which uniquely identifies the request. type: - string - 'null' x-open-allow-strlist: false x-open-field-id: 2 type: object x-open-allow-strlist: false description: OK summary: Get the details of Saved Audiences [Dmp Saved_audience List](https://business-api.tiktok.com/portal/docs?id=1780154619404290) tags: - Audience x-open-allowlist: {} x-open-denylist: {} x-open-rules: base_rule: null extra_rule: base_source: [] http_query_source: [] http_source: - name: advertiser_id required: true source: $.http.query.advertiser_id type: number - children: - type: number is_expand: true name: saved_audience_ids required: false source: $.http.query.saved_audience_ids[] sub_type: number type: array - name: page required: false source: $.http.query.page type: number - name: page_size required: false source: $.http.query.page_size type: number - children: - name: core_user_id required: false source: $.context.core_user_id type: number is_expand: true name: context_info required: false type: object plugins: after_response: [] before_request: [] request_query_rule: null request_rule: advertiser_id: $.http.query.advertiser_id context_info: core_user_id: $.context.core_user_id page: $.http.query.page page_size: $.http.query.page_size saved_audience_ids: $.http.query.saved_audience_ids[] response_cookie: [] response_header: [] response_rule: page_info: page: $.rpc.output.page_info.page page_size: $.rpc.output.page_info.page_size total_number: $.rpc.output.page_info.total_number total_page: $.rpc.output.page_info.total_page saved_audiences[][]: - actions[][]: - action_category_ids: $.rpc.output.saved_audiences[].actions[].action_category_ids action_period: $.rpc.output.saved_audiences[].actions[].action_period action_scene: $.rpc.output.saved_audiences[].actions[].action_scene video_user_actions: $.rpc.output.saved_audiences[].actions[].video_user_actions age_groups: $.rpc.output.saved_audiences[].age_groups audience_ids: $.rpc.output.saved_audiences[].audience_ids carrier_ids: $.rpc.output.saved_audiences[].carrier_ids device_model_ids: $.rpc.output.saved_audiences[].device_model_ids device_price_ranges: $.rpc.output.saved_audiences[].device_price_ranges excluded_audience_ids: $.rpc.output.saved_audiences[].excluded_audience_ids gender: $.rpc.output.saved_audiences[].gender interest_category_ids: $.rpc.output.saved_audiences[].interest_category_ids interest_keyword_ids: $.rpc.output.saved_audiences[].interest_keyword_ids languages: $.rpc.output.saved_audiences[].languages location_ids: $.rpc.output.saved_audiences[].location_ids min_android_version: $.rpc.output.saved_audiences[].min_android_version min_ios_version: $.rpc.output.saved_audiences[].min_ios_version network_types: $.rpc.output.saved_audiences[].network_types operating_systems: $.rpc.output.saved_audiences[].operating_systems saved_audience_id: $.rpc.output.saved_audiences[].saved_audience_id saved_audience_name: $.rpc.output.saved_audiences[].saved_audience_name x-open-scene-labels: [] x-open-settings: pop_resp_nullvalue: false components: securitySchemes: AccessToken: type: apiKey in: header name: Access-Token description: Long-term access token issued by POST /oauth2/access_token/ after advertiser authorization. See https://business-api.tiktok.com/portal/docs?id=1738373164380162