Campaigns

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",
      "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.

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
}

string

required

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

string

required

Campaign start date (ISO format).

string

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

string

Free-text description.

string

Associate the campaign with an existing brand.

string

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.

boolean

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",
    "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",
      "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"
}

asOfTimestamp indicates when media tracking metrics were last refreshed. It may be null if no media has been tracked yet.

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"
}

string | null

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,
    "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": "[email protected]",
      "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": "[email protected]"
}

Bulk add example:

{
  "creatorEmails": [
    "[email protected]",
    "[email protected]"
  ]
}

Send either creatorEmail or creatorEmails, but not both.

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "creatorEmail": "[email protected]",
    "creatorProfileId": "cp_...",
    "campaignCreatorRecordId": "ccr_..."
  }
}

If you send creatorEmails, the response is batched:

{
  "success": true,
  "successCount": 2,
  "failureCount": 0,
  "results": [
    {
      "campaignId": "camp_...",
      "creatorEmail": "[email protected]",
      "creatorProfileId": "cp_...",
      "campaignCreatorRecordId": "ccr_...",
      "added": true
    }
  ]
}

Common errors

400: missing or invalid creatorEmail
400: invalid creatorEmails payload

The former bulk contract upsert is deprecated. Add creators first, then read and write each creator’s unified contract through the campaignCreatorRecordId contract-history endpoints. Contract writes require a complete contract and basedOnVersionId.

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

Remove a creator from a campaign.

Query parameters

email (required)

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "creatorEmail": "[email protected]",
    "campaignCreatorRecordId": "ccr_...",
    "removed": true
  }
}

Common errors

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

SDK v1

Campaign management

GET /sdk/v1/campaigns

Query parameters

Response

POST /sdk/v1/campaigns

Body

Response

Common errors

GET /sdk/v1/campaigns/:campaignId

Response

Common errors

PATCH /sdk/v1/campaigns/:campaignId

Body

Response

Common errors

DELETE /sdk/v1/campaigns/:campaignId

Response

Common errors

Campaign creators

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

Query parameters

Response

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

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

Body

Response

Common errors

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

Query parameters

Response

Common errors

​GET /sdk/v1/campaigns

​Query parameters

​Response

​POST /sdk/v1/campaigns

​Body

​Response

​Common errors

​GET /sdk/v1/campaigns/:campaignId

​Response

​Common errors

​PATCH /sdk/v1/campaigns/:campaignId

​Body

​Response

​Common errors

​DELETE /sdk/v1/campaigns/:campaignId

​Response

​Common errors

​Campaign creators

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

​Query parameters

​Response

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

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

​Body

​Response

​Common errors

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

​Query parameters

​Response

​Common errors

GET /sdk/v1/campaigns

Query parameters

Response

POST /sdk/v1/campaigns

Body

Response

Common errors

GET /sdk/v1/campaigns/:campaignId

Response

Common errors

PATCH /sdk/v1/campaigns/:campaignId

Body

Response

Common errors

DELETE /sdk/v1/campaigns/:campaignId

Response

Common errors

Campaign creators

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

Query parameters

Response

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

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

Body

Response

Common errors

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

Query parameters

Response

Common errors