Ad Code Request

Request an ad code for one finalized video so you can run it as a paid ad from your own ad account. On TikTok this is a Spark Code; Instagram partner / branded-content codes are coming later.

The assigned account manager generates the code on the account and submits it. You then retrieve it by polling the same endpoint.

Cost: 7 credits per ad code.

CAUTION: Rules to know before running a Spark Ad

• The caption is locked once the Spark Code is generated. Make sure the video's caption is final before requesting the code.
• The sound must be original audio or from TikTok's Commercial Music Library. Videos using trending/licensed sounds get muted or rejected when run as ads.
• The post can stay "Show only in ads" (hidden from the profile) if needed.

Request an Ad Code

POST /videos/:id/ad-code-request

The :id is a video ID (the finalized video you want to promote), not a bundle ID. Use GET /accounts/:id/analytics/videos or your finalized orders to find video IDs.

Prerequisites

• The video must be finalized
• The video must be on TikTok (Instagram partner codes are coming later)
• The video must have a live post link
• The video's order must have an assigned manager
• No other ad code request can be in progress for the same video
• You need at least 7 credits in your balance

Request Body

Field	Type	Required	Description
note	string	No	Optional message to your manager (max 500 chars), e.g. the campaign this code is for
platform	string	No	Defaults to the video's platform. Only tiktok is available today

curl -X POST https://app.tokportal.com/api/ext/videos/{video_id}/ad-code-request \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "note": "For our Q3 Spark Ads campaign"
  }'

Response (201)

{
  "data": {
    "ad_code_request_id": "uuid",
    "video_id": "uuid",
    "status": "pending",
    "platform": "tiktok",
    "code": null,
    "note": "For our Q3 Spark Ads campaign",
    "created_at": "2026-06-16T10:22:00Z"
  },
  "credits_charged": 7,
  "credits_remaining": 1240
}

Get / Poll the Code

GET /videos/:id/ad-code-request

Returns the latest ad code request for the video. The code field stays null until your manager submits it (status in_review) or it is delivered (status finalized). Poll this endpoint until code is present.

curl https://app.tokportal.com/api/ext/videos/{video_id}/ad-code-request \
  -H "X-API-Key: sk_xxx"

Response (200) — once the manager has submitted the code

{
  "data": {
    "ad_code_request_id": "uuid",
    "video_id": "uuid",
    "status": "in_review",
    "platform": "tiktok",
    "code": "#TTSpark_AbC123XyZ",
    "note": "For our Q3 Spark Ads campaign",
    "created_at": "2026-06-16T10:22:00Z",
    "submitted_at": "2026-06-16T14:05:00Z",
    "delivered_at": null
  }
}

If no request exists for the video, data is null.

Using the code (in TikTok Ads Manager)

Once you have the Spark Code, run the video as a native ad from your own ad account:

1. TikTok Ads Manager → Creative library → Spark Ads posts.
2. Click Apply for authorization and paste the code.
3. The post appears in your library with its authorization period.
4. When creating an ad, pick the authorized post, add your CTA + landing URL, and publish.

If a delivered code does not work, report it (this reopens the task for the manager) by submitting a correction:

curl -X PATCH https://app.tokportal.com/api/ad-code-requests/{ad_code_request_id} \
  -H "Authorization: Bearer $TOKPORTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "pending_corrections", "feedback": "Code rejected in Ads Manager" }'

Ad Code Statuses

Status	Meaning
pending	Request created, waiting for the manager
accepted	Manager acknowledged the request
in_review	Manager submitted the code — code is now readable
pending_corrections	A correction was requested; the manager will re-submit
finalized	Delivered and confirmed (manager is paid). Terminal
cancelled	Cancelled (e.g. the manager could not generate it); your 7 credits are refunded

TIP: Poll until delivered After POST, poll GET /videos/:id/ad-code-request every few seconds. As soon as status is in_review and code is non-null, you can use the Spark Code in TikTok Ads Manager.

NOTE: Instagram coming later Ad codes are TikTok-only today. Instagram partner / branded-content codes will use the same endpoints with platform: "instagram" once available.