Announcements API

Note :

* are mandatory parameters

Table of Contents

1. Add Announcement :

Purpose

To post an announcement using API

Sample request URL:

https://people.zoho.com/people/api/announcement/addAnnouncement?subject=Wellness Program!&message=Enjoy a week-long wellness program at all our office locations.&emailList=c.spalding@zylker.com&notify=true&isSticky=true&&isCommentDisable=true&authtoken=<token>

Params:

*subjectSubject of the announcement to be added
*messageMessage to be given in the announcement
expiryDateExpiry date of the Announcement given in specified format ; -1 denotes no expiration for the announcement
locationLocation which receives the announcement/ If param not given then all locations receive the announcement
emailListEmail IDs to send notification (multiple emails can be separated with comma)/ if param not given then no mail notifications will be sent
notifyif true is given - mail notification will be sent to the people in the given locations/ if locations is not given, the mail notification will be sent to all locations; if false is given - no email notification is sent
isStickyif true is given then it is added as a sticky announcement; if false is given then it is added as an announcement
isCommentDisableif true is given then adding comment is disabled for the user; if false is given then adding comment is enabled for the user.

XML Response:

Success response:

<response uri="/api/announcement/addAnnouncement">    
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>
            <owner>3000000013255</owner>
            <messageText>Enjoy a week-long wellness program at all our office locations.</messageText>
            <emailList>c.spalding@zylker.com,</emailList>
            <subject>Wellness Program!</subject>
            <isNotify>1</isNotify>
            <isCommentDisable>1</isCommentDisable>
            <publishDate>1543211455782</publishDate>
            <announcementId>3000000183025</announcementId>
            <isActive>true</isActive>
            <notifyOthersEmailIds>c.spalding@zylker.com,</notifyOthersEmailIds>
            <isSticky>true</isSticky>
        </resultData>
    </result>
</response>

Error response:

<response uri="/api/announcement/addAnnouncement">
    <status>1</status>
    <message>We have encountered an exception</message>
    <errors>
        <resultData></resultData>
    </errors>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "owner": "3000000013255",
                "messageText": "Enjoy a week-long wellness program at all our office locations.",
                "emailList": "c.spalding@zylker.com,",
                "subject": "Wellness Program!",
                "isNotify": 1,
                "isCommentDisable": 1,
                "publishDate": "1543211440496",
                "announcementId": "3000000183023",
                "isActive": true,
                "notifyOthersEmailIds": "c.spalding@zylker.com,",
                "isSticky": true
            }
        },
        "message": "Success", "uri": "/api/announcement/addAnnouncement",   
        "status": 0
    }
}

Error response:

{
    "response": {
        "message": "We have encountered an exception",
        "uri": "/api/announcement/addAnnouncement",    
        "errors": {
            "resultData": {}
        },
        "status": 1
    }
}

2. Update Announcement :

Purpose

To edit an already posted announcement

Sample request URL:

https://people.zoho.com/people/api/announcement/updateAnnouncement?subject=Wellness Program!&message=Enjoy a week-long wellness program at all our office locations.&emailList=c.spalding@zylker.com&notify=true&isSticky=true&isCommentDisable=true&
id=3610330000035 69704&authtoken=<token>

Params:

*idID of the announcement to be updated
*subjectSubject of the announcement
*messageMessage to be given in the announcement
expiryDateExpiry date of the announcement given in specified format ; -1 denotes no expiration for the announcement
locationLocation which receives the announcement/ If param not given then all locations receive the announcement
emailListEmail IDs to send notification (multiple emails can be separated with comma)/ if param not given then no mail notifications will be sent
notifyif true is given - mail notification will be sent to the people in the given location/ if location is not given, the mail notification will be sent to all locations; if false is given - no email notification is sent
isStickyif true is given then it is updated as a sticky announcement; if false is given then it is updated as an announcement
isCommentDisableif true is given then adding comment is disabled for the user; if false is given then adding comment is enabled for the user.

XML Response:

Success response:

<response uri="/api/announcement/updateAnnouncement">
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>            
            <owner>3000000013255</owner>
            <messageText>Enjoy a week-long wellness program at all our office locations.</messageText>
            <emailList>c.spalding@zylker.com,</emailList>
            <subject>Wellness Program!</subject>
            <isNotify>1</isNotify>
            <isCommentDisable>1</isCommentDisable>
            <announcementId>3000000183025</announcementId>
            <publishDate>1543211455782</publishDate>
            <isActive>true</isActive>
            <notifyOthersEmailIds>c.spalding@zylker.com,</notifyOthersEmailIds>
            <isSticky>false</isSticky>
        </resultData>
    </result>
</response>

Error response:

<response uri="/api/announcement/updateAnnouncement">
    <status>1</status>
    <message>We have encountered an exception</message>
    <errors>
        <resultData></resultData>
    </errors>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "owner": "3000000013255",
                "messageText": "Enjoy a week-long wellness program at all our office locations.",
                "emailList": "c.spalding@zylker.com,",
                "subject": "Wellness Program!",
                "isNotify": 1,
                "isCommentDisable": 1,
                "announcementId": "3000000183025",
                "publishDate": "1543211455782",
                "isActive": true,
                "notifyOthersEmailIds": "c.spalding@zylker.com,",
                "isSticky": false
            }
        },
        "message": "Success",
         "uri": "/api/announcement/updateAnnouncement", 
        "status": 0
    }
}

Error response:

{
    "response": {
        "message": "We have encountered an exception",
      "uri": "/api/announcement/updateAnnouncement",  
      "errors": {
            "resultData": {}
        },
        "status": 1
    }
}

3. Delete Announcement :

Purpose

To delete a posted announcement using API. This will delete all data pertaining to an announcement.

Sample request URL:

https://people.zoho.com/api/announcement/deleteAnnoucement?id=448358000000257003&authtoken=<token>

Params:

*idID of the announcement to be deleted

XML Response:

Success response:

<response uri="/api/announcement/deleteAnnouncement">
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>
            <status>1</status>
        </resultData>
    </result>
</response>

Error response:

<response uri="/api/announcement/deleteAnnouncement">
    <status>1</status>
    <message>You are not permitted to access announcements;</message>
    <errors>
        <resultData></resultData>
    </errors>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "status": 1
            }
        },
        "message": "Success",
        "uri": "/api/announcement/deleteAnnouncement",  
        "status": 0
    }
}

Error response:

{
    "response": {
        "message": "You are not permitted to access announcements;",
        "uri": "/api/announcement/deleteAnnouncement",   
        "errors": {
            "resultData": {}
        },
        "status": 1
    }
}

4. Enable/Disable Announcement :

Purpose

To enable or disable an announcement. Disabling an announcement will retain related data and so the announcement can be enabled when required.

Sample request URL:

https://people.zoho.com/api/announcement/enableDisableAnnouncement? id=3000000183011&authtoken=<token>

Params:

*idID of the announcement to be enabled/disabled. If announcement is currently enabled, then if param is given then the announcement is disabled and vice versa.

XML Response:

Success response:

<response uri="/api/announcement/enableDisableAnnouncement">
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>
            <status>0</status>
        </resultData>
    </result>
</response>

Error response:

<response uri="/api/announcement/enableDisableAnnouncement">
    <status>1</status>
    <message>You are not permitted to access announcements;</message>
    <errors>
        <resultData></resultData>
    </errors>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "status": 1
            }
        },
        "message": "Success",
        "uri": "/api/announcement/enableDisableAnnouncement",  
        "status": 0
    }
}

Error response:

{
    "response": {
        "result": {
            "code": "Permission Denied",
            "resultData": {}
        },
        "message": "You are not permitted to access announcements;",
        "uri": "/api/announcement/enableDisableAnnouncement",  
        "status": 0
    }
}

5. Add Announcement Comment :

Purpose

To comment on an announcement using API

Sample request URL:

https://people.zoho.com/api/announcement/addAnnouncementComment?id=448358000000257007&authtoken=<token>&comment=Great

Params:

*idID of the announcement for which comment is to be added
*commentcomment to be given for the announcement

XML Response:

Success response:

<response uri="/api/announcement/addAnnouncementComment">
    <status>1</status>
    <message>Success</message>
    <result>
        <code>200</code>
        <resultData>
            <commentList>
                <commat>1542094544468</commat>
                <isDelete>true</isDelete>
                <isHTML>false</isHTML>
                <empName>Spalding</empName>
                <commentId>361033000003569710</commentId>
                <comment>Great</comment>
                <type>Announcement</type>
                <commby>642094013</commby>
            </commentList>
        </resultData>
    </result>
</response>

Error response:

<response uri="/api/announcement/addAnnouncementComment">
    <status>0</status>
    <message>This announcement is not applicable for your location</message>
    <errors>
        <code>Permision_denied</code>
        <resultData></resultData>
    </errors>
</response>

JSON Response:

Success response:

{
    "response": {
        "message": "Success",
        "uri": "/api/announcement/addAnnouncementComment"", 
        "result": {
            "code": 200,
            "resultData": {
                "commentList": {                    
                    "commat": "1542094507603",
                    "isDelete": true,
                    "isHTML": false,
                    "empName": "Spalding",
                    "commentId": "361033000003569708",
                    "comment": "Great",
                    "type": "Announcement",
                    "commby": "642094013",
                }
            }
        },
        "status": 1
    }
}

Error response:

{
    "response": {
        "errors": {
            "code": "Permision_denied",
            "resultData": {}
        },
        "message": "This announcement is not applicable for your location",
        "uri": "/api/announcement/addAnnouncementComment"",
        "status": 0
    }
}

6. Delete Announcement Comment :

Purpose

To delete a comment of an announcement

Sample request URL:

https://people.zoho.com/api/announcement/deleteAnnouncementComment?commentId=448358000000257017&authtoken=<token>

Params:

*commentIdID of the comment to be deleted

XML Response:

Success response:

<response uri="/api/announcement/deleteAnnouncementComment">
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>
            <commentid>3000000183013</commentid>
        </resultData>
    </result>
</response>

Error response:

<response uri="/api/announcement/deleteAnnouncementComment">
    <status>1</status>
    <message>You are not permitted to access announcements;</message>
    <errors>
        <resultData></resultData>
    </errors>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "commentid": "3000000183013"
            }
        },
        "message": "Success",
        "uri": "/api/announcement/deleteAnnouncementComment",
        "status": 0
    }
}

Error response:

{
    "response": {
        "message": "You are not permitted to access announcements;",
        "uri": "/api/announcement/deleteAnnouncementComment",
        "errors": {
            "resultData": {}
        },
        "status": 1
    }
}

7. Get All Announcements :

Purpose

To list all announcements using API

Sample request URL:

https://people.zoho.com/people/api/announcement/getAllAnnouncement?authtoken=<token>&startIdx=1&search=Program&isSticky=false

Params:

isStickyif true is given then all the sticky announcements are fetched; if false is given then all the announcements are fetched
*startIdxthe starting index to be given - 10 records from the given starting index will be fetched at a time ; starting index should be 1 or greater than 1 ( if isSticky is given then the param will fetch based on results from isSticky )
searchkeyword given is searched from the 10 records (from the given starting index); if param not given then no search is done

XML Response:

Success response:

<response uri="/api/announcement/getAllAnnouncement">
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>
            <announcementList>
                <data>
                    <owner>3000000013255</owner>
                    <modifiedTime>1543209052900</modifiedTime>
                    <subject>Wellness Program!</subject>
                    <isCommentDisable>1</isCommentDisable>
                    <isNotify>1</isNotify>
                    <announcementId>3000000183011</announcementId>
                    <publishDate>1543209052899</publishDate>
                    <expireDate>-1</expireDate>
                    <message>Enjoy a week-long wellness program at all our office locations.</message>
                    <isActive>false</isActive>
                    <isSticky>1</isSticky>
                    <notifyOthersEmailIds>c.spalding@zylker.com,</notifyOthersEmailIds>
                </data>
                <data>
                    <owner>3000000013255</owner>
                    <modifiedTime>1542962837811</modifiedTime>
                    <subject>Wellness Program!</subject>
                    <isCommentDisable>0</isCommentDisable>
                    <isNotify>1</isNotify>
                    <announcementId>3000000166005</announcementId>
                    <publishDate>1542962837811</publishDate>
                    <expireDate>-1</expireDate>
                    <message>Enjoy a week-long wellness program at all our office locations.</message>
                    <isActive>true</isActive>
                    <isSticky>1</isSticky>
                    <notifyOthersEmailIds>c.spalding@zylker.com,</notifyOthersEmailIds>
                </data>
            </announcementList>
            <annLikeCnt>{"success":true,"statusIds":{"3000000171125":[true,1]},"commentIds":{}}
</annLikeCnt>
            <hasNext>true</hasNext>
            <commentsCnt>{"3000000183011":4}</commentsCnt>
        </resultData>
    </result>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "announcementList": [
                    {
                        "owner": "3000000013255",
                        "modifiedTime": "1543209052900",
                        "subject": "Wellness Program!",
                        "isCommentDisable": 1,
                        "isNotify": 1,
                        "announcementId": "3000000183011",
                        "publishDate": "1543209052899",
                        "expireDate": -1,
                        "message": "Enjoy a week-long wellness program at all our office locations.",
                        "isActive": false,
                        "isSticky": 1,
                        "notifyOthersEmailIds": "c.spalding@zylker.com,"
                    }
                ],
                "annLikeCnt": {
                    "success": true,
                    "statusIds": {
                        "3000000171125": [
                            true,
                            1
                        ]
                    },
                    "commentIds": {}
                },
                "hasNext": true,
                "commentsCnt": {
                    "3000000183011": 4
                }
            }
        },
        "message": "Success",
        "uri": "/api/announcement/getAllAnnouncement",
        "status": 0
    }
}

8. Get Single Announcement by ID :

Purpose

To fetch a particular announcement using its unique announcement ID

Sample request URL:

https://people.zoho.com/people/api/announcement/getAnnouncementByID?authtoken=<token>&id=3610330000098011

Params:

*idID of the single announcement to be fetched

XML Response:

Success response:

<response uri="/api/announcement/getAnnouncementByID">
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>
            <announcementList>
                <data>
                    <owner>3000000013255</owner>
                    <modifiedTime>1542962837811</modifiedTime>
                    <subject>Wellness Program!</subject>
                    <isNotify>1</isNotify>
                    <isCommentDisable>1</isCommentDisable>
                    <announcementId>3000000166005</announcementId>
                    <publishDate>1542962837811</publishDate>
                    <expireDate>-1</expireDate>
                    <message>Enjoy a week-long wellness program at all our office locations.</message>
                    <isActive>true</isActive>
                    <isSticky>1</isSticky>
                    <notifyOthersEmailIds>c.spalding@zylker.com,</notifyOthersEmailIds>
                </data>
            </announcementList>
            <annLikeCnt>{}</annLikeCnt>
            <commentsCnt>{}</commentsCnt>
        </resultData>
    </result>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "announcementList": [
                    {
                        "owner": "3000000013255",
                        "modifiedTime": "1542962837811",
                        "subject": "Wellness Program!",
                        "isNotify": 1,                 
                        "isCommentDisable": 1,                        
                        "announcementId": "3000000166005",
                        "publishDate": "1542962837811",
                        "expireDate": -1,
                        "message": "Enjoy a week-long wellness program at all our office locations.",
                        "isActive": true,
                        "isSticky": 1,
                        "notifyOthersEmailIds": "c.spalding@zylker.com,"
                    }
                ],
                "annLikeCnt": {},
                "commentsCnt": {}
            }
        },
        "message": "Success",
        "uri": "/api/announcement/getAnnouncementByID", 
        "status": 0
    }
}

9. Filter Announcement API:

Purpose

To filter announcements

Sample request URL:

https://people.zoho.com/people/api/announcement/filterAnnouncement? enable=1&startIdx=1&isSticky=true&authtoken=<token>

Params:

isSticky:if true is given then all the sticky announcements are filtered; if false is given then all announcements are filtered
location:Announcements of the location mentioned is filtered; if param not given then all location announcements are filtered ( if isSticky is given then this param will fetch based on results from isSticky)
enable:
  • if 1 is given and isSticky is true and Locations is given - then all enabled sticky announcements of the given location will be filtered
  • if 0 is given and isSticky is true and Location is given then all disabled sticky announcements of the given location will be filtered
  • if 1 is given and isSticky is true and no location is given then all enabled sticky announcements of all locations will be filtered
  • if 0 is given and isSticky is true and no location is given then all disabled sticky announcements of all locations will be filtered 
  • If 1 is given and isSticky is false/not given and Location is given, then all enabled announcements of the given locations will be filtered
  • if 0 is given and isSticky is false/not given and Location is given, then all disabled announcements of the given locations will be filtered
*startIdxthe starting index to be given - 10 records from the given starting index will be filtered at a time; starting index should be 1 or greater than 1 ( it will filter based on results from isSticky, location and enable params)

XML Response:

Success response:

<response uri="/api/announcement/filterAnnouncement">    
    <status>0</status>
    <message>Success</message>
    <result>
        <resultData>
            <announcementList>
                <data>
                    <owner>3000000013255</owner>
                    <modifiedTime>1542978181572</modifiedTime>
                    <subject>1</subject>
                    <isNotify>1</isNotify>
                    <isCommentDisable>1</isCommentDisable>
                    <announcementId>3000000171125</announcementId>
                    <publishDate>1542978181571</publishDate>
                    <expireDate>-1</expireDate>
                    <location>["3000000020013"]</location>
                    <message>
                        <div>1</div>
                    </message>
                    <isActive>true</isActive>
                    <isSticky>1</isSticky>
                    <notifyOthersEmailIds>c.spalding@zylker.com,</notifyOthersEmailIds>
                </data>
                <data>
                    <owner>3000000013356</owner>
                    <modifiedTime>1542713376832</modifiedTime>
                    <subject>Wellness Program!</subject>
                    <isNotify>1</isNotify>
                    <isCommentDisable>0</isCommentDisable>
                    <announcementId>3000000149011</announcementId>
                    <publishDate>1542713376832</publishDate>
                    <expireDate>-1</expireDate>
                    <location>["3000000020013"]</location>
                    <message>Enjoy a week-long wellness program at all our office locations.</message>
                    <isActive>true</isActive>
                    <isSticky>1</isSticky>
                    <notifyOthersEmailIds>c.spalding@zylker.com,</notifyOthersEmailIds>
                </data>
                <data>
                    <owner>3000000013356</owner>
                    <modifiedTime>1542711511036</modifiedTime>
                    <subject>Wellness Program!</subject>
                    <isNotify>1</isNotify>
                    <isCommentDisable>1</isCommentDisable>
                    <announcementId>3000000148063</announcementId>
                    <publishDate>1542711503920</publishDate>
                    <expireDate>-1</expireDate>
                    <location>["3000000020013"]</location>
                    <message>Enjoy a week-long wellness program at all our office locations.</message>
                    <isActive>true</isActive>
                    <isSticky>1</isSticky>
                </data>
                <data>                    
                    ​<owner>3000000013356</owner>
                    <modifiedTime>1542711452452</modifiedTime>
                    <subject>Wellness Program!</subject>
                    <isNotify>1</isNotify>
                    <isCommentDisable>1</isCommentDisable>
                    <announcementId>3000000148057</announcementId>
                    <publishDate>1542711452452</publishDate>
                    <expireDate>-1</expireDate>
                    <location>["3000000020013"]</location>
                    <message>Enjoy a week-long wellness program at all our office locations.</message>
                    <isActive>true</isActive>
                    <isSticky>1</isSticky>
                </data>
            </announcementList>
            <annLikeCnt>{"success":true,"statusIds":{"3000000171125":[true,1]},"commentIds":{}}
</annLikeCnt>
            <hasNext>true</hasNext>
            <commentsCnt>{}</commentsCnt>
        </resultData>
    </result>
</response>

JSON Response:

Success response:

{
    "response": {
        "result": {
            "resultData": {
                "announcementList": [
                    {
                        "owner": "3000000013255",
                        "modifiedTime": "1542978181572",
                        "subject": "1",
                        "isNotify": 1,
                        "isCommentDisable": 1,
                        "announcementId": "3000000171125",
                        "publishDate": "1542978181571",
                        "expireDate": -1,
                        "location": [
                            "3000000020013"
                        ],
                        "message": "<div&g;1</div>",
                        "isActive": true,
                        "isSticky": 1,
                        "notifyOthersEmailIds": "c.spalding@zylker.com,"
                    },
                    {
                        "owner": "3000000013356",
                        "modifiedTime": "1542711452452",
                        "subject": "Wellness Program!",                        
                        "isNotify": 1,                      
                        "isCommentDisable": 0,
                        "announcementId": "3000000148057",
                        "publishDate": "1542711452452",
                        "expireDate": -1,
                        "location": [
                            "3000000020013"
                        ],
                        "message": "Enjoy a week-long wellness program at all our office locations.",
                        "isActive": true,
                        "isSticky": 1
                    }
                ],
                "annLikeCnt": {
                    "success": true,
                    "statusIds": {
                        "3000000171125": [
                            true,
                            1
                        ]
                    },
                    "commentIds": {}
                },
                "hasNext": true,
                "commentsCnt": {}
            }
        },
        "message": "Success",
        "uri": "/api/announcement/filterAnnouncement",  
        "status": 0
    }
}