Skip to main content
Use these operations when a handle was imported before its creator was known. Both preserve the existing contract ID, post IDs, and daily analytics history. One creator can have several attached ghost handles, within one campaign or across campaigns. Call the operation once per ghost contract with the same creatorId. Each ghost contract has one creator assignment. These endpoints do not move a handle from one real creator to another or merge two existing creator contracts.

​
Before you start

Use a scoped Platform API key or OAuth access token. Both use https://app.sideshift.app/api/oauth/v1. Legacy API keys for /api/v1 cannot call these routes. Your company must have an active subscription. You need three SideShift IDs:
  • Campaign ID: the campaign that contains the ghost handle.
  • Ghost contract ID: the contractId returned when that handle was created.
  • Creator ID: the creator’s user ID, such as an id returned by List creators. Do not use a social handle, a contract ID, or an ID from your previous provider.
The creator must already be saved in your company’s Creator Database or have a real contract with your company. List creators returns contracted creators; it does not search the full SideShift user directory. For a database-only creator, use the SideShift user ID from your existing mapping or the platform. The campaign and ghost contract must both belong to the credential’s company. For agency subaccounts, use the normal act-as flow. Do not send a companyId in the body.

​
Attach for analytics

For OAuth, replace x-api-key with Authorization: Bearer YOUR_ACCESS_TOKEN. Send only one authentication method.
Attachment changes creator attribution on the contract, its posts, and the matching campaign handle. Tracking and analytics history remain in place. The contract stays a ghost with payments disabled and uses no creator seat. Analytics filters that exclude ghost handles still exclude these posts. If you have not created the handle yet, you can pass creatorId when you add the ghost handle instead of making a separate attachment request.

​
Convert to a creator contract

Use the same body and authentication with the /convert endpoint and a new idempotency key:
A new conversion returns isGhostHandle: false and contractStatus: "pending". It uses the campaign’s payment terms. It does not sign or activate the contract, send an invitation message, or pay the creator. The creator must accept through the normal platform flow. Normal approval and seat checks apply at activation. Complete any required brand-owned document fields before conversion. The API does not accept signatures, payment terms, or arbitrary contract fields in this request. If the creator already has an active or pending real contract in the campaign, conversion returns 409 without changing either contract. Use analytics attachment if you only need the extra handles attributed to that creator. Existing posts and tracking dates are preserved. Review the campaign’s payment terms and payout start before activation: conversion does not reset historical content or create a new tracking period.

​
Batch migrations and retries

Keep a mapping of your previous provider’s record, campaign ID, ghost contract ID, and creator ID. Process one handle per request and record each successful response.
  • Use a distinct Idempotency-Key for each operation and ghost contract. Keys must contain 1–200 characters.
  • After a timeout or 500, retry with the same key, IDs, and body. A completed keyed request returns its original response.
  • Reusing a key with a different campaign, contract, or body returns 409 idempotency_conflict.
  • A request still in progress returns 409. Wait before retrying it. A RESOURCE_CHANGED conflict can be retried with the same request after the campaign or contract change is complete.
  • Respect Retry-After on 429. Process conversions in a campaign sequentially to reduce conflicts from concurrent campaign updates.
Contract attribution, campaign handles, and post attribution commit together in the source database. A failed transaction changes none of them. Analytics read models and cached totals can take time to reflect the change.

​
Supported contracts

These endpoints support unpaid, active or pending, tracking-only ghost handle contracts with at most 450 posts each. A larger contract is rejected before any write. Contact support for larger migrations. Ghost videos, retired creator contracts, and contracts with payment or acceptance history are not supported. Sandbox credentials cannot make these changes. See API errors for the standard error envelope.