All documentation
Documentation
GET /sdk/v1/campaign-creators/:campaignCreatorRecordId/contract-history
Returns the creator's contract timeline in a UI-ready format. The response identifies the current contract, the next scheduled contract, and every historic or scheduled version.
All requests require X-Application-Id and X-Api-Key.
Path parameter
campaignCreatorRecordId(required): the campaign creator whose contracts you want to read.
Example request
curl -sS "$BASE_URL/sdk/v1/campaign-creators/CCR_123/contract-history" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY"
Response
{
"success": true,
"data": {
"campaignCreatorRecordId": "CCR_123",
"campaignId": "camp_123",
"campaignName": "Summer launch",
"creatorProfileId": "CP_123",
"creatorEmail": "jordan@example.com",
"businessDate": "2026-08-01",
"timeZone": "America/Los_Angeles",
"current": {
"versionId": "CCCH_CURRENT",
"effectiveDate": "2026-07-01",
"effectiveThroughDate": "2026-07-31",
"status": "CURRENT",
"isCurrent": true,
"contract": {
"type": "FIXED",
"currency": "USD",
"fixedPayment": {
"currency": "USD",
"conversionPolicy": null,
"amount": 500,
"per": "CREATOR",
"calculation": "STANDARD",
"upfrontPercentage": null,
"expectedPosts": null,
"minimumPosts": null,
"prorateByTime": false,
"platforms": [],
"crossposts": null
},
"cpmPayment": null,
"bonusPayment": null,
"crosspostRequirements": null,
"recurringPayment": null,
"postsUploadedOnOrAfter": null
}
},
"nextScheduled": {
"versionId": "CCCH_SCHEDULED",
"effectiveDate": "2026-08-15",
"status": "SCHEDULED",
"isNextScheduled": true,
"contract": {
"type": "FIXED",
"currency": "USD",
"fixedPayment": {
"currency": "USD",
"conversionPolicy": null,
"amount": 600,
"per": "CREATOR",
"calculation": "STANDARD",
"upfrontPercentage": null,
"expectedPosts": null,
"minimumPosts": null,
"prorateByTime": false,
"platforms": [],
"crossposts": null
},
"cpmPayment": null,
"bonusPayment": null,
"crosspostRequirements": null,
"recurringPayment": null,
"postsUploadedOnOrAfter": null
}
},
"history": [
{
"versionId": "CCCH_HISTORIC",
"effectiveDate": "2026-06-01",
"effectiveThroughDate": "2026-06-30",
"status": "HISTORIC",
"contract": {
"type": "FIXED",
"currency": "USD",
"fixedPayment": {
"currency": "USD",
"conversionPolicy": null,
"amount": 400,
"per": "CREATOR",
"calculation": "STANDARD",
"upfrontPercentage": null,
"expectedPosts": null,
"minimumPosts": null,
"prorateByTime": false,
"platforms": [],
"crossposts": null
},
"cpmPayment": null,
"bonusPayment": null,
"crosspostRequirements": null,
"recurringPayment": null,
"postsUploadedOnOrAfter": null
}
},
{
"versionId": "CCCH_CURRENT",
"effectiveDate": "2026-07-01",
"effectiveThroughDate": "2026-07-31",
"status": "CURRENT",
"isCurrent": true,
"contract": {
"type": "FIXED",
"currency": "USD",
"fixedPayment": {
"currency": "USD",
"conversionPolicy": null,
"amount": 500,
"per": "CREATOR",
"calculation": "STANDARD",
"upfrontPercentage": null,
"expectedPosts": null,
"minimumPosts": null,
"prorateByTime": false,
"platforms": [],
"crossposts": null
},
"cpmPayment": null,
"bonusPayment": null,
"crosspostRequirements": null,
"recurringPayment": null,
"postsUploadedOnOrAfter": null
}
}
]
}
}
timeZone is the campaign's effective IANA timezone, after applying the
campaign override, agency fallback, and final UTC fallback. businessDate
and contract effective dates are evaluated in this timezone.
status is one of:
CURRENT: active onbusinessDateSCHEDULED: begins on a future effective dateHISTORIC: ended beforebusinessDate
When a contract enables bonuses, bonusPayment.pays is
CAMPAIGN_COMPLETION, NOW, or NOW_AND_STOP. These same values are accepted
when creating a contract version. See
bonus payout timing
for the stop policy and its payout scopes.
A version saved as Simplified payment terms has type: "RULES", null
payment sections, and one more field, paymentRules: the payment agreement
as Grade stored it. You can send that contract back to the create endpoint.
See Simplified payment terms.
An empty timeline returns current: null, nextScheduled: null, and
history: []. To create its first contract, send basedOnVersionId: null to
the create endpoint. null is an explicit empty-timeline concurrency
assertion, not a default: the write fails if another contract appears first.
Keep the versionId for the version governing the date you intend to edit.
Pass it as basedOnVersionId when creating a version. If another writer
changes that part of the timeline first, the write is rejected instead of
silently overwriting newer contract terms.
Common errors
401: missing or invalid SDK credentials404: campaign creator record not found
Use Create a contract version to add a new effective date to this timeline.
