API Docs

Campaigns API

Campaigns define cadence, nudge schedule, and formatting defaults for case-study collection.

Endpoints

  • GET /api/v1/campaigns
  • POST /api/v1/campaigns
  • GET /api/v1/campaigns/:id
  • PATCH /api/v1/campaigns/:id
  • DELETE /api/v1/campaigns/:id
  • GET /api/v1/campaigns/:campaign_id/campaign_periods
  • POST /api/v1/campaigns/:campaign_id/campaign_periods
  • GET /api/v1/campaigns/:campaign_id/content_versions
  • POST /api/v1/campaigns/:campaign_id/content_versions

Filtering, Sorting, Include

  • Filters: name, cadence, deadline_day, format_template, active
  • Sort fields: id, name, cadence, deadline_day, active, created_at, updated_at
  • Include: campaign_periods, content_versions, employees

GET /api/v1/campaigns

curl -X GET "https://cases.shipmentbot.com/api/v1/campaigns?filter[active]=true&sort=-name&include=campaign_periods,content_versions&page[number]=1&page[size]=1" \
  -H "Accept: application/json" \
  -H "X-API-Key: csb_live_your_token_here"
{
  "data": [
    {
      "id": "2",
      "type": "campaigns",
      "attributes": {
        "name": "Weekly Product Stories",
        "cadence": "weekly",
        "deadline_day": "friday",
        "nudge_days": ["monday", "wednesday", "friday"],
        "format_template": "spin",
        "active": true,
        "created_at": "2026-03-02T09:10:00.000Z",
        "updated_at": "2026-03-02T09:10:00.000Z"
      },
      "relationships": {
        "campaign_periods": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/relationships/campaign_periods",
            "related": "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods"
          },
          "data": [{ "id": "11", "type": "campaign_periods" }]
        },
        "content_versions": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/relationships/content_versions",
            "related": "https://cases.shipmentbot.com/api/v1/campaigns/2/content_versions"
          },
          "data": [{ "id": "7", "type": "content_versions" }]
        },
        "employees": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/relationships/employees",
            "related": "https://cases.shipmentbot.com/api/v1/employees"
          },
          "data": [
            { "id": "4", "type": "employees" },
            { "id": "5", "type": "employees" }
          ]
        }
      },
      "links": {
        "self": "https://cases.shipmentbot.com/api/v1/campaigns/2"
      }
    }
  ],
  "included": [
    {
      "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": []
        },
        "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": []
        }
      },
      "links": {
        "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/11"
      }
    }
  ],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns?filter%5Bactive%5D=true&sort=-name&include=campaign_periods%2Ccontent_versions&page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "first": "https://cases.shipmentbot.com/api/v1/campaigns?filter%5Bactive%5D=true&sort=-name&include=campaign_periods%2Ccontent_versions&page%5Bnumber%5D=1&page%5Bsize%5D=1",
    "last": "https://cases.shipmentbot.com/api/v1/campaigns?filter%5Bactive%5D=true&sort=-name&include=campaign_periods%2Ccontent_versions&page%5Bnumber%5D=3&page%5Bsize%5D=1",
    "next": "https://cases.shipmentbot.com/api/v1/campaigns?filter%5Bactive%5D=true&sort=-name&include=campaign_periods%2Ccontent_versions&page%5Bnumber%5D=2&page%5Bsize%5D=1",
    "prev": null
  },
  "meta": {
    "page": {
      "number": 1,
      "size": 1,
      "total_records": 3,
      "total_pages": 3
    }
  }
}

GET /api/v1/campaigns/:id

curl -X GET "https://cases.shipmentbot.com/api/v1/campaigns/2?include=campaign_periods" \
  -H "Accept: application/json" \
  -H "X-API-Key: csb_live_your_token_here"
{
  "data": {
    "id": "2",
    "type": "campaigns",
    "attributes": {
      "name": "Weekly Product Stories",
      "cadence": "weekly",
      "deadline_day": "friday",
      "nudge_days": ["monday", "wednesday", "friday"],
      "format_template": "spin",
      "active": true,
      "created_at": "2026-03-02T09:10:00.000Z",
      "updated_at": "2026-03-02T09:10:00.000Z"
    },
    "relationships": {
      "campaign_periods": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/relationships/campaign_periods",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods"
        },
        "data": [{ "id": "11", "type": "campaign_periods" }]
      },
      "content_versions": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/relationships/content_versions",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/2/content_versions"
        },
        "data": [{ "id": "7", "type": "content_versions" }]
      },
      "employees": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/relationships/employees",
          "related": "https://cases.shipmentbot.com/api/v1/employees"
        },
        "data": [{ "id": "4", "type": "employees" }]
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/campaigns/2"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns/2?include=campaign_periods"
  },
  "meta": {}
}

POST /api/v1/campaigns

curl -X POST "https://cases.shipmentbot.com/api/v1/campaigns" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: csb_live_your_token_here" \
  -d '{
    "data": {
      "type": "campaigns",
      "attributes": {
        "name": "Monthly Executive Stories",
        "cadence": "monthly",
        "deadline_day": "thursday",
        "nudge_days": ["monday", "wednesday"],
        "format_template": "spin",
        "active": true
      }
    }
  }'
{
  "data": {
    "id": "12",
    "type": "campaigns",
    "attributes": {
      "name": "Monthly Executive Stories",
      "cadence": "monthly",
      "deadline_day": "thursday",
      "nudge_days": ["monday", "wednesday"],
      "format_template": "spin",
      "active": true,
      "created_at": "2026-03-05T18:20:00.000Z",
      "updated_at": "2026-03-05T18:20:00.000Z"
    },
    "relationships": {
      "campaign_periods": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/12/relationships/campaign_periods",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/12/campaign_periods"
        },
        "data": []
      },
      "content_versions": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/12/relationships/content_versions",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/12/content_versions"
        },
        "data": []
      },
      "employees": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/12/relationships/employees",
          "related": "https://cases.shipmentbot.com/api/v1/employees"
        },
        "data": [{ "id": "4", "type": "employees" }]
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/campaigns/12"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns/12"
  },
  "meta": {}
}

Create Validation Error (422)

{
  "data": null,
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns"
  },
  "meta": {},
  "errors": [
    {
      "status": "422",
      "title": "Validation Error",
      "detail": "Cadence is not included in the list",
      "source": {
        "pointer": "/data/attributes/cadence"
      }
    }
  ]
}

PATCH /api/v1/campaigns/:id

curl -X PATCH "https://cases.shipmentbot.com/api/v1/campaigns/12" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: csb_live_your_token_here" \
  -d '{
    "data": {
      "type": "campaigns",
      "id": "12",
      "attributes": {
        "name": "Monthly Executive Stories (Paused)",
        "active": false,
        "nudge_days": ["wednesday"]
      }
    }
  }'
{
  "data": {
    "id": "12",
    "type": "campaigns",
    "attributes": {
      "name": "Monthly Executive Stories (Paused)",
      "cadence": "monthly",
      "deadline_day": "thursday",
      "nudge_days": ["wednesday"],
      "format_template": "spin",
      "active": false,
      "created_at": "2026-03-05T18:20:00.000Z",
      "updated_at": "2026-03-05T18:24:10.000Z"
    },
    "relationships": {
      "campaign_periods": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/12/relationships/campaign_periods",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/12/campaign_periods"
        },
        "data": []
      },
      "content_versions": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/12/relationships/content_versions",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/12/content_versions"
        },
        "data": []
      },
      "employees": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaigns/12/relationships/employees",
          "related": "https://cases.shipmentbot.com/api/v1/employees"
        },
        "data": [{ "id": "4", "type": "employees" }]
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/campaigns/12"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns/12"
  },
  "meta": {}
}

DELETE /api/v1/campaigns/:id

curl -X DELETE "https://cases.shipmentbot.com/api/v1/campaigns/12" \
  -H "X-API-Key: csb_live_your_token_here"

Successful response: 204 No Content.

Show/Update/Delete Not Found (404)

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

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

Full field list is documented on Campaign Periods API.

curl -X GET "https://cases.shipmentbot.com/api/v1/campaigns/2/campaign_periods?sort=-starts_on" \
  -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": []
        },
        "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": []
        }
      },
      "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
    }
  }
}

Nested: 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 11",
        "starts_on": "2026-03-09",
        "ends_on": "2026-03-15",
        "status": "open"
      }
    }
  }'
{
  "data": {
    "id": "12",
    "type": "campaign_periods",
    "attributes": {
      "label": "Week 11",
      "starts_on": "2026-03-09",
      "ends_on": "2026-03-15",
      "status": "open",
      "created_at": "2026-03-05T18:27:09.000Z",
      "updated_at": "2026-03-05T18:27:09.000Z"
    },
    "relationships": {
      "campaign": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/12/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/12/relationships/submissions",
          "related": "https://cases.shipmentbot.com/api/v1/campaign_periods/12/submissions"
        },
        "data": []
      },
      "nudges": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/12/relationships/nudges",
          "related": "https://cases.shipmentbot.com/api/v1/nudges?filter%5Bcampaign_period_id%5D=12"
        },
        "data": []
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/12"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaign_periods/12"
  },
  "meta": {}
}

Nested: GET /api/v1/campaigns/:campaign_id/content_versions

Full field list is documented on Content Versions API.

curl -X GET "https://cases.shipmentbot.com/api/v1/campaigns/2/content_versions?sort=position" \
  -H "X-API-Key: csb_live_your_token_here"
{
  "data": [
    {
      "id": "7",
      "type": "content_versions",
      "attributes": {
        "name": "LinkedIn Single",
        "prompt_template": "Write a concise SPIN-style LinkedIn post from submission data.",
        "output_type": "single",
        "position": 0,
        "active": true,
        "created_at": "2026-03-02T09:17:00.000Z",
        "updated_at": "2026-03-02T09:17:00.000Z"
      },
      "relationships": {
        "campaign": {
          "links": {
            "self": "https://cases.shipmentbot.com/api/v1/content_versions/7/relationships/campaign",
            "related": "https://cases.shipmentbot.com/api/v1/campaigns/2"
          },
          "data": { "id": "2", "type": "campaigns" }
        }
      },
      "links": {
        "self": "https://cases.shipmentbot.com/api/v1/content_versions/7"
      }
    }
  ],
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns/2/content_versions?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://cases.shipmentbot.com/api/v1/campaigns/2/content_versions?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "last": "https://cases.shipmentbot.com/api/v1/campaigns/2/content_versions?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "next": null,
    "prev": null
  },
  "meta": {
    "page": {
      "number": 1,
      "size": 25,
      "total_records": 1,
      "total_pages": 1
    }
  }
}

Nested: POST /api/v1/campaigns/:campaign_id/content_versions

curl -X POST "https://cases.shipmentbot.com/api/v1/campaigns/2/content_versions" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: csb_live_your_token_here" \
  -d '{
    "data": {
      "type": "content_versions",
      "attributes": {
        "name": "Carousel Draft",
        "prompt_template": "Generate a five-card carousel.",
        "output_type": "multi",
        "position": 1,
        "active": true
      }
    }
  }'
{
  "data": {
    "id": "8",
    "type": "content_versions",
    "attributes": {
      "name": "Carousel Draft",
      "prompt_template": "Generate a five-card carousel.",
      "output_type": "multi",
      "position": 1,
      "active": true,
      "created_at": "2026-03-05T18:29:44.000Z",
      "updated_at": "2026-03-05T18:29:44.000Z"
    },
    "relationships": {
      "campaign": {
        "links": {
          "self": "https://cases.shipmentbot.com/api/v1/content_versions/8/relationships/campaign",
          "related": "https://cases.shipmentbot.com/api/v1/campaigns/2"
        },
        "data": { "id": "2", "type": "campaigns" }
      }
    },
    "links": {
      "self": "https://cases.shipmentbot.com/api/v1/content_versions/8"
    }
  },
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/content_versions/8"
  },
  "meta": {}
}

403 Current Account Required

If the authenticated user has no current_account, account-scoped endpoints return:

{
  "data": null,
  "included": [],
  "links": {
    "self": "https://cases.shipmentbot.com/api/v1/campaigns"
  },
  "meta": {},
  "errors": [
    {
      "status": "403",
      "title": "Forbidden",
      "detail": "A current account is required for this endpoint."
    }
  ]
}