Work Location APIs
Your company's work location details can be added and managed under Organization > Work Location in Zoho Directory. You can use the APIs below to fetch, update, or delete this information. Each work location is assigned with a unique identifier.
End Points
Create a new work location
Get all work locations available in the organization
Update a work location's details
Get specific work location's details
Delete a work location
Set any existing work location as primary
Create a new work location
Creates a new work location in the given organization with the provided details. Information such as the name of the location, postal address, timezone, and language should be sent in the request payload to create a location.
OAuth Scope : ZohoDirectory.Orgs.CREATE
Arguments
location_name
string
Name provided for the work location.
street_address
string
Street address that is added to the work location.
city
string
Name of the city added to the work location.
state
string
Name of the state added to the work location.
postal_code
string
Postal code added to the corresponding work location.
country
string
Code of the country added to the work location. Eg., 'in' for India.
timezone
string
Timezone of the work location.
language
string
Code of the language added to the work location.
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
.url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations")
.post(body)
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "POST",
"hostname": "zohoapis.com",
"port": null,
"path": "/directory/api/v2/orgs/987000000654321/locations",
"headers": {
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();
import http.client
conn = http.client.HTTPSConnection("zohoapis.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("POST", "/directory/api/v2/orgs/987000000654321/locations", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request POST \
--url https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"locations": {
"location_name": "Work Location 1",
"street_address": "1xx, Dxxxxx xxxxx, xxxxxt",
"city": "Txxxxr",
"state": "Kxxxxa",
"postal_code": "9xxxx9",
"country": "in",
"timezone": "Etc/GMT+12",
"language": "en"
}
}
{
"status_code": 201,
"resource_name": "locations",
"message": "... //Successfully completed",
"locations": {
"location_id": ".....",
"href": "....."
}
}
{
"status_code": 400,
"error_code": "invalid_field_value",
"message": "If location_name is empty or invalid"
}
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "no_permission",
"message": "API is accessible to admins alone"
}
{
"status_code": 404,
"error_code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
Get all work locations available in the organization
Fetches all the locations and their details added to the organization in Zoho One. This includes the postal address given while adding the location, the ID of the location, and indication whether the location is set as primary or not.
OAuth Scope : ZohoDirectory.Orgs.READ
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations")
.get()
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "GET",
"hostname": "zohoapis.com",
"port": null,
"path": "/directory/api/v2/orgs/987000000654321/locations",
"headers": {
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("zohoapis.com")
headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }
conn.request("GET", "/directory/api/v2/orgs/987000000654321/locations", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request GET \
--url https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"status_code": 200,
"resource_name": "locations",
"locations": [
{
"street_address": "1xx, Dxxxxx xxxxx, xxxxxt",
"country": "in",
"location_name": "Work Location 1",
"is_primary": true,
"city": "Txxxxr",
"timezone": "Etc/GMT+12",
"language": "en",
"state": "Kxxxxa",
"postal_code": "9xxxx9",
"location_id": "1xxxxxx8"
},
{...},
{...}
]
}
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "no_permission",
"message": "API is accessible to admins only"
}
{
"status_code": 404,
"error_code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
Update a work location's details
Modify any existing work location with the required details.
OAuth Scope : ZohoDirectory.Orgs.UPDATE
Arguments
location_name
string
Name provided for the work location.
street_address
string
Street address that is added to the work location.
city
string
Name of the city added to the work location.
state
string
Name of the state added to the work location.
postal_code
string
Postal code added to the corresponding work location.
country
string
Code of the country added to the work location. Eg., 'in' for India.
timezone
string
Timezone of the work location.
language
string
Code of the language added to the work location.
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
location_id
string
(Required)
ID of the work location.
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
.url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8")
.put(body)
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "PUT",
"hostname": "zohoapis.com",
"port": null,
"path": "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8",
"headers": {
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();
import http.client
conn = http.client.HTTPSConnection("zohoapis.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("PUT", "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request PUT \
--url https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"locations": {
"location_name": "Work Location 1",
"street_address": "1xx, Dxxxxx xxxxx, xxxxxt",
"city": "Txxxxr",
"state": "Kxxxxa",
"postal_code": "9xxxx9",
"country": "in",
"timezone": "Etc/GMT+12",
"language": "en"
}
}
{
"status_code": 200,
"resource_name": "locations",
"message": "... //Successfully completed",
"locations": {
"location_id": ".....",
"href": "....."
}
}
{
"status_code": 400,
"error_code": "invalid_field_value",
"message": "If the updated location_name does not match the allowed pattern"
}
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "no_permission",
"message": "API is accessible to admins alone"
}
{
"status_code": 404,
"error_code": "invalid_identifier",
"message": "If the location is not found by the given location_id"
}
{
"status_code": 500,
"error_code": "general_error",
"message": "If an internal error occurs during IAM primary location update"
}
Get specific work location's details
Fetches given location's details added to the organization in Zoho One. This includes the postal address given while adding the location and indication whether the location is set as primary or not.
OAuth Scope : ZohoDirectory.Orgs.READ
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
location_id
string
(Required)
ID of the work location.
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8")
.get()
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "GET",
"hostname": "zohoapis.com",
"port": null,
"path": "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8",
"headers": {
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("zohoapis.com")
headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }
conn.request("GET", "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request GET \
--url https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"status_code": 200,
"resource_name": "locations",
"locations": {
"street_address": "1xx, Dxxxxx xxxxx, xxxxxt",
"country": "in",
"location_name": "Work Location 1",
"is_primary": true,
"city": "Txxxxr",
"timezone": "Etc/GMT+12",
"language": "en",
"state": "Kxxxxa",
"postal_code": "9xxxx9",
"location_id": "1xxxxxx8"
}
}
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "no_permission",
"message": "API is accessible to admins only"
}
{
"status_code": 404,
"error_code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
Delete a work location
Deletes the given work location from the relevant organization in Zoho One.
OAuth Scope : ZohoDirectory.Orgs.DELETE
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
location_id
string
(Required)
ID of the work location.
Query Parameters
force
boolean
If true, deletes the location even though users were assigned to it; The default value is false
update_and_delete
boolean
If true, reassigns users to the location specified by replace_field_id before deleting; The default value is false
replace_field_id
string
The location_id to reassign users to when update_and_delete is true
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8")
.delete(null)
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.build();
Response response = client.newCall(request).execute();
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8"
type: DELETE
headers: headers_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "DELETE",
"hostname": "zohoapis.com",
"port": null,
"path": "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8",
"headers": {
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("zohoapis.com")
headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }
conn.request("DELETE", "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request DELETE \
--url https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "no_permission",
"message": "API is accessible to admins alone"
}
{
"status_code": 404,
"error_code": "invalid_identifier",
"message": "If the location is not found by the given location_id"
}
{
"status_code": 405,
"error_code": "unsupported_operation",
"message": "If the location is published or drafted in Zoho Publish"
}
{
"status_code": 409,
"error_code": "resource_in_use",
"message": "If users are still assigned to the location and force is not set to true"
}
Set any existing work location as primary
Marks the given work location as the primary location.
OAuth Scope : ZohoDirectory.Orgs.UPDATE
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
location_id
string
(Required)
ID of the work location.
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
.url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8/primary")
.put(body)
.addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
.addHeader("content-type", "application/json")
.build();
Response response = client.newCall(request).execute();
parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8/primary"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "PUT",
"hostname": "zohoapis.com",
"port": null,
"path": "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8/primary",
"headers": {
"Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();
import http.client
conn = http.client.HTTPSConnection("zohoapis.com")
payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"
headers = {
'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
'content-type': "application/json"
}
conn.request("PUT", "/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8/primary", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request PUT \
--url https://zohoapis.com/directory/api/v2/orgs/987000000654321/locations/1xxxxxx8/primary \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"status_code": 200,
"resource_name": "locations",
"message": "... //Successfully completed",
"locations": {
"id": ".....",
"href": "....."
}
}
{
"status_code": 400,
"error_code": "invalid_field_value",
"message": "Invalid or missing field in request payload."
}
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "no_permission",
"message": "It is accessible to admins alone"
}
{
"status_code": 404,
"error_code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
{
"status_code": 405,
"error_code": "unsupported_operation",
"message": "If the existing location has invalid field value for street address and/or city and/or state and/or country and/or postal_code"
}