Designation APIs
Designations define employee job titles or official roles (e.g., Sales Manager, Support Agent). Properly assigning designations can help you simplify employee administration.
End Points
Create a new designation
Get all the designations in the organization
Rename a designation
Get specific designation's details
Delete a designation
Create a new designation
Creates a new designation for the given organization.
OAuth Scope : ZohoOne.Orgs.CREATE
Arguments
designation_name
string
Name of the designation.
users
array
User to whom the designation is to be assigned.
user_id
string
Represents the user id to whom you want to assign the designation
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/one/api/v2/orgs/987000000654321/designations")
.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/one/api/v2/orgs/987000000654321/designations"
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": "/one/api/v2/orgs/987000000654321/designations",
"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", "/one/api/v2/orgs/987000000654321/designations", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request POST \
--url https://zohoapis.com/one/api/v2/orgs/987000000654321/designations \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"designations": {
"designation_name": "DXXXXXXXr",
"users": [
{
"user_id": "2xxxxxxxxxxxxxxxx6"
}
]
}
}
{
"status_code": 201,
"resource_name": "designations",
"message": "... //Successfully completed",
"designations": {
"designation_id": ".....",
"href": "....."
}
}
{
"status_code": 400,
"error_code": "invalid_field_value",
"message": "If designation_name is not given/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."
}
{
"status_code": 409,
"error_code": "resource_already_exists",
"message": "Given designation name is already exists"
}
Get all the designations in the organization
Fetches all the designations available under the given organization ID.
OAuth Scope : ZohoOne.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/one/api/v2/orgs/987000000654321/designations")
.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/one/api/v2/orgs/987000000654321/designations"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "GET",
"hostname": "zohoapis.com",
"port": null,
"path": "/one/api/v2/orgs/987000000654321/designations",
"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", "/one/api/v2/orgs/987000000654321/designations", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request GET \
--url https://zohoapis.com/one/api/v2/orgs/987000000654321/designations \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"status_code": 200,
"resource_name": "designations",
"designations": [
{
"created_time": "2024-xx-14T14:57:42.617+0530",
"designation_name": "DXXXXXXXr",
"designation_id": "9xxxxxx4"
},
{...},
{...}
]
}
{
"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."
}
Rename a designation
Renames an existing designation with the given new name.
OAuth Scope : ZohoOne.Orgs.UPDATE
Arguments
designation_name
string
Name of the designation.
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
designation_id
string
(Required)
ID of the designation.
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/one/api/v2/orgs/987000000654321/designations/9xxxxxx4")
.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/one/api/v2/orgs/987000000654321/designations/9xxxxxx4"
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": "/one/api/v2/orgs/987000000654321/designations/9xxxxxx4",
"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", "/one/api/v2/orgs/987000000654321/designations/9xxxxxx4", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request PUT \
--url https://zohoapis.com/one/api/v2/orgs/987000000654321/designations/9xxxxxx4 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
--header 'content-type: application/json' \
--data '{"field1":"value1","field2":"value2"}'
{
"designations": {
"designation_name": "DXXXXXXXr"
}
}
{
"status_code": 200,
"resource_name": "designations",
"message": "... //Successfully completed",
"designations": {
"designation_id": ".....",
"href": "....."
}
}
{
"status_code": 400,
"error_code": "invalid_field_value",
"message": "If the given designation_name is invalid"
}
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "ACCESS_DENIED",
"message": "You do not have permission to perform this action."
}
{
"status_code": 404,
"error_code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
{
"status_code": 409,
"error_code": "resource_already_exists",
"message": "If the given designation_name is already exists"
}
{
"status_code": 500,
"error_code": "general_error",
"message": "If an internal server error occurs during designation creation"
}
Get specific designation's details
Fetches the given designation's details such as it's creation time, name and ID.
OAuth Scope : ZohoOne.Orgs.READ
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
designation_id
string
(Required)
ID of the designation.
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://zohoapis.com/one/api/v2/orgs/987000000654321/designations/9xxxxxx4")
.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/one/api/v2/orgs/987000000654321/designations/9xxxxxx4"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "GET",
"hostname": "zohoapis.com",
"port": null,
"path": "/one/api/v2/orgs/987000000654321/designations/9xxxxxx4",
"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", "/one/api/v2/orgs/987000000654321/designations/9xxxxxx4", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request GET \
--url https://zohoapis.com/one/api/v2/orgs/987000000654321/designations/9xxxxxx4 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"status_code": 200,
"resource_name": "designations",
"designations": {
"created_time": "2024-xx-14T14:57:42.617+0530",
"designation_name": "DXXXXXXXr",
"designation_id": "9xxxxxx4"
}
}
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "ACCESS_DENIED",
"message": "You do not have permission to perform this action."
}
{
"status_code": 404,
"error_code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
Delete a designation
Deletes the given designation from the organization.
OAuth Scope : ZohoOne.Orgs.DELETE
Path Parameters
org_id
string
(Required)
The unique identifier of the org.
designation_id
string
(Required)
ID of the designation.
Query Parameters
force
boolean
If true, deletes a designation even though users were assigned to it; The default value is false
update_and_delete
boolean
If true, reassigns users to the designation specified by replace_field_id before deleting; The default value is false
replace_field_id
string
The designation_id to reassign users to when update_and_delete is true
OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
.url("https://zohoapis.com/one/api/v2/orgs/987000000654321/designations/9xxxxxx4")
.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/one/api/v2/orgs/987000000654321/designations/9xxxxxx4"
type: DELETE
headers: headers_data
connection: <connection_name>
];
info response;
const http = require("https");
const options = {
"method": "DELETE",
"hostname": "zohoapis.com",
"port": null,
"path": "/one/api/v2/orgs/987000000654321/designations/9xxxxxx4",
"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", "/one/api/v2/orgs/987000000654321/designations/9xxxxxx4", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
curl --request DELETE \
--url https://zohoapis.com/one/api/v2/orgs/987000000654321/designations/9xxxxxx4 \
--header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
{
"status_code": 401,
"error_code": "INVALID_TOKEN",
"message": "Authentication required."
}
{
"status_code": 403,
"error_code": "ACCESS_DENIED",
"message": "You do not have permission to perform this action."
}
{
"status_code": 404,
"error_code": "RESOURCE_NOT_FOUND",
"message": "The requested resource was not found."
}
{
"status_code": 409,
"error_code": "resource_in_use",
"message": "If users are still assigned to the designation and force is not set to true"
}