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; on Instagram it is a partner / branded-content code.

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 or Instagram
• The video must have a live post link
• The saved account must have active TokPortal Coverage or be permanently grandfathered
• If an active order exists, its manager is authoritative and must still be an active Account Manager
• TokPortal walks completed orders newest-first and assigns the first historical manager who is still active
• The request appears directly in that manager's Calendar. Accept & start acknowledges the assigned work; it is not a marketplace claim
• Cancelled orders are never used as fallback
• No other ad code request can be in progress for the same video
• You need at least 7 credits in your balance

A completed bundle remains eligible without a delivery-age limit. Coverage validation, manager assignment, the 7-credit debit, and request creation commit atomically. A failed prerequisite never creates a request or debit. If Coverage later pauses or lapses, unfinished work is withheld from the manager queue and does not become late; reactivation restores it through the account-level resume flow.

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. Accepted values: tiktok, instagram

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.

Errors

Code	Status	When
AD_CODE_VIDEO_NOT_FOUND	404	Video ID not found
AD_CODE_NOT_OWNED	403	Video belongs to another user
AD_CODE_VIDEO_NOT_FINALIZED	409	Video is not finalized
AD_CODE_NO_POST_URL	409	The finalized video has no live post link
MANAGED_ACCOUNT_TASK_BLOCKED	409	Coverage is inactive or the account is detached, banned, missing Coverage, or otherwise unavailable. Fetch the account Coverage state and reactivate only when recoverable.
AD_CODE_NO_CM	409	The active order has no eligible active manager
AD_CODE_NO_ORDER	409	No non-cancelled support order or active historical manager can be resolved
AD_CODE_ALREADY_EXISTS	409	Another ad-code request is already open
INSUFFICIENT_CREDITS	402	Fewer than 7 credits are available

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 from the TokPortal dashboard. The public API currently supports creating and polling ad-code requests; it does not expose the dashboard-only correction transition. Do not call the internal /api/ad-code-requests/{id} route with a public API key.

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: Platform terminology TokPortal returns the same request shape for TikTok Spark Codes and Instagram partner / branded-content codes. The platform field identifies the target network.