Campaigns

A campaign is a budgeted creator program with payout rules and platform targeting. Org-scoped: the URL identifies the organization.

Operations

Operation	Method + path	Token scope	Role	Notes
List campaigns	`GET /organizations/:organization_id/campaigns.json`	`read` or `write`	Organization member	Paginated
Show campaign	`GET /organizations/:organization_id/campaigns/:id.json`	`read` or `write`	Organization member	ETag on `show`
Create campaign	`POST /organizations/:organization_id/campaigns.json`	`write`	Organization admin	Creates a draft
Update campaign	`PATCH /organizations/:organization_id/campaigns/:id.json`	`write`	Organization admin	Post-publish fields are restricted
Delete campaign	`DELETE /organizations/:organization_id/campaigns/:id.json`	`write`	Organization admin	Only allowed while still deletable by business rules

Resource shape

{
  "id": "rTcVwY",
  "name": "Summer UGC Campaign",
  "status": "draft",
  "currency": "usd",
  "countries": ["US", "GB"],
  "website": "https://example.com/product",
  "content_type": "ugc",
  "category": "product",
  "platform_ids": ["youtube", "tiktok"],
  "tiktok_music_id": "7038475063498387456",
  "cpm_amount": 500,
  "min_payout_amount": 1000,
  "max_payout_amount": 10000,
  "base_reward_amount": 0,
  "total_budget_amount": 0,
  "used_amount": 0,
  "unused_amount": 0,
  "view_count": 0,
  "submissions_count": 0,
  "published_at": null,
  "paused_at": null,
  "created_at": "2026-05-01T10:00:00Z",
  "updated_at": "2026-05-06T10:00:00Z",
  "url": "https://app.paidcollabs.com/organizations/gKpMxN/campaigns/rTcVwY.json",
  "banner_image_url": "https://app.paidcollabs.com/rails/active_storage/...",
  "brief": "<p>Create a product demo in your own style...</p>"
}

status is one of draft, active, paused, finished. brief is included on show only and is rendered HTML (rich text).

List

GET /organizations/:organization_id/campaigns.json

Returns the organization’s campaigns (subject to your role’s policy scope). Paginated.

Show

GET /organizations/:organization_id/campaigns/:id.json

Returns one campaign including the rendered brief HTML. Sets an ETag.

Create

POST /organizations/:organization_id/campaigns.json

{
  "campaign": {
    "name": "Summer UGC Campaign",
    "website": "https://example.com/product",
    "content_type": "ugc",
    "category": "product",
    "currency": "usd",
    "cpm_amount": 500,
    "min_payout_amount": 1000,
    "max_payout_amount": 10000,
    "base_reward_amount": 0,
    "platform_ids": ["youtube", "tiktok"],
    "countries": ["US", "GB"],
    "brief": "<p>Create a product demo in your own style...</p>"
  }
}

Creates a draft campaign. Requires a write-scoped token and an admin role on the organization. Returns 201 Created with the new campaign.

If you omit optional fields, the server fills them from the campaign form defaults where possible. Budget totals always start at zero on create; funding happens separately.

Update

PATCH /organizations/:organization_id/campaigns/:id.json

{
  "campaign": {
    "name": "Updated campaign name",
    "cpm_amount": 650
  }
}

Returns 200 OK with the updated campaign.

Once a campaign has been published, only the same fields allowed in the web UI remain writable; financial fields are no longer accepted.

Delete

DELETE /organizations/:organization_id/campaigns/:id.json

Returns 204 No Content. Fails if the campaign is no longer a draft or already has fundings.

State transitions (not yet exposed via JSON)

POST .../publish, .../pause, and .../resume still redirect today. JSON support is not rolled out for those actions yet.

Errors

Code	When
`401`	Missing token, or read token attempting a write
`403`	You’re authenticated but your role can’t perform this action
`404`	Campaign or org does not exist for you
`422`	Validation failed