Positions

curl --location 'https://api.exode.biz/saas/v2/staff/position/list?take=10&page=1&search=Backend' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Authorization: Bearer YOUR_TOKEN'

const axios = require('axios');

async function getPositionList() {
  const { data } = await axios.get(
    'https://api.exode.biz/saas/v2/staff/position/list',
    {
      params: {
        take: 10,
        page: 1,
        search: 'Backend',
      },
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

getPositionList();

{
  "success": true,
  "code": 200,
  "payload": {
    "page": 1,
    "count": 2,
    "pages": 1,
    "isFirst": true,
    "isLast": true,
    "items": [
      {
        "id": 4,
        "createdAt": "2026-07-02T11:15:47.216Z",
        "updatedAt": "2026-07-02T11:15:47.260Z",
        "archivedAt": null,
        "schoolId": 198,
        "name": "Staff Backend Engineer",
        "extId": "e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47"
      },
      {
        "id": 3,
        "createdAt": "2026-07-02T11:15:47.207Z",
        "updatedAt": "2026-07-02T11:15:47.207Z",
        "archivedAt": null,
        "schoolId": 198,
        "name": "Backend Engineer",
        "extId": null
      }
    ],
    "next": {
      "skip": 0,
      "take": 10,
      "page": 1
    },
    "prev": {
      "skip": 0,
      "take": 10,
      "page": 1
    }
  }
}

curl --location 'https://api.exode.biz/saas/v2/staff/position/list?take=10&page=1&search=Backend' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Authorization: Bearer YOUR_TOKEN'

const axios = require('axios');

async function getPositionList() {
  const { data } = await axios.get(
    'https://api.exode.biz/saas/v2/staff/position/list',
    {
      params: {
        take: 10,
        page: 1,
        search: 'Backend',
      },
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

getPositionList();

{
  "success": true,
  "code": 200,
  "payload": {
    "page": 1,
    "count": 2,
    "pages": 1,
    "isFirst": true,
    "isLast": true,
    "items": [
      {
        "id": 4,
        "createdAt": "2026-07-02T11:15:47.216Z",
        "updatedAt": "2026-07-02T11:15:47.260Z",
        "archivedAt": null,
        "schoolId": 198,
        "name": "Staff Backend Engineer",
        "extId": "e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47"
      },
      {
        "id": 3,
        "createdAt": "2026-07-02T11:15:47.207Z",
        "updatedAt": "2026-07-02T11:15:47.207Z",
        "archivedAt": null,
        "schoolId": 198,
        "name": "Backend Engineer",
        "extId": null
      }
    ],
    "next": {
      "skip": 0,
      "take": 10,
      "page": 1
    },
    "prev": {
      "skip": 0,
      "take": 10,
      "page": 1
    }
  }
}

Request headers

string

required

The service user’s API token in the Bearer YOUR_TOKEN format. The school owner issues the token in the admin panel: Manage → School → For developers → API keys — see the “Authentication” section for details.

integer

required

The numeric ID of the seller — the account the school belongs to. Copy it on the API keys page, in the Integration data → Identifiers card. The token’s permissions are checked against this ID.

integer

required

The numeric ID of the school, found in the same place as Seller-Id. The value must match the seller’s school — otherwise a 400 error with cause: "ForbiddenSchoolMismatch" is returned.

Positions are a directory of job titles for school employees (for example, “Backend Engineer”). Positions are assigned to employees on hiring and promotion and are used by the staff module to describe the employment structure.

All staff module endpoints are available only to schools in the corporate segment (Corporate). Requests from schools in other segments are rejected.

Permission requirements

Reading (list) requires the “Staff browsing” permission (StaffView). Creating, updating and deleting require the “Staff Management” permission (StaffManage). In all cases, token authentication is required and the school must belong to the Corporate segment.

The service user must be authenticated with a token and have the appropriate access rights to the specified school.

A position name is unique within the school, case-insensitive (“Manager” and “manager” are the same name). Creating a position with, or renaming a position to, a name that already exists in the same school returns the StaffPositionNameIsNotUniq error.

The extId field is the position’s external ID from the client’s system (CRM/1C, for example a GUID). It is unique within the school among non-deleted records (unique index school + extId). 1 to 50 characters, cannot contain / or whitespace characters, because the value is used in ext/{extId} paths.

Linking to departments and grades

A position can be limited to a list of departments and a list of grades. Both links are optional: positions can be created without them, this affects nothing, and they can be linked later.

departmentIds — the departments where the position is available. Not passed or an empty array — the position is common to the whole school (shown as “All departments” in the UI). When the link is set, an employee cannot be hired, promoted or transferred to this position in another department — StaffPositionNotInDepartment is returned (see employments).
gradeIds — the grades that can be given to an employee in this position. Not passed or an empty array — any grade of the school fits.

The array replaces the whole list: to add a department, pass the full new list. [] removes the link, and a field omitted on update keeps the link unchanged. Pass the internal IDs of departments and grades (not extId): a department ID by its extId is available via department/list?extIds=.... The links are not returned in the position response — position/list?departmentId={id} returns the positions of a department.

If the school has an org-structure source app connected (for example, the Verifix integration), positions with an extId are managed by it: creating a position with an extId, changing the name or extId of such a position and deleting it via the API return the MiniappInstallationManagedEntity error. The links to departments and grades (departmentIds, gradeIds) can still be changed.

List positions

GET /saas/v2/staff/position/list

Requires authentication and the “Staff browsing” permission (StaffView).

The endpoint returns a paginated list of positions. Pagination and filter parameters are passed as query parameters.

Parameters

integer

Number of records to skip (offset pagination). Minimum 0.

integer

Number of records to return per page. From 1 to 1000.

integer

Page number (an alternative to skip). Minimum 1.

integer[]

Filter by position IDs. Up to 250 values.

string

Search by position name. Maximum 50 characters. The search is fuzzy (it also finds partial matches), so to find a specific position by name, compare the name of the returned records with your value case-insensitively, or, more reliably, search by extIds.

string[]

Filter by a list of external IDs (extId). Up to 250 values, each up to 50 characters.

integer

Positions available in the department: the ones linked to it and the ones common to the whole school (with no department link).

enum

Sort direction by creation date. Possible values: ASC, DESC. The id and updatedAt parameters work the same way.

Response

object

required

Paginated object: items (array of positions), page, count, pages, isFirst, isLast, next, prev.

curl --location 'https://api.exode.biz/saas/v2/staff/position/list?take=10&page=1&search=Backend' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Authorization: Bearer YOUR_TOKEN'

const axios = require('axios');

async function getPositionList() {
  const { data } = await axios.get(
    'https://api.exode.biz/saas/v2/staff/position/list',
    {
      params: {
        take: 10,
        page: 1,
        search: 'Backend',
      },
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

getPositionList();

{
  "success": true,
  "code": 200,
  "payload": {
    "page": 1,
    "count": 2,
    "pages": 1,
    "isFirst": true,
    "isLast": true,
    "items": [
      {
        "id": 4,
        "createdAt": "2026-07-02T11:15:47.216Z",
        "updatedAt": "2026-07-02T11:15:47.260Z",
        "archivedAt": null,
        "schoolId": 198,
        "name": "Staff Backend Engineer",
        "extId": "e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47"
      },
      {
        "id": 3,
        "createdAt": "2026-07-02T11:15:47.207Z",
        "updatedAt": "2026-07-02T11:15:47.207Z",
        "archivedAt": null,
        "schoolId": 198,
        "name": "Backend Engineer",
        "extId": null
      }
    ],
    "next": {
      "skip": 0,
      "take": 10,
      "page": 1
    },
    "prev": {
      "skip": 0,
      "take": 10,
      "page": 1
    }
  }
}

Create a position

POST /saas/v2/staff/position/create

Requires authentication and the “Staff Management” permission (StaffManage).

Request parameters

string

required

Position name. 1 to 100 characters. Leading and trailing spaces are trimmed automatically. Must be unique within the school.

string

The position’s external ID from the client’s system (CRM/1C). 1 to 50 characters, cannot contain / or whitespace characters. Must be unique within the school among non-deleted records.

integer[]

IDs of the departments where the position is available. Up to 250 values. Not passed or [] — the position is common to the whole school. Every department must belong to the school, otherwise StaffDepartmentNotFound is returned. See Linking to departments and grades.

integer[]

IDs of the grades that can be given to an employee in this position. Up to 100 values. Not passed or [] — any grade fits. Every grade must belong to the school, otherwise StaffGradeNotFound is returned.

curl --location 'https://api.exode.biz/saas/v2/staff/position/create' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --data-raw '{
    "name": "Backend Engineer",
    "departmentIds": [12, 15]
  }'

const axios = require('axios');

async function createPosition() {
  const { data } = await axios.post(
    'https://api.exode.biz/saas/v2/staff/position/create',
    {
      name: 'Backend Engineer',
      departmentIds: [12, 15],
    },
    {
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

createPosition();

{
  "success": true,
  "code": 201,
  "payload": {
    "id": 3,
    "createdAt": "2026-07-02T11:15:47.207Z",
    "updatedAt": "2026-07-02T11:15:47.207Z",
    "archivedAt": null,
    "schoolId": 198,
    "name": "Backend Engineer",
    "extId": null
  }
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionNameIsNotUniq",
  "message": "Staff position name is not uniq",
  "error": "Staff position name is not uniq"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionExtIdIsNotUniq",
  "message": "Staff position extId is not uniq",
  "error": "Staff position extId is not uniq"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffDepartmentNotFound",
  "message": "Staff department not found",
  "error": "Staff department not found"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffGradeNotFound",
  "message": "Staff grade not found",
  "error": "Staff grade not found"
}

{
  "code": 400,
  "success": false,
  "cause": "MiniappInstallationManagedEntity",
  "message": "The record is managed by a miniapp",
  "error": "The record is managed by a miniapp",
  "data": {
    "installationId": 7
  }
}

{
  "code": 401,
  "success": false,
  "cause": "Forbidden",
  "error": "Forbidden seller resource - permissions StaffManage",
  "message": "Forbidden seller resource - permissions StaffManage"
}

Update a position

PUT /saas/v2/staff/position/{positionId}/update

Requires authentication and the “Staff Management” permission (StaffManage).

Parameters

integer

required

ID of the position to update within the school.

string

New position name. 1 to 100 characters. Leading and trailing spaces are trimmed automatically. Must be unique within the school.

string

The position’s external ID from the client’s system (CRM/1C). 1 to 50 characters, cannot contain / or whitespace characters. Must be unique within the school among non-deleted records.

integer[]

New list of IDs of the departments where the position is available (up to 250). Replaces the current list as a whole; [] makes the position common to the whole school; not passed — the link is kept. StaffDepartmentNotFound if a department is not found in the school.

integer[]

New list of grade IDs of the position (up to 100). Replaces the current list as a whole; [] — any grade fits; not passed — the list is kept. StaffGradeNotFound if a grade is not found in the school.

curl --location --request PUT 'https://api.exode.biz/saas/v2/staff/position/4/update' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --data-raw '{
    "name": "Staff Backend Engineer",
    "departmentIds": [12]
  }'

const axios = require('axios');

async function updatePosition() {
  const { data } = await axios.put(
    'https://api.exode.biz/saas/v2/staff/position/4/update',
    {
      name: 'Staff Backend Engineer',
      departmentIds: [12],
    },
    {
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

updatePosition();

{
  "success": true,
  "code": 200,
  "payload": {
    "id": 4,
    "createdAt": "2026-07-02T11:15:47.216Z",
    "updatedAt": "2026-07-02T11:15:47.260Z",
    "archivedAt": null,
    "schoolId": 198,
    "name": "Staff Backend Engineer",
    "extId": null
  }
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionNameIsNotUniq",
  "message": "Staff position name is not uniq",
  "error": "Staff position name is not uniq"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionExtIdIsNotUniq",
  "message": "Staff position extId is not uniq",
  "error": "Staff position extId is not uniq"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffDepartmentNotFound",
  "message": "Staff department not found",
  "error": "Staff department not found"
}

Update a position by extId

PUT /saas/v2/staff/position/ext/{extId}/update

Requires authentication and the “Staff Management” permission (StaffManage).

Equivalent of the update-by-ID endpoint: the position is looked up by the external ID extId within the school. The extId value in the path must be URL-encoded.

Parameters

string

required

External ID (extId) of the position to update within the school. Must be URL-encoded.

string

New position name. 1 to 100 characters. Leading and trailing spaces are trimmed automatically. Must be unique within the school.

string

New external ID of the position. 1 to 50 characters, cannot contain / or whitespace characters. Must be unique within the school among non-deleted records.

integer[]

New list of IDs of the departments where the position is available (up to 250). Works the same as update by ID.

integer[]

New list of grade IDs of the position (up to 100). Works the same as update by ID.

curl --location --request PUT 'https://api.exode.biz/saas/v2/staff/position/ext/e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47/update' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_TOKEN' \
  --data-raw '{
    "name": "Staff Backend Engineer"
  }'

const axios = require('axios');

async function updatePositionByExtId() {
  const extId = encodeURIComponent('e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47');

  const { data } = await axios.put(
    `https://api.exode.biz/saas/v2/staff/position/ext/${extId}/update`,
    {
      name: 'Staff Backend Engineer',
    },
    {
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Content-Type': 'application/json',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

updatePositionByExtId();

{
  "success": true,
  "code": 200,
  "payload": {
    "id": 4,
    "createdAt": "2026-07-02T11:15:47.216Z",
    "updatedAt": "2026-07-02T11:15:47.260Z",
    "archivedAt": null,
    "schoolId": 198,
    "name": "Staff Backend Engineer",
    "extId": "e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47"
  }
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionNotFound",
  "message": "Staff position not found",
  "error": "Staff position not found"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionNameIsNotUniq",
  "message": "Staff position name is not uniq",
  "error": "Staff position name is not uniq"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionExtIdIsNotUniq",
  "message": "Staff position extId is not uniq",
  "error": "Staff position extId is not uniq"
}

Delete a position

DELETE /saas/v2/staff/position/{positionId}/delete

Requires authentication and the “Staff Management” permission (StaffManage).

A position cannot be deleted while it has active employees (including a scheduled hire with a future date): the method returns StaffPositionHasActiveEmployments. First change the employees’ position via promote or terminate them.

Parameters

integer

required

ID of the position to delete within the school.

Response

integer

required

Number of deleted records (1 on successful deletion).

curl --location --request DELETE 'https://api.exode.biz/saas/v2/staff/position/4/delete' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Authorization: Bearer YOUR_TOKEN'

const axios = require('axios');

async function deletePosition() {
  const { data } = await axios.delete(
    'https://api.exode.biz/saas/v2/staff/position/4/delete',
    {
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

deletePosition();

{
  "success": true,
  "code": 200,
  "payload": {
    "affected": 1
  }
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionHasActiveEmployments",
  "message": "Staff position has active employments",
  "error": "Staff position has active employments"
}

{
  "code": 401,
  "success": false,
  "cause": "Forbidden",
  "error": "Forbidden seller resource - permissions StaffManage",
  "message": "Forbidden seller resource - permissions StaffManage"
}

Delete a position by extId

DELETE /saas/v2/staff/position/ext/{extId}/delete

Requires authentication and the “Staff Management” permission (StaffManage).

Equivalent of the delete-by-ID endpoint: the position is looked up by the external ID extId within the school. The extId value in the path must be URL-encoded.

Parameters

string

required

External ID (extId) of the position to delete within the school. Must be URL-encoded.

Response

integer

required

Number of deleted records (1 on successful deletion).

curl --location --request DELETE 'https://api.exode.biz/saas/v2/staff/position/ext/e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47/delete' \
  --header 'Seller-Id: {{ sellerId }}' \
  --header 'School-Id: {{ schoolId }}' \
  --header 'Authorization: Bearer YOUR_TOKEN'

const axios = require('axios');

async function deletePositionByExtId() {
  const extId = encodeURIComponent('e2b4a1c0-7f3d-4b6a-9c2e-1d5f8a0b3c47');

  const { data } = await axios.delete(
    `https://api.exode.biz/saas/v2/staff/position/ext/${extId}/delete`,
    {
      headers: {
        'Seller-Id': '{{ sellerId }}',
        'School-Id': '{{ schoolId }}',
        'Authorization': 'Bearer YOUR_TOKEN',
      },
    }
  );
  console.log(data.payload);
}

deletePositionByExtId();

{
  "success": true,
  "code": 200,
  "payload": {
    "affected": 1
  }
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionNotFound",
  "message": "Staff position not found",
  "error": "Staff position not found"
}

{
  "code": 400,
  "success": false,
  "cause": "StaffPositionHasActiveEmployments",
  "message": "Staff position has active employments",
  "error": "Staff position has active employments"
}

Updated: 2026-10-16 13:24 UTC

Working with the API

Users

Staff (HR)

Groups

Courses

Access and sales

Reports and exports

Custom fields

Forms

Missing a method?

All objects

Request headers

Permission requirements

Linking to departments and grades

List positions

Parameters

Response

Create a position

Request parameters

Update a position

Parameters

Update a position by extId

Parameters

Delete a position

Parameters

Response

Delete a position by extId

Parameters

Response

​Request headers

​Permission requirements

​Linking to departments and grades

​List positions

​Parameters

​Response

​Create a position

​Request parameters

​Update a position

​Parameters

​Update a position by extId

​Parameters

​Delete a position

​Parameters

​Response

​Delete a position by extId

​Parameters

​Response

Request headers

Permission requirements

Linking to departments and grades

List positions

Parameters

Response

Create a position

Request parameters

Update a position

Parameters

Update a position by extId

Parameters

Delete a position

Parameters

Response

Delete a position by extId

Parameters

Response