# Create a new announcement

Create the individual Announcement details.

## Endpoint

**POST** `/api/v1/mdm/announcements`

## Request

### Request URL

`https://{server-hostname}:8383/api/v1/mdm/announcements`

### Scope

`MDMDeviceMgmt.CREATE`

### Header

`Authorization: d92d4xxxxxxxxxxxxx15f52`

### Request Parameters

#### Request Headers

| Name | Type | Required | Value |
|---|---|---|---|
| Content-Type | string | Mandatory | application/json |
| Accept | string | Mandatory | application/json |

#### Request Body

`application/json`

| Attribute | Type | Required | Description |
|---|---|---|---|
| announcement_name | string | Mandatory | Name/title of the announcement. Must be unique within the customer |
| announcement_format | integer | Optional | Display format for the announcement (e.g., 1) |
| announcement_detail | JSON Object | Optional | Nested object containing message details including title, content, icon, and acknowledgement settings |

### Sample Request

```curl
curl --request POST \
  --url https://appdomain/api/v1/mdm/announcements \
  --header 'Accept: application/json' \
  --header 'Authorization:  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"announcement_name":"Test announcement","announcement_format":1,"announcement_detail":{"ack_button":"Got It","nbar_message":"You have a new announcement","title_color":"#ffffff","nbar_icon":"/images/announcement/nbaricon/info.png","needs_acknowledgement":true,"detail_message":"<p>Test announcement message</p>","title":"Test announcement"}}'
```

### Sample Request Body

Create an announcement that requires acknowledgement from devices:

```json
{
  "announcement_name": "Test announcement",
  "announcement_format": 1,
  "announcement_detail": {
    "ack_button": "Got It",
    "nbar_message": "You have a new announcement",
    "title_color": "#ffffff",
    "nbar_icon": "/images/announcement/nbaricon/info.png",
    "needs_acknowledgement": true,
    "detail_message": "<p>Test announcement message</p>",
    "title": "Test announcement"
  }
}
```

Create an informational announcement without acknowledgement requirement:

```json
{
  "announcement_name": "System Maintenance Notice",
  "announcement_format": 1,
  "announcement_detail": {
    "ack_button": "",
    "nbar_message": "Scheduled maintenance tonight",
    "title_color": "#ff5722",
    "nbar_icon": "/images/announcement/nbaricon/info.png",
    "needs_acknowledgement": false,
    "detail_message": "<p>System will undergo maintenance from 10PM to 2AM</p>",
    "title": "System Maintenance"
  }
}
```

## Response

### Response Parameters

#### HTTP Code 200

Response Body: `application/json`

| Attribute | Type | Description |
|---|---|---|
| announcement_id | long | Unique ID representing the newly created announcement |
| announcement_name | string | Name/title of the announcement |
| announcement_format | string | Display format code for the announcement |
| creation_time | string | Epoch timestamp (milliseconds) when the announcement was created |
| last_modified_time | string | Epoch timestamp (milliseconds) when the announcement was last modified |
| created_by_user | string | Username of the admin who created the announcement |
| last_modified_by_user | string | Username of the admin who last modified the announcement |
| collection_id | string | Internal collection ID associated with this announcement |
| profile_id | string | Internal profile ID associated with this announcement |
| ack_button | string | Acknowledgement button text shown on device. Empty string if acknowledgement not required |
| needs_acknowledgement | boolean | Whether the announcement requires acknowledgement from the device user |
| is_moved_to_trash | boolean | Whether the announcement has been soft-deleted |
| no_of_devices_distributed | string | Number of devices the announcement is distributed to |
| no_of_groups_distributed | string | Number of groups the announcement is distributed to |
| priority | string | Priority level of the announcement |
| last_distributed_time | string | Epoch timestamp of the last distribution. -1 if never distributed |
| announcement_detail | JSON Object | Nested object containing announcement message content details |

### Possible Response Codes

| Code | Type |
|---|---|
| 200 | HTTP code |

### Sample Response: HTTP 200

Response after creating an announcement with acknowledgement:

```json
{
  "creation_time": "1777342912041",
  "last_modified_time": "1777342912041",
  "announcement_name": "Test announcement",
  "announcement_format": "1",
  "needs_acknowledgement": true,
  "last_modified_by_user": "admin",
  "no_of_devices_distributed": "0",
  "priority": "0",
  "created_by_user": "admin",
  "no_of_groups_distributed": "0",
  "collection_id": "9007199254741063",
  "ack_button": "Got It",
  "last_distributed_time": "-1",
  "is_moved_to_trash": false,
  "profile_id": "9007199254741063",
  "announcement_id": "9007199254740995",
  "announcement_detail": {
    "nbar_message": "You have a new announcement",
    "title_color": "#ffffff",
    "nbar_icon": "/images/announcement/nbaricon/info.png",
    "announcement_img_id": "9007199254740995",
    "detail_message": "<p>Test announcement message</p>",
    "title": "Test announcement"
  }
}
```

## Rate Limits

![ ](https://www.zohowebstatic.com/sites/zweb/images/people/ico-help.png)

**Duration:** 1 minute | **Threshold:** 30 | **Lock period:** 5 minutes

Duration - Time window for the threshold.  
Threshold - Number of API calls allowed within the specified duration.  
Lock Period - Wait time before consecutive API requests.