# Update campaign
It allows to update some parameters of a campaign.
### API Description
## Update
> Update an existing campaign
```json
{"openapi":"3.1.0","info":{"title":"Batch - REST API","version":"2.9"},"tags":[{"name":"Campaigns"}],"servers":[{"url":"https://api.batch.com/{version}","description":"production","variables":{"version":{"default":"2.10","description":"Version of the API"}}}],"security":[{"rest_key":[]}],"components":{"securitySchemes":{"rest_key":{"type":"http","scheme":"bearer","description":"## API Key Authentication\n\nAuthentication is required in order to interact with Batch's APIs.\n\nBatch implements authentication using API Keys, that we call the \"REST API Key\".\nYou can find it on your dashboard.\n\nPlease make sure that you keep this key secret. You should never use it in client apps to call APIs from there as it would\neasily be extractable.\n\n### How to authenticate\n\nIn order to authenticate your requests, add your REST API Key in the `Authorization` header and prefix it by `Bearer`. Example: `Authorization: Bearer bcd38d9rfb38ra28`.\n"}},"parameters":{"HeaderProjectKey":{"in":"header","name":"X-Batch-Project","description":"The unique project key, identifying a project on the Batch platform","schema":{"type":"string"},"required":true}},"schemas":{"campaign_update":{"type":"object","required":["id","campaign"],"properties":{"id":{"type":"string","description":"Campaign id received from the create API"},"campaign":{"type":"object","$ref":"#/components/schemas/campaign","description":"Campaign object as describe in the create query. An update on a campaign will overwrite its contents. It is not possible to update a completed or running campaign if not recurrent"}}},"campaign":{"type":"object","required":["name","state","messages","when"],"properties":{"name":{"type":"string","description":"Display name of the campaign on the dashboard"},"state":{"type":"string","enum":["DRAFT","RUNNING","STOPPED"],"description":"State of the campaign to create. Draft campaigns are not sent until they are started (updated to RUNNING). Stopped campaigns are paused and can be resumed by updating them to RUNNING."},"send_rate":{"type":"integer","minimum":1000,"maximum":1000000,"description":"Determines the maximum number of messages to be sent per minute."},"when":{"type":"object","$ref":"#/components/schemas/when","description":"Campaign programation details (when/how to send)"},"targeting":{"type":"object","$ref":"#/components/schemas/targeting","description":"Who should be reached by the campaign"},"labels":{"type":"array","items":{"type":"string"},"description":"An array of labels to assign to the campaign for organizational and capping purposes. Limited at 5 labels per campaign."},"messages":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/email"},{"$ref":"#/components/schemas/push"}],"discriminator":{"propertyName":"channel_type","mapping":{"email":"#/components/schemas/email","push":"#/components/schemas/push"}}},"description":"Messages to send, only one kind of message is allowed at a time."}}},"when":{"type":"object","required":["start_time"],"properties":{"local_time":{"type":"boolean","description":"If true, Batch servers will send messages according to each time zone. The campaign will take 24 hours to complete"},"start_time":{"type":"string","description":"Campaign start date in UTC in a RFC 3339 date-time format (for example 2023-10-24T10:22:00Z) or ***now*** to start the campaign as soon as the call is made"}}},"targeting":{"type":"object","properties":{"languages":{"type":"array","items":{"type":"string"},"description":"An array containing all device languages to be targeted. All language codes in this array must be contained in the messages object. [See here](https://doc.batch.com/api/campaigns/advanced#_language-and-country-codes) for matching rules and valid language codes. E.g.{\"languages\":[\"it\",\"fr\"]}"},"regions":{"type":"array","items":{"type":"string"},"description":"An array containing all the geographical regions codes to be targeted. [See here](https://doc.batch.com/api/campaigns/advanced#_language-and-country-codes) for all valid region codes. E.g.{\"regions\":[\"FR\",\"US\"]}"},"query":{"type":"object","description":"A mongo inspired query object containing filters & operators, based on native attributes (app version, OS version, etc) and custom users data (attributes, tags & events defined by you in the SDK)"}}},"email":{"title":"email","description":"A representation of an email message","type":"object","required":["channel_type","subject","sender_identity_id","html"],"properties":{"channel_type":{"type":"string","enum":["email"]},"subject":{"type":"string","description":"Your email subject. Can use personalization"},"sender_identity_id":{"type":"string"},"reply_to":{"type":"object","required":["email_address"],"properties":{"email_address":{"type":"string"}}},"html":{"type":"string","description":"Your email content as html. Can use personalization"},"languages":{"type":"array","items":{"$ref":"#/components/schemas/languageEmail"},"description":"Array of translations. Default language content is located at the level above."}}},"languageEmail":{"type":"object","required":["language","subject","sender_identity_id","html"],"properties":{"language":{"type":"string"},"subject":{"type":"string","description":"Your email subject. Can use personalization"},"sender_identity_id":{"type":"string"},"reply_to":{"type":"object","required":["email_address"],"properties":{"email_address":{"type":"string"}}},"html":{"type":"string","description":"Your email content as html. Can use personalization"}}},"push":{"title":"push","description":"A representation of a push message","type":"object","required":["channel_type","platform_type","body"],"properties":{"channel_type":{"type":"string","enum":["push"]},"platform_type":{"type":"array","items":{"type":"string","enum":["ios","android","web"]}},"title":{"type":"string","description":"Title of the notification. Can use personalization"},"body":{"type":"string","description":"Body of the notification. Can use personalization"},"media":{"type":"object","description":"Rich notification content","properties":{"picture":{"type":"string","description":"URL to an image that will be displayed as the main notification image. The file must be a RGB PNG or JPG image with a minimum height of 300px and width of 200px. Your server must support the HTTP OPTION verb. Can use personalization"}}},"priority":{"type":"string","enum":["normal","high"],"default":"high","description":"Defines the priority of your message on iOS (APNS) and Android (FCM). If you set `push_type` to `background`, this value MUST be `normal`"},"push_type":{"type":"string","enum":["alert","background"],"default":"alert","description":"Defines whether notifications should show an alert or be silent to trigger a background action"},"time_to_live":{"type":"integer","description":"Time to live (TTL) represents the time a notification can be held for delivery in seconds before expiring. If a user was offline and comes back online after this duration, the notification will not be delivered. It does not remove notifications already delivered to devices. Setting a value of `0` disables the TTL, which leaves expiration up to the platform push service","minimum":0,"maximum":2419200,"default":0},"filter_push_tokens":{"type":"string","enum":["all","collected","imported"],"default":"collected","description":"`all` - the campaign will target imported and collected push tokens
`collected` - the campaign will target only collected push tokens, detected by Batch SDKs
`imported` - the campaign will target only imported push tokens, not yet detected by Batch SDKs\n"},"ios":{"type":"object","description":"iOS specific attributes","properties":{"deeplink":{"type":"string","maxLength":1024,"description":"Deeplink that the notification should point to once opened. Can use personalization"},"custom_payload":{"type":"string","description":"String representation of a JSON object. Can be used to override standard keys, such as `aps`. Using the `com.batch` key is forbidden. Can use personalization"}}},"android":{"type":"object","description":"Android specific attributes","properties":{"deeplink":{"type":"string","maxLength":1024,"description":"Deeplink that the notification should point to once opened. Can use personalization"},"custom_payload":{"type":"string","description":"String representation of a JSON object. Can be used to override standard keys, such as `aps`. Using the `com.batch` key is forbidden. Can use personalization"},"media":{"type":"object","description":"Rich notification content","properties":{"icon":{"type":"string","description":"URL to an image that will be displayed as the icon of a notification. The file must be a square PNG or JPG image with a minimum size of 196px and your server must support the HTTP OPTION verb. Can use personalization"}}},"collapse_key":{"type":"object","description":"Defines how notifications are managed when an offline device goes online (enabled by default). If enabled, the device will only show the most recent notification. If disabled, it will show all the notifications received when the device was offline. You should disable the collapse key if all your notifications matter (E.g. messages, etc) . You can use up to 3 different collapse keys if you want users to get only one notification of each kind when coming online (E.g. marketing messages, alert, etc)","properties":{"enabled":{"type":"boolean","description":"Whether the collapse_key is enabled or not"},"key":{"type":"string","description":"collapse_key grouping value"}}}}},"web":{"type":"object","description":"Web specific attributes","properties":{"deeplink":{"type":"string","maxLength":1024,"description":"Deeplink that the notification should point to once opened. Can use personalization"},"media":{"type":"object","description":"Rich notification content","properties":{"icon":{"type":"string","description":"URL to an image that will be displayed as the icon of a notification. The file must be a square PNG or JPG image with a minimum size of 196px and your server must support the HTTP OPTION verb. Can use personalization"}}}}},"languages":{"type":"array","items":{"$ref":"#/components/schemas/languagePush"},"description":"Array of translations. Default language content is located at the level above."}}},"languagePush":{"type":"object","required":["language","body"],"properties":{"language":{"type":"string"},"title":{"type":"string","description":"Title of the notification. Can use personalization"},"body":{"type":"string","description":"Body of the notification. Can use personalization"},"media":{"type":"object","description":"Rich notification content","properties":{"picture":{"type":"string","description":"URL to an image that will be displayed as the main notification image. The file must be a RGB PNG or JPG image with a minimum height of 300px and width of 200px. Your server must support the HTTP OPTION verb. Can use personalization"}}},"ios":{"type":"object","description":"iOS specific attributes","properties":{"deeplink":{"type":"string","maxLength":1024,"description":"Deeplink that the notification should point to once opened. Can use personalization"}}},"android":{"type":"object","description":"Android specific attributes","properties":{"deeplink":{"type":"string","maxLength":1024,"description":"Deeplink that the notification should point to once opened. Can use personalization"},"media":{"type":"object","description":"Rich notification content","properties":{"icon":{"type":"string","description":"URL to an image that will be displayed as the icon of a notification. The file must be a square PNG or JPG image with a minimum size of 196px and your server must support the HTTP OPTION verb. Can use personalization"}}}}},"web":{"type":"object","description":"Web specific attributes","properties":{"deeplink":{"type":"string","maxLength":1024,"description":"Deeplink that the notification should point to once opened. Can use personalization"},"media":{"type":"object","description":"Rich notification content","properties":{"icon":{"type":"string","description":"URL to an image that will be displayed as the icon of a notification. The file must be a square PNG or JPG image with a minimum size of 196px and your server must support the HTTP OPTION verb. Can use personalization"}}}}}}},"EmptyResponse":{"type":"object"},"Error":{"type":"object","required":["error_message","error_code"],"properties":{"error_message":{"description":"A human readable error message","type":"string"},"error_code":{"description":"Error code","type":"string"}}}},"responses":{"200":{"description":"Request successful, campaign udpated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmptyResponse"}}}},"400":{"description":"The request is malformed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"The Rest API Key is not valid for this project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Batch's services are under maintenance. Please try again later","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/campaigns/update":{"post":{"operationId":"campaigns_update","summary":"Update","description":"Update an existing campaign","tags":["Campaigns"],"parameters":[{"$ref":"#/components/parameters/HeaderProjectKey"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/campaign_update"}}}},"responses":{"200":{"$ref":"#/components/responses/200"},"400":{"$ref":"#/components/responses/400"},"401":{"$ref":"#/components/responses/401"},"404":{"$ref":"#/components/responses/404"},"429":{"$ref":"#/components/responses/429"},"500":{"$ref":"#/components/responses/500"},"503":{"$ref":"#/components/responses/503"}}}}}}
```
### Request structure
The Campaign API exposes a POST endpoint that allows to update a campaign:
`/campaigns/update`
#### Headers and authentication
See [Overview → Using Project APIs](https://doc.batch.com/developer/api/cep/..#request-headers-and-authentication).
#### Post data
The body of the request must contain a valid JSON payload describing the campaign.
Exemple of a request body:
```json
{
"id": "orchestration_0664hyh918hr1gnzka9py5t62nrc0e1q",
"campaign": {
"name": "The campaign name",
"state": "RUNNING",
"when": {
"local_time": false,
"start_time": "2024-01-24T10:22:00Z"
},
"targeting": {
"languages": [
"fr"
],
"regions": [
"FR"
],
"query": {
"firstname": {
"$eq": "Jane"
}
}
},
"messages": [
{
"channel_type": "email",
"subject": "The campaign subject",
"sender_identity_id": "4012",
"reply_to": {
"email_address": "jane.doe@demobatch.com"
},
"html": "The campaign HTML content"
}
]
}
}
```
### identifier block
"id": "orchestration_0664hyh918hr1gnzka9py5t62nrc0e1q"
Campaign identifier is received in the API Campaign create response.
### Campaign block
See [API Campaigns create](https://doc.batch.com/developer/api/cep/campaigns/create) for details about parameters.
### Responses
#### Success
If the POST to the API endpoint is successfull you will receive an **HTTP 200** confirmation.
#### Failure
If the POST data does not meet the API requirements you will receive an actionable error message. Contact us at if you need further support.
* `AUTHENTICATION_INVALID` (Http status code: 401, Error code: 10)
* `API_MISUSE` (Http status code: 403, Error code: 12)
* `ROUTE_NOT_FOUND` (Http status code: 404, Error code: 20)
* `MISSING_PARAMETER` (Http status code: 400, Error code: 30)
* `MALFORMED_PARAMETER` (Http status code: 400, Error code: 31)
* `MALFORMED_JSON_BODY` (Http status code: 400, Error code: 32)
* `SERVER_ERROR` (Http status code: 500, Error code: 1)
* `MAINTENANCE_ERROR` (Http status code: 503, Error code: 2)
* `TOO_MANY_REQUESTS` (Http status code: 429, Error code: 60)\
If you get a "too many requests" response, please wait for at least 5 seconds before trying again. Further requests might still return this error.