All documentation
Documentation
All endpoints below require:
X-Application-IdX-Api-Key
GET /sdk/v1/campaigns
List campaigns for your agency with optional filtering, sorting, and pagination.
Query parameters
page(default1)limit(default50)searchorquery(optional; searches campaign name)sortBy(optional)sortOrder(ascordesc)status(optional)campaignStatuses(optional; comma-separated)paymentStatuses(optional; comma-separated)timeStartandtimeEnd(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 requiredCampaign name. You can also use campaignTitle as an alias.
startDate string body requiredCampaign start date (ISO format).
endDate string bodyCampaign end date (ISO format). Omit for open-ended campaigns.
campaignDescription string bodyFree-text description.
brandId string bodyAssociate the campaign with an existing brand.
timeZone string bodyOptional 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 trueOptional. 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: missingcampaignNameorstartDate400:activateis invalid or set tofalse400:timeZoneis 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 bodyIANA 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 ortimeZoneis invalid404: 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 agency409: 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
searchorquery(optional; searches creator name/email)includeHidden(optional;trueorfalse)fields(optional; comma-separated response fields)startDateandendDate(optional;YYYY-MM-DD, provided together)page(default1)limit(default100, maximum500)sortBy(optional):creatorName,totalViews,totalLikes,totalComments,totalSharessortOrder(ascordesc)
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 invalidcreatorEmail400: invalidcreatorEmailspayload
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: missingemail404: creator not found in this campaign409: 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.
