> ## Documentation Index > Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt > Use this file to discover all available pages before exploring further. # List Employees > Returns employees of the key's tenant, newest first. Draft (CREATED) and deleted employees are never returned. Related objects are included only when requested via `expand`. Required scope: employees:read Error Codes: - INTEGRATION.API_KEY_INVALID: The API key is missing, inactive, expired, or unknown. - DEVELOPER.SCOPE_INSUFFICIENT: The key lacks the employees:read scope. - INVALID_ARGUMENT: An unknown filter/expand value or a malformed page_token. ## OpenAPI ````yaml /api-reference/openapi.yaml get /developer/v1/employees openapi: 3.0.3 info: description: >- Публичный Developer API Doodocs People. Аутентификация — заголовок X-API-Key. title: Doodocs People API version: 1.0.0 servers: - description: Production url: https://app.doodocs.kz/api security: - ApiKeyAuth: [] tags: - description: ApiKeyService exposes Developer API key utilities. name: ApiKeyService - description: >- DocumentService is the public Developer API for documents: reading, creating, downloading, routing, and signing. Authentication: X-API-Key. Every call runs as the key's owner within the key's tenant — the owner's document permissions decide what is visible and which actions are allowed, exactly as they would in the web app. Fields that carry personal data of other participants (names, IIN, positions) are never exposed; participants are identified by id only. Typical flow: discover a template with ListDocumentTemplates / GetDocumentTemplate (to learn its variable_schema), create a draft with CreateDocument, set its route with SetDocumentRoute, launch it with SendDocument, then apply signatures with SignDocument as slots become active. To circulate a document produced elsewhere, upload it with FileService and pass the confirmed file_id to CreateDocument instead of a template. name: DocumentService - description: |- EmployeeService is the public Developer API for reading employees. Authentication: X-API-Key. The key's tenant and the key owner's data scope determine which employees and fields are visible; sensitive fields the caller may not view are omitted and listed in `redacted_fields`. name: EmployeeService - description: |- FileService uploads the files documents are created from. Authentication: X-API-Key. An upload belongs to the key's owner, and only their key can attach it to a document. Flow: CreateFileUpload reserves the file and returns a presigned POST form, the client sends the bytes straight to storage, ConfirmFileUpload marks the upload complete, and CreateDocument attaches it by id. name: FileService - description: IngestService accepts batches of external records into the tenant. name: IngestService - name: LoginService - description: |- WebhookService lets a tenant manage subscriptions to Developer API events. Authentication: X-API-Key with the webhooks:manage scope. name: WebhookService paths: /developer/v1/employees: get: tags: - EmployeeService summary: List Employees description: |- Returns employees of the key's tenant, newest first. Draft (CREATED) and deleted employees are never returned. Related objects are included only when requested via `expand`. Required scope: employees:read Error Codes: - INTEGRATION.API_KEY_INVALID: The API key is missing, inactive, expired, or unknown. - DEVELOPER.SCOPE_INSUFFICIENT: The key lacks the employees:read scope. - INVALID_ARGUMENT: An unknown filter/expand value or a malformed page_token. operationId: EmployeeService_ListEmployees parameters: - description: Maximum employees to return. Default 100, capped at 1000. in: query name: limit schema: format: int32 type: integer - description: >- Opaque continuation token from a previous response. Bound to the filter set; reusing it with different filters is rejected with INVALID_ARGUMENT. in: query name: page_token schema: type: string - description: >- Restrict to these statuses (repeat the parameter for multiple values). in: query name: status schema: items: enum: - EMPLOYEE_STATUS_UNSPECIFIED - EMPLOYEE_STATUS_HIRED - EMPLOYEE_STATUS_ACCEPTED - EMPLOYEE_STATUS_ONBOARDING - EMPLOYEE_STATUS_ACTIVE - EMPLOYEE_STATUS_TERMINATED - EMPLOYEE_STATUS_LEAVE - EMPLOYEE_STATUS_ON_HOLD format: enum type: string type: array - description: Restrict to these department ids (repeat for multiple values). in: query name: department_id schema: items: type: string type: array - description: >- Only employees whose card changed at or after this instant. Does not cover renames of related objects (person, department) or hierarchy moves. in: query name: updated_since schema: format: date-time type: string - description: 'Related objects to include: person, department, job_title, manager.' in: query name: expand schema: items: type: string type: array - description: >- Compute total_count. Off by default because it adds a COUNT per page and is only an estimate above ~10k rows. in: query name: include_total schema: type: boolean responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListEmployeesResponse' description: OK default: content: application/json: schema: $ref: '#/components/schemas/Status' description: Default error response components: schemas: ListEmployeesResponse: properties: employees: description: The page of employees, newest first. items: $ref: '#/components/schemas/Employee' readOnly: true type: array next_page_token: description: >- Continuation token for the next page; empty when there are no more results. readOnly: true type: string total_count: description: |- Total matching employees; present only when include_total was set. Approximate above ~10k rows. readOnly: true type: string type: object Status: description: >- The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). properties: code: description: >- The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code]. format: int32 type: integer details: description: >- A list of messages that carry the error details. There is a common set of message types for APIs to use. items: $ref: '#/components/schemas/GoogleProtobufAny' type: array message: description: >- A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client. type: string type: object Employee: description: >- Employee is the public projection of an employment record. Personal identity lives on `person`, populated only via expand. properties: create_time: description: When the employee record was created. format: date-time readOnly: true type: string department: allOf: - $ref: '#/components/schemas/DepartmentRef' description: Populated only with expand=department. readOnly: true department_id: description: Department the employee belongs to; expand=department for its title. readOnly: true type: string employee_number: description: Personnel number («табельный номер»); empty when not assigned. readOnly: true type: string end_date: description: >- Last day of employment, YYYY-MM-DD; empty until the employee is terminated. readOnly: true type: string id: description: Employee id (UUID), stable within the tenant. readOnly: true type: string job_title: allOf: - $ref: '#/components/schemas/JobTitleRef' description: Populated only with expand=job_title. readOnly: true job_title_id: description: Job title (position); expand=job_title for its title. readOnly: true type: string location_id: description: Work location; empty when not assigned. readOnly: true type: string manager: allOf: - $ref: '#/components/schemas/ManagerRef' description: Populated only with expand=manager. readOnly: true manager_id: description: Direct manager's employee id; expand=manager for their name. readOnly: true type: string organization_id: description: Legal entity the employee is employed by. readOnly: true type: string person: allOf: - $ref: '#/components/schemas/Person' description: The person's identity; populated only with expand=person. readOnly: true redacted_fields: description: >- Field keys (object.field, e.g. "persons.iin") the caller may not view and that were therefore omitted from this response. items: type: string readOnly: true type: array start_date: description: First day of employment, YYYY-MM-DD (empty when unset). readOnly: true type: string status: description: Employment lifecycle state. enum: - EMPLOYEE_STATUS_UNSPECIFIED - EMPLOYEE_STATUS_HIRED - EMPLOYEE_STATUS_ACCEPTED - EMPLOYEE_STATUS_ONBOARDING - EMPLOYEE_STATUS_ACTIVE - EMPLOYEE_STATUS_TERMINATED - EMPLOYEE_STATUS_LEAVE - EMPLOYEE_STATUS_ON_HOLD format: enum readOnly: true type: string update_time: description: When the record last changed; drives the updated_since filter. format: date-time readOnly: true type: string work_email: description: Corporate email address. readOnly: true type: string type: object GoogleProtobufAny: additionalProperties: true description: >- Contains an arbitrary serialized message along with a @type that describes the type of the serialized message. properties: '@type': description: The type of the serialized message. type: string type: object DepartmentRef: description: DepartmentRef is a minimal department reference. properties: id: description: Department id (UUID). readOnly: true type: string title: description: Department name. readOnly: true type: string type: object JobTitleRef: description: JobTitleRef is a minimal job-title reference. properties: id: description: Job title id (UUID). readOnly: true type: string title: description: Job title name. readOnly: true type: string type: object ManagerRef: description: >- ManagerRef is a deliberately narrow view of the manager: identity only, no nested person and no employment detail. The manager row is fetched UNSCOPED and UNREDACTED (redaction only covers the primary record + its person), so expand=manager must not project any field beyond id + display name — anything else (employee_number, job_title_id, department_id) leaks an out-of-scope record's attributes. properties: full_name: description: The manager's display name. readOnly: true type: string id: description: >- The manager's employee id; fetch their full profile with GetEmployee. readOnly: true type: string type: object Person: description: Person is the identity of the human behind the employee record. properties: birth_date: description: Date of birth, YYYY-MM-DD. readOnly: true type: string first_name: description: Given name. readOnly: true type: string full_name: description: Ready-to-display full name. readOnly: true type: string iin: description: |- National identification number (ИИН). Omitted and listed in redacted_fields when the key owner may not view it. readOnly: true type: string last_name: description: Family name. readOnly: true type: string middle_name: description: Patronymic; empty when absent. readOnly: true type: string personal_email: description: Personal email address. readOnly: true type: string phone: description: Personal phone number. readOnly: true type: string type: object securitySchemes: ApiKeyAuth: in: header name: X-API-Key type: apiKey ````