API workflows - SideShift

Each recipe below states its goal and the scopes it needs, then shows a curl call and the response shape straight from the API reference. They all assume you already hold an access token. See the OAuth quickstart for registration, the PKCE authorization-code flow, and the token exchange. Every request goes to the production base URL and carries the bearer token:

Base URL:  https://app.sideshift.app/api/oauth/v1
Header:    Authorization: Bearer <access_token>

A few conventions used throughout (see Errors and rate limits for the full rules):

Cursor pagination. List responses are { data, nextCursor, hasMore }. Pass an opaque cursor (from a prior nextCursor) plus an optional limit (default 25, max 100; messaging lists on SideShift’s own messaging clamp to 50). When hasMore is false, nextCursor is null.
Idempotency. Every POST/PATCH/PUT accepts an Idempotency-Key header. Replaying the same key + body returns the original response; the same key with a different body is rejected with 409 idempotency_conflict. Sensitive money-moving writes (/payouts/execute, /payouts/quick-pay) require it.
Errors. Every error is { error: { code, message, requestId } }. Lists and reads can return 401/402/403/429; writes add 400/404/409.
Each request has one effective tenant. It defaults to the connected company; an agency-parent OAuth grant can select one consented direct child with X-Act-As-Company. There is no cross-tenant union, and unknown query parameters such as companyId or client are not general tenant selectors.

Realistic placeholder ids used below: company Dsc8SfHtPjzNGDKzMqBP, campaign prog_abc123, contract ctr_abc123, creator user_xyz, invoice inv_abc123. Conversation and message ids on SideShift’s own messaging are bare UUIDs, such as 6f1d2c3b-8a4e-4b9c-9d0e-1f2a3b4c5d6e. Post ids are the platform’s own and are not prefixed, so they appear as bare numbers such as 7661286873087642894.

1. Create a complete campaign and update its payment structure

Goal: create a usable campaign in one call, update its CPM payment structure, then read it back. Scopes: campaigns:write to create/update, campaigns:read to read.

Create the campaign - `POST /campaigns`

The campaign must include complete payout/tracking terms. Tracking-only campaigns can omit payout amounts and expected-post targets, but must set analyticsOnly: true and name at least one platform. Omitted status defaults to active, so the campaign immediately appears in analytics filters; pass "status": "draft" explicitly to keep it unpublished.

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "Spring TikTok Push",
    "paymentStructure": { "type": "fixed", "analyticsOnly": true },
    "requirements": { "platforms": ["tiktok"] }
  }'

201 Created returns the new id:

{ "data": { "id": "prog_abc123" } }

Set the payment structure - `PUT /campaigns/{id}/payment-structure`

Replace the structure. The body wraps a paymentStructure object (forwarded to the campaign update service verbatim - cpmRate >= 0 normalization and crosspostMaturityDays validation are reused from the canonical service).

curl -X PUT https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/payment-structure \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "paymentStructure": { "type": "cpm", "cpmRate": 5, "paymentBasis": "views" } }'

200 OK:

{ "data": { "id": "prog_abc123" } }

Read it back with GET /campaigns/{id}/payment-structure:

curl https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/payment-structure \
  -H "Authorization: Bearer $TOKEN"

{ "data": { "type": "cpm", "cpmRate": 5, "paymentBasis": "views", "crosspostMaturityDays": 7 } }

Read the whole campaign - `GET /campaigns/{id}`

curl https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123 \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "id": "prog_abc123",
    "name": "Spring TikTok Push",
    "description": "Q2 creator push on TikTok",
    "emoji": "🚀",
    "campaignType": "ugc",
    "experienceMode": "standard",
    "paymentStructure": { "type": "cpm", "cpmRate": 5, "paymentBasis": "views" }
  }
}

GET /campaigns lists campaigns (paged, with optional status and search filters). PATCH /campaigns/{id} updates fields, and there are POST /campaigns/{id}/archive and POST /campaigns/{id}/duplicate lifecycle actions, all campaigns:write.

Optional next step - post the campaign to the marketplace

The id returned above is the campaign’s programId. The final, opt-in step of the create-campaign flow - mirroring the dashboard’s “Post & Get Applications” button - is to post the campaign to the Creator Marketplace so creators can discover it and apply. Pass that programId to POST /jobs (with marketplace targeting and a cover image); see §8 Post an existing campaign to the marketplace. Skip it if you’d rather bring creators on directly via invites or contract offers (§3).

2. List and process applications

A campaign application is a creator’s handle request against one of your campaigns. The platform exposes approve and reject only - there is no “shortlist” action. Scopes: applications:read to list/get, applications:write to review. Not every application carries a handle. Campaign-manager campaigns never collect one. Paid-ads campaigns collect one only when the campaign needs ad authorization for that platform - otherwise a paid-ads acceptance is handle-free too. A handle-free acceptance lands in the same queue as a campaign-join request: isJoinRequest is true, handle is an empty string, and platform is null. Branch on isJoinRequest before rendering handle or platform copy. Approving a join request approves the membership itself; no handle is added to the campaign.

List applications - `GET /applications`

Cursor-paginated, sorted pending → approved → rejected.

curl "https://app.sideshift.app/api/oauth/v1/applications?limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "prog_abc123_r1",
      "programId": "prog_abc123",
      "requestId": "r1",
      "handle": "@janecreator",
      "platform": "tiktok",
      "status": "pending",
      "creator": { "id": "user_xyz", "name": "Jane Creator" },
      "isJoinRequest": false
    },
    {
      "id": "prog_abc123_r2",
      "programId": "prog_abc123",
      "requestId": "r2",
      "handle": "",
      "platform": null,
      "status": "pending",
      "creator": { "id": "user_pqr", "name": "Sam Creator" },
      "isJoinRequest": true
    }
  ],
  "nextCursor": "eyJpZCI6InByb2dfYWJjMTIzX3IyIn0=",
  "hasMore": false
}

Application id is composite. The id is {programId}_{requestId} (here prog_abc123_r1) - that exact string is what you pass to the get and status endpoints. Don’t try to reconstruct it from parts.

Get one application - `GET /applications/{id}`

curl https://app.sideshift.app/api/oauth/v1/applications/prog_abc123_r1 \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "id": "prog_abc123_r1",
    "programId": "prog_abc123",
    "requestId": "r1",
    "handle": "@janecreator",
    "platform": "tiktok",
    "status": "pending",
    "creator": { "id": "user_xyz", "name": "Jane Creator" },
    "isJoinRequest": false
  }
}

Approve - `POST /applications/{id}/status`

action is approve or reject only. Approving auto-accepts the program contract and sends the creator a direct message + signed PDF + notifications (sensitive), so use a fresh Idempotency-Key. Approval is also where your plan’s creator seat cap is enforced. If approving would exceed the cap, the call returns 402 with code: subscription_required, the application stays pending, and nothing is written:

{
  "error": {
    "code": "subscription_required",
    "message": "You're using 10 of 10 creator seats. Upgrade to keep hiring, or end a contract to free one.",
    "requestId": "req_..."
  }
}

Free a seat by ending an active contract, or upgrade the plan, then retry the same approve call.

curl -X POST https://app.sideshift.app/api/oauth/v1/applications/prog_abc123_r1/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "action": "approve" }'

200 OK - on approve you get the auto-created contract id and its status:

{
  "data": {
    "requestId": "r1",
    "creatorId": "user_x",
    "programId": "prog_abc123",
    "contractId": "ctr_1",
    "status": "approved",
    "contractStatus": "active"
  }
}

Reject - same endpoint, `action: "reject"`

curl -X POST https://app.sideshift.app/api/oauth/v1/applications/prog_abc123_r2/status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "action": "reject" }'

{ "data": { "requestId": "r2", "programId": "prog_abc123", "contractId": null, "status": "rejected" } }

3. Invite and contract a creator

Two ways to bring a creator onto a campaign: a shareable invite link (anyone with it can join), or a direct contract offer to a specific creator.

Create a campaign invite link - `POST /campaigns/{id}/invites`

This is the product’s mechanism for inviting creators to a campaign. The body is optional; you can cap uses and expiry. Returns a token + shareable link. Scope: creators:write.

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/invites \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "expiresInDays": 14, "maxUses": 25, "label": "Spring outreach" }'

201 Created:

{ "data": { "token": "a1b2c3", "link": "https://app.sideshift.app/program-invite/a1b2c3" } }

There is also a tenant-wide invite surface - GET /invites (list, creators:read), POST /invites (create with programId in the body, creators:write), and DELETE /invites/{id} (revoke by token, creators:write). See workflow note below. Team-member invites are not on this surface yet - a non-campaign invite type is rejected with 400.

Offer a contract - `POST /contracts`

The UI-equivalent of inviting a specific creator to a campaign. companyId is always the token’s tenant (never client-supplied); programId must belong to it. Required: programId, contractorId, contractorName. Fires the invite notification + contract PDF (sensitive). Scope: contracts:write.

curl -X POST https://app.sideshift.app/api/oauth/v1/contracts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "programId": "prog_abc123", "contractorId": "user_xyz", "contractorName": "Jane Creator" }'

201 Created:

{ "data": { "id": "ctr_new123", "programId": "prog_abc123" } }

List contracts - `GET /contracts`

Cursor-paginated, with optional status, programId, creatorId filters. Scope: contracts:read.

curl "https://app.sideshift.app/api/oauth/v1/contracts?programId=prog_abc123&limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    { "id": "ctr_abc123", "companyId": "Dsc8SfHtPjzNGDKzMqBP", "contractorId": "user_xyz", "programId": "prog_abc123", "status": "active" },
    { "id": "ctr_def456", "companyId": "Dsc8SfHtPjzNGDKzMqBP", "contractorId": "user_qrs", "programId": "prog_abc123", "status": "pending" }
  ],
  "nextCursor": "eyJpZCI6ImN0cl9kZWY0NTYifQ==",
  "hasMore": false
}

GET /contracts/{id} returns a single contract in the same shape.

Update one creator’s contract - `PATCH /contracts/{id}`

Use the targeted update when one creator’s base retainer or posting platforms change. Scope: contracts:write. Only send the values you intend to change. The API resolves the contract’s effective campaign + per-creator terms and preserves every unmentioned payment field and requirement. platforms is the creator’s exact replacement set, not a union. The campaign must already use per-creator payment terms; a campaign-level contract returns 409 conflict with guidance to update the campaign instead.

curl -X PATCH https://app.sideshift.app/api/oauth/v1/contracts/ctr_abc123 \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "baseRetainer": 1250,
    "platforms": ["tiktok", "instagram"]
  }'

A real edit uses the dashboard’s contract-change flow: it validates the resulting terms, appends history, regenerates the PDF, re-opens an active contract for creator review, and sends the creator a review-link DM.

{
  "data": {
    "success": true,
    "changed": true,
    "contractId": "ctr_abc123",
    "updatedFields": ["baseRetainer", "platforms"],
    "previous": {
      "baseRetainer": 1000,
      "platforms": ["tiktok"]
    },
    "current": {
      "baseRetainer": 1250,
      "platforms": ["tiktok", "instagram"]
    },
    "pdfRegenerated": true,
    "pendingCreatorContractUpdate": true
  }
}

Repeating an already-current value is a no-op: changed is false, and the API does not regenerate the PDF, append history, or notify the creator. Sandbox grants cannot call this endpoint because a real edit sends an external DM.

Cancel a contract - `POST /contracts/{id}/cancel`

Scope: contracts:write.

curl -X POST https://app.sideshift.app/api/oauth/v1/contracts/ctr_abc123/cancel \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

{ "data": { "id": "ctr_abc123", "status": "cancelled" } }

4. Add ghost handles and videos to a campaign

Goal: use the normal SideShift campaign flow to add tracked handles or videos, one at a time or in bulk. Scope: campaigns:write. The campaign id lives in the URL and the company tenant comes from the OAuth token. The bulk endpoints accept structured JSON, so API clients do not need to construct the CSV used by the dashboard uploader.

Add one handle - `POST /campaigns/{id}/ghost-handles`

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/ghost-handles \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "platform": "tiktok",
    "handle": "@janecreator",
    "description": "Track this account"
  }'

Use optional creatorId to attach the ghost handle to an existing creator. Supported handle platforms are tiktok, instagram, youtube, snapchat, facebook, twitter, and x.

Bulk add handles - `POST /campaigns/{id}/ghost-handles/bulk`

One request accepts 1–500 handles. Existing platform + handle pairs are skipped and reported in the response.

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/ghost-handles/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "handles": [
      { "platform": "tiktok", "handle": "@janecreator", "name": "Jane Creator" },
      { "platform": "instagram", "handle": "brandclips" }
    ]
  }'

{
  "data": {
    "programId": "prog_abc123",
    "summary": { "total": 2, "created": 1, "skipped": 1, "errors": 0 },
    "results": [
      {
        "platform": "tiktok",
        "handle": "janecreator",
        "status": "created",
        "contractId": "ctr_abc123"
      },
      {
        "platform": "instagram",
        "handle": "brandclips",
        "status": "skipped",
        "reason": "Handle already exists in program"
      }
    ]
  }
}

Add one video - `POST /campaigns/{id}/ghost-videos`

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/ghost-videos \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "platform": "youtube",
    "videoUrl": "https://www.youtube.com/watch?v=abc123",
    "creatorId": "creator_abc123"
  }'

creatorId and description are optional. Supported video platforms are tiktok, instagram, youtube, and snapchat.

Bulk add videos - `POST /campaigns/{id}/ghost-videos/bulk`

One request accepts 1–500 videos. platform is optional when SideShift can detect it from the URL; existing URLs in the campaign are skipped.

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/ghost-videos/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "videos": [
      {
        "ghostName": "Jane Creator",
        "platform": "tiktok",
        "videoUrl": "https://www.tiktok.com/@jane/video/123"
      },
      {
        "ghostName": "Brand Clip",
        "videoUrl": "https://www.instagram.com/reel/abc123/"
      }
    ]
  }'

Backfill observed daily history - `POST /campaigns/{id}/analytics-history`

Use this when migrating from another analytics provider. Send cumulative observations (never estimated/interpolated values) captured before SideShift’s first native snapshot. The endpoint resolves each row within the token-bound company and campaign, derives daily deltas, re-bases the first native snapshot, and verifies Firestore plus Postgres before an import succeeds. The same endpoint has two modes:

validate (default) runs identity resolution and the complete splice plan without writes.
import writes the validated batch. It requires the exact current confirmCampaignName.

Every request requires an 8–200 character Idempotency-Key. Reuse a key only to retry the exact same body. A batch supports 1–2,000 rows and at most 500 unique posts. Partition larger exports by post; never split one post’s history across requests. Each included post must carry its complete imported history so an earlier newly supplied date can safely recalculate successor deltas. Validate first:

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/analytics-history \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hardlaunch-rezi-batch-01-validate" \
  -d '{
    "mode": "validate",
    "sourceId": "hardlaunch-rezi-2026-08-01",
    "unmatchedPostPolicy": "error",
    "rows": [
      {
        "postId": "7661286873087642894",
        "date": "2026-07-11",
        "cumulative": {
          "views": 374,
          "likes": 2,
          "comments": 0,
          "shares": 0,
          "bookmarks": 0
        }
      }
    ]
  }'

postId or postUrl is required; supplying both is allowed. Instagram shortcodes from provider exports are resolved through the tracked URL. All five cumulative metrics are required because the Firestore and Postgres history rows share that complete observation contract. Use 0 only when the provider observed zero; do not substitute zero for an unavailable metric. Dates are UTC YYYY-MM-DD. Cumulative declines are preserved as real negative deltas and returned as warnings. When validation returns ready: true, submit the same rows in import mode with a fresh key:

curl -X POST https://app.sideshift.app/api/oauth/v1/campaigns/prog_abc123/analytics-history \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hardlaunch-rezi-batch-01-import" \
  -d '{
    "mode": "import",
    "sourceId": "hardlaunch-rezi-2026-08-01",
    "confirmCampaignName": "Rezi Automations",
    "unmatchedPostPolicy": "error",
    "rows": [
      {
        "postId": "7661286873087642894",
        "date": "2026-07-11",
        "cumulative": { "views": 374, "likes": 2, "comments": 0, "shares": 0, "bookmarks": 0 }
      }
    ]
  }'

The response includes input/resolution counts, planned history and boundary writes, blockers, warnings, and (after import) exact Firestore/Postgres verification counts. Details are capped at 100 entries with companion *Truncated flags; summary counts always describe the full batch. Unmatched rows block by default. After investigating a known unmatched subset, set unmatchedPostPolicy: "skip"; an import must also provide expectedUnmatchedPostCount equal to the validated batch’s exact summary.unmatchedPosts. This prevents a changed batch from silently skipping more posts. Sandbox grants can validate, but cannot import.

Read analytics for tracked content

curl "https://app.sideshift.app/api/oauth/v1/analytics/accounts?program=prog_abc123&limit=50" \
  -H "Authorization: Bearer $TOKEN"

With analytics:read, the response groups tracked posts by creator handle + platform and includes per-account post, view, and engagement totals plus a cross-account summary. The other aggregate reads are GET /analytics/overview, /analytics/kpis, /analytics/time-series, and /analytics/videos.

5. Payout read flows

Read your wallet ledger, pending amounts, and balances. Scope: payouts:read.

Payout history - `GET /payouts`

Wallet ledger entries (payouts + deposits), cursor-paginated, with an aggregate summary. Optional filters: type (debit/credit), creatorId, contractId, status, fromDate, toDate, reason.

curl "https://app.sideshift.app/api/oauth/v1/payouts?type=debit&limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "led_abc123",
      "amount": 625,
      "type": "debit",
      "status": "completed",
      "description": "Payout for ctr_abc123",
      "contractId": "ctr_abc123",
      "creatorId": "user_xyz",
      "programId": "prog_abc123",
      "createdAt": "2026-06-17T18:00:00Z"
    }
  ],
  "summary": { "totalDebits": 625, "totalCredits": 5000, "net": 4375 },
  "nextCursor": "eyJpZCI6ImxlZF9kZWY0NTYifQ==",
  "hasMore": false
}

Pending payouts - `GET /payouts/pending`

Calculated pending/overdue amounts for active/expired contracts. Optional programId, creatorId, minAmount, sortBy (amount/dueDate/creator), sortOrder.

curl "https://app.sideshift.app/api/oauth/v1/payouts/pending?sortBy=amount&sortOrder=desc" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "ctr_abc123",
      "contractId": "ctr_abc123",
      "contractName": "Jane Creator — Spring TikTok Push",
      "amount": 625,
      "status": "due",
      "dueDate": "2026-06-20T00:00:00Z",
      "creatorId": "user_xyz",
      "creatorName": "Jane Creator",
      "programId": "prog_abc123"
    }
  ],
  "summary": { "totalPending": 625, "count": 1 },
  "nextCursor": null,
  "hasMore": false
}

Wallet + payout stats - `GET /payouts/stats`

curl https://app.sideshift.app/api/oauth/v1/payouts/stats \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "availableBalance": 4375,
    "pendingBalance": 625,
    "totalOwed": 625,
    "lifetimeDeposits": 5000,
    "lifetimePaidOut": 625,
    "currency": "USD"
  }
}

Money-moving writes exist but are out of scope for casual use. POST /payouts/execute (run/dry-run contract payouts) and POST /payouts/quick-pay (pay anyone by email) require payouts:write. They are sensitive: the Idempotency-Key header is required (a 400 without it), and sandbox / test-mode grants are rejected with 403 forbidden. Read the idempotency and sandbox rules in Errors and rate limits before calling them.

6. Invoice lifecycle

Create, inspect, (re)send, and void an invoice. Scopes: invoices:write to create/send/void, invoices:read to list/get.

Create + send - `POST /invoices`

Creates and emails an invoice. Sandbox-rejected (fires real Stripe/Whop/Resend side effects) - a sandbox grant returns 403 forbidden. Amounts are in cents. If the invoice allows BNPL rails (klarna, affirm, afterpay_clearpay, sezzle, zip, card installments, and more), the hosted invoice page offers a Pay now / Pay over time picker; BNPL is processed by Whop. The payer total is unchanged, but the merchant’s net proceeds are reduced by a 16% merchant fee when the payer pays over time. BNPL options appear only when the provider is enabled, supports the invoice currency, and the invoice total is within the provider’s supported amount range. Renewal invoices do not offer BNPL.

curl -X POST https://app.sideshift.app/api/oauth/v1/invoices \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "customerEmail": "client@example.com", "lineItems": [{ "description": "Consulting", "amountCents": 50000 }] }'

201 Created (the created invoice plus a top-level url):

{
  "data": {
    "id": "inv_abc123",
    "invoiceNumber": "INV-1001",
    "status": "open",
    "customerEmail": "client@example.com",
    "currency": "usd",
    "totalCents": 50000,
    "hostedInvoiceUrl": "https://app.sideshift.app/invoice/inv_abc123",
    "pdfUrl": "https://app.sideshift.app/invoice/inv_abc123.pdf",
    "createdAt": "2026-06-17T18:00:00Z"
  },
  "url": "https://app.sideshift.app/invoice/inv_abc123"
}

Get one - `GET /invoices/{id}`

curl https://app.sideshift.app/api/oauth/v1/invoices/inv_abc123 \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "id": "inv_abc123",
    "invoiceNumber": "INV-1001",
    "status": "open",
    "customerEmail": "client@example.com",
    "currency": "usd",
    "totalCents": 50000,
    "hostedInvoiceUrl": "https://app.sideshift.app/invoice/inv_abc123",
    "pdfUrl": "https://app.sideshift.app/invoice/inv_abc123.pdf",
    "createdAt": "2026-06-17T18:00:00Z"
  }
}

(Re)send the email - `POST /invoices/{id}/send`

Sends a real email via Resend (sandbox-rejected). Returns the refreshed invoice.

curl -X POST https://app.sideshift.app/api/oauth/v1/invoices/inv_abc123/send \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

{ "data": { "id": "inv_abc123", "invoiceNumber": "INV-1001", "status": "open", "currency": "usd", "totalCents": 50000 } }

Payment links

Set invoiceType to payment_link in the create body to get a shareable checkout link instead of an emailed invoice. Omit the customer fields - the payer enters their name and email at checkout. Reusable links mint a child invoice for each payment. Sending email on a payment link returns 409.

Void - `POST /invoices/{id}/void`

Voids an unpaid invoice (cancels the Whop plan + any in-flight Stripe wire or BNPL PaymentIntent, best-effort). Idempotent - voiding an already-void invoice returns its current state; voiding a paid invoice is 409 already_paid. If a Stripe payment already completed, void fails with 409 payment_not_cancelable - refresh the invoice before voiding.

curl -X POST https://app.sideshift.app/api/oauth/v1/invoices/inv_abc123/void \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

{ "data": { "id": "inv_abc123", "invoiceNumber": "INV-1001", "status": "void", "currency": "usd", "totalCents": 50000 } }

List - `GET /invoices`

Cursor-paginated; optional status (all/open/pending/partial_paid/paid/ void/overdue/refunded/partially_refunded) and customerEmail filters.

curl "https://app.sideshift.app/api/oauth/v1/invoices?status=open&limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "inv_abc123",
      "invoiceNumber": "INV-1001",
      "status": "open",
      "customerEmail": "client@example.com",
      "currency": "usd",
      "totalCents": 50000,
      "hostedInvoiceUrl": "https://app.sideshift.app/invoice/inv_abc123",
      "pdfUrl": "https://app.sideshift.app/invoice/inv_abc123.pdf",
      "createdAt": "2026-06-17T18:00:00Z"
    }
  ],
  "nextCursor": "eyJpZCI6Imludl9hYmMxMjMifQ==",
  "hasMore": false
}

7. Messages

Read the company’s inbox and send messages as the company. Scopes: messages:read to list and read, messages:write to send and manage. SideShift moved chat from a connected provider to its own messaging, one company at a time. A company moves the first time a person opens the app; the API never starts the move. Three states matter to an integration:

Not started. The company keeps the previous behavior: provider-backed conversations, feed_… support-channel ids, and the older conversation ids.
Moving. Every messaging request answers 409 conflict with meta.reason: "messaging_migrating" and meta.retryAfterSeconds: 60. Nothing is sent. The move takes minutes; retry after the delay.
Moved. Every conversation is a native room. Ids are bare UUIDs, rows carry chatType: "native", messages carry source: "native", and writes answer lane: "native". The recipes below show this state.

Old ids keep working after the move: a feed_… id or an older conversation id resolves to the same room. A room that stayed on the provider answers 404 not_found with meta.reason: "conversation_left_on_provider". A machine app (client credentials, no acting person) acts as the company on every messaging route. The product calls the three kinds “Support chat”, “Direct message” and “Group chat”. The API keeps support channel as the wire name for a support chat. Two budgets apply on top of the resource rate limit: 60 message sends and 10 conversation creations per minute, per credential and company. A refused write answers 429 rate_limited with Retry-After and meta.retryAfterSeconds. The full list of typed refusals is in Messaging refusals. The response while a company is moving:

{
  "error": {
    "code": "conflict",
    "message": "This company's messaging is moving to SideShift's own inbox. Retry in a minute.",
    "meta": { "reason": "messaging_migrating", "retryAfterSeconds": 60 },
    "requestId": "req_8f1c2e9a4b7d"
  }
}

Start at the inbox - `GET /inbox`

The merged inbox: support channels and DM conversations by last-message time, the same list a person sees. Each item’s type names the follow-up read and send: support_channel → /support-channels/{id}/messages, dm → /conversations/{id}/messages. It is a snapshot: limit is at most 50, there is no cursor, and hasMore is always false. Page deeper with the two lists below.

curl "https://app.sideshift.app/api/oauth/v1/inbox?limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "type": "support_channel",
      "id": "6f1d2c3b-8a4e-4b9c-9d0e-1f2a3b4c5d6e",
      "name": "Jane Creator",
      "lastMessageAt": "2026-09-07T18:05:00Z",
      "lastMessagePreview": "Thanks, sending the brief now!",
      "lastMessageBy": "Jane Creator",
      "unreadCount": 1,
      "customer": { "externalUserId": null, "username": null, "name": "Jane Creator" },
      "customerUserId": "user_xyz",
      "participants": [{ "id": "user_xyz", "name": "Jane Creator", "profileImageUrl": null }],
      "chatType": "native"
    },
    {
      "type": "dm",
      "id": "9d2b4f6a-0c1e-4d3f-8a5b-6c7d8e9f0a1b",
      "name": "Launch crew",
      "lastMessageAt": "2026-09-06T09:12:00Z",
      "lastMessagePreview": "Posting schedule is in the doc.",
      "lastMessageBy": "Acme Inc",
      "unreadCount": 0,
      "customer": null,
      "customerUserId": null,
      "participants": [{ "id": "user_xyz", "name": "Jane Creator", "profileImageUrl": null }],
      "chatType": "native"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

On a native row lastMessageBy is the sender’s display name, and unreadCount is the company’s own count on every item.

Support channels - `GET /support-channels` and `POST /support-channels/{id}/messages`

A support channel is the main employer-creator conversation: applicant chats, campaign invites, payout receipts and creator support all land here. On a company that has moved, open is ignored (a native room is never resolved), resolvedAt is always null, and limit is clamped to 50. nextCursor is an opaque string: pass it back as cursor.

curl "https://app.sideshift.app/api/oauth/v1/support-channels?limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "6f1d2c3b-8a4e-4b9c-9d0e-1f2a3b4c5d6e",
      "customName": null,
      "customerUser": { "externalUserId": null, "username": null, "name": "Jane Creator" },
      "customerName": "Jane Creator",
      "customerUserId": "user_xyz",
      "lastMessageAt": "2026-09-07T18:05:00Z",
      "lastMessagePreview": "Thanks, sending the brief now!",
      "lastMessageBy": "Jane Creator",
      "resolvedAt": null,
      "createdAt": null,
      "chatType": "native"
    }
  ],
  "nextCursor": "eyJwYWdlIjoyfQ==",
  "hasMore": true
}

Read the thread with GET /support-channels/{id}/messages; the items have the message shape shown under conversations below. Send into the channel with an Idempotency-Key, and reuse the same key if the call times out:

curl -X POST https://app.sideshift.app/api/oauth/v1/support-channels/6f1d2c3b-8a4e-4b9c-9d0e-1f2a3b4c5d6e/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "content": "Hi Jane! The brief is on the campaign page." }'

201 Created:

{
  "data": {
    "id": "0c9a7b1e-3d5f-4a2b-8c6d-7e8f9a0b1c2d",
    "channelId": "6f1d2c3b-8a4e-4b9c-9d0e-1f2a3b4c5d6e",
    "delivered": true,
    "createdAt": "2026-09-07T18:10:00Z"
  }
}

List conversations - `GET /conversations`

Every room the company belongs to, support rooms included on a company that has moved. Cursor-paginated, limit clamped to 50. channelId on a native room is the former provider channel id when the room was moved from one, else null.

curl "https://app.sideshift.app/api/oauth/v1/conversations?limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "9d2b4f6a-0c1e-4d3f-8a5b-6c7d8e9f0a1b",
      "lastMessage": "Posting schedule is in the doc.",
      "lastMessageBy": "Acme Inc",
      "members": ["Dsc8SfHtPjzNGDKzMqBP", "user_xyz"],
      "groupName": "Launch crew",
      "isProgramGroupChat": true,
      "isSystemNotification": false,
      "timestamp": "2026-09-06T09:12:00Z",
      "isBookmarked": false,
      "unreadCount": 0,
      "channelId": null,
      "chatType": "native",
      "participants": [{ "id": "user_xyz", "name": "Jane Creator", "profileImageUrl": null }]
    }
  ],
  "nextCursor": "eyJwYWdlIjoyfQ==",
  "hasMore": true
}

Read a conversation’s messages - `GET /conversations/{id}/messages`

Newest first, both directions, limit clamped to 50. A conversation the company does not belong to, or one that does not exist, is 404 not_found. A 502 upstream_error means the read failed mid-page: retry with the same cursor.

curl "https://app.sideshift.app/api/oauth/v1/conversations/9d2b4f6a-0c1e-4d3f-8a5b-6c7d8e9f0a1b/messages?limit=25" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": [
    {
      "id": "4b2e6d8a-1c3f-4e5a-9b7c-2d4f6a8c0e1b",
      "content": "Thanks, sending the brief now!",
      "source": "native",
      "senderUserId": "user_xyz",
      "senderName": "Jane Creator",
      "senderExternalUserId": null,
      "senderUsername": null,
      "createdAt": "2026-09-07T18:05:00Z",
      "updatedAt": "2026-09-07T18:05:00Z",
      "isEdited": false,
      "isDeleted": false,
      "replyingToMessageId": null,
      "threadRootId": null,
      "reactionCounts": [{ "emoji": "❤️", "count": 1 }],
      "attachmentCount": 0
    },
    {
      "id": "0c9a7b1e-3d5f-4a2b-8c6d-7e8f9a0b1c2d",
      "content": "Hi! Following up on the campaign.",
      "source": "native",
      "senderUserId": "Dsc8SfHtPjzNGDKzMqBP",
      "senderName": "Acme Inc",
      "senderExternalUserId": null,
      "senderUsername": null,
      "createdAt": "2026-09-07T18:00:00Z",
      "updatedAt": "2026-09-07T18:00:00Z",
      "isEdited": false,
      "isDeleted": false,
      "replyingToMessageId": null,
      "threadRootId": null,
      "reactionCounts": [],
      "attachmentCount": 0
    }
  ],
  "nextCursor": null,
  "hasMore": false
}

senderUserId is the sender’s SideShift user id (the company id for the company’s own messages). The items also carry sender and timestamp, older names for senderName and createdAt.

Send a message - `POST /messages`

Sandbox-rejected - this sends a real message, so a sandbox grant returns 403 forbidden. Provide exactly one of conversationId (post into an existing room) or creatorId, plus content. creatorId resolves the pair’s conversation - a native room on a company that has moved - and creates it when none exists; a creator the company cannot message answers 404 not_found with meta.reason. attachment_ids are provider file ids: a native room refuses them with 400 invalid_request (attachments_unsupported_on_native_conversation) and sends nothing - resend without them.

curl -X POST https://app.sideshift.app/api/oauth/v1/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "creatorId": "user_xyz", "content": "Hi! Following up on the campaign." }'

201 Created:

{
  "data": {
    "messageId": "0c9a7b1e-3d5f-4a2b-8c6d-7e8f9a0b1c2d",
    "conversationId": "6f1d2c3b-8a4e-4b9c-9d0e-1f2a3b4c5d6e",
    "delivered": true,
    "externalMessageId": null,
    "lane": "native"
  }
}

Message ids are bare UUIDs everywhere. A route that takes a message_id (react, forward) accepts a native:-prefixed id too.

Manage a conversation

The other writes, and what a native room answers:

Call	Body	Native answer
`POST /conversations`	`participantId`, or `groupName` + `participantIds`	`{ id, conversationId, channelId, lane: "native" }` - an existing 1:1 room is reused
`POST /conversations/{id}/reactions`	`message_id`, `emoji`	`{ success, emoji, messageId }`
`POST /conversations/{id}/forward`	`content`, optional `message_id`	`{ forwarded, messageId, delivered: true, externalMessageId: null, recipientId: null, lane: "native" }`
`POST /conversations/{id}/members`	`member_id` (a creator id)	`{ member: { userId, principalId } }`
`DELETE /conversations/{id}/members`	-	`{ left: true }`
`PATCH /conversations/{id}`	`name` (blank clears it)	`{ success, name }`

POST /conversations spends the creation budget (10 per minute); the sends and the forward spend the send budget (60 per minute).

8. Post an existing campaign to the marketplace

Goal: post a campaign to the marketplace so creators can discover it and apply - the same result as the dashboard’s “Post & Get Applications” button. This is the opt-in final step of the create-campaign flow, whether the campaign is one you just created in §1 or an existing one. Scope: jobs:write. A “campaign posted to the marketplace” is a job linked to the campaign. Create a job with programId set to the campaign id: the job appears in the public feed and its applications flow back to the campaign. (Creating a job spends 1 posting credit and requires a cover image - pass a hosted imageUrl or an inline imageDataUrl.) End to end, the flow is: create a campaign (§1) → (optional) post it to the marketplace with targeting (below) → applications come in (§2).

Post the campaign - `POST /jobs`

curl -X POST https://app.sideshift.app/api/oauth/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "title": "Spring TikTok Push — creators wanted",
    "description": "Post short-form TikToks for our spring push.",
    "jobType": "Content Creator",
    "creatorType": "ugc_ads",
    "paymentType": "performance",
    "cpmRate": "5",
    "imageUrl": "https://cdn.example.com/spring-push.png",
    "platformFocus": ["TikTok"],
    "ageRequirement": "18+",
    "contentType": "UGC",
    "accountType": "personal_account",
    "programId": "prog_abc123"
  }'

201 Created returns the new job id - the campaign is now discoverable and accepting applications:

{ "data": { "jobId": "job_abc123", "programId": "prog_abc123", "imageUrl": "https://cdn.example.com/spring-push.png" } }

Use programIds instead of programId to link the job to several campaigns at once. Applications land on the linked campaign(s) - process them with the applications flow. To post to multiple campaigns or pull the linked job later, GET /jobs lists the tenant’s jobs.The MCP equivalent is the create_job tool with programId set - same single mechanism, same “Post & Get Applications” result.

​1. Create a complete campaign and update its payment structure

​Create the campaign - POST /campaigns

​Set the payment structure - PUT /campaigns/{id}/payment-structure

​Read the whole campaign - GET /campaigns/{id}

​Optional next step - post the campaign to the marketplace

​2. List and process applications

​List applications - GET /applications

​Get one application - GET /applications/{id}

​Approve - POST /applications/{id}/status

​Reject - same endpoint, action: "reject"

​3. Invite and contract a creator

​Create a campaign invite link - POST /campaigns/{id}/invites

​Offer a contract - POST /contracts

​List contracts - GET /contracts

​Update one creator’s contract - PATCH /contracts/{id}

​Cancel a contract - POST /contracts/{id}/cancel

​4. Add ghost handles and videos to a campaign

​Add one handle - POST /campaigns/{id}/ghost-handles

​Bulk add handles - POST /campaigns/{id}/ghost-handles/bulk

​Add one video - POST /campaigns/{id}/ghost-videos

​Bulk add videos - POST /campaigns/{id}/ghost-videos/bulk

​Backfill observed daily history - POST /campaigns/{id}/analytics-history

​Read analytics for tracked content

​5. Payout read flows

​Payout history - GET /payouts

​Pending payouts - GET /payouts/pending

​Wallet + payout stats - GET /payouts/stats

​6. Invoice lifecycle

​Create + send - POST /invoices

​Get one - GET /invoices/{id}

​(Re)send the email - POST /invoices/{id}/send

​Payment links

​Void - POST /invoices/{id}/void

​List - GET /invoices

​7. Messages

​Start at the inbox - GET /inbox

​Support channels - GET /support-channels and POST /support-channels/{id}/messages

​List conversations - GET /conversations

​Read a conversation’s messages - GET /conversations/{id}/messages

​Send a message - POST /messages

​Manage a conversation

​8. Post an existing campaign to the marketplace

​Post the campaign - POST /jobs

1. Create a complete campaign and update its payment structure

Create the campaign - `POST /campaigns`

Set the payment structure - `PUT /campaigns/{id}/payment-structure`

Read the whole campaign - `GET /campaigns/{id}`

Optional next step - post the campaign to the marketplace

2. List and process applications

List applications - `GET /applications`

Get one application - `GET /applications/{id}`

Approve - `POST /applications/{id}/status`

Reject - same endpoint, `action: "reject"`

3. Invite and contract a creator

Create a campaign invite link - `POST /campaigns/{id}/invites`

Offer a contract - `POST /contracts`

List contracts - `GET /contracts`

Update one creator’s contract - `PATCH /contracts/{id}`

Cancel a contract - `POST /contracts/{id}/cancel`

4. Add ghost handles and videos to a campaign

Add one handle - `POST /campaigns/{id}/ghost-handles`

Bulk add handles - `POST /campaigns/{id}/ghost-handles/bulk`

Add one video - `POST /campaigns/{id}/ghost-videos`

Bulk add videos - `POST /campaigns/{id}/ghost-videos/bulk`

Backfill observed daily history - `POST /campaigns/{id}/analytics-history`

Read analytics for tracked content

5. Payout read flows

Payout history - `GET /payouts`

Pending payouts - `GET /payouts/pending`

Wallet + payout stats - `GET /payouts/stats`

6. Invoice lifecycle

Create + send - `POST /invoices`

Get one - `GET /invoices/{id}`

(Re)send the email - `POST /invoices/{id}/send`

Payment links

Void - `POST /invoices/{id}/void`

List - `GET /invoices`

7. Messages

Start at the inbox - `GET /inbox`

Support channels - `GET /support-channels` and `POST /support-channels/{id}/messages`

List conversations - `GET /conversations`

Read a conversation’s messages - `GET /conversations/{id}/messages`

Send a message - `POST /messages`

Manage a conversation

8. Post an existing campaign to the marketplace

Post the campaign - `POST /jobs`