Designation APIs

All designations available in your organization can be added and managed under Organization > Designations in Zoho Directory. This enables you to track and manage employees under each designation. Each designation is assigned with a unique identifier.

End Points

POST

/orgs/{org_id}/designations

GET

/orgs/{org_id}/designations

PUT

/orgs/{org_id}/designations/{designation_id}

GET

/orgs/{org_id}/designations/{designation_id}

DELETE

/orgs/{org_id}/designations/{designation_id}

Create a new designation

Creates a new designation for the given organization.
OAuth Scope : ZohoDirectory.Orgs.CREATE

Arguments

designation_name

string

Name of the designation.

users

array

User to whom the designation is to be assigned.

Show Sub-Attributes

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.

Request Example

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/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/directory/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": "/directory/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", "/directory/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/directory/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"
            }
        ]
    }
}

Response Example

{
    "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 : ZohoDirectory.Orgs.READ

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/directory/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/directory/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": "/directory/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", "/directory/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/directory/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 : ZohoDirectory.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.

Request Example

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/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/directory/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": "/directory/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", "/directory/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/directory/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"
    }
}

Response Example

{
    "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 : ZohoDirectory.Orgs.READ

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

designation_id

string

(Required)

ID of the designation.

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/directory/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/directory/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": "/directory/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", "/directory/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/directory/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 : ZohoDirectory.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

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/directory/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/directory/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": "/directory/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", "/directory/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/directory/api/v2/orgs/987000000654321/designations/9xxxxxx4 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

Response Example

{
    "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"
}