Documentation / Campaign management

Campaigns

Create, list, update, and delete campaigns, and manage campaign creators via /sdk/v1.

campaigns · json
{
  "success": true,
  "data": [
    {
      "campaignId": "camp_...",
      "campaignName": "Spring launch",
      "campaignStatus": "ONGOING",
      "tiktokScrapeCountryCode": null,
      "startDate": "2026-03-01T00:00:00.000Z",
      "endDate": null,
      "timeZone": "America/New_York",
      "agencyTimeZone": "America/Los_Angeles",
      "effectiveTimeZone": "America/New_York"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1 },
  "asOfTimestamp": "2026-03-03T12:00:00.000Z",
  "metrics": {
    "campaignCount": 1,
    "totalCreatorsCount": 5,
    "pendingValue": 0,
    "spentValue": 500,
    "committedValue": 1000,
    "totalViews": 25000,
    "totalLikes": 1200,
    "totalComments": 80,
    "totalShares": 45
  }
}
All documentation

All endpoints below require:

  • X-Application-Id
  • X-Api-Key

GET /sdk/v1/campaigns

List campaigns for your agency with optional filtering, sorting, and pagination.

Query parameters

  • page (default 1)
  • limit (default 50)
  • search or query (optional; searches campaign name)
  • sortBy (optional)
  • sortOrder (asc or desc)
  • status (optional)
  • campaignStatuses (optional; comma-separated)
  • paymentStatuses (optional; comma-separated)
  • timeStart and timeEnd (optional; ISO timestamps)
  • endingBefore (optional; ISO timestamp)
  • endingDate (optional; ISO timestamp)

Response

{
  "success": true,
  "data": [
    {
      "campaignId": "camp_...",
      "campaignName": "Spring launch",
      "campaignStatus": "ONGOING",
      "tiktokScrapeCountryCode": null,
      "startDate": "2026-03-01T00:00:00.000Z",
      "endDate": null,
      "timeZone": "America/New_York",
      "agencyTimeZone": "America/Los_Angeles",
      "effectiveTimeZone": "America/New_York"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1 },
  "asOfTimestamp": "2026-03-03T12:00:00.000Z",
  "metrics": {
    "campaignCount": 1,
    "totalCreatorsCount": 5,
    "pendingValue": 0,
    "spentValue": 500,
    "committedValue": 1000,
    "totalViews": 25000,
    "totalLikes": 1200,
    "totalComments": 80,
    "totalShares": 45
  }
}

timeZone is the campaign override and may be null. agencyTimeZone is the agency default and may also be null. effectiveTimeZone is always present and resolves in this order: campaign timezone, agency timezone, then UTC.

TikTok scraping country

Grade can enable scraping locations for your agency. Check SDK settings for access and the supported country list.

Set tiktokScrapeCountryCode to a supported uppercase country code, such as "VN", on campaign creation or update. Send null to use default scraping; omitting the field on update preserves the saved value. List and detail responses include the saved value.

The country applies to subsequent TikTok account discovery and video refreshes for this campaign, including manual refreshes and retries. It does not change campaign timezone or trigger an immediate scrape. If Grade disables agency access, scraping returns to default and the saved country is retained.

{ "tiktokScrapeCountryCode": "VN" }

Creating or updating this field requires campaigns:write and agency access. An unsupported code returns 400 (INVALID_TIKTOK_SCRAPE_COUNTRY); disabled agency access returns 403 (TIKTOK_SCRAPE_LOCATION_DISABLED). Completed campaigns cannot change country (403, CAMPAIGN_COMPLETED).

POST /sdk/v1/campaigns

Create a campaign. Campaigns are created as active (ONGOING).

Body

{
  "campaignName": "Summer campaign",
  "startDate": "2026-06-01",
  "endDate": "2026-08-31",
  "campaignDescription": "Influencer campaign for summer product line",
  "brandId": "brand_...",
  "timeZone": "America/New_York",
  "activate": true
}
campaignName string body required

Campaign name. You can also use campaignTitle as an alias.

startDate string body required

Campaign start date (ISO format).

endDate string body

Campaign end date (ISO format). Omit for open-ended campaigns.

campaignDescription string body

Free-text description.

brandId string body

Associate the campaign with an existing brand.

timeZone string body

Optional IANA timezone name, such as America/New_York or Europe/Paris. Omit it or send null to inherit the agency timezone. Use the timezone catalog to get accepted names and display labels.

activate boolean body default true

Optional. If provided, this must be true. false is not supported in SDK campaign creation.

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "campaignStatus": "ONGOING",
    "tiktokScrapeCountryCode": null,
    "timeZone": "America/New_York",
    "agencyTimeZone": "America/Los_Angeles",
    "effectiveTimeZone": "America/New_York"
  }
}

Common errors

  • 400: missing campaignName or startDate
  • 400: activate is invalid or set to false
  • 400: timeZone is not a valid IANA timezone

GET /sdk/v1/campaigns/:campaignId

Fetch a single campaign with its details and high-level analytics in one response.

Response

{
  "success": true,
  "data": {
    "campaign": {
      "campaignId": "camp_...",
      "campaignName": "Summer campaign",
      "campaignStatus": "ONGOING",
      "tiktokScrapeCountryCode": null,
      "startDate": "2026-06-01T00:00:00.000Z",
      "endDate": "2026-08-31T00:00:00.000Z",
      "campaignDescription": "Influencer campaign for summer product line",
      "timeZone": "America/New_York",
      "agencyTimeZone": "America/Los_Angeles",
      "effectiveTimeZone": "America/New_York"
    },
    "analytics": {
      "totalCreators": 5,
      "totalViews": 25000,
      "totalLikes": 1200,
      "totalComments": 80,
      "totalShares": 45
    }
  },
  "asOfTimestamp": "2026-03-03T12:00:00.000Z"
}

Common errors

  • 404: campaign not found or does not belong to your agency

PATCH /sdk/v1/campaigns/:campaignId

Update a campaign. All fields are optional; only the fields you include are changed.

Body

{
  "campaignName": "Updated campaign name",
  "startDate": "2026-06-15",
  "endDate": "2026-09-30",
  "campaignDescription": "Revised description",
  "brandId": "brand_...",
  "timeZone": "Europe/Paris"
}
timeZone string | null body

IANA timezone name for the campaign. Send null to clear the override and inherit the agency timezone. Use the timezone catalog to get accepted names and display labels.

Set endDate, campaignDescription, brandId, or timeZone to null to clear it. When an effective timezone changes, Grade realigns future calendar pay-cycle dates for campaign creators.

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "updated": true,
    "tiktokScrapeCountryCode": null,
    "timeZone": "Europe/Paris",
    "agencyTimeZone": "America/Los_Angeles",
    "effectiveTimeZone": "Europe/Paris"
  }
}

Common errors

  • 400: no updatable field was provided or timeZone is invalid
  • 404: campaign not found or does not belong to your agency

DELETE /sdk/v1/campaigns/:campaignId

Soft-delete a campaign.

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "deleted": true
  }
}

Common errors

  • 404: campaign not found or does not belong to your agency
  • 409: cannot delete because payouts already exist for this campaign

Campaign creators

Campaign creators are identified by email. You can manage membership explicitly with the endpoints below, but it is optional — calling media or contract upsert endpoints with an email automatically adds the creator to the campaign if they are not already a member.

GET /sdk/v2/campaigns/:campaignId/creators

List creators with the compact response recommended for new integrations.

See List campaign creators (v2) for the complete field list, date-range behavior, pagination, and response examples.

Query parameters

  • search or query (optional; searches creator name/email)
  • includeHidden (optional; true or false)
  • fields (optional; comma-separated response fields)
  • startDate and endDate (optional; YYYY-MM-DD, provided together)
  • page (default 1)
  • limit (default 100, maximum 500)
  • sortBy (optional): creatorName, totalViews, totalLikes, totalComments, totalShares
  • sortOrder (asc or desc)

Response

{
  "success": true,
  "data": [
    {
      "campaignId": "camp_...",
      "creatorEmail": "creator@example.com",
      "creatorProfileId": "cp_...",
      "campaignCreatorRecordId": "ccr_...",
      "pendingValue": 125,
      "currency": "USD",
      "totalViews": 50000
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "total": 1,
    "totalPages": 1
  },
  "dateRange": null,
  "effectiveTimeZone": "America/New_York"
}

GET /sdk/v1/campaigns/:campaignId/creators

Returns the original, larger response for existing v1 clients. Its page limit remains 100, it supports cpmResultValue sorting, and it does not use the v2 field projection.

See List campaign creators (v1 legacy) for its response fields and migration guidance.

POST /sdk/v1/campaigns/:campaignId/creators

Add one or more creators to a campaign by email.

Body

{
  "creatorEmail": "creator@example.com"
}

Bulk add example:

{
  "creatorEmails": [
    "creator1@example.com",
    "creator2@example.com"
  ]
}

Send either creatorEmail or creatorEmails, but not both.

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "creatorEmail": "creator@example.com",
    "creatorProfileId": "cp_...",
    "campaignCreatorRecordId": "ccr_..."
  }
}

If you send creatorEmails, the response is batched:

{
  "success": true,
  "successCount": 2,
  "failureCount": 0,
  "results": [
    {
      "campaignId": "camp_...",
      "creatorEmail": "creator1@example.com",
      "creatorProfileId": "cp_...",
      "campaignCreatorRecordId": "ccr_...",
      "added": true
    }
  ]
}

Common errors

  • 400: missing or invalid creatorEmail
  • 400: invalid creatorEmails payload

Move a creator between campaigns

Use Move a creator between campaigns to transfer an existing membership to another ongoing campaign in your agency. The move preserves the campaign creator record ID, media, contract history, and payouts. It requires the campaigns:write scope.

DELETE /sdk/v1/campaigns/:campaignId/creators

Remove a creator from a campaign.

Query parameters

  • email (required)

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "creatorEmail": "creator@example.com",
    "campaignCreatorRecordId": "ccr_...",
    "removed": true
  }
}

Common errors

  • 400: missing email
  • 404: creator not found in this campaign
  • 409: cannot remove creator because payments exist

Complete or reopen a campaign

POST /sdk/v1/campaigns/:campaignId/complete and POST /sdk/v1/campaigns/:campaignId/reopen accept {} and require campaigns:write. They use the same lifecycle validation as the platform. Completed campaigns are read-only until reopened; reopening preserves existing media and payment history and may fail when the campaign is not eligible to resume.

Enable or disable score calculation

PATCH /sdk/v1/campaigns/:campaignId/scoring requires campaigns:write and a boolean body, such as { "enabled": false }. Use true to re-enable. See creator scoring and payment adjustments for per-creator controls.

Describe your program.

Grade turns it into a program it can track and pay.