Hello everyone!
Welcome back to this week's post in the Kaizen series on User's Unavailability APIs.
Business and meetings go hand in hand. There are times when you attend a meeting with your clients or partners on a weekday and during the working hours.
During such times, Zoho CRM gives you the option to mark yourself unavailable, so that you do not get invited to other meetings or calls.
When you have synced Zoho CRM's calendar with an external system, these APIs allow you to ensure that the data is up to date in both places so you never miss a meeting because of date and time conflicts.
Additionally, if you are the admin, you are at liberty to view the details of the availability of other users, too.
Let us now discuss these APIs in detail.
Use this API to mark yourself unavailable during a set period.
Request URL: {api-domain}/crm/v4/settings/users_unavailability
Request Method: POST
Scope: ZohoCRM.settings.users_unavailability.ALL/WRITE
Input Body:
{ "users_unavailability": [ { "comments": "Unavailable during this time. Please schedule a call later.", "from": "2023-02-28T19:00:00+05:30", "to": "2023-03-10T20:00:00+05:30", "user": { "name": "Patricia Boyle", "id": "554xxxx966", "zuid": "554xxx5011" } } ] } |
Key | Description |
| Any comment you want to add to describe your unavailability. |
| The date and time(in the ISO8601 format) from which you will be unavailable. |
| The date and time(in the ISO8601 format) after which you will be available. |
| The name(optional), ID(from the Get users API, mandatory), and zuid(from the Get users API, optional) |
Response:
{ "users_unavailability": [ { "code": "SUCCESS", "details": { "id": "3652397000011056002" }, "message": "Unavailability created successfully.", "status": "success" } ] } |
Use this API to update the details of your unavailability.
Request URL: {api-domain}/crm/v4/settings/users_unavailability or {api-domain}/crm/v4/settings/users_unavailability/{id}
Request Method: PUT
Scope: ZohoCRM.settings.users_unavailability.ALL/UPDATE
Input Body:
{ "users_unavailability": [ { "comments": "Unavailable - Updated the 'from' time", "from": "2023-03-01T15:00:00+05:30", "id": "3652397000011056002" } ] } |
Response:
{ "users_unavailability": [ { "code": "SUCCESS", "details": { "id": "3652397000011056002" }, "message": "Unavailability updated successfully.", "status": "success" } ] } |
Use this API to delete the details of your unavailability.
Request URL: {api-domain}/crm/v4/settings/users_unavailability/{id}
Request Method: DELETE
Scope: ZohoCRM.settings.users_unavailability.ALL/DELETE
Response:
{ "users_unavailability": [ { "code": "SUCCESS", "details": { "id": "3652397000011056002" }, "message": "Unavailability deleted Successfully", "status": "success" } ] } |
Use this API to get the details of the unavailability of a user.
Only admins can get the details of all users, while non-admin users can only fetch their own details.
Request URL: {api-domain}/crm/v4/settings/users_unavailability
Request Method: GET
Scope: ZohoCRM.settings.users_unavailability.ALL/GET
Optional Parameters:
- group_ids - The unique ID of the user group that the user belongs to. To fetch the details of the user from multiple groups, you can give the IDs as comma-separated values.
- role_ids - The unique ID of the role that the user belongs to. To get the users from multiple roles, input their role IDs as comma-separated values.
- territory_ids - The unique ID of the territory that the user is a part of. To get the users belonging to multiple territories, input their territory IDs as comma-separated values.
- include_inner_details - Use this parameter to get the user's ZUID in the response. The value for this parameter is user.zuid
- filters - The criteria to filter the users based on the time they will be unavailable. You can filter using groups and comparators as follows:
- group - Contains the comparator, value and the API name of the field based on which you want to filter the results. The allowed comparators are equals, not_equals, between, greater_than, greater_equal, less_than, and less_equal.
- group_operator - The operator AND or OR.
Note that the value of this parameter must be encoded.
Example: filters=%7B%22comparator%22%3A%22equal%22%2C%22field%22%3A%7B%22api_name%22%3A%22to%22%7D%2C%22value%22%3A%222023-03-10T20%3A00%3A00%2B05%3A30%22%7D&include_inner_details=user.zuid
Sample Request:
{{api-domain}}/crm/v4/settings/users_unavailability?filters=%7B%22comparator%22%3A%22equal%22%2C%22field%22%3A%7B%22api_name%22%3A%22to%22%7D%2C%22value%22%3A%222023-03-10T20%3A00%3A00%2B05%3A30%22%7D&include_inner_details=user.zuid
Response:
{ "users_unavailability": [ { "comments": "Unavailable during this time. Please schedule a call later.", "service": "CRM", "tp_event_id": null, "all_day": false, "from": "2023-02-28T19:00:00+05:30", "id": "3652397000011056010", "to": "2023-03-10T20:00:00+05:30", "title": null, "user": { "name": "Patricia Boyle", "id": "36xxx17", "zuid": "6xxxxx8" }, "tp_calendar_id": null } ], "info": { "per_page": 200, "count": 1, "page": 1, "more_records": false } } |
We hope you found this post useful. Let us know your questions and feedback in the comment section, or write to us at support@zohocrm.com.
We will see you next week with another interesting post.
Cheers!