Sign in
Target Collabs

Send a Target Collab invite directly

Send a single TikTok Shop Target Collab (TC) invitation to a creator by handle. This is a convenience surface — it internally creates a single-creator TC automation and immediately starts it.

Queued semantics. The response returns immediately with status: "queued". Actual TC delivery happens asynchronously through Reacher's TC delivery worker (browser automation, the same path the portal uses). Typical end-to-end latency is a few seconds, sometimes longer under worker load. Poll GET /public/v1/automations/{automation_id} for delivery status and target_collabs.invitation_id once the worker submits.

Not for bulk. For >10 invites at a time, use POST /public/v1/automations/target-collab directly with a multi-creator audience — that's more efficient than calling this endpoint in a loop, and exposes the full TC feature set (content type, sample policy, follow-up DMs).

Required. read_write scope, Idempotency-Key header. Pass X-Dry-Run: true to validate without persisting or queueing.

post/target-collabs

Headers

Idempotency-Keystring nullable
X-Dry-Runstring nullable

Request body

creator_handlestring required

TikTok @-handle (without the @). Resolved server-side against this shop's CRM / affiliate list (a row in crm_creators for reacher_shop_id=<shop_id> whose creator_name matches the handle, ordered by GMV via a LEFT JOIN against the region's creator table). The creator must already have interacted with your shop — handles for creators who haven't applied / sampled / transacted yet will not resolve, even if the handle exists globally on TikTok. Unknown handle → 404 CREATOR_NOT_FOUND.

product_idstring required

TikTok Shop product ID to attach to the invitation.

commission_ratenumber required

Affiliate commission rate (0.0-1.0, e.g. 0.20 for 20%).

shop_ads_commission_ratenumber nullable

Optional Shop Ads (co-funded) commission rate (0.0-1.0). When set, persists into the legacy PRODUCTS blob at the per-product level; the TC runtime fills the matching field on the TC form. Omit to leave unset (worker treats as not configured).

messagestring required

TC card message body shown to the creator (max 500 chars). Mirrors target_collab.message on the full TC create surface — the portal rejects bodies containing the word amazon.

invitation_namestring required

Name shown on the TC invitation card (max 30 chars). Same field as target_collab.invitation_name on the full TC create.

valid_untilstring date nullable

Date the TC card stops being valid. Defaults to today + 30 days when omitted. After this date the dispatcher stops the underlying automation (see internal/queries/automations_to_run.py).

Response

Successful Response

automation_idinteger required

Underlying Automations.automation_id, for polling.

statusstring required

Always queued on success. The underlying automation is running immediately; the field name reflects delivery semantics (the TC invite itself is queued for the worker).

creator_idstring required

Resolved creator_id for the supplied handle.

creator_handlestring required

The handle echoed back (stripped of any leading @).

shop_idinteger required

Shop the invite was created under.

check_status_atstring required

Relative URL for polling automation state — /public/v1/automations/{automation_id}.

queued_atstring required

ISO-8601 timestamp at which the start transition fired.

dry_runboolean

True when X-Dry-Run was set — no automation row was created and no worker job was queued. automation_id is 0 and queued_at reflects the request time.

Changes

No recorded changes to this endpoint across all 1 revision of this API.