Get Department Details

Get the basic node information for a specified department.

API information

Item	Description
API name	Get Department Details
Permission scope	contact.department.read(read organization structure)
HTTP method	POST / GET
Endpoint	https://{gateway_host}/open/v1/contact/department/get
Data format	application/json(for POST) or URL query
Authentication	App-level access_token(requires contact.department.read permission)

Prerequisites

1. The app has been published and enabled under "Internal Apps" in the admin console.
2. A valid app-level access_token has been obtained.
3. The department must be within the app's visibility scope.

Request parameters

Header

Header	Required	Description
Authorization	No	Bearer <access_token>，recommended credential transport method; choose it instead of query or form authentication
Content-Type	No	Send application/json when a POST request uses JSON

Parameter list

Parameters may be sent in a POST JSON body, POST form, or GET query:

Parameter	Type	Required	Description
access_token	string	Yes	App-level token（if it is not sent in the Authorization header, it is required)
dept_id	string	Yes	Department ID (a positive integer string). The system also accepts aliases deptId, departmentId, department_id
language	string	No	Reserved localization parameter; it currently does not affect the response

Note: When the enterprise department tree has only one root node, dept_id="1" is automatically mapped to that root department.

Request examples

POST Request examples：

POST https://{gateway_host}/open/v1/contact/department/get
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "dept_id": "20"
}

GET Request examples：

GET https://{gateway_host}/open/v1/contact/department/get?dept_id=20
Authorization: Bearer <access_token>

Response parameters

Successful response (the platform's unified response envelope):

{
  "code": 200,
  "msg": "",
  "data": {
    "deptId": "20",
    "name": "R&D department",
    "parentId": "10",
    "order": 1
  }
}

Field	Type	Description
code	integer	Business status code; 200 indicates success
msg	string	Message; empty on success
data.deptId	string	Department ID as a string
data.name	string	Department name
data.parentId	string	Parent department ID. When the parent is outside the app's visibility scope, the value is truncated upward to "0", making this department a top-level node in the visible tree
data.order	integer	Display sort weight under the parent department

Permissions and visibility filtering

1. Visibility-scope check: If the department does not exist, has been deleted, or is outside the app's authorized visibility scope, the API returns DEPARTMENT_NOT_FOUND without exposing unauthorized enterprise structure.
2. Virtual root adaptation: If the app is authorized for only a branch, parentId appears as "0" when that department is queried, allowing the client to build a traversable local tree.

Error codes

Authentication and middleware errors (HTTP status)

HTTP status	msg Error code	Description
401	INVALID_TOKEN	The token is missing, expired, revoked, or the app is unavailable
403	SCOPE_DENIED	The token lacks contact.department.read permission
403	IP_DENIED	The source IP is not in the IP allowlist configured in the app security settings

Business errors (HTTP 200, code=500)

{
  "code": 500,
  "msg": "DEPARTMENT_NOT_FOUND",
  "data": null
}

msg error code	Description and troubleshooting guidance
INVALID_REQUEST	Parameter dept_id is missing, empty, or not a valid positive integer string
DEPARTMENT_NOT_FOUND	The department does not exist, has been deleted, or is outside the app's authorized visibility scope
PERMISSION_DENIED	The app state is invalid (disabled, unpublished, or deleted)
SERVER_ERROR	Internal server error; retry later

Multilingual call examples

The following examples run on the server; never send app secrets or app tokens to a client.

Shell

curl -sS -X POST "https://{gateway_host}/open/v1/contact/department/get" \
  -H "Authorization: Bearer access-token-xxx" \\\n  -H "Content-Type: application/json" \
  -d '{"dept_id":"20"}'

PHP

<?php
// Production code should check the HTTP status and response body before mapping business errors.
$handle = curl_init('https://{gateway_host}/open/v1/contact/department/get');
curl_setopt_array($handle, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer access-token-xxx', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"dept_id":"20"}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($handle);
curl_close($handle);

Golang

package main

import (
    "bytes"
    "net/http"
)

func main() {
    // Use the token only in a server-side request and follow the API transport contract.
    request, _ := http.NewRequest(http.MethodPost, "https://{gateway_host}/open/v1/contact/department/get", bytes.NewBufferString(`{"dept_id":"20"}`))
    request.Header.Set("Authorization", "Bearer access-token-xxx")
    request.Header.Set("Content-Type", "application/json")
    response, _ := http.DefaultClient.Do(request)
    defer response.Body.Close()
}

C++

#include <curl/curl.h>

int main() {
    // Enable TLS verification and handle HTTP errors in production.
    CURL* handle = curl_easy_init();
    struct curl_slist* headers = nullptr;
    headers = curl_slist_append(headers, "Authorization: Bearer access-token-xxx");
    headers = curl_slist_append(headers, "Content-Type: application/json");
    curl_easy_setopt(handle, CURLOPT_URL, "https://{gateway_host}/open/v1/contact/department/get");
    curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "POST");
    curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers);
    curl_easy_setopt(handle, CURLOPT_POSTFIELDS, R"({"dept_id":"20"})");
    const CURLcode result = curl_easy_perform(handle);
    curl_slist_free_all(headers);
    curl_easy_cleanup(handle);
    return result == CURLE_OK ? 0 : 1;
}