---
title: "[beta] Creates a campaign."
method: POST
path: "/maintenance/campaigns"
tags: ["Beta APIs"]
---

# \[beta\] Creates a campaign.

`POST /maintenance/campaigns`

## Request

- Base URL: `https://api.samsara.com`
- URL: `https://api.samsara.com/maintenance/campaigns`
- Auth: HTTP bearer

Creates a campaign. The campaign is created in your organization's Draft status with `createdSource` set to `api`. Creating a campaign never creates work orders or places items on hold.

 <b>Rate limit:</b> 100 requests/min (learn more about rate limits <a href="https://developers.samsara.com/docs/rate-limits" target="_blank">here</a>).

To use this endpoint, select **Write Campaigns** under the Work Orders category when creating or editing an API token. <a href="https://developers.samsara.com/docs/authentication#scopes-for-api-tokens" target="_blank">Learn More.</a>
 

 **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our <a href="https://forms.gle/zkD4NCH7HjKb7mm69" target="_blank">API feedback form</a>. If you encountered an issue or noticed inaccuracies in the API documentation, please <a href="https://www.samsara.com/help" target="_blank">submit a case</a> to our support team.

## Request body

- CampaignsPostCampaignsRequestBody: Campaign to create.
  - `campaignNumber` string: Customer or OEM-aligned campaign number.
  - `campaignType` 'safetyRecall' | 'mandatoryCampaign' | 'voluntary' | 'internal', required: Type of the campaign. Valid values: `safetyRecall`, `mandatoryCampaign`, `voluntary`, `internal`
  - `description` string: Free-form description of the campaign.
  - `endTime` string, date-time: End of the campaign in RFC 3339 format. Must not be before `startTime`.
  - `isWarranty` boolean: Whether campaign work is expected to be claimable as warranty or recall work. Defaults to false.
  - `name` string, required: Display name of the campaign.
  - `recallMetadata` CampaignRecallMetadataRequestObjectRequestBody: Recall provenance for a recall-sourced campaign.
    - `nhtsaRecallNumber` string: NHTSA recall number.
    - `oemNotificationTime` string, date-time: Time the OEM issued the notification, in RFC 3339 format. Only the date component is meaningful; the time component is stored as provided.
    - `oemRecallNumber` string: OEM recall number.
    - `ownerNotificationTime` string, date-time: Time owners were notified, in RFC 3339 format. Only the date component is meaningful; the time component is stored as provided.
    - `partsAvailableTime` string, date-time: Time parts became available, in RFC 3339 format. Only the date component is meaningful; the time component is stored as provided.
    - `recallSource` 'recallMasters' | 'nhtsa' | 'oem' | 'manual' | 'api', required: Where the recall notice came from. Valid values: `recallMasters`, `nhtsa`, `oem`, `manual`, `api`
    - `remedyAvailableTime` string, date-time: Time a remedy became available, in RFC 3339 format. Only the date component is meaningful; the time component is stored as provided.
    - `supersededByRecallNumber` string: Recall number that supersedes this recall.
  - `startTime` string, date-time: Start of the campaign in RFC 3339 format.
  - `workOrderPriority` 'High' | 'Low' | 'Medium' | 'Urgent': Priority applied to work orders generated from the campaign. Uses the same values as the `priority` field of the Work Orders API. Defaults to no priority. Valid values: `High`, `Low`, `Medium`, `Urgent`
  - `workOrderTemplateId` string: ID of a work order template, as returned by GET /maintenance/work-order-templates, that pre-populates work orders generated from the campaign.

## Response `200`

OK response.

- CampaignsPostCampaignsResponseBody
  - `data` CampaignResponseObjectResponseBody, required: A recall or campaign: a one-time batch of work applied across a targeted group of assets.
    - `campaignNumber` string: Customer or OEM-aligned campaign number.
    - `campaignType` 'safetyRecall' | 'mandatoryCampaign' | 'voluntary' | 'internal' | 'unknown', required: Type of the campaign. Defaults to `unknown` when the type is not recognized. Valid values: `safetyRecall`, `mandatoryCampaign`, `voluntary`, `internal`, `unknown`
    - `createdAtTime` string, date-time, required: Time the campaign was created, in RFC 3339 format.
    - `createdSource` 'dashboard' | 'api' | 'assistant' | 'unknown', required: Where the campaign was created from. Campaigns created through this API are `api`. Defaults to `unknown` when the source is not recorded. Valid values: `dashboard`, `api`, `assistant`, `unknown`
    - `description` string: Free-form description of the campaign.
    - `endTime` string, date-time: End of the campaign in RFC 3339 format.
    - `id` string, required: Unique ID of the campaign.
    - `isWarranty` boolean, required: Whether campaign work is expected to be claimable as warranty or recall work. Defaults to false.
    - `name` string, required: Display name of the campaign.
    - `recallMetadata` CampaignRecallMetadataResponseObjectResponseBody: Recall provenance carried on a recall-sourced campaign.
      - `nhtsaRecallNumber` string: NHTSA recall number.
      - `oemNotificationTime` string, date-time: Time the OEM issued the notification, in RFC 3339 format.
      - `oemRecallNumber` string: OEM recall number.
      - `ownerNotificationTime` string, date-time: Time owners were notified, in RFC 3339 format.
      - `partsAvailableTime` string, date-time: Time parts became available, in RFC 3339 format.
      - `recallSource` 'recallMasters' | 'nhtsa' | 'oem' | 'manual' | 'api' | 'unknown', required: Where the recall notice came from. Valid values: `recallMasters`, `nhtsa`, `oem`, `manual`, `api`, `unknown`
      - `remedyAvailableTime` string, date-time: Time a remedy became available, in RFC 3339 format.
      - `supersededByRecallNumber` string: Recall number that supersedes this recall.
    - `startTime` string, date-time: Start of the campaign in RFC 3339 format.
    - `status` CampaignStatusResponseObjectResponseBody, required: The customer-defined status of a campaign and the fixed state behind it.
      - `id` string, required: ID of the status definition.
      - `name` string, required: Customer-facing name of the status.
      - `state` 'draft' | 'active' | 'onHold' | 'complete' | 'cancelled' | 'unknown', required: Fixed system state behind the status. Campaigns created through the API start in `draft`. Defaults to `unknown` when the status definition no longer exists. Valid values: `draft`, `active`, `onHold`, `complete`, `cancelled`, `unknown`
    - `updatedAtTime` string, date-time, required: Time the campaign was last updated, in RFC 3339 format.
    - `workOrderPriority` 'High' | 'Low' | 'Medium' | 'Urgent': Priority applied to work orders generated from the campaign. Uses the same values as the `priority` field of the Work Orders API. Valid values: `High`, `Low`, `Medium`, `Urgent`
    - `workOrderTemplateId` string: ID of the work order template that pre-populates work orders generated from the campaign.

## Other responses

- `401`: Unauthorized response.
- `404`: Not Found response.
- `405`: Method Not Allowed response.
- `413`: Content Too Large response.
- `429`: Too Many Requests response.
- `500`: Internal Server Error response.
- `501`: Not Implemented response.
- `502`: Bad Gateway response.
- `503`: Service Unavailable response.
- `504`: Gateway Timeout response.
- `default`: Bad Request response.

---

[API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)