Use the Microsoft Graph API to work with Viva Engage
Important
APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.
The Microsoft Graph API enables apps to manage communities in Viva Engage. Viva Engage is a social fabric for the Microsoft Viva suite of apps that connects people across the organization to share and learn. It's a place where employees can connect with leaders, coworkers, and communities, share their knowledge and ideas, and find belonging at work.
Important
The Viva Engage API in Microsoft Graph is only supported for Viva Engage networks in native mode. You can't use this API to manage legacy or external Viva Engage networks.
Authorization
To call the Viva Engage API in Microsoft Graph, your app needs to acquire an access token. For details about access tokens, see Get access tokens to call Microsoft Graph. Your app also needs the appropriate permissions. For more information, see Microsoft Graph permissions reference.
Common use cases
The following table lists common use cases for the Viva Engage API.
| Use case | API | Notes |
|---|---|---|
| Create a community | POST /employeeExperience/communities | If successful, this method returns a 202 Accepted response code that contains a link to an engagementAsyncOperation object. |
| Poll for community creation status | GET /employeeExperience/engagementAsyncOperations/{engagementAsyncOperationId} | If successful, this method returns a 200 OK response code and an engagementAsyncOperation object in the response body. Periodically check the status of the operation by making a GET request to this location; wait >30 seconds between checks. When the request completes successfully, the status indicates succeeded and the resourceLocation points to the created or modified resource. |
| Get a community after creation | GET /employeeExperience/communities/{communityId} | If successful, this method returns a 200 OK response code and a community object in the response body. The community object references the associated Microsoft 365 group ID that you can use for community membership and ownership management. |
| Get a list of communities | GET /employeeExperience/communities | If successful, this method returns a 200 OK response code and a collection of Viva Engage community objects in the response body. |
| Update a community | PATCH /employeeExperience/communities/{communityId} | If successful, this method updates an existing Viva Engage community and returns a 204 No Content response code. |
| Delete a community | DELETE /employeeExperience/communities/{communityId} | If successful, this method deletes a Viva Engage community along with all associated Microsoft 365 content, including the connected Microsoft 365 group, OneNote notebook, and Planner plans. For more information, see What happens if I delete a Viva Engage community connected to Microsoft 365 groups. |
| Add members to a community | POST /groups/{groupId}/members/$ref | When new members are added to a group, the associated membership of the community is automatically updated. |
| Remove a member from a community | DELETE /groups/{groupId}/members/{userId}/$ref | When a member is removed from a group, the associated membership of the community is automatically updated. |
| Add a community admin | POST /groups/{groupId}/owners/$ref | When a user is added as a group owner, they automatically become an admin of the associated community. |
| Remove a community admin | DELETE /groups/{groupId}/owners/{userId}/$ref | When a group owner is removed, they stop being admin for the associated community. You can't remove the last owner (user object) of a group. |
Communities and groups
For Viva Engage networks in native mode, the creation of a new Viva Engage community also results in the creation of a connected Microsoft 365 group, along with a new SharePoint site, OneNote notebook, and Planner plan. Use the associated group to manage operations on a community, for example:
- Add or remove group members
- Manage group ownership
- Delete a group
- Rename a group
- Update the group description
For more information about the relationship between Viva Engage communities and Microsoft 365 groups, see Viva Engage and Microsoft 365 Groups.
Note: You can't use the Create group API to provision a Viva Engage community.
API limits
Viva Engage API calls are subject to rate limiting, allowing 10 requests per user, per app, within a 30-second time period. When you exceed the rate limit, all subsequent requests return a 429 Too Many Requests response code.
For guidance on how to handle throttling in Microsoft Graph, see Microsoft Graph throttling guidance.
Next steps
- Use the Microsoft Graph API to manage communities in Viva Engage.
- Try the Viva Engage API in the Graph Explorer.