API reference

Employees

Endpoints and input schemas from the console's API registry.

GET /api/employees

List employees

Needs the people.directory or people.manage permission on the API key's role.

No request-body schema is supplied for this operation in the registry.

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off

POST /api/employees

Create a employee

Needs the people.manage permission on the API key's role.

JSON request schema
{
  "type": "object",
  "properties": {
    "fullName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "preferredName": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "workEmail": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "string",
              "format": "email",
              "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
            },
            {
              "type": "null"
            }
          ]
        },
        {
          "type": "string",
          "const": ""
        }
      ]
    },
    "phone": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50
        },
        {
          "type": "null"
        }
      ]
    },
    "position": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 150
        },
        {
          "type": "null"
        }
      ]
    },
    "departmentId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "managerId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "gradeId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "employmentType": {
      "type": "string",
      "enum": [
        "PERMANENT",
        "CONTRACT",
        "PART_TIME",
        "INTERN"
      ]
    },
    "joinDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "confirmationDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "resignDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "workState": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 10
        },
        {
          "type": "null"
        }
      ]
    },
    "gender": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "FEMALE",
            "MALE"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "RESIGNED",
        "TERMINATED"
      ]
    },
    "employeeNo": {
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "workWeek": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "fullName"
  ]
}

Documented responses

  • 200 — OK
  • 201 — Created
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off

GET /api/employees/{id}

Read a employee

Needs the people.directory or people.manage permission on the API key's role.

Path parameters

  • id — required path parameter

No request-body schema is supplied for this operation in the registry.

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off
  • 404 — Not found in this company

PATCH /api/employees/{id}

Change a employee

Needs the people.manage permission on the API key's role.

Path parameters

  • id — required path parameter
JSON request schema
{
  "type": "object",
  "properties": {
    "fullName": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "preferredName": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 100
        },
        {
          "type": "null"
        }
      ]
    },
    "workEmail": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "string",
              "format": "email",
              "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
            },
            {
              "type": "null"
            }
          ]
        },
        {
          "type": "string",
          "const": ""
        }
      ]
    },
    "phone": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 50
        },
        {
          "type": "null"
        }
      ]
    },
    "position": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 150
        },
        {
          "type": "null"
        }
      ]
    },
    "departmentId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "managerId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "gradeId": {
      "anyOf": [
        {
          "type": "string",
          "minLength": 1
        },
        {
          "type": "null"
        }
      ]
    },
    "employmentType": {
      "type": "string",
      "enum": [
        "PERMANENT",
        "CONTRACT",
        "PART_TIME",
        "INTERN"
      ]
    },
    "joinDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "confirmationDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "resignDate": {
      "anyOf": [
        {
          "type": "string",
          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
        },
        {
          "type": "null"
        }
      ]
    },
    "workState": {
      "anyOf": [
        {
          "type": "string",
          "maxLength": 10
        },
        {
          "type": "null"
        }
      ]
    },
    "gender": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "FEMALE",
            "MALE"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "RESIGNED",
        "TERMINATED"
      ]
    },
    "employeeNo": {
      "type": "string",
      "minLength": 1,
      "maxLength": 30
    },
    "workWeek": {
      "anyOf": [
        {},
        {
          "type": "null"
        }
      ]
    }
  }
}

Documented responses

  • 200 — OK
  • 400 — The body is not valid; `error` says why
  • 401 — No valid API key
  • 403 — The key's role lacks the permission, or the module is off
  • 404 — Not found in this company

Other policy and state errors may also apply. See API key permissions and limits and the complete OpenAPI document.