For AI agents: markdown of this page — /docs-content-en/workday/work-reports/subordinates.md documentation index — /llms.txt

Subordinate work reports

GET /v1/workday/work-reports/subordinates

Returns the submitted work reports of the credential owner and of the employees whose time records the owner can read. Useful for a manager reviewing the team's reports.

Requires the timeman scope and the credential owner's Bitrix24 right to read the time records of subordinates or of all employees. With the right to read the time records of all employees, the reports of the whole company are returned. READONLY keys can read reports.

Parameters

Parameter Type Required Default Description
ParameteruserId (query) Typeinteger Requiredno Default— DescriptionEmployee ID — return only this employee's reports. List: GET /v1/users
ParameteruserIds (query) Typestring Requiredno Default— DescriptionComma-separated employee IDs, for example 103,105. If userId is also passed, the reports of all listed employees are returned. List: GET /v1/users
ParameteractiveOnly (query) Typeboolean Requiredno Default— DescriptionAccepted but does not change the result: only submitted reports are returned
ParameterdateFrom (query) Typestring Requiredno Default— DescriptionPeriod start in ISO 8601 format with a time zone. Reports whose period overlaps the given one are returned; the boundaries are inclusive
ParameterdateTo (query) Typestring Requiredno Default— DescriptionPeriod end in the same format
Parameterlimit (query) Typeinteger Requiredno Default5 DescriptionHow many employees to return, from 1 to 50
Parameteroffset (query) Typeinteger Requiredno Default0 DescriptionHow many employees to skip. Cannot be combined with page
Parameterpage (query) Typeinteger Requiredno Default1 DescriptionPage number, with limit employees per page. Cannot be combined with offset

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/work-reports/subordinates?userIds=103,105" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/workday/work-reports/subordinates?userIds=103,105" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/work-reports/subordinates?userIds=103,105', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})
const { data, meta } = await res.json()

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/workday/work-reports/subordinates?userIds=103,105', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})
const { data, meta } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean Descriptiontrue when the request succeeds
Fielddata Typearray DescriptionEmployees with submitted reports. An employee without matching reports is not included. The credential owner comes first if they have matching reports
Fielddata[].userId Typeinteger DescriptionEmployee ID. List: GET /v1/users
Fielddata[].user Typeobject | null DescriptionThe employee
Fielddata[].user.id Typeinteger DescriptionEmployee ID, the same as userId
Fielddata[].user.name Typestring DescriptionEmployee's first and last name
Fielddata[].user.photo Typestring | null DescriptionProfile photo URL
Fielddata[].reports Typearray DescriptionThe employee's submitted reports in descending id order. For the report structure, see Report fields
Fieldmeta.offset Typeinteger DescriptionHow many employees were skipped
Fieldmeta.limit Typeinteger DescriptionHow many employees fit on a page
Fieldmeta.hasMore Typeboolean Descriptiontrue if more employees follow this page
Fieldmeta.nextOffset Typeinteger | null DescriptionThe offset value for the next page, or null if there are no more pages
Fieldmeta.paginationUnit Typestring DescriptionAlways users: limit and offset count employees, not reports

Response example

The main report fields are shown. For the full list, see Report fields:

JSON 
{
  "success": true,
  "data": [
    {
      "userId": 103,
      "user": {
        "id": 103,
        "name": "Anna Smith",
        "photo": null
      },
      "reports": [
        {
          "id": 79,
          "userId": 103,
          "active": true,
          "reportType": "week",
          "reportDate": "2023-03-02T10:39:37.000Z",
          "dateFrom": "2023-01-15T21:00:00.000Z",
          "dateTo": "2023-01-21T21:00:00.000Z",
          "report": "Hi :)",
          "type": "REPORT",
          "mark": "G",
          "approve": "Y"
        }
      ]
    },
    {
      "userId": 105,
      "user": {
        "id": 105,
        "name": "John Brown",
        "photo": null
      },
      "reports": [
        {
          "id": 115,
          "userId": 105,
          "active": true,
          "reportType": "week",
          "reportDate": "2024-02-14T11:34:24.000Z",
          "dateFrom": "2024-02-04T21:00:00.000Z",
          "dateTo": "2024-02-10T21:00:00.000Z",
          "report": "",
          "type": "REPORT",
          "mark": "X",
          "approve": "N"
        },
        {
          "id": 111,
          "userId": 105,
          "active": true,
          "reportType": "week",
          "reportDate": "2024-01-26T14:20:50.000Z",
          "dateFrom": "2024-01-21T21:00:00.000Z",
          "dateTo": "2024-01-27T21:00:00.000Z",
          "report": "",
          "type": "REPORT",
          "mark": "X",
          "approve": "N"
        }
      ]
    }
  ],
  "meta": {
    "offset": 0,
    "limit": 5,
    "hasMore": false,
    "nextOffset": null,
    "paginationUnit": "users"
  }
}

Error response example

400 — limit is greater than 50:

JSON 
{
  "success": false,
  "error": {
    "code": "WORKDAY_REPORT_LIMIT_EXCEEDED",
    "message": "Report list limit must be between 1 and 50"
  }
}

Errors

HTTP Code Description
HTTP400 CodeWORKDAY_REPORT_LIMIT_EXCEEDED Descriptionlimit is greater than 50
HTTP400 CodeINVALID_PARAMS DescriptionuserId, limit, or page is not a positive integer; userIds is not a comma-separated list of positive integers; offset is not a non-negative integer; offset and page were passed together; activeOnly is not true, false, 1, or 0; a date has no time zone, does not exist, or is not later than 1970-01-01T00:00:00Z; an unknown parameter is passed, such as order or select; a parameter is passed twice
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionThe credential owner lacks the right to read the time records of subordinates or of all employees
HTTP409 CodeTIMEMAN_MODULE_NOT_ENABLED DescriptionTime Management is not available on this portal
HTTP422 CodeBITRIX_ERROR DescriptionBitrix24 refused the operation
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable or returned a response of an unexpected shape
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionAn app key was sent without a session token in Authorization: Bearer
HTTP401 CodeINVALID_SESSION DescriptionThe session token is invalid or has expired
HTTP403 CodeSCOPE_DENIED DescriptionThe key lacks the timeman scope
HTTP429 CodeRATE_LIMITED DescriptionThe report read limit (30 requests per minute per key–user pair) or the general request limit was exceeded. The effective report read limit is in the x-ratelimit-limit header

For the full list of common API errors, see Errors.

See also