👥 TikTok Ads - Accounts

📖 Overview

The accounts module provides access to TikTok advertiser accounts associated with the authenticated access token. After OAuth authentication, users can list all advertiser accounts they have access to and select one for campaign management and reporting.

Source Files:

Controller: external/Integrations/TikTok/Controllers/accounts.js
Route: external/Integrations/TikTok/Routes/accounts.js
Provider: external/Integrations/TikTok/providers/tiktok-analytics.js

External API: TikTok Marketing API - Advertiser Management

🗄️ Collections Used

`tiktok.tokens`

Operations: Read
Model: shared/models/tik-tok-token.js
Usage Context: Retrieve access token for API authentication

`analytics_tiktokanalytics_userconfigs`

Operations: Create, Update (via separate endpoint)
Model: external/models/analytics-tiktokanalytics-userconfig.js
Usage Context: Store selected advertiser account for reporting

🔄 Data Flow

sequenceDiagram
    participant Client as DashClicks App
    participant Controller as Accounts Controller
    participant Keys as Keys Model
    participant Provider as TikTok Provider
    participant TikTok as TikTok Marketing API
    participant DB as MongoDB

    Client->>Controller: GET /accounts/advertisers
    Controller->>Keys: Find token by account ID
    Keys->>DB: Query tiktok.tokens
    DB-->>Keys: Return token document
    Keys-->>Controller: Access token
    Controller->>Provider: getAdvertisersAccounts()
    Provider->>TikTok: GET /oauth2/advertiser/get
    Note over Provider,TikTok: Access-Token: {token}<br/>app_id + secret in URL
    TikTok-->>Provider: Advertiser list response
    Provider-->>Controller: Formatted data
    Controller-->>Client: JSON response with advertisers

🔧 Business Logic & Functions

Get Advertiser Accounts

`advertisers(req, res, next)`

Purpose: Retrieve list of TikTok advertiser accounts accessible with the current access token

Source: Controllers/accounts.js

External API Endpoint: GET https://business-api.tiktok.com/v1.3/oauth2/advertiser/get

Request:

GET /v1/integrations/tiktok/accounts/advertisers
Authorization: Bearer {jwt_token}

Query Parameters:

Parameter	Type	Required	Description
None	-	-	No additional parameters supported

Returns: Promise<Array<Object>>

Business Logic Flow:

Validate Account Access
- Call checkAccountAccess(req) utility
- Extract DashClicks account ID from JWT
- Return 400 error if account ID invalid
Fetch OAuth Token
- Call keysModel.find(accountId)
- Retrieves token from tiktok.tokens collection
- If KEYS_NOT_FOUND error, return 400:
```
{
  "success": false,
  "errno": 400,
  "message": "Record Not found!"
}
```
Call TikTok API
- Provider Function: tiktokAnalyticsProvider.getAdvertisersAccounts()
- HTTP Method: GET
- URL: {TIKTOK_BASE_URL}/{TIKTOK_VERSION}/oauth2/advertiser/get
- Query Parameters:
  - app_id={TIK_TOK_CLIENT_ID}
  - secret={TIKTOK_CLIENT_SECRET}
- Headers:
```
{
  "Access-Token": "{access_token}"
}
```
Extract Advertiser List
- Response structure: { code, message, data: { list: [...] } }
- Extract data.list array
- No pagination available for this endpoint
Return Response
- Format: Array of advertiser objects
- HTTP 200 status

API Request Example:

GET https://business-api.tiktok.com/v1.3/oauth2/advertiser/get?app_id=1234567890&secret=your_secret
Headers:
  Access-Token: act.1234567890abcdef...

API Response Example:

{
  "code": 0,
  "message": "OK",
  "data": {
    "list": [
      {
        "advertiser_id": "1234567890",
        "advertiser_name": "My Business Account",
        "company": "My Company LLC",
        "currency": "USD",
        "timezone_id": "America/New_York",
        "status": "STATUS_ENABLE",
        "description": "Account description"
      },
      {
        "advertiser_id": "0987654321",
        "advertiser_name": "Another Business",
        "company": "Another Company Inc",
        "currency": "EUR",
        "timezone_id": "Europe/London",
        "status": "STATUS_ENABLE",
        "description": "Second account"
      }
    ]
  }
}

Success Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "advertiser_id": "1234567890",
      "advertiser_name": "My Business Account",
      "company": "My Company LLC",
      "currency": "USD",
      "timezone_id": "America/New_York",
      "status": "STATUS_ENABLE",
      "description": "Account description"
    },
    {
      "advertiser_id": "0987654321",
      "advertiser_name": "Another Business",
      "company": "Another Company Inc",
      "currency": "EUR",
      "timezone_id": "Europe/London",
      "status": "STATUS_ENABLE",
      "description": "Second account"
    }
  ]
}

Error Handling:

Error	Cause	Response
`Invalid Account Id`	Account access check failed	`{ success: false, message: "Invalid Account Id" }`
`KEYS_NOT_FOUND`	No OAuth token exists	`{ success: false, errno: 400, message: "Record Not found!" }`
TikTok API Error	API request failed	Error passed to next() middleware

Error Response (No Token):

{
  "success": false,
  "errno": 400,
  "message": "Record Not found!"
}

Example Usage:

// Frontend: List advertisers after OAuth
const response = await fetch('/v1/integrations/tiktok/accounts/advertisers', {
  headers: {
    Authorization: `Bearer ${jwtToken}`,
  },
});

const { data } = await response.json();
// data is array of advertiser objects

// User selects advertiser, then save config:
await fetch('/v1/integrations/tiktok/useranalyticsconfig', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${jwtToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    advertiser_id: data[0].advertiser_id,
    advertiser_name: data[0].advertiser_name,
  }),
});

Side Effects:

⚠️ Makes external API call to TikTok Marketing API
⚠️ Uses API quota from TikTok rate limits

🔗 Integration Points

Internal Services

Account Selection Flow:

User completes OAuth authentication
Frontend calls GET /accounts/advertisers to list options
User selects advertiser account from list
Frontend calls POST /useranalyticsconfig (see Authentication)
Advertiser ID saved in analytics_tiktokanalytics_userconfigs
All subsequent API calls use saved advertiser_id

Used By:

Campaign listing endpoints
Ad group listing endpoints
Ads listing endpoints
Analytics reporting endpoints

External API Dependencies

Provider: TikTok Marketing API
Endpoints: /oauth2/advertiser/get
Authentication: Access-Token header + app_id/secret in URL
Rate Limits: TikTok enforces per-app and per-advertiser limits

📊 Advertiser Object Structure

Fields Returned:

Field	Type	Description
`advertiser_id`	String	Unique advertiser account identifier
`advertiser_name`	String	Display name of advertiser account
`company`	String	Company name associated with account
`currency`	String	Account currency (USD, EUR, etc.)
`timezone_id`	String	Timezone for reporting (e.g., America/New_York)
`status`	String	Account status (STATUS_ENABLE, STATUS_DISABLE)
`description`	String	Account description text

Account Status Values:

STATUS_ENABLE - Account active and can run ads
STATUS_DISABLE - Account disabled, cannot run ads

🧪 Edge Cases & Special Handling

No Advertisers Available

Issue: User completes OAuth but has no advertiser accounts Response: Empty array in data field

{
  "success": true,
  "message": "SUCCESS",
  "data": []
}

Handling: Frontend should display "No advertiser accounts found" message

Multiple Advertisers

Issue: User has access to multiple advertiser accounts Handling:

Frontend displays all advertisers in selection UI
User must select one advertiser before proceeding
Selected advertiser saved via /useranalyticsconfig endpoint
Only one advertiser can be active per DashClicks account

Token Revoked During Request

Issue: OAuth token invalidated between authentication and advertiser fetch Response: TikTok API returns 401/403 error Handling:

Error middleware detects invalid token
Marks token as token_invalidated: true
Returns TOKEN_INVALIDATED error message
User must re-authenticate via OAuth flow

⚠️ Important Notes

🔐 Authentication Required: Requires valid OAuth access token
📋 No Pagination: Advertiser endpoint returns all accounts in single response
🔑 App Credentials in URL: Uses app_id and secret as query parameters
🎯 Account Selection: Users must select one advertiser for campaign operations
🔒 Single Advertiser: Only one advertiser per DashClicks account
⚡ Rate Limits: Subject to TikTok Marketing API rate limiting
🌍 Multi-Currency: Advertisers can have different currencies and timezones
✅ Status Filtering: Only enabled accounts can run campaigns

Integration Overview: TikTok Integration Index
Authentication: OAuth 2.0 Flow
Campaign Management: Campaigns, Ad Groups, Ads
Analytics: Reporting & Metrics
TikTok Advertiser API: Marketing API Documentation

📖 Overview​

🗄️ Collections Used​

tiktok.tokens​

analytics_tiktokanalytics_userconfigs​

🔄 Data Flow​

🔧 Business Logic & Functions​

Get Advertiser Accounts​

advertisers(req, res, next)​

🔗 Integration Points​

Internal Services​

External API Dependencies​

📊 Advertiser Object Structure​

🧪 Edge Cases & Special Handling​

No Advertisers Available​

Multiple Advertisers​

Token Revoked During Request​

⚠️ Important Notes​

🔗 Related Documentation​

Documentation Assistant