Documentation / Campaign management / Campaign creators

Read campaign creator contract history

Read a campaign creator's contract timeline and identify the current contract.

read campaign creator contract history · bash
curl -sS "$BASE_URL/sdk/v1/campaign-creators/CCR_123/contract-history" \
  -H "X-Application-Id: $APP_ID" \
  -H "X-Api-Key: $API_KEY"
All 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 on businessDate
  • SCHEDULED: begins on a future effective date
  • HISTORIC: ended before businessDate

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 credentials
  • 404: campaign creator record not found

Use Create a contract version to add a new effective date to this timeline.

Describe your program.

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