Update Territory of a User

Purpose

To update the start/end date/time of a territory assigned to an user.

Request URL

https://fsm.zoho.com/fsm/v1/users/<user_id>/Territories

user_id - The ID (the value of User in the Service_Resources key present in the List Users API response) of the user.

Request Method

PUT

Scope

scope=ZohoFSM.users.UPDATE

Input JSON Keys

Name	Description	Type
Territory (mandatory)	The ID of the territory you want to assign to the user.	JSON Object
Start_Date_Time (mandatory)	The date/time from which you want the user to be active/available in this territory. The value must be in the ISO format YYYY-MM-DDThh:mm:ssTZD.	DateTime
End_Date_Time	The date/time after which you want the user to be inactive/unavailable in this territory. The value must be in the ISO format YYYY-MM-DDThh:mm:ssTZD	DateTime
id (mandatory)	The ID of the territory entry you want to update. Refer to this API doc to get this ID.	String

Sample Request

Copiedcurl --request PUT 'https://fsm.zoho.com/fsm/v1/users/6191XXXX7001/Territories' \
--header 'Authorization: Zoho-oauthtoken 1000.26xxxxxxxxxx.xxxxxxxxxx0' \
--header 'content-type: application/json' \
--data "{"field1":"value1","field2":"value2"}"

Sample Input

Copied{
    "data": [
        {
            "Territory": {
                "id": "6191000000371233"
            },
            "Start_Date_Time": "2023-12-31T23:00:00-06:00",
            "End_Date_Time": "2024-07-22T15:00:00-06:00",
            "id": "6191000000371238"
        }
    ]
}

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "Modified_Time": "2024-07-22T02:40:07-05:00",
                "Modified_By": {
                    "name": "Alicia Florrick",
                    "id": "6191000000227001"
                },
                "Created_Time": "2023-10-05T02:34:06-05:00",
                "id": "6191000000227298",
                "Created_By": {
                    "name": "Alicia Florrick",
                    "id": "6191000000227001"
                }
            },
            "message": "record updated",
            "status": "success"
        }
    ]
}

Sample Error Response

Copied//The ID of the territory related record you have used does not belong to the territory whose details you are trying to update.
{
    "data": [
        {
            "code": "INVALID_DATA",
            "details": {
                "module": "Territories"
            },
            "message": "Territory change is not allowed once added."
        }
    ]
}

Sample Error Response

Copied//You cannot change the start/end date/time of the territory such that active service appointments assigned to the user in this territory fall outside the active period (start date/time - end date/time) of the user in the territory.
{
    "data": [
        {
            "code": "INVALID_DATA",
            "details": {
                "module": "Service_Resource_X_Territory",
                "info": {
                    "Crew": {},
                    "Territory": {},
                    "Service_Appointments": [
                        {
                            "Service_Appointment": {
                                "Scheduled_End_Date_Time": "2024-06-11T04:00:00-05:00",
                                "Territory": {
                                    "id": "6191000000227288"
                                },
                                "Actual_Start_Date_Time": "2024-06-11T02:47:32-05:00",
                                "id": "6191000000592080",
                                "Scheduled_Start_Date_Time": "2024-06-11T03:00:00-05:00",
                                "Actual_End_Date_Time": null,
                                "Name": "AP-411"
                            },
                            "id": "6191000000592089",
                            "Service_Resource": {
                                "id": "6191000000227293"
                            }
                        }
                    ]
                }
            },
            "message": "Service resource has active service appointment at requested time "
        }
    ]
}

Sample Error Response

Copied//The End_Date_Time provided is before the Start_Date_Time
{
    "data": [
        {
            "code": "INVALID_DATA",
            "details": {},
            "message": "End Date Time must be after Start Date Time",
            "status": "error"
        }
    ]
}