API Docs

Campaign Periods API

Campaign periods represent a date-bounded collection window within a campaign.

Endpoints

  • GET /api/v1/campaigns/:campaign_id/campaign_periods
  • POST /api/v1/campaigns/:campaign_id/campaign_periods
  • GET /api/v1/campaign_periods/:id
  • PATCH /api/v1/campaign_periods/:id
  • GET /api/v1/campaign_periods/:campaign_period_id/submissions
  • POST /api/v1/campaign_periods/:campaign_period_id/submissions

Delete: there is currently no DELETE /api/v1/campaign_periods/:id endpoint.

Filtering, Sorting, Include

  • Filters: label, status, starts_on, ends_on, campaign_id
  • Sort fields: id, label, status, starts_on, ends_on, created_at, updated_at
  • Include: campaign, submissions, nudges
  • Valid status values: open, closed

GET /api/v1/campaigns/:campaign_id/campaign_periods

curl -X GET "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods?filter[status]=open&sort=-starts_on&include=submissions" \
  -H "Accept: application/json" \
  -H "X-API-Key: csb_live_your_token_here"
{
  "data": [
    {
      "id": "11",
      "type": "campaign_periods",
      "attributes": {
        "label": "Week 10",
        "starts_on": "2026-03-02",
        "ends_on": "2026-03-08",
        "status": "open",
        "created_at": "2026-03-02T09:15:00.000Z",
        "updated_at": "2026-03-02T09:15:00.000Z"
      },
      "relationships": {
        "campaign": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/11/relationships/campaign",
            "related": "https://cases.shipmentbot.com/api/v1/campaigns/2"
          },
          "data": { "id": "2", "type": "campaigns" }
        },
        "submissions": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/11/relationships/submissions",
            "related": "https://cases.shipmentbot.com/api/v1/campaign_periods/11/submissions"
          },
          "data": [{ "id": "15", "type": "submissions" }]
        },
        "nudges": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/11/relationships/nudges",
            "related": "https://cases.shipmentbot.com/api/v1/nudges?filter%5Bcampaign_period_id%5D=11"
          },
          "data": [{ "id": "21", "type": "nudges" }]
        }
      },
      "links": {
        "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/11"
      }
    }
  ],
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "last": "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "next": null,
    "prev": null
  },
  "meta": {
    "page": {
      "number": 1,
      "size": 25,
      "total_records": 1,
      "total_pages": 1
    }
  }
}

POST /api/v1/campaigns/:campaign_id/campaign_periods

curl -X POST "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: csb_live_your_token_here" \
  -d '{
    "data": {
      "type": "campaign_periods",
      "attributes": {
        "label": "Week 12",
        "starts_on": "2026-03-16",
        "ends_on": "2026-03-22",
        "status": "open"
      }
    }
  }'
{
  "data": {
    "id": "13",
    "type": "campaign_periods",
    "attributes": {
      "label": "Week 12",
      "starts_on": "2026-03-16",
      "ends_on": "2026-03-22",
      "status": "open",
      "created_at": "2026-03-05T18:47:00.000Z",
      "updated_at": "2026-03-05T18:47:00.000Z"
    },
    "relationships": {
      "campaign": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/campaign",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/2"
        },
        "data": { "id": "2", "type": "campaigns" }
      },
      "submissions": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/submissions",
          "related": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/submissions"
        },
        "data": []
      },
      "nudges": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/nudges",
          "related": "https://cases.shipmentbot.com/api/v1/nudges?filter%5Bcampaign_period_id%5D=13"
        },
        "data": []
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13"
  },
  "meta": {}
}

GET /api/v1/campaign_periods/:id

curl -X GET "https://cases.shipmentbot.com/api/v1/campaign_periods/13?include=campaign,submissions,nudges" \
  -H "Accept: application/json" \
  -H "X-API-Key: csb_live_your_token_here"
{
  "data": {
    "id": "13",
    "type": "campaign_periods",
    "attributes": {
      "label": "Week 12",
      "starts_on": "2026-03-16",
      "ends_on": "2026-03-22",
      "status": "open",
      "created_at": "2026-03-05T18:47:00.000Z",
      "updated_at": "2026-03-05T18:47:00.000Z"
    },
    "relationships": {
      "campaign": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/campaign",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/2"
        },
        "data": { "id": "2", "type": "campaigns" }
      },
      "submissions": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/submissions",
          "related": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/submissions"
        },
        "data": []
      },
      "nudges": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/nudges",
          "related": "https://cases.shipmentbot.com/api/v1/nudges?filter%5Bcampaign_period_id%5D=13"
        },
        "data": []
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13?include=campaign,submissions,nudges"
  },
  "meta": {}
}

PATCH /api/v1/campaign_periods/:id

curl -X PATCH "https://cases.shipmentbot.com/api/v1/campaign_periods/13" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: csb_live_your_token_here" \
  -d '{
    "data": {
      "type": "campaign_periods",
      "id": "13",
      "attributes": {
        "status": "closed",
        "label": "Week 12 (Closed)"
      }
    }
  }'
{
  "data": {
    "id": "13",
    "type": "campaign_periods",
    "attributes": {
      "label": "Week 12 (Closed)",
      "starts_on": "2026-03-16",
      "ends_on": "2026-03-22",
      "status": "closed",
      "created_at": "2026-03-05T18:47:00.000Z",
      "updated_at": "2026-03-05T18:48:22.000Z"
    },
    "relationships": {
      "campaign": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/campaign",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/2"
        },
        "data": { "id": "2", "type": "campaigns" }
      },
      "submissions": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/submissions",
          "related": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/submissions"
        },
        "data": []
      },
      "nudges": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13/relationships/nudges",
          "related": "https://cases.shipmentbot.com/api/v1/nudges?filter%5Bcampaign_period_id%5D=13"
        },
        "data": []
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/13"
  },
  "meta": {}
}

Nested Submissions Routes

Campaign period submissions are fully documented on Submissions API. 

curl -X GET "https://cases.shipmentbot.com/api/v1/campaign_periods/13/submissions" \
  -H "X-API-Key: csb_live_your_token_here"
curl -X POST "https://cases.shipmentbot.com/api/v1/campaign_periods/13/submissions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: csb_live_your_token_here" \
  -d '{
    "data": {
      "type": "submissions",
      "attributes": {
        "status": "draft",
        "situation": "Example situation",
        "problem": "Example problem",
        "implication": "Example implication",
        "solution": "Example solution"
      },
      "relationships": {
        "employee": {
          "data": { "type": "employees", "id": "4" }
        }
      }
    }
  }'

Error Examples

404 Campaign Period Not Found

{
  "data": null,
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/999999"
  },
  "meta": {},
  "errors": [
    {
      "status": "404",
      "title": "Not Found",
      "detail": "Campaign period not found"
    }
  ]
}

422 Validation Error (date range)

{
  "data": null,
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods"
  },
  "meta": {},
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "Ends on must be on or after starts_on",
      "source": {
        "pointer": "/data/attributes/ends_on"
      }
    }
  ]
}